Skip to content
AndonDocs
GitHub
Change Andon

Design system

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

Read this before you change what the board looks like or how fast it loads. The spec itself, with the tokens, type scale, components and motion values, is DESIGN.md at the repository root. Who uses Andon, and on which devices, is in PRODUCT.md.

Build UI from the kit

The board is React 19 and Vite, with shadcn/ui on Radix, Tailwind v4 tokens and lucide icons. There is no second component kit, no second state library and no CSS-in-JS.

  1. Look for the nearest thing that already exists: a page in apps/board/src/pages/, a component in components/<area>/, a hook in lib/<domain>.ts.

  2. Need a primitive the board doesn’t have yet? Add it from inside apps/board:

    shell
    pnpm dlx shadcn@<the pinned version> add <name>

    pnpm won’t install a release younger than 7 days (minimumReleaseAge in pnpm-workspace.yaml). If the generator asks for a newer one, pin the package to a release at least 7 days old (npm view <pkg> time).

  3. Colour comes from tokens in apps/board/src/index.css, used as Tailwind classes (bg-status-running, text-muted-foreground). Never a raw hex value. The front matter of DESIGN.md mirrors those tokens; change both together.

  4. Data goes through lib/db.ts, never @andon/client or supabase-js directly: that one indirection is where the board’s client is made and typed.

The rules people notice

  • Status colour is the only colour. Running is green, needs input is amber, waiting is blue, review is violet, failed is red and queued is neutral. Everything else is greyscale.
  • Red means failed and nothing else. Priority is a neutral glyph; overdue dates and bounced cards are amber.
  • Colour is never the only signal. Every status also has a word and a place.
  • One loop. The needs-you pulse is the app’s only looping animation, apart from the voice orb during a call and the mascot’s clips. Don’t add another.
  • Motion animates transform, opacity, colour and clip only, takes at most 400 ms, never blocks input, and exits faster than it enters. Reduced motion and the Dashboard’s night dim keep colour and opacity changes and drop movement, lifts and loops.
  • One primary action per state (Run, Approve outputs, Reply, Continue, Retry). The rest go in a menu. Every move or edit offers Undo.
  • Text is at least 12 px. Numbers that change or are compared (elapsed time, counts, 2/3) are mono and tabular.
  • Plain language replaces identifiers. Show “Ready”, not agent_ready.
  • A failed write never reports success. Writes are optimistic, and a failure rolls back and says so.

Three devices

The board is first-class at three widths, and a change isn’t reviewed until someone has looked at all three in a real browser:

Width Device What it is for
1440 desktop steering, keyboard first
1024 to 1180 iPad, often on a stand the Dashboard, read from across the room
390 phone Needs you first, then approve or reply, with 44 px touch targets

pnpm dev (or pnpm dev:demo for seeded review data) and a browser at those widths is the check. The Playwright projects desktop, ipad and iphone cover the same widths in tests (Testing).

The bundle budget

The board’s initial JavaScript (the entry script and every chunk index.html preloads) must stay within 200 KB brotli. Route chunks that load on demand don’t count. Check it with:

shell
pnpm --filter @andon/board budget

It builds the board twice: once with canary keys to check no secret reaches the bundle (scripts/key-check.mjs), and once to measure (scripts/bundle-budget.mjs). Every route module is lazy. App.tsx holds only the sign-in and org gates; the signed-in board (the store, the app shell, its providers and the page switch) is SignedIn.tsx, a chunk of its own, and each page in it is lazy again. A static import in App.tsx lands in the first load along with everything it imports, so put new signed-in code under SignedIn.tsx instead. To see what a chunk holds, build with pnpm exec vite build --sourcemap and read its .map’s sources. The usual offenders are zod (any @andon/shared module that defines a schema keeps it), lib/desktop.ts, Radix primitives, run polling and motion helpers.

Loading and live updates

A board left open all day must stay cheap:

  • Read by a batch of ids, never one card at a time: card_board_v and attention_v are views with many subselects.
  • Anything that loads on mount, on an event and on a timer goes behind loadGate and coalesce (lib/coalesce.ts), and skips work while document.visibilityState is hidden. useMachines is the example to copy.
  • Every new interval or subscription needs a visibility check and a clean-up.
  • Keep the last good data when a read fails, rather than showing an empty list.

Settings

Settings has six pages, from SETTINGS_PAGES in apps/board/src/lib/settings-index.ts. Every new <SettingsRow label="…"> or <SwitchRow label="…"> needs its label in SETTINGS_INDEX, or the index test fails. A setting’s name and place is user-facing: a rename also updates every docs page that gives its path (Writing docs).