Design system
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.
-
Look for the nearest thing that already exists: a page in
apps/board/src/pages/, a component incomponents/<area>/, a hook inlib/<domain>.ts. -
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 (
minimumReleaseAgeinpnpm-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). -
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. -
Data goes through
lib/db.ts, never@andon/clientorsupabase-jsdirectly: 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:
pnpm --filter @andon/board budgetIt 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_vandattention_vare views with many subselects. - Anything that loads on mount, on an event and on a timer goes behind
loadGateandcoalesce(lib/coalesce.ts), and skips work whiledocument.visibilityStateishidden.useMachinesis 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).
