Design system

A financial-infrastructure design language: deep ink type, hairline structure, thin display headlines, pill buttons, and tabular figures wherever money appears.

Principles

Nothing configurable ships without a description. Field and SettingsSection both require one, so an ambiguous control can't be written without deliberately working around the API. Field also requires htmlFor and wires the description to the control with aria-describedby — a description nobody hears is not a description.
Colour is never the only signal. Neither is an icon, nor a title tooltip — that reaches a mouse and nothing else. Every state says what it is in words, visibly or for a screen reader.
Ink, not black. Type is a deep navy. Pure black reads harsh against the cool near-white canvas.
Hairlines carry structure. Borders do the work that heavy shadows would; elevation stays subtle and blue-tinted.
One filled button per band. The filled primary pill marks the commit action; everything else is secondary or ghost.
Money is tabular. Every currency and count cell uses tnum so columns line up — the quiet signal that this is financial software.
Power without clutter. Rarely-changed, higher-risk configuration goes behind an Advanced disclosure rather than being hidden or removed.

Foundations

Typography — Geist Sans (UI) and Geist Mono (code, keys), self-hosted. Every tier from display down to heading renders at weight 300 with negative tracking (−1.4px at 56px down to 0 at 18px); that editorial air is the signature. Never bump a display or heading tier above 300 — a test fails if you do.
Type tiers — fifteen roles, and only these. display-xxl/xl/lg/md (56/48/32/26) · heading-lg/md/sm (22/20/18) · body-lg/md (16/15, body-md is the page default) · body-tabular (14, figures) · button-md/sm (16/14) · caption (13, figures) · micro (11) · micro-cap (10, uppercase eyebrow). Tailwind's own sizes, and any arbitrary pixel value, are not this scale and do not pass review.
Icons — lucide-react only, no emoji in chrome. 16px inside controls, 20px in feature spots.
Radius — 4px tags · 6px inputs · 8px compact cards and alerts · 12px cards · 16px large chrome · full-round buttons.
Spacing — an 8px base with 2/4/12 for fine work, so padding, margin and gap step in eights. Cards pad 24px; feature cards 32px; marketing bands 64px. Tailwind's half-steps (6px, 10px, 20px) are not on it. Component dimensions are separate: the 44px touch floor is a requirement, not a spacing choice.
Elevation — shadow-e1 for cards on white, shadow-e2 for floating panels. The gradient mesh, not shadow, is the depth medium on marketing surfaces.
Motion — 150–300ms ease-out; animate-fade-up for page and step entry. Everything respects prefers-reduced-motion, including animate-spin and animate-pulse.
Targets — controls reach 44px below the sm breakpoint. The desktop scale is unchanged; only the touch floor moves.

Color tokens

The mesh accents — --teal, --ochre, --violet, --coral — are decorative. They are tuned to read inside a 28px blur and sit between 2.3:1 and 4:1 against white, so they are never a button and never a state fill; --success, --warning and --destructive own state and carry the contrast to be read.

Defined as CSS variables in globals.css (light + .dark) and mapped into Tailwind via @theme inline — use classes like bg-card, text-muted-foreground, border-border:

--backgroundPage canvas and the deep-navy ink used for all type

--canvasWhite panels, the cool band under heroes, the warm interlude

--cardElevated surfaces: cards, tables, sidebars

--primaryBrand blue: filled buttons, links, active states, press

--primary-subduedPale fill behind tags and eyebrow pills

--brand-darkDeep navy fill for inverted bands and code blocks, and the light type that sits on it

--ink-secondaryBody copy that sits one step below the headline

--mutedSubdued fills and helper text

--borderHairlines — inputs sit on a slightly cooler line than cards

--destructiveOutcome colors

--chart-1 … chart-5Categorical data-viz palette

bg-primary

bg-[var(--brand-dark)]

bg-canvas-soft

bg-muted

bg-destructive

Components

shadcn-style components live in src/components/ui/ (Button with cva variants, Card, Skeleton, AlertDialog, Command); the shared kit in src/components/ui.tsx carries the clarity primitives.

import { Button } from "@/components/ui/button";

<Button>Book now</Button>
<Button variant="secondary" size="sm">Details</Button>
<Button variant="destructive">Cancel booking</Button>

Writing a settings screen

Group decisions with SettingsSection, describe every control with Field, and push expert options into Advanced. Labels name the decision in the operator's words (“Free-cancellation cutoff”), the description says what it changes, and the hint carries the unit and an example.

<SettingsSection
  title="Booking rules"
  description="These decide which times customers are offered on your booking form."
>
  <Field
    label="Minimum notice"
    description="How far ahead someone must book. With 4, a customer at noon
                 cannot pick a time before 4pm today."
    htmlFor="bookingLeadHours"
    hint="In hours. Raise it if same-day jobs catch you short-staffed."
  >
    <input id="bookingLeadHours" name="bookingLeadHours" type="number" className={input} />
  </Field>

  <Advanced description="Travel time and how far ahead bookings open.">
    …
  </Advanced>
</SettingsSection>

Interaction patterns

Toasts — every action outcome surfaces as a sonner toast. Server actions redirect with ?ok= / ?error=; the global FlashToaster converts those to toasts, scales the duration to the message length, and strips the params from the URL.
Command palette — ⌘K anywhere in admin: jump to a page (each listed with its description) or search bookings, customers, and providers.
Confirm dialogs — destructive submits go through ConfirmButton, which spells out the consequence and blocks Enter-key submission of the underlying form.
Live updates — the tracking page and team chat subscribe to /api/live (server-sent events) and refresh the server-component tree when data changes.
Drag to reschedule — calendar chips drag between days; the drop is validated server-side and answered with a toast.
Status badges — every status carries its plain-language meaning as real text (visually hidden, plus a tooltip for a mouse), so “no show” and “partial refund” never need a glossary on any device.
Live regions — anything that changes without a page load announces it: LiveRefresh, search, bulk selection, and the tracking timeline.

Signature surfaces

The .bb-mesh class paints the gradient-mesh backdrop used on the marketing hero: soft organic washes of brand blue, warm sand, and teal across the upper third of the page, with content floating above on white. It dims automatically in dark mode.

Dark mode

next-themes toggles a .dark class (system-aware). Token-based components adapt automatically; a small compatibility layer in globals.css remaps the status-color literals (bg-emerald-100, text-amber-700…) that badges still use.

The rules are tested

tests/unit/interface-rules.test.ts enforces the parts of this page a machine can see — emoji in chrome, a colour literal with no dark-mode value, a bolded display tier, a bare outline-none, an unnamed nav, a missing skip link, three dots where an ellipsis belongs, a size or radius off the scale. It also parses DESIGN.md and fails when globals.css drifts from it, role by role and colour by colour, so the document and the stylesheet cannot quietly describe different systems. It needs nothing running. tests/e2e/accessibility.spec.ts runs axe over every route in both themes for what only the rendered page shows.

Rule of thumb for new code: never hardcode a hex or a neutral-* — reach for a semantic token class. Charts read their colors from --chart-* so they follow the theme too. Note that --brand-dark pairs with --brand-dark-foreground, never --primary-foreground: the first stays dark in both themes while the second flips, so that pairing goes dark-on-dark.