# 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](https://github.com/psci-labs/andon/blob/main/DESIGN.md) at the repository root. Who uses Andon, and on
which devices, is in [PRODUCT.md](https://github.com/psci-labs/andon/blob/main/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`:

   ```sh
   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](https://andon-docs.pages.dev/contributing/testing.md)).

## 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:

```sh
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](https://andon-docs.pages.dev/contributing/writing-docs.md)).
