Design system

Two layers, strictly separated. Components never name a raw value — they ask for a purpose. That indirection is what makes a theme swap, a colorblind mode or a brand change an edit to one file instead of a search across every component.

Layer 1 · primitive ramps

Neutral steps are deliberately tight below 800 — that dark end is where panels separate from the canvas, and it needs more resolution than the light end ever will.

Two families, hard limit — and one superfamily, which is the point. IBM Plex Sans carries the entire interface; IBM Plex Mono is restricted to order IDs, transaction hashes and API keys, where character disambiguation genuinely matters and a slashed zero earns its keep. Numbers stay in Plex Sans with tabular figures, which is why the order book does not shiver on every tick.

A single multiplier generates the whole scale, so p-3 is always 12px and nobody has to memorise a lookup table. A dense terminal lives almost entirely in steps 1–3; anything above 8 is page-level composition.

Fixed layout constants

Chrome dimensions are tokenised too, so panels compute against them with calc() instead of scattering magic numbers across components.

Radius encodes scale: the larger the surface, the softer the corner. Controls sit at md, containers at lg, and only modals reach xl.

Border tokens

Each tier pairs a shadow with its surface token — on this ground the shadow alone is nearly invisible, so lightness does the real work and the shadow only reinforces it.

Rings — state, not depth

Trading interfaces punish slow animation. Nothing that gates a click exceeds 120ms; base is for surfaces, and slow is reserved for panels and sheets that move a long distance.

Named animations

Mobile-first — unprefixed styles are the phone layout. Conventional Tailwind names are kept rather than custom ones, so muscle memory and every doc example still apply.

Kept in the repo on purpose. The decisions are the interesting part of a design system, and they are exactly what gets lost once the tokens look inevitable in hindsight.

1. 00

   Read the system before drawing anything

   done

   Mapped the existing backend contract from source rather than assuming it — the REST surface, the websocket feed shapes and the database enums are what the UI has to model.

   • ·11 REST endpoints behind JWT bearer auth
   • ·WS feeds: last-traded-price, mark-price, depth, trades
   • ·Depth arrives as [price, qty] string tuples — decimals stay strings end to end
   • ·Gap found: no private user channel yet, so fills and order status are REST-only for now
2. 01

   Resolve the stack forks

   done

   Four decisions that would have been expensive to reverse later: framework, token authoring, theme scope and charting. Settled before a line of CSS.

3. 02

   Build the two-layer token system

   done

   Layer 1 primitives — raw ramps with no opinion about usage. Layer 2 semantic aliases pointing at them. Components read only Layer 2, which is the whole reason a theme swap is a one-file edit.

   • ·5 primitive ramps → 58 semantic tokens
   • ·Type scale: display through micro, plus a tabular numeric set
   • ·4px spatial grid from a single multiplier
   • ·Radii, borders, elevation, motion, breakpoints, layout constants
4. 03

   Verify the tokens actually compile

   done

   Grepped the compiled CSS for every token family rather than trusting the build's green checkmark. This caught a real bug.

   • ·Tailwind v4 has no --duration-* theme namespace — the variables existed but generated no utility classes, silently
   • ·Fixed by registering the four named speeds via @utility
   • ·Re-verified: 13 token families generate, keyframes included
5. 04

   Catch the tree-shaking trap

   done

   Rendering the styleguide exposed a second silent failure — two neutral steps were undefined at runtime and fell back to inherited text color. Plain @theme drops any variable no utility class references, and this page reads tokens through var() in inline styles, which the scanner cannot see.

   • ·Symptom: the neutral ramp rendered light-dark-light at the top end
   • ·Cause: --color-neutral-200 and -50 were tree-shaken out of :root
   • ·Would also have silently broken every --size-* layout constant
   • ·Fixed with @theme static, which emits all declared variables
   • ·Re-verified 31 tokens resolve in the browser, not just in the build
6. 05

   Base components

   done

   Eighteen atoms built from the tokens, variants typed through CVA. Every interactive control implements the same six states, and Field owns the label/hint/error accessibility wiring so no input re-implements it.

   • ·cn() had to teach tailwind-merge the custom type scale — stock behaviour silently drops text-body-md when it meets text-buy-text, which would have stripped the size off every button
   • ·12 merge cases pinned in a throwaway test before any component was written
   • ·NumericInput is a text input, not type=number: number inputs discard malformed values and scroll-mutate on hover, which is unacceptable for money
   • ·Delta and Side close the Phase 1 colorblind gap — the sign and the word are not optional props
   • ·Verified in-browser: label binding 23/23, aria-invalid wired to role=alert, roving tabindex on the segmented control
7. 06

   Design pass — type and signature

   done

   A deliberate check against the design-lead brief before organisms get built on top. Two gaps: the type pairing was the reflexive choice, and the system had no signature element. Both are cheap to change now and expensive after Phase 3 builds dense surfaces.

   • ·Ran a specimen bake-off — Inter vs IBM Plex Sans vs Archivo vs Instrument Sans, in a real order book at 11-13px
   • ·Chose IBM Plex on a structural argument: mono and sans sit adjacent in the same table row, and a superfamily keeps those columns optically aligned
   • ·Dropped Inter's cv05/ss03 feature settings, which do not exist in Plex
   • ·Added slashed zero on monospace only — order ids get transcribed, prose does not
   • ·Signature: the seam. Opposing quantities meet at a join whose position is the ratio, and the value sits on the join
8. 07

   Design review pass

   done

   First round of feedback against the built terminal. Four of five points held; the fifth was misdiagnosed in a useful way — the % buttons and the leverage slider were read as duplicates, which is a labelling failure rather than a redundant control.

   • ·Inputs raised instead of recessed, 44px with 20px figures in the ticket only — tables stay dense
   • ·Leverage slider rebuilt: its track was surface-inset on a dark panel, so only the thumb was visible
   • ·% row labelled 'of buying power' and grouped with Quantity; leverage moved behind a divider
   • ·Directional ramps dimmed against measured contrast, muted fills 24% → 22%
   • ·Ticket Seam cut — it showed nothing at 0% and Margin required already states it
   • ·Post/reduce-only collapsed behind an Advanced disclosure
9. 08

   Overlays, scrolling and elevation

   done

   Radix took over the behaviour-heavy overlays, the terminal became a fixed viewport shell, and every section finally got an elevation. Driven by real feedback against the built screen rather than a checklist.

   • ·Radix Dialog, Tabs, Tooltip and ScrollArea — used directly rather than via the shadcn CLI, which would have injected its own token vocabulary into globals.css
   • ·ScrollArea is now the default scroll region: its overlay scrollbar takes no layout width, so a native bar can no longer appear mid-stream and reflow the rows beneath it
   • ·Terminal is h-dvh + overflow-hidden at lg; min-height floors totalling ~622px were forcing a page scrollbar on short laptops
   • ·scrollbar-gutter: stable reserves the page scrollbar permanently
   • ·Every section is a raised panel on the base canvas, separated by an 8px seam — the market bar included, since full-bleed stopped aligning once the gutter was reserved
   • ·Order-book depth bars split into two nested tints: cumulative behind, the level's own size in front
   • ·Deposit dialog added, mapping to POST /order/onramp
10. 09

    Waiting, absence and failure

    done

    Every surface that depends on a network now has three designed states instead of one. The rule that fell out of it: check loading BEFORE empty, or an account with no positions flashes “No open positions” on every page load — telling someone something false about their money.

    • ·Skeleton, SkeletonRows and SkeletonTable pinned to --size-row and to the real table's min-width, so nothing shifts when data lands
    • ·EmptyState and ErrorState share one structure, so a panel's height does not jump between empty, failed and loaded
    • ·Error states are `danger`, never `sell` — red means SHORT everywhere else, so the triangle glyph and the heading carry the meaning
    • ·The order book now distinguishes “socket still opening” from “the book is genuinely empty”; a permanent shimmer on a quiet market is a lie
    • ·The chart's placeholder is candle-shaped — a grey rectangle reads as a broken chart
11. 10

    Toasts, and the status/direction collision

    done

    Fill confirmations on Radix Toast. The design problem was not the component: a fill carries a STATUS and a DIRECTION, and both want the colour. Green means LONG here, so a green “Filled” on a short fill states the opposite of the truth.

    • ·Split by job — the toast container carries status only, and direction lives in the body as a Side badge, which always prints the word
    • ·There is deliberately no buy/sell toast intent; a completed fill is `neutral`, not `success`, because --color-success aliases the long green
    • ·Rejections keep their glyph: a failure is not a direction, and the triangle carries it without hue
    • ·The visible stack is capped at four — a market order against a thin book fills in partials and an uncapped queue buries the market bar
    • ·Radix keeps a toast mounted while its exit animation runs, so dismissal is not a race between a timer and a transition
    • ·Found and fixed: Dialog's `animate-in fade-in` were tailwindcss-animate classes with no plugin installed — dead CSS behind a green build
12. 11

    Global header and landing page

    done

    Deposit and the account menu moved out of the market bar, which had been holding account-level actions only because it was the sole piece of top chrome. The terminal's fixed-viewport contract survived the extra 56px row.

    • ·Radix DropdownMenu for the account menu — items style off data-highlighted, so arrowing looks identical to mousing
    • ·The margin used/free Seam appears inside the menu: repetition is what makes a signature one
    • ·Header is a hard h-(--size-header) shrink-0 row inside the h-dvh column — no min-height, or short laptops grow a page scrollbar again
    • ·Landing page is the only route allowed the display type scale, and is deliberately static: the feed falls back to a simulator, and a marketing page quietly showing invented prices is worse than one showing none
13. 12

    Review pass — the two things that were wrong

    done

    Both reported from looking at the built screen, and both were real. One was a composition bug in CSS that no build could have caught; the other was a design failure that a contrast measurement turned into a number.

    • ·Dialogs jittered on open and close: Tailwind v4 compiles -translate-x-1/2 to the INDEPENDENT `translate` property, not `transform`. The keyframe also said translate(-50%,-50%), and since CSS applies `translate` before `transform`, the whole animation ran at -100%/-100% and snapped into place when it ended
    • ·Fix: keyframes animate `transform` only and never restate the centring — scale composes cleanly, translate does not. Measured after: 0px of centre drift across the entrance and every scrub point of the exit
    • ·Toasts were going unnoticed. Measured: surface-overlay against the panel behind it is 1.06:1 — for practical purposes the same colour, and shadow cannot rescue it on near-black where elevation is carried by lightness
    • ·Fix: a dedicated surface-toast at the top of the elevation ladder (1.24:1), border-strong, shadow-e4, and a grey stripe on the neutral intent so a fill has the same anatomy as every other toast
    • ·The entrance now carries the attention rather than the position: a short travel, then TWO luminance ticks peaking at 1.70:1 before cooling to rest over 560ms — a repeated signal reads as deliberate where one can be mistaken for a repaint, and the eye catches the second even if it missed the arrival
    • ·Runs `linear` so the keyframe percentages are a rhythm rather than an ease curve; only the travel segment keeps ease-out-quart, via a per-keyframe animation-timing-function
    • ·Toasts moved from bottom-right to top-right, offset by --size-header. Bottom-right was dead space diagonally opposite the dialog the user had just dismissed; docking at top-0 would have covered the Deposit button and account menu, so it clears the header and covers the ambient market bar instead
    • ·The stack is flex-col-reverse: newest nearest the docked edge, so an expiring toast is removed from the far end and nothing above it shifts
14. 13

    Backend integration

    next

    Replace the five placeholder modules with a real API client: markets, candles, account balances, the account tables and the order submit path. Fills arrive over the private ws-server channel rather than the local stand-in that fires them today.

Stack decisions

Design decisions

Carried deliberately rather than quietly. Each one has a decision point attached so it does not become an accidental default.