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.
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.
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.
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.
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.
Fast on the canvas
Painting, dragging and handles stay under a frame. UI work that can wait moves off the pointer path.
Keyboard and focus first
Every control is reachable from the keyboard, says what it is, and shows where focus is.
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.
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.
| Class | Size | Used for |
|---|---|---|
text-2xs | 10px | Keyboard chips, dense counters, footers |
text-xs | 12px | Most panel text: labels, buttons, helper lines |
text-sm | 14px | Body copy in dialogs and section headers |
text-lg | 17–20px | Headings only (fluid) |
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.52px14px1.56px28px312px416px624px832px
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
| Class | Radius | Used for |
|---|---|---|
rounded-sm | 4px | Chips, small inputs |
rounded-md | 6px | Fields, list rows (--radius) |
rounded-lg | 10px | Buttons, tiles, panels (--radius-lg) |
rounded-full | pill | Pills only |
Panels and dialogs
Three surfaces
Desktop
The full editor: the tool rail, the side panels, the gallery and the review panel, floating over the canvas.
Dock / tablet
The same tools in a compact layout, for a snapped window or a tablet. Panels tighten; nothing is removed.
Phone
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
Button · light Button · dark ButtonThe one text button: default, ghost, secondary and link variants on a size axis.
components/ui/button.tsx (source on GitHub, opens in a new tab)IconButton · light IconButton · dark IconButtonA single square icon button: the top bar's Undo, Redo, Zoom and Settings.
components/ui/icon-button.tsx (source on GitHub, opens in a new tab)ToolButton · light ToolButton · dark ToolButtonA tile in a tool grid; selected, idle and disabled are three separate looks.
components/ui/tool-button.tsx (source on GitHub, opens in a new tab)
Controls
ToggleButtonGroup · light ToggleButtonGroup · dark ToggleButtonGroupA row of buttons in a pill. Independent toggles announce aria-pressed; as a choice (mode="select") it is a radio group.
components/ui/toggle-button-group.tsx (source on GitHub, opens in a new tab)ToolButtonGroup · light ToolButtonGroup · dark ToolButtonGroupA grid of options. Passing a value makes it a radio group: one Tab stop, arrow keys.
components/ui/tool-button-group.tsx (source on GitHub, opens in a new tab)NumberField · light NumberField · dark NumberFieldA labeled number box, its word attached with a real label so a screen reader says what the number is.
components/ui/number-field.tsx (source on GitHub, opens in a new tab)SizeSlider · light SizeSlider · dark SizeSliderA slider with a readout; arrow keys step by one even when the track uses presets.
components/ui/size-slider.tsx (source on GitHub, opens in a new tab)ControlRow · light ControlRow · dark ControlRowLabel on the left, live value on the right, the control underneath, and the reason under that when it is off.
components/ui/control-row.tsx (source on GitHub, opens in a new tab)
Feedback
Skeleton · light Skeleton · dark SkeletonContent that exists but hasn't arrived. Still under Reduce Motion.
components/ui/skeleton.tsx (source on GitHub, opens in a new tab)Spinner · light Spinner · dark SpinnerWork in progress inside a button or line. Keeps turning under Reduce Motion: a frozen spinner reads as a hang.
components/ui/spinner.tsx (source on GitHub, opens in a new tab)StatusMark · light StatusMark · dark StatusMarkOne mark per meaning: complete, working, attention, failed, backed up, on this device.
components/ui/status-mark.tsx (source on GitHub, opens in a new tab)AsyncStatus · light AsyncStatus · dark AsyncStatusThe five states of anything that waits, in one view.
components/ui/async-status.tsx (source on GitHub, opens in a new tab)ReasonNote · light ReasonNote · dark ReasonNoteWhy a control is off right now. Muted, not a warning: a step is missing.
components/ui/status-note.tsx (source on GitHub, opens in a new tab)
Surfaces
ToolPanel · light ToolPanel · dark ToolPanelThe vertical rhythm of a tool panel's body: header, controls, sections and actions, 16px apart.
components/ui/tool-panel.tsx (source on GitHub, opens in a new tab)Dialog · light Dialog · dark DialogThe modal primitive, with the shared scrim and focus trap.
components/ui/dialog.tsx (source on GitHub, opens in a new tab)Tooltip · light Tooltip · dark TooltipHover and focus hints. The native title attribute is not used as a tooltip.
components/ui/tooltip.tsx (source on GitHub, opens in a new tab)PanelActionBar · light PanelActionBar · dark PanelActionBarThe actions at the foot of a settings panel: Apply Crop, Reset and Apply, Resize.
components/ui/panel-action-bar.tsx (source on GitHub, opens in a new tab)
06
Loading and interaction states
Everything that waits is in one of five states, and none of them invents its own spinner or toast.
| State | Means | Shows |
|---|---|---|
| Ready | nothing pending | nothing extra |
| Loading | fetching something that exists | skeletons in place of what it will fill |
| Processing | computing something new | the source stays visible and inert; progress when the length is known |
| Saved | a result landed somewhere durable | a check mark, briefly |
| Error | it didn't work | what 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.
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.
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
- UI Consistency (on GitHub, opens in a new tab)The ten rules, the scales, and when a control is a toggle or a radio group
- UI Exceptions (on GitHub, opens in a new tab)Every place that breaks a rule on purpose, and why
- UI Inventory (on GitHub, opens in a new tab)What the UI is actually built from, counted
- UI overview (on GitHub, opens in a new tab)Where to start, and the UI work that shipped
- Editor stylesheet (on GitHub, opens in a new tab)The tokens: colors, fonts, radii, elevation, motion
- Shared class strings (on GitHub, opens in a new tab)Tile states, the hover ring, confirm buttons
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.
41 color tokens · 17 components · 2 themes
01
Principles
The rules this site is built on. Each one is written in the stylesheet it governs, next to the value it explains.
A value is a token first
tokens.css holds the palette, the type scale, the spacing and the motion. The rule it sets: a new value gets a name there before anything uses it.
Two families and one outlier
Geist sets every heading and every paragraph. JetBrains Mono is for figures, labels and code, and never for running text.
One theme, and it's dark
The site has a single dark theme. A surface is raised by making it lighter, never by making it glow.
The gutter does the centering
Every section pads by one gutter token that grows on wide screens, so no page needs a max-width of its own.
A CTA never wraps
The pill button stays on one line at every width and is at least 44px tall.
Motion answers you
Things move when you do something. A handful of named durations cover it, and under Reduce Motion they all drop to one short one.
Readable without JavaScript
Every route is prerendered to HTML, so a search engine or a link preview gets the real page.
02
Colors
One dark theme, written in OKLCH. The swatches below are painted by the tokens themselves, and the values are read from tokens.css at build time.
Paper
The surfaces, darkest to lightest. A raised surface takes the next step up.
--color-paperoklch(13% 0.018 35)--color-paper-2oklch(17% 0.020 35)--color-paper-3oklch(22% 0.022 35)--color-paper-4oklch(28% 0.020 35)
Ink
Text. The contrast beside each is measured against the page background.
--color-inkoklch(95% 0.010 70)17.4:1 on paper--color-ink-2oklch(78% 0.015 60)10.0:1 on paper--color-ink-3oklch(58% 0.015 50)4.7:1 on paper
Rules
--color-ruleoklch(28% 0.018 40)--color-rule-strongoklch(40% 0.025 40)
Accent and focus
Amber is the one accent. accent-ink is the dark text that sits on an amber fill.
--color-accentoklch(74% 0.180 55)--color-accent-softoklch(74% 0.060 55)--color-accent-inkoklch(15% 0.040 50)--color-accent-2oklch(68% 0.220 18)--color-focusoklch(82% 0.180 55)
Bloom
The two soft glows behind the page, mixed in at 16 to 30 percent. Nothing else uses them.
--color-bloom-1oklch(74% 0.220 50)--color-bloom-2oklch(60% 0.220 15)
Contribution grid
The Trail Log's squares. Level 0 is an empty day: a tinted surface, never a pure gray.
--color-grid-0oklch(20% 0.012 40)--color-grid-1oklch(34% 0.070 48)--color-grid-2oklch(48% 0.115 50)--color-grid-3oklch(61% 0.150 52)--color-grid-4oklch(74% 0.180 55)
03
Typography
Geist for headings and body, JetBrains Mono for figures, labels and code. Both are variable fonts served from this site, one file per subset for every weight.
| Token | Size | Used for |
|---|---|---|
--text-2xs | 0.6875rem | The smallest labels: tile names and counts |
--text-xs | 0.75rem | Tags, eyebrows and mono labels |
--text-sm | 0.8125rem | Buttons and small notes |
--text-ui | 0.9375rem | Anything you act on: buttons, tables, lists |
--text-base | 1rem | Copy that sits beside controls and gets scanned |
--text-prose | 1.125rem | Long-form reading. Blog posts and nothing else |
--text-lg | 1.25rem | The deck under a page title |
--text-xl | 1.5rem | A release headline |
--text-section | clamp(2rem, 2vw + 1rem, 2.75rem) | Section headings |
--text-hero | clamp(2.75rem, 5vw + 1rem, 5.75rem) | The home page hero |
--text-display | clamp(3rem, 9vw + 0.25rem, 8rem) | A statement of 50 characters or fewer |
--text-statement | clamp(1.75rem, 4.5vw, 3rem) | The closing line above every footer |
--text-figure | clamp(5rem, 15vw, 11rem) | One number set larger than any headline: the $0 on Pricing |
The big sizes are fluid: each one names its smallest size, how fast it grows with the screen, and where it stops.
04
Spacing, layout and radii
Nine spacing steps on a 4px grid, one column width, and one gutter that also does the centering.
Spacing scale
--space-2xs4px--space-xs8px--space-sm12px--space-md16px--space-lg24px--space-xl40px--space-2xl64px--space-3xl96px--space-4xl144px
Layout
| Token | Value | Used for |
|---|---|---|
--page-max | 72rem | The widest the content column gets, matched to the home page's product shot |
--page-gutter | max(clamp(1.25rem, 5vw, 4rem), calc((100vw - var(--page-max)) / 2)) | The side padding of every section. Past the column's width it grows, and that growth is the centering |
--measure | 65ch | The line length of a blog post |
--banner-height | calc(94px + var(--announce-height)) | What every page's top padding clears: the nav plus the announcement bar |
Radii
| Token | Value | Used for |
|---|---|---|
--radius-xs | 2px | Keycaps and code chips |
--radius-sm | 6px | Small boxes: a swatch, the skip link |
--radius-md | 10px | Cards and panels |
--radius-pill | 999px | Buttons and tags |
--radius-logo | 20% | The horse mark, as a proportion, so it has the same corner at any size |
05
Components
The classes the pages are built from. These are the real thing, not pictures: this page uses the same ones.
CTA
The pill button. Fill is the main action, outline is the second, and a large size is for heroes.
styles.css (source on GitHub, opens in a new tab)Tag
A mono pill for a label: where code runs, the kind of change, the latest release.
styles.css (source on GitHub, opens in a new tab)Tile
A filter button with a count under its label. The Trail Log's months use it, and so do the two tabs on this page.
trail.css (source on GitHub, opens in a new tab)Action button
A large outline button for a download or a doc, stacked in a pair at the end of a page.
architecture.css (source on GitHub, opens in a new tab)Next cards
The cards at the end of a page that say where to go next.
tool-page.css (source on GitHub, opens in a new tab)Skip link
The first Tab stop on every page. It stays off screen until it has focus, then jumps past the nav.
styles.css (source on GitHub, opens in a new tab)
06
Motion
Six named durations and three curves, so a hover on one page feels like a hover on every other.
| Token | Value | Used for |
|---|---|---|
--dur-micro | 120ms | Hover and press: a color or a border changing |
--dur-short | 220ms | Something arriving, like the phone menu |
--dur-long | 420ms | A bigger landing: the home page's tool buttons settling |
--dur-morph | 720ms | The nav bar condensing as you scroll |
--dur-ambient | 3.2s | A slow loop for something idling, not something responding |
--dur-reduced | 150ms | What every animation and transition drops to under Reduce Motion |
--ease-out | cubic-bezier(0.16, 1, 0.3, 1) | A thing arriving |
--ease-in | cubic-bezier(0.7, 0, 0.84, 0) | A thing leaving. Defined, and nothing uses it yet |
--ease-in-out | cubic-bezier(0.65, 0, 0.35, 1) | A toggle between two states |
07
Accessibility
What every page on the site does, whatever it is about.
Focus you can see
A 2px amber ring just outside the control's edge, on everything that takes focus.
Targets you can hit
The pill buttons, the action buttons and the tabs are at least 44px tall, the size a finger needs.
Skip to the content
The first Tab stop on every page is a link past the nav.
Reduce Motion is honored
Every animation and transition drops to 150ms and runs once. Nothing loops.
Dark by declaration
The page says it is dark, so the browser's own scrollbars and form controls match it.
Read the source
- tokens.css (on GitHub, opens in a new tab)Every token, with the reason for each one written beside it
- styles.css (on GitHub, opens in a new tab)The shared classes: nav, buttons, tags, the home page
- animations.css (on GitHub, opens in a new tab)Every animation, and the Reduce Motion rule
- Marketing README (on GitHub, opens in a new tab)How to run the site and how a release reaches it
Why the site has its own
Because the two do different jobs. The editor is a tool you sit in for an hour, so it stays quiet and gets out of the way. This site is a page you read for a minute, so it gets the big type and the amber. One set of tokens couldn't do both.
Everything above is read from tokens.css when the site is built. The Figma file is the same page as layers you can pull apart.
89 tokens · 2 font families · 1 theme