We’re working on bringing Naji — the horse behind the name — home to Jacksonville.Bringing Naji home to Jacksonville.Meet Naji

Design System · the editor and this site

Design System

The foundations, components, interaction patterns, and accessibility rules behind Image Horse. Pick the editor or this site.

01

Principles

Seven rules every panel in the editor is held to. The UI was counted before any of them was decided, so each rule describes what most of the editor already did.

  1. Consistency over novelty

    A control looks and behaves the same everywhere it appears. A new look has to earn its place against the one people already know.

  2. One primitive per pattern

    If components/ui has it, the editor imports it. A hand-rolled copy of something that already exists is treated as the defect, even when it looks right.

  3. Honest feedback

    Loading, progress and errors say what is actually happening. Nothing spins forever, and an error always says what failed and offers a way out.

  4. The document is the truth

    The engine owns the pixels and the open document. While a photo switch is in flight the UI reads nothing from the photo that is leaving.

  5. Fast on the canvas

    Painting, dragging and handles stay under a frame. UI work that can wait moves off the pointer path.

  6. Keyboard and focus first

    Every control is reachable from the keyboard, says what it is, and shows where focus is.

  7. Local first, your call

    Edits run in your browser. Anything that needs a server says so, and the editor still works with it switched off.

02

Colors and themes

The editor has two themes, a warm-paper light and an earth-tone dark. Every color is a token: no hex in the components. The values below are read from the editor's own stylesheet at build time.

Backgrounds and surfaces

  • --bg-primary
    light
    #f3efe8
    dark
    #121212
  • --bg-secondary
    light
    #fbf9f5
    dark
    #181818
  • --bg-tertiary
    light
    #e9e3d8
    dark
    #222222
  • --bg-elevated
    light
    #ffffff
    dark
    #2b2b2b
  • --popover
    light
    #ffffff
    dark
    #181818

Text

  • --text-primary
    light
    #2a2622
    dark
    #eeeeee
  • --text-secondary
    light
    #5c554c
    dark
    #b4b4b4
  • --text-muted
    light
    #6b6258
    dark
    #969696

Accent and selection

primary-strong is the ink of a selected tile. The light accent is too pale to be read as text on its own tint.

  • --accent
    light
    #c98f3f
    dark
    #fcdfc2
  • --primary
    light
    #c98f3f
    dark
    #fcdfc2
  • --primary-strong
    light
    #7d5927
    dark
    #fcdfc2
  • --secondary
    light
    #efe7d8
    dark
    #3a3128

Borders and focus

Focus is neutral ink, not the accent: the accent already means "selected".

  • --border
    light
    #e4ddcd
    dark
    #211f1a
  • --border-active
    light
    #c98f3f
    dark
    #fcdfc2
  • --input
    light
    #d8d0c2
    dark
    #484848
  • --focus-ring
    light
    #2a2622
    dark
    #eeeeee

Status

  • --success
    light
    #16a34a
    dark
    #22c55e
  • --warning
    light
    #d97706
    dark
    #f59e0b
  • --destructive
    light
    #dc2626
    dark
    #e55032
  • --destructive-strong
    light
    #b91c1c
    dark
    #ef6a4a

Disabled

Disabled is not its own color. A disabled button keeps its shape and drops to the tertiary surface with muted text; a disabled tool tile also fades to 40% and goes gray.

Enabled and disabled · light
Enabled and disabled · dark

03

Typography

DM Sans for the interface, JetBrains Mono for numbers and anything code-like. Three sizes carry almost the whole app, and the scale is closed: no one-off sizes.

This page doesn't ship the editor's DM Sans files, so the specimens use it if your system has it and a plain sans-serif otherwise. JetBrains Mono is shared with this site.

The editor's interface type scale
ClassSizeUsed for
text-2xs10pxKeyboard chips, dense counters, footers
text-xs12pxMost panel text: labels, buttons, helper lines
text-sm14pxBody copy in dialogs and section headers
text-lg17–20pxHeadings only (fluid)
Type in a panel · light
Type in a panel · dark

Numbers in readouts are monospaced so a changing value doesn't make its neighbors jump, and they line up in a column.

04

Spacing, layout and radii

Eight spacing steps, in Tailwind units, carry almost every gap in the editor. Anything off the scale needs a written exception.

Spacing scale

  • 0.52px
  • 14px
  • 1.56px
  • 28px
  • 312px
  • 416px
  • 624px
  • 832px

Inside a panel, controls sit 16px apart (a tool panel's own rhythm) and a control's label sits 8px above it. Panels keep a 16px edge.

Radii

Radius tokens · light
Radius tokens · dark
Radius classes
ClassRadiusUsed for
rounded-sm4pxChips, small inputs
rounded-md6pxFields, list rows (--radius)
rounded-lg10pxButtons, tiles, panels (--radius-lg)
rounded-fullpillPills only

Panels and dialogs

A tool panel · light
A tool panel · dark

Three surfaces

  • Desktop wide windows

    The full editor: the tool rail, the side panels, the gallery and the review panel, floating over the canvas.

  • Dock / tablet about 960px

    The same tools in a compact layout, for a snapped window or a tablet. Panels tighten; nothing is removed.

  • Phone about 390px

    The Mobile version: browse the gallery, add photos and download. It does not have the editing tools.

05

Components

The shared primitives in app/src/components/ui. Each card is a static picture drawn from the editor's tokens, with a link to the real component.

Actions

Controls

Feedback

Surfaces

06

Loading and interaction states

Everything that waits is in one of five states, and none of them invents its own spinner or toast.

The five async states
StateMeansShows
Readynothing pendingnothing extra
Loadingfetching something that existsskeletons in place of what it will fill
Processingcomputing something newthe source stays visible and inert; progress when the length is known
Saveda result landed somewhere durablea check mark, briefly
Errorit didn't workwhat failed, in words, and an action, usually Try again

Skeleton

Something that exists hasn't arrived yet. A thumbnail is either a skeleton or the real photo, never a gray half-loaded one.

Progress

Something new is being made. The source stays visible and can't be touched until it's done.

Failure

It didn't work. The error replaces the progress, says what failed, and offers Try again.

A fast load doesn't flash

Skeletons wait 300 ms before they appear, so a load that finishes sooner shows nothing in between. Under Reduce Motion the shimmer stops and the placeholder stays still.

Press one.
Gallery thumbnails · light
Gallery thumbnails · dark

Switching photos

While the next photo loads, the footer and canvas say "Loading" and the panels that describe the document go to skeletons, inert, until the new photo is really in. They never show the old photo's numbers under the new photo's name. A request the switch made pointless is dropped quietly, not shown as an error.

A document-dependent panel mid-switch · light
A document-dependent panel mid-switch · dark

07

Accessibility and consistency

The editor's UI constitution, in short. The full rules, the counts behind them and the reasons live in the repo.

  • WCAG 2.1 AA

    The bar for every surface. Contrast pairs are measured, and the measurements are written next to the tokens.

  • A choice says which choice

    Exclusive options are a named radio group with aria-checked. aria-pressed is only for independent toggles.

  • Focus you can see

    A dashed outline in neutral ink on every interactive element. Selected, hover and focus each use their own channel, so they never look alike.

  • Announced, not just shown

    A failure is an alert. A validation line that changes while you type is polite, so it never interrupts every keystroke.

  • Targets you can hit

    Touch targets are sized for a finger, and pinned by a test.

  • Loading means loading

    A region that is loading says so to a screen reader and is inert until it isn't; an error replaces the progress instead of sitting beside it.

  • One owner for each value

    A value is per photo, per tool or app-wide, and the UI reads it from that owner, never from a copy that may describe the photo that is leaving.

Exceptions are decisions

Some places break a rule on purpose: the white badges and labels drawn on top of a photo, which have to stay white in both themes, or the stacking order inside a single gallery thumbnail. Each one is written down with its reason in the exceptions registry. An entry there is a decision someone made and recorded, not a bug waiting for a fix.

Read the source

Why write it down

Because consistency is the feature. An editor where every slider, tile and dialog works the same way is one you stop thinking about, and that only lasts if the rules live somewhere a person can read them.

Everything above is drawn from docs/UI_CONSISTENCY.md and the editor's own stylesheet. The Figma file is the same page as layers you can pull apart.