diff --git a/.agents/skills/frontend/information-architecture/SKILL.md b/.agents/skills/frontend/information-architecture/SKILL.md
index 021ea868..df17c0e7 100644
--- a/.agents/skills/frontend/information-architecture/SKILL.md
+++ b/.agents/skills/frontend/information-architecture/SKILL.md
@@ -44,7 +44,7 @@ Rules:
 - **"Schema history" is not a sibling tab.** Version history lives inside the Schema tab, below the editor and beside the `VersionNavigator` seam. The two overlap on purpose: the navigator is the *reader* (one version, with what it changed), the history is the *ledger* (every version at once). `?tab=versions` remains as a redirect; it does not appear in the tab bar.
 - **The 4-step checklist is onboarding, not navigation.** It retires itself twice over: when the journey is finished (`hasReleases` makes `done` derivable) and when somebody dismisses it. Dismissal is **per project** and persisted — finishing one project does not teach you the pipeline for the next. It gates nothing and is never the sole path to a screen.
   `hasReleases` is derived in `useProjectReadiness` from the two-hop read (project → dataset → releases) rather than added to the project-stats wire model: the Overview dashboard already makes both requests for its own cards, so a third spelling of the fact on the server would be exactly the drift these rules exist to prevent.
-- **Inference is a rail destination, not a project tab.** Model connections carry no `project_id`: one workspace is one SQLite file, every project uses the same connections, and navigation maps 1:1 to domain objects — so a project tab would state a scope the object does not have. This **supersedes the earlier rail rule** ("logo, collapse toggle, Home, Projects, account avatar — nothing else"); the rail now carries Home, Projects, Inference and the account control, and `DESIGN.md` carries the same membership in both places it states it. What earns a rail entry is a workspace-level object with nowhere else to live, never mere frequency of use.
+- **Inference is a rail destination, not a project tab.** Model connections carry no `project_id`: one workspace is one SQLite file, every project uses the same connections, and navigation maps 1:1 to domain objects — so a project tab would state a scope the object does not have. This **supersedes the earlier rail rule** ("logo, collapse toggle, Home, Projects, account avatar — nothing else"); the rail now carries Home, Projects, Inference and the account control, and `docs/ui/navigation.md` carries the same membership. What earns a rail entry is a workspace-level object with nowhere else to live, never mere frequency of use.
 - **Home is the workspace's dashboard, and Overview is the project's.** They do not
   overlap, because they answer different questions: Home asks *what is waiting on me,
   anywhere*, which no single project can answer, and Overview asks *what does this
diff --git a/.agents/skills/process/public-writing/SKILL.md b/.agents/skills/process/public-writing/SKILL.md
index 5644b1bc..5cd3e4bc 100644
--- a/.agents/skills/process/public-writing/SKILL.md
+++ b/.agents/skills/process/public-writing/SKILL.md
@@ -75,13 +75,13 @@ issue number — inside a sentence, a quotation, or a denial. "Nothing here clos
 
 ## Paragraphs, not notation — and voice
 
-Write the way `DESIGN.md` writes: complete sentences that explain reasoning. Telegraphic
-fragments, bare citation chains and stacked parentheticals cost the reader more than they save
-the writer. Structure still earns its place — a settled-options list stays a list, a comparison
-stays a table.
+Write complete sentences that explain reasoning, the way this repository's documentation
+writes. Telegraphic fragments, bare citation chains and stacked parentheticals cost the reader
+more than they save the writer. Structure still earns its place — a settled-options list stays
+a list, a comparison stays a table.
 
-`DESIGN.md`'s copy rules hold here too: **no exclamation marks, no "successfully", no "please"**
-— plus no filler acknowledgment, no restating the request before answering, no announcing a
+House style for public prose: **no exclamation marks, no "successfully", no "please"** — plus
+no filler acknowledgment, no restating the request before answering, no announcing a
 conclusion the text does not support.
 
 Before posting, reread the draft asking: does it name a company or product, and is the mention a
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6f326007..ea586b99 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -280,10 +280,13 @@ If a change fights either boundary, the change is wrong — not the boundary.
 
 Any change to `@visionset/app` or `@visionset/ui-core` is governed by
 [`DESIGN.md`](DESIGN.md) at the repository root — **read it before building or changing a
-screen**, not after. It owns the tokens, the type scale, the navigation rules, the tab
-shapes, the annotation workspace, and (since #206) the rules for project-level data
-surfaces: what a header carries, how numbers are formatted, and why a disabled button with
-no explanation is forbidden.
+screen**, not after. It owns the visual foundations: colour semantics, typography roles,
+spacing, radius, materials, motion, action hierarchy, and accessibility. The product's own
+UI rules live beside it: [`docs/ui/product-principles.md`](docs/ui/product-principles.md)
+(what a screen must show and offer — headers, numbers, why a disabled button with no
+explanation is forbidden), [`docs/ui/navigation.md`](docs/ui/navigation.md) (breadcrumbs,
+the rail, URL state), and [`docs/ui/annotator.md`](docs/ui/annotator.md) (the annotation
+workspace).
 
 It is prose over running code, not decoration. `frontend/ui-core/src/styles.css` carries the
 tokens and `tokens.ts` mirrors them, gated against each other in both directions by
diff --git a/DESIGN.md b/DESIGN.md
index db974a59..f6a2ab6e 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -1,1413 +1,424 @@
----
-version: 1
-name: VisionSet
-description: >
-  VisionSet frontend design system — the authoritative visual contract for the M5 app
-  (@visionset/app + @visionset/ui-core) and the annotator demo. GitHub-inspired,
-  content-first, accessible UI on Radix primitives + lucide icons (decision H), styled
-  with design tokens. Adapted 2026-07-30 from v1's DESIGN.md (computer-vision-lab-app),
-  whose values were verified in its source; the reference screenshots are described in
-  the 2026-07-30 design comment on issue #51. Implemented by #128 (M5 WS-1):
-  frontend/ui-core/src/styles.css carries these values as Tailwind v4 @theme tokens
-  and frontend/ui-core/src/tokens.ts mirrors them for callers that cannot read CSS,
-  with a test asserting the two agree in both directions. This file is the prose
-  half; those two are the running half.
-colors:
-  # Primary action — a near-black with an indigo undertone. NOT the brand.
-  primary: "#1e2130"            # filled buttons, active tab rule, active tool
-  primary-hover: "#2a2d40"
-  primary-foreground: "#ffffff"
-  # Brand — Robomous coral, TWO sites in the whole product (see "Where the brand is")
-  brand: "#e85d44"              # the rail's wordmark, and the progress bar's fill
-  # Surfaces
-  background: "#fafafb"         # the page
-  card: "#ffffff"               # a surface sitting on it
-  popover: "#ffffff"
-  muted: "#f3f4f6"              # subtle fills, hover backgrounds, secondary surfaces
-  disabled: "#f3f4f6"           # a disabled control's fill
-  stage: "#e4e6ec"              # the annotator's surround — the neutral a picture is judged against
-  # Text
-  foreground: "#1b1d28"         # primary text
-  muted-foreground: "#6b6e7e"   # secondary / meta text, inactive tabs
-  disabled-foreground: "#a0a3b1"
-  # Lines & focus
-  border: "#e7e8ec"             # hairlines, dividers
-  input: "#dcdde4"              # input and secondary-button borders — a step darker
-  ring: "rgba(30, 33, 48, 0.35)"  # the action colour at 35%
-  # Status — desaturated, to sit on a near-monochrome page
-  success: "#2e7d5b"            # completed states
-  warning: "#b98217"
-  destructive: "#c93b3b"        # errors, destructive actions
-  # Dark chrome (app rail / sidebar) — the same near-black as `primary`
-  sidebar: "#1e2130"
-  sidebar-accent: "#2a2d40"     # rail hover, and the ACTIVE rail item's fill
-  sidebar-strong: "#161823"
-  sidebar-muted: "#8b8fa3"      # inactive rail icons and labels
-  sidebar-foreground: "#ffffff"
-typography:
-  page-title:
-    fontFamily: system-ui
-    fontSize: 1.5rem            # text-2xl (1.875rem on md+)
-    fontWeight: 600
-    letterSpacing: "-0.025em"
-  section-title:
-    fontFamily: system-ui
-    fontSize: 1rem
-    fontWeight: 600
-  body:
-    fontFamily: system-ui
-    fontSize: 0.875rem          # 14px base
-    lineHeight: 1.6
-  meta:
-    fontFamily: system-ui
-    fontSize: 0.75rem
-    fontWeight: 400
-  label:
-    fontFamily: system-ui
-    fontSize: 0.875rem
-    fontWeight: 500
-rounded:
-  sm: 4px                       # chips, small controls
-  md: 8px                       # buttons, inputs, badges (default; --radius 0.5rem)
-  lg: 12px                      # alerts, dialogs, sheets, tab lists
-  xl: 16px                      # cards
-  full: 9999px                  # avatars, progress bars, pills
-spacing:
-  xs: 4px
-  sm: 8px                      # inline groups, field gap
-  md: 16px                     # default layout unit
-  lg: 24px                     # grids and page sections
-  xl: 32px                     # form section padding
-  page: 24px
-elevation:
-  none: "none"
-  card: "shadow"               # resting cards
-  raised: "shadow-md"          # card hover
-  overlay: "shadow-lg"         # dialogs, sheets, toasts, dropdowns
-layout:
-  sidebar-width: 240px
-  sidebar-width-collapsed: 60px
-  sidebar-width-mobile: 280px
----
-
-## Overview
-
-VisionSet's interface is **neutral-first, content-first, and accessible**. The screen is
-almost monochrome — cool greys with a faint indigo undertone — and the colour a person can
-act on is a **near-black** (`#1e2130`): filled buttons, the active tab's rule, the active
-tool. A dark rail in that same near-black frames a bright content area.
-
-**Robomous coral (`#e85d44`) is not the interface's colour.** It appears in exactly two
-places (see *Where the brand is*, below), and everything else that used to wear it now
-wears the near-black. The reasoning is in the token file and worth repeating here: an
-interface whose every button is brand-coloured spends the brand on "Cancel". Making colour
-scarce is what lets the two places it survives actually mean something.
-
-**Design principles** (inherited from v1, kept):
-
-1. **Token-driven, not hardcoded.** Color, radius, and spacing come from the token
-   registry above, surfaced as semantic utilities. Never a hex, `rgb()` or raw `var()`
-   color in a class string — v1 spent its life migrating away from that; VisionSet starts
-   clean and stays clean. **Enforced**: `tests/scripts/design_tokens.test.mjs` scans every
-   tracked frontend source for a Tailwind arbitrary colour (`bg-[#eb5a47]`,
-   `text-[var(--x)]`) and fails the build. An *inline* style carrying a **schema-supplied**
-   colour is the sanctioned exception and the only one — `classColor` answers with whatever
-   the kernel stored, and Tailwind has never seen it, so no utility could name it.
-2. **Radix + lucide only for primitives** (decision H, epic #51). v1 built on shadcn/ui,
-   which is Radix + Tailwind — the same constraint from the other end. FontAwesome is v1
-   legacy and does not come along.
-3. **Content over chrome.** Subtle borders, minimal shadows, no gradients, quiet
-   hover/focus effects. The interface is neutral; the brand is not a surface fill and is not
-   an interaction colour at all. Whitespace is generous
-   on forms and lists, where the content is a few things a person reads one at a time —
-   and **is not a substitute for information**: see principle 7, which governs the
-   surfaces whose content is a dataset.
-4. **Accessible by default.** Real `<button>`/`<a>` elements, visible `focus-visible`
-   rings, keyboard operability, and every async surface has loading / empty / error
-   states (skeletons preserve layout; errors are destructive alerts with a recovery
-   action; empty states are a centered card with a muted icon, title, and one primary
-   action).
-5. **Consistency beats novelty.** A new screen should be indistinguishable in styling
-   from the existing ones.
-
-**Added 2026-08-01 (#206)**, for the surfaces whose subject is a dataset rather than a form:
-
-6. **Data first.** VisionSet is a dataset tool, and every project-level screen surfaces real
-   data — counts, distributions, samples — before configuration. **The test: if a screen
-   would render identically for an empty project and a 100k-image one, it is wrong.** The
-   project view failed it for its whole life before #212, because it opened on a schema
-   editor and a schema is the same document either way.
-7. **Density over whitespace, on data surfaces.** Our users are ML engineers and
-   professional annotators working with large ontologies — a fifty-class ontology is
-   ordinary. Prefer compact lists, tables and two-panel layouts to spacious single-column
-   forms. This does not license crowding: it licenses *showing more of the thing the user
-   came for*, which is the same instinct as principle 3 applied to a screen whose content
-   is plural.
-8. **Action-forward.** Every major screen answers "what do I do next?" with exactly one
-   primary CTA. On a project page that action is annotating.
-9. **Never disable without explanation.** A button either stays enabled and answers with a
-   message, or it carries an adjacent explanation of what would enable it, or it is not
-   rendered at all. **A bare disabled grey button is forbidden** — it is a question the
-   interface refuses to answer. #160 is the same bug from the other side: a control that
-   rendered `disabled` because a callback was missing made the annotator unreachable, and
-   nothing on screen said so.
-10. **The annotation workspace is self-sufficient.** No flow may force navigation out of
-   the editor, and no exit may lose work. Back saves first, the way the asset navigator
-   already did; a class the schema lacks is created from the class field without leaving
-   the page; **looking at the job's other frames is an overlay, not an exit** (#390 — the
-   grid button opens a gallery over the workspace and the URL does not move). Ratified
-   2026-08-05 (#368) and **immovable**: this is the one screen somebody sits in for an
-   hour, and every trip out of it is a trip back through a list, a tab and a scroll
-   position to the frame they were looking at. The grid jump was listed here as a
-   sanctioned *exit* until #390; that was the principle's own example failing it, since
-   choosing the next frame is a flow **inside** annotating rather than a reason to leave.
-
-## Colors
-
-Map intent → token; never invent a value:
-
-| Intent | Token |
-|--------|-------|
-| Primary action / active tool | `primary` (`#1e2130`), hover `primary-hover` |
-| Active tab rule | `primary` — see **Tabs** below |
-| Accent tint (chips, selected rows) | `primary` at 10% alpha, border `primary` |
-| Page surface | `background` (`#fafafb`) |
-| Card / popover surface | `card` / `popover` (`#ffffff`) |
-| Subtle fill / hover / secondary surface | `muted` (`#f3f4f6`) |
-| A disabled control | `disabled` fill, `disabled-foreground` ink, **no border** |
-| The stage a picture sits on (annotator surround) | `stage` (`#e4e6ec`) |
-| Primary text | `foreground` (`#1b1d28`) |
-| Secondary / meta text, inactive tabs | `muted-foreground` (`#6b6e7e`) |
-| Borders & dividers | `border` (`#e7e8ec`) |
-| Input / secondary-button border | `input` (`#dcdde4`) |
-| Focus ring | `ring` — the action colour at 35% |
-| Completed / success | `success` (`#2e7d5b`) |
-| Warning | `warning` (`#b98217`) |
-| Errors / destructive | `destructive` (`#c93b3b`) |
-| Dark rail chrome | `sidebar` (`#1e2130`); active item `sidebar-accent` + white; the rest `sidebar-muted` |
-| The brand | `brand` (`#e85d44`) — **two sites only**, below |
-
-The palette is defined for light mode; dark mode is a post-beta concern.
-
-### Where the brand is
-
-Coral appears in the product in exactly two places, and adding a third is a design
-decision rather than a styling one — raise it in review, do not put it in a diff:
-
-1. **The wordmark** in the rail (`frontend/app/src/shell/AppShell.tsx`).
-2. **The `Progress` primitive's fill** (`frontend/ui-core/src/primitives/Feedback.tsx`) — the
-   ingest bar, the weight download's, and any bar that comes after them.
-
-A progress bar is the one piece of chrome a person watches rather than reads, which is
-where the coral buys attention instead of spending it. The styleguide shows a `brand`
-swatch as well — a styleguide is where a value is inspected, not where it is used.
-
-The second entry names the **primitive** rather than one of its callers, and the recorded
-reason is why: it argues about what a progress bar *is*, not about which screen has one. A
-rule phrased as *the ingest bar* would make the weight download's bar look like the third
-site this list forbids, and the honest reading — one component, used twice — would have had
-to be argued from scratch every time a bar appeared.
-
-To check the invariant:
+# VisionSet design foundations
+
+## Purpose
+
+This document is the visual and interaction contract for every VisionSet interface: the
+M5 app (`@visionset/app` + `@visionset/ui-core`), the annotator demo, and any surface
+built after them. It answers one question — **how should a VisionSet interface look,
+feel, and behave visually?** — and deliberately answers nothing else.
+
+The design language is inspired by Vercel's Geist design system: minimal, precise,
+neutral-first, monochrome-leaning, with colour reserved for meaning. VisionSet does not
+use Vercel's components; Geist is the reference for the language, and VisionSet owns its
+own implementation. The intended layering, from foundation to screen:
+
+```text
+Geist-inspired foundations            (this document)
+        ↓
+VisionSet semantic design tokens      (frontend/ui-core — implementation)
+        ↓
+shadcn-derived / project-owned primitives
+        ↓
+VisionSet patterns
+        ↓
+Product screens
+```
 
+What this document does **not** own: product behaviour
+([`docs/ui/product-principles.md`](docs/ui/product-principles.md)), navigation
+([`docs/ui/navigation.md`](docs/ui/navigation.md)), the annotation workspace
+([`docs/ui/annotator.md`](docs/ui/annotator.md)), the data shell
+([`docs/ui.md`](docs/ui.md)), frontend architecture and library choices
+([`docs/architecture/frontend/`](docs/architecture/frontend/README.md)), or test
+mechanics. Rules here are stated as the present contract; enforcement details live with
+the tests and contributor docs.
+
+## Design Philosophy
+
+Each principle is a decision rule, not a slogan. When two of them conflict on a concrete
+screen, the earlier one wins.
+
+1. **Content first.** The interface recedes; the user's data — images, annotations,
+   counts — is the loudest thing on screen. Chrome earns its pixels: subtle borders,
+   minimal shadows, no gradients, no decoration.
+2. **Neutral first.** The screen is near-monochrome. Colour is scarce so that colour can
+   mean something: one accent for action and focus, and the status hues for state. A
+   surface is never flooded with a hue to make it interesting.
+3. **Precise.** Alignment, spacing, and type sit on the scales below — never eyeballed.
+   Two screens built by two people should be indistinguishable in styling.
+4. **Hierarchy through structure, not volume.** Typography, spacing, hairlines, and
+   materials carry hierarchy. Reaching for a louder colour or a heavier shadow to make
+   something "stand out" is a hierarchy failure upstream.
+5. **Dense where the content is plural.** VisionSet's users are ML engineers and
+   professional annotators; on data surfaces, showing more of the thing the user came for
+   beats whitespace. Generosity belongs to forms and prose, read one thing at a time.
+6. **Fast.** Interfaces respond on the frame the user acts; waits are acknowledged
+   immediately and quietly. Motion never makes anyone wait.
+7. **Accessible by default.** Semantic HTML, keyboard operability, visible focus, and
+   redundant (never colour-only) signals are part of the definition of done, not a pass
+   afterwards.
+8. **Consistent over novel.** Reuse the token, the role, the material, the pattern. A new
+   visual treatment is a design decision made in this document, not in a component diff.
+9. **Theme-agnostic.** Every rule below is written against semantic roles, not against
+   light-mode values, so light and dark themes are a token swap — never a redesign.
+
+## Foundations
+
+### Color
+
+The colour system has two layers, and application code speaks only the second.
+
+**Primitive palette.** Neutral-anchored scales in the Geist manner — `Gray`, `Gray Alpha`
+(for borders and fills that must composite over any surface), `Blue`, `Red`, `Amber`,
+`Green`, `Teal`, `Purple`, `Pink` — each a numeric ramp from subtle background steps to
+high-contrast foreground steps. Primitives are the vocabulary tokens are defined *from*;
+no component names one directly.
+
+**Semantic aliases.** What components consume. Each names an intent, resolves to a
+primitive step per theme, and is the only spelling of that intent:
+
+| Alias | Intent |
+| --- | --- |
+| `background` | The page |
+| `background-subtle` | A recessed area of the page |
+| `surface` | A raised element sitting on the background (card, popover, input) |
+| `surface-hover` / `surface-active` | Its pointer states |
+| `border` | Hairlines and dividers |
+| `border-hover` / `border-active` | Interactive-element borders under pointer / active |
+| `foreground` | Primary text |
+| `foreground-secondary` | Secondary and meta text |
+| `accent` | The action colour: primary actions, active states, focus, selection tint |
+| `info` | Work in flight; neutral-positive information |
+| `success` | A settled, succeeded state |
+| `warning` | Something is waiting on a person |
+| `error` | Failure, refusal, destruction |
+
+Rules:
+
+- **Map intent to alias; never invent a value.** Raw colour values appear only in token
+  definitions. This is a standing invariant, machine-enforced; one exception exists — an
+  inline style carrying a *schema-supplied* class colour, which is user data no token
+  could name.
+- **Status hues are for status** (see *Status* below), never for emphasis, branding, or
+  action hierarchy.
+- **The accent is one colour product-wide.** Active tool, active tab, primary action,
+  selection tint, and focus ring are all readings of the same accent, so the interface has
+  one voice for "this is where the action is".
+- Aliases are defined for both light and dark resolutions from the start. A rule that
+  only makes sense in light mode ("near-white page") is written as its intent
+  ("`background` at the theme's base step") instead.
+
+**VisionSet-specific extension:** **`stage`** — the neutral surround an image is judged
+against in the annotation workspace. It is not `background` and not a generic fill: it
+must shift the perceived colour of a photograph as little as possible while staying
+distinguishable from both the page and a white-bordered asset. It stays in the token set
+as a product-owned semantic role; its usage rules are in
+[`docs/ui/annotator.md`](docs/ui/annotator.md).
+
+**Migration note.** The current implementation still spells several intents as
+implementation-artifact tokens — `primary`/`primary-hover` (the accent), `sidebar`,
+`sidebar-accent`, `sidebar-strong`, `sidebar-muted` (a hardcoded dark rail),
+`disabled`/`disabled-foreground`, `success-hover`, `muted`, `card`, `popover`,
+`destructive`. These are not part of this contract; the token-implementation phase maps
+them onto the aliases above (e.g. the rail becomes surfaces of the dark theme's own
+scale, disabled states become reduced-emphasis readings of existing roles, `destructive`
+becomes `error`).
+
+#### Brand
+
+Robomous coral is **brand identity, not interface semantics**. The logo and wordmark may
+use it; functional UI — buttons, states, progress, focus — uses semantic colour based on
+meaning. There is no counted quota of brand appearances and no rule tying any control's
+colour to the brand; introducing brand colour into a functional control is simply a
+semantic-colour violation, whatever the count.
+
+### Typography
+
+- **Interface text: Geist Sans.** With a real fallback stack, until and unless the
+  implementation phase decides otherwise for offline-first reasons.
+- **Technical values: Geist Mono** — identifiers, hashes, model references, measurements,
+  code-like values, technical metadata. Mono marks *machine-shaped* content; it is never
+  decoration, and prose never wears it.
+- **Semantic roles, not utility soup.** Text styles are named roles; a screen picks a
+  role, never a free combination of size/weight/tracking:
+
+```text
+heading-32  heading-24  heading-20  heading-16     page and section headings
+copy-16     copy-14     copy-13                    prose, descriptions, help
+label-14    label-13    label-12                   form labels, meta, table headers
+button-14   button-12                              control text
+mono-14     mono-13     mono-12                    technical values
 ```
-git grep -nE '(bg|text|border|ring|fill|stroke)-brand' -- frontend
+
+  Exact metrics (size, line-height, weight, tracking per role) are fixed by the token
+  implementation; the roles and their hierarchy are the contract. The default reading
+  size for application UI is the 14 tier; 16 is for prose-first surfaces.
+- **Numbers that change use tabular figures** wherever layout stability matters — stat
+  values, counters, anything a user watches update.
+- One scale. A size or weight that is not a role does not appear.
+
+### Spacing
+
+A 4px-based scale: `4, 8, 12, 16, 24, 32, 48, 64`. 16px is the default layout unit
+inside a surface; 24px separates page sections; 8px groups inline elements; 4px is for
+intra-control geometry. Spacing states *relationship*: things spaced alike are related
+alike, and a one-off gap value is a relationship the reader cannot parse.
+
+### Grid and Layout
+
+- **Prefer intrinsic CSS layout.** Grid and Flexbox, sized by content and constraints —
+  not JavaScript measurement where CSS can solve it, and not fixed widths where a
+  min/max constraint says what is actually meant.
+- **Preserve alignment.** Edges align across siblings; a screen has a small number of
+  vertical rhythm lines, and content snaps to them.
+- **Support content growth.** Text wraps rather than truncates unless the value is
+  re-readable elsewhere; identifiers wrap rather than truncate mid-token; controls are
+  never clipped — a readout yields before a button does.
+- **Prevent accidental overflow.** A container that can scroll declares it; nothing
+  overflows a dialog, a panel, or the viewport as a side effect of long data.
+- Exact page, dialog, rail, and column dimensions are screen-level decisions and live
+  with the product docs ([`docs/ui/product-principles.md`](docs/ui/product-principles.md),
+  [`docs/ui/navigation.md`](docs/ui/navigation.md)) — the foundation constrains *how*
+  layout is done, not each width.
+
+### Radius
+
+A compact scale, assigned by material level rather than picked per component:
+
+```text
+small   6px    chips, inputs, small controls, tiles
+medium  12px   cards, panels, menus, dialogs' inner surfaces
+large   16px   large floating surfaces, modals
+full    pill / circular surfaces: avatars, pills, progress tracks
 ```
 
-(No `\b` — `git grep -E` is POSIX ERE, which has no word boundary; a pattern carrying one
-matches nothing and exits as if the tree were clean.)
-
-Four lines match and **three of them are usages**: the two above, plus the styleguide
-swatch. The fourth is the `--color-brand` comment in `frontend/ui-core/src/styles.css`,
-which states this rule rather than applying it, and which says the same two sites this list
-does. The count is machine-enforced: `tests/scripts/design_tokens.test.mjs` asserts the
-three usage sites on every `pnpm test`, so a fourth site fails the suite rather than a
-reading.
-
-Three stays three however many bars there are, because the fill lives inside the primitive
-and a second caller adds no occurrence of its own — which is exactly what makes the
-invariant checkable by this grep after the change above.
-
-### One filled button per view
-
-Principle 8 says a screen answers "what do I do next?" with exactly one primary CTA. With
-a near-black primary the rule is *visual* as well as structural: a filled button is now the
-loudest thing on a grey page, so two of them compete far more than two coral ones did.
-Sibling actions are the outlined `secondary` variant — `card` fill, `input` border,
-`foreground` ink. A row action inside a table is per-row, never the view's forward action,
-so those are `secondary` too.
-
-The known exceptions, all legitimate: a modal `Dialog`'s confirm button (it overlays the
-page, so it is its own view), the steps of the ingest stepper (only the active step
-renders), and **the annotation editor's paired forward actions**.
-
-That last one is the only place two filled buttons sit side by side, and it is recorded
-rather than tolerated. The editor's top bar carries the primary next-action (`Save and
-next` / `Next`, or `Finish job` on the last frame) in `primary`, and **Save and stay** in
-`success`, immediately to its right. Two filled controls compete when they are two
-answers to *what do I do next*; these are two halves of **one** answer — having finished
-with this frame, advance or persist in place — and a person choosing between them is not
-choosing between two calls to action. Colour is what separates their intent: a second
-near-black beside the first would contend with it rather than pair with it, and the two
-would read as a bar that could not decide. `success` is the only other fill in the
-product, and this is its only filled use.
-
-The count test therefore reads the bar as `bg-primary` exactly once and `bg-success`
-exactly once — still a count, still asserted from both sides.
-
-**The rule is a count, so it is tested as one — in both directions.** A test asserting that
-*the* CTA is present, or that a sibling is `secondary`, passes just as happily with two
-filled buttons on the page; that is the defect #388 was filed for. The enforcement pattern
-is a document-wide sweep — collect every `button.bg-primary` and assert the whole set — which
-catches the zero-filled case as well: an invitation whose destination does not exist, beside
-a header that stood back for it, leaves the view answering "what do I do next?" with nothing.
-Both failures are the same rule violated, counted from opposite sides.
-
-### Status colour
-
-**A status picks an intent, never a colour**, and the intent comes from the three semantic
-tokens above plus neutral. One mapping, product-wide (#391) — before it, the same five
-per-asset states were drawn in three private vocabularies, so `accepted` was green in the
-annotator and near-black in the gallery, and a *skipped* frame was painted `destructive`.
-
-| Family | Token |
-|---|---|
-| Done, settled, succeeded — `annotated`, `accepted`, batch `completed`, ingest `completed`, export `succeeded` — **and the annotation editor's `Save and stay` fill** | `success` |
-| Waiting on a person — `review_pending` | `warning` |
-| Failed — ingest `failed`, export `failed`, a corrupt file, a refusal | `destructive` |
-| Nothing has happened, or a decision was taken and nothing is wrong — `unannotated`, `skipped`, batch `draft`, export `queued`/`cancelled` | neutral |
-| Work is in flight — batch `in_annotation`, ingest `running`, export `running` | `primary` (the near-black action colour) |
-
-Three rules follow from it, and each was a real defect before it was a rule:
-
-1. **`destructive` is for errors only.** A `skipped` frame and a `cancelled` export are
-   *decisions*; painting them red tells somebody who chose an outcome that it went wrong.
-2. **`warning` means one thing: something is waiting on a person.** It is not "in
-   progress" — work in flight is the healthy majority state, and colouring the majority
-   state amber makes a list of ordinary work read as a list of problems.
-3. **"Finished" has one colour.** A completed batch and a completed ingest run are the same
-   fact about two nouns; they read `outline` and `success` respectively until #391.
-
-**The word always rides with the colour.** Colour alone is never a status — the badge
-carries its label, the dot carries the word beside it, and where a dot has no room the
-accessible name and the tooltip carry it (`● annotated · Saved`). A second non-colour
-channel exists on the per-asset dot as well: `filled` / `ring` / `hollow` / `muted` says how
-far along a frame is, so the vocabulary survives a monochrome screen.
-
-The single spelling for the per-asset states is `frontend/ui-core/src/screens/batchState.ts`
-(`PROGRESS_TONE`, `progressDotClass`, `progressCellClass`). Every other family writes its
-own small map beside its own labels, typed against the shared `BadgeTone` union — so a
-sixth colour is a compile error rather than a diff nobody notices.
-
-### Success and the exception that no longer exists
-
-`success` (`#2e7d5b`) is a real token as of #323. v1's documented exception — a hardcoded
-`text-green-600` for the "saved" indicator — is retired with it: there is no longer a
-sanctioned hardcoded colour anywhere in the frontend, and `design_tokens.test.mjs` was
-already refusing one.
-
-It gained two companions when the annotation editor's **Save and stay** became a filled
-control: `success-foreground` (`#ffffff`, the ink on that fill) and `success-hover`
-(`#3a896b`). The hover is derived rather than picked — `primary-hover` lifts `primary` by
-(+12, +12, +16) per channel, and the same deltas applied to `success` give this — so the
-bar's two filled controls brighten by the same amount under a pointer instead of each
-having its own feel. They exist for that one control; a status *ink* still uses plain
-`success`.
-
-## Typography
-
-System font stack (`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, …`), **14px
-base**, line-height 1.6. One scale — reuse it, don't invent sizes:
-
-| Role | Spec |
-|------|------|
-| Page title | 1.5rem / 600 / tracking -0.025em |
-| Section / card title | 1rem / 600 |
-| Body | 0.875rem |
-| Label | 0.875rem / 500 |
-| Meta / helper / timestamps | 0.75rem, muted-foreground |
-| Error text | 0.75rem, destructive |
-
-## Layout
-
-- **App shell**: dark left rail (logo, collapse toggle, Home, Projects, Inference, account
-  avatar at the bottom — nothing else; #58, and #421's decision of 2026-08-08 which
-  supersedes it by adding Inference), bright content area. Rail width 240px, 60px
-  collapsed, 280px mobile — a single source of truth.
-  **What earns a rail entry**: a workspace-level object every project uses, which has
-  nowhere else to live. Model connections carry no project id, so a project tab would
-  state a scope the object does not have. A destination that belongs to one project does
-  not qualify, however often it is visited.
-- **Page widths**: lists/dashboards/detail `max-w-7xl`; forms/settings `max-w-3xl`;
-  centered, `px-4 md:px-6 py-6`.
-- **Dialog widths**: the primitive's default `max-w-lg` for a confirmation or a form of
-  stacked single fields; **`max-w-2xl`** for a form whose fields sit side by side, because
-  `ClassFields`' grid splits on `md:` — a *viewport* breakpoint — so the box must be wide
-  enough for a split it cannot prevent; `max-w-3xl` for a dialog whose content is a grid
-  rather than a form (`FrameGallery`). Three sizes, and a fourth needs a reason written here
-  rather than picked by eye. **Any dialog whose content grows with the data carries
-  `max-h-[85vh] overflow-y-auto`** — `DialogContent` is centred with `-translate-y-1/2`, so
-  one taller than the viewport overflows off both edges and takes its own footer with it,
-  which is not a state a person can recover from.
-- **Page header**: title + subtitle left, actions right, `border-b` below, `mb-8`.
-- **Grids**: cards at `gap-6`, 2/3 columns by breakpoint; 16px is the default layout
-  unit, 24px separates page sections. Detail two-column: `1fr / 320px`, stacking below
-  `lg`. Breakpoints 640 / 768 / 1024 / 1280.
-
-## Navigation rules
-
-VisionSet is an **application**, not a website. Somebody who walks into a sub-view has
-to be able to walk back out of it *from the screen*, without reaching for the browser
-and without knowing the URL scheme. Before **#199** five of the six sub-views offered
-nothing at all and the sixth offered history, so this section exists to keep the rule
-from being rediscovered one screen at a time.
-
-- **Every sub-view declares its ancestor chain, and it is rendered in full.**
-  `navigate(-1)` is not an ancestor: it means the gallery when you clicked a tile,
-  nothing at all on a fresh tab, and one asset at a time after walking forward
-  through a job. Every destination has to be the same however the page was reached —
-  clicked through, pasted, reloaded, or walked forward from a sibling. The
-  destinations live in one `PARENT` table in `app/src/routes.tsx`, because a
-  destination is a fact about the route table and `ui-core` deliberately has no
-  router.
-
-  A single-level control is not enough, and the gallery is why. Its control read
-  `← road-signs` — the *project's* name — while landing on the project's **Batches
-  tab**. Both halves were right: the tab is where somebody leaving a batch belongs,
-  and naming the project is the most one level can say. Only the chain says both,
-  and it reads `Projects / road-signs / Batches`.
-- **Ancestors only. The current page is the `<h1>`, never a crumb**, which is also
-  why no crumb carries `aria-current`. A breadcrumb repeating the heading beneath it
-  spends a line telling somebody what they are already reading.
-- **A tab in the query string is a level.** #171 put tabs in the URL because
-  somebody links to one and returns to it — that makes it somewhere you were, so it
-  is somewhere you can be sent back to. It is what the gallery's third crumb *is*.
-- **The affordance names its destinations.** "Back" alone is a promise about history;
-  "Projects", or a project's own name, is a promise about structure — the one the
-  control can keep. A name that has not loaded yet falls back to the noun
-  (`parentLabel`) rather than to nothing, so the control does not change width under
-  a cursor that is already aiming at it. Each crumb truncates with its full label in
-  `title`, and the row never wraps to a second line at any width.
-- **Placement follows the pane.** On a padded page it is `patterns/Breadcrumb.tsx`
-  directly above the page header: meta-size, muted, `/` separators and no arrow,
-  pulled left by the gutter (`-ml-1`) so the first crumb aligns with the `<h1>`
-  beneath it. On the full-bleed editor there is **no chain** — the way out is the
-  first control in the 44px top bar, a 36px ghost `ArrowLeft` meaning *up*, because
-  that bar's left zone is a `minmax(0, 1fr)` track already truncating to hold the
-  navigation cluster on the bar's geometric centre, and crumbs there would be paid
-  for out of the frame's identity readout.
-- **Below `lg` the same chain collapses to `← <immediate parent>`**, which is the
-  shape the single-level control had. One component, one items array, one set of
-  destinations, two presentations — and the collapse is CSS on one DOM node per
-  crumb, never a second list, so nothing is read twice by a screen reader and the
-  two presentations have nowhere to drift apart.
-- **A screen takes it as optional callbacks, never a route.** The same rule every
-  forward edge follows: `ui-core` may not import a router, so a host that has nowhere
-  to send anybody renders no control rather than a dead one. A screen omits a level
-  it has no callback for rather than rendering dead text, which is what makes an
-  empty chain mean *nothing to offer*. The host spells every URL; the screen supplies
-  every label, because a project's name is behind a query `ui-core` makes and
-  `routes.tsx` does not fetch.
-- **The rail is for top-level destinations only.** Per-screen return navigation never
-  lives on it — that is what lets it name where it goes, and what keeps the rail the
-  five things `## Layout` gives it. A rail destination therefore has no breadcrumb of
-  its own, for the reason a tab has none: the rail *is* its way out, and a second
-  answer to "where am I" inside the pane would contradict it.
-- **The browser's Back button stays correct, and is never the only way out.** Nothing
-  here replaces it; a `replace` navigation is still right where a change is a view of
-  the same resource rather than a place (#171's tabs).
-- **A control that means "show me more of what I am already in" does not navigate.**
-  The annotation page's arrow means *up*: it exits to the batch, saving first, and
-  that is legitimate. Its grid button means *switch frames*, which is the `‹` / `›`
-  navigator with pictures — so it opens a **gallery overlay inside the editor** and
-  the URL does not move (#390). The two used to share a destination on the reasoning
-  that the annotator's parent *is* the grid; the coincidence was real and the
-  conclusion was wrong, because going up and looking at your own frames are
-  different intentions and only one of them is a reason to leave. The overlay is a
-  switcher and nothing else: no batch actions, no selection, no route change. The
-  batch view stays the home of batch operations.
-- **Not everything selectable is a place.** A tab is in the query string (#171)
-  because somebody links to it and returns to it; the schema version somebody is
-  glancing at (#232) is component state, because it is a lens on the tab they are
-  already in. The test is whether the thing survives being pasted to a colleague as
-  a destination — if the answer is "they would want the current one instead", it is
-  view state and the URL should not carry it. Getting this wrong in the other
-  direction is worse than it looks: `ui-core` has no router, so every URL-borne
-  choice has to be threaded through the host as a prop and a callback.
-
-## Tabs
-
-**One shape** (`primitives/Tabs.tsx`) — page sections, GitHub's repository nav. A row on a
-full-width `border` hairline; the active tab carries a **2px `primary` rule sitting on
-that hairline** plus `foreground` text; an inactive tab carries no border, no fill and no
-shadow, and gets a `muted` background on hover or focus. The inactive tab keeps the same
-2px border at `transparent`, so selecting one does not shift the row.
-
-There used to be two, chosen by a `variant` on `TabsList` which every trigger inherited.
-**#182** made this one the default: the original was a segmented control, and on the
-project view that put three pressed-looking buttons directly under the page's real
-buttons. **#368** removed the other — `segmented`, the annotation panel's
-**Objects | Labels** switch — along with the switch itself, when class selection moved to
-the top bar and the panel became one Annotations view. With one caller gone there was no
-second shape, so the `variant` prop, the context that carried it and the `data-variant`
-attribute went too: three pieces of machinery describing a choice nobody has.
-
-**The space between a tab bar and its content belongs to `TabsContent`, and to nothing
-else.** It is `mt-3` (12px), one declaration — and a consumer must not add a gap of its
-own. `AnnotatorPanel` wrapped this margin in a `flex flex-col gap-3` and the two added,
-floating the tabs 24px above the panel they switch (**#188**). The primitive owns it
-rather than the consumers because that is the direction nobody can forget: a `Tabs` which
-is not a flex column at all still spaces correctly. Asserted by measurement — the
-styleguide specimen and the project view — rather than by a class string, since a class
-assertion would have seen both rules and been satisfied.
-
-**The active underline is `primary`**, the same near-black as a filled button, so the
-section you are in looks like the rest of the interface rather than like an advertisement.
-The active label is `foreground` at the base `font-medium`; inactive labels are
-`muted-foreground`. There is deliberately **no extra weight bump** on the active tab —
-colour and the rule already carry it, and a second signal reflows the row's metrics for
-nothing. (Two earlier `Tabs.tsx` docstrings argued over whether this rule could be orange.
-#323 settled it by removing the orange: `primary` is not the brand any more.)
-
-Focus is **not** styled here at all: `styles.css`'s base layer gives every
-`:focus-visible` element a 2px `ring` outline, and an outline is painted outside the box,
-so it never depended on the segmented chip's fill. The trigger adds
-`focus-visible:bg-muted` only so the ring encloses a fill rather than the page.
-
-## Home
-
-The workspace's front page, and the rail's first entry. It was a redirect to the project
-list until there were numbers worth showing; what makes it a page rather than a second
-list is that it answers a different question. A list answers *what exists*. Home answers
-**what is waiting on me, and where do I carry on** — which is a question no single project
-can answer, because the state that matters is spread across all of them.
-
-It carries nothing project-scoped. No class distribution, no samples, no schema state:
-those belong to the project's own Overview, and a second copy here is the drift this
-document exists to prevent. Every row is a *pointer*, and pressing it goes to the screen
-that owns the thing.
-
-**Two states, and the first one is gone for good.** A workspace with no projects renders
-one invitation and nothing else — a headline, a line of body, the filled **Create
-project**, and three quiet cards naming the cycle (ingest, annotate, release) with no
-controls on them. The cards are there so somebody can see what the tool does before
-committing to it; a button on each would be three more things competing with the one that
-matters. Once a project exists this state never returns, and the dashboard renders with
-real zeros wherever the numbers are genuinely zero.
-
-**Layout** is the two-column detail contract, `1fr / 320px`, stacking below `lg`. The main
-column is the resume card, then what needs attention, then a short list of recent
-projects. The 320px aside is four stat cards in a 2×2 grid — projects, images,
-annotations, releases — and beneath them the activity feed.
-
-**A section with nothing in it is not rendered.** Not as a placeholder, not as a zero, not
-as "nothing here yet" — absent. A dashboard whose every section is an apology has taught
-the reader nothing and taken a screen to do it. The stat cards are the deliberate
-exception: a count of zero is a *measurement*, and four cards that came and went would
-make the aside jump on every visit.
-
-### Continue where you left off
-
-The card names a project, a batch, a count in tabular figures, and a picture of the frame
-it would open. It holds the view's one filled button.
-
-**It is ranked by when somebody last worked the batch.** That is the only work-dating
-timestamp in the storage format, and it exists for this. Batches nobody has worked since it
-became recordable rank behind every batch that has one, ordered among themselves by how far
-through they are — which is the whole population of a workspace created before the stamp
-existed, since it was added without a backfill and a moment that was never recorded cannot
-be invented. Such a workspace therefore behaves as it did before and converges to real
-recency the moment anybody uses it. A batch still has no age of its own: nothing dates its
-creation or its state changes, so *the oldest untouched batch* remains underivable.
-
-**The label is load-bearing, and it is the wire that picks it.** The card renders three
-promises out of one slot: **Continue annotating** when the batch has a frame nobody has
-labeled, **Review annotations** when the labeling is done and frames are waiting on a
-reviewer, and **Open batch** when it needs neither and there is no frame to open. The first
-two go to the editor and the third to the gallery, because a button claiming a frame that
-does not exist would land somewhere empty.
-
-The two editor promises are the same destination, and that is the point rather than a
-shortcut: a frame awaiting review opens read-only with **Accept** and **Return to
-annotator** on it, so the reviewer and the annotator are one screen wearing what it is
-looking at. Under *Review annotations* the count line changes with the label — `k waiting on
-review` rather than `n / m annotated`, since how much of the batch is labeled is not the
-number anybody came for.
-
-**Which of the three applies is decided by the kernel and carried on the response.** The
-order between them is a judgment about what somebody should do next, not a fact the rest of
-the response restates, and a judgment spelled once in the kernel and again in the browser is
-one that drifts. Contrast the first-run state, which is deliberately *not* a field: that one
-is a count the response already carries.
-
-### Needs your attention, and activity
-
-Attention rows are one line each: a batch holding frames awaiting review, a background job
-that failed, a background job still running. A review row links to its batch. **A job row
-links nowhere and says so by not being a link** — a background job names an ingest run or a
-release in its payload, never a project, and no screen shows one. That is the rule for a
-section whose consuming surface does not exist yet, and inventing a destination would be
-principle 9's dead button with a friendlier label.
-
-Activity is a projection over timestamps that already exist, never an event log, capped at
-about eight and newest first. Two of its four kinds say less than they might, and the copy
-must not overstate them: an ingest row reports *the last data that arrived in this
-project*, not one run finishing, because an ingest records no time at all; and a schema row
-reports a version being **created**, because which version is active is derived — it is the
-highest — so there is no activation to date.
-
-### The one filled button, in every state
-
-Principle 8 is a count, so Home answers it in every state and there is never a second.
-First run offers **Create project**. A workspace with somewhere to carry on offers whichever
-of **Continue annotating**, **Review annotations** or **Open batch** the resume card
-resolved to, and the header's own New project steps back to `secondary` behind it. Only a
-workspace with nothing open at all offers **New project** as the filled one — when every
-batch is finished and nothing is waiting on a reviewer, starting the next piece of work
-genuinely is what comes next.
-
-That last state is the one to keep honest. It used to absorb a workspace whose only
-outstanding work was a review, which meant the page answered "what do I do next?" by
-suggesting more work rather than by naming the work already waiting.
-
-The first-run CTA opens the **same dialog** the project list's button opens, rather than
-navigating to the screen that carries it. A filled button labelled *Create project* that
-only moved somewhere else would promise an action it does not perform.
-
-## Project surfaces
-
-The project view is the face of a project, and principle 6 is the rule it kept failing: it
-opened on the schema editor, which is configuration, and a schema renders the same for a
-project with nothing in it and a project with a hundred thousand images. This section is
-what #207–#213 build against.
-
-### The project header
-
-Four lines and two buttons, in this order:
-
-1. The breadcrumb (`Projects`, this page's whole chain), per **Navigation rules**.
-2. The project name, at the page-title role.
-3. The description **if there is one**. If there is not, render *nothing* — the string "No
-   description." spends a line telling somebody about a field rather than about their
-   project, which is principle 6 in miniature.
-4. Metadata chips, left to right: task type, sensor modality, active schema version
-   (`v1 active`), last ingest (`Ingested 2d ago`).
-
-**A chip with no data is omitted, never rendered as a placeholder.** Half of these have no
-source on the wire today — `ProjectOut` carries `id`, `name` and `description` — so a
-project shows the chips that can be answered and no others. Inventing a field to fill a
-chip, or rendering `Unknown`, is the "No description." mistake with a border around it.
-
-Actions are right-aligned: one **primary CTA**, one **secondary**, and an overflow menu
-(`⋯`) for the rest. Never more than two visible buttons plus the overflow. On the project
-page the primary is **Annotate**, because principle 8 asks what the user came to do and the
-answer is never "rename this".
-
-**Annotate has three shapes, and the cost of the choice tracks the ambiguity.** With no batch
-open for annotation there is nowhere to send anybody, so the button is absent and Ingest takes
-the filled slot — principle 9, rather than a disabled control that never says what would
-enable it. With exactly one, it jumps straight there. With two or more it reads `Annotate ▾`
-and opens a menu of those batches, each row carrying the batch name, its remaining `N to do`,
-and the schema version it is pinned to. The chevron is not decoration: a button that opens a
-choice must not be shaped like one that jumps. The pinned version earns its place in the row
-because approval fixes it and nothing later moves it, so which batch you pick decides which
-schema you annotate under — a consequence that is invisible everywhere else on the page.
-Never a silent default, and never one remembered from last time: a control's destination may
-not be a function of session history.
-
-### The first run
-
-**The Overview's first-run region is driven by the project's state, and renders exactly one
-invitation.** No classes and no images invites the classes (with the other order named
-beneath it as prose, because both are legitimate); classes and no images invites the ingest;
-images and no classes invites the classes again and says annotation opens from the first
-approved batch; a project with both gets no invitation and is the dashboard. **It guides and
-never gates** — Ingest and Schema stay independently reachable throughout, and where the
-invitation holds the page's one filled button the header steps its own Ingest back to
-`secondary`.
-
-**The four-station onboarding checklist is retired (2026-08-07, #388), reversing #289.** It
-was not made smarter or better-sequenced: a project three seconds old showed three
-invitations at once — a filled header Ingest, a checklist whose active step said *labels*,
-and an outlined Ingest in the empty state — so whichever a person followed, the page was
-also telling them to do something else. Dismissibility was the answer to "onboarding a
-person has read is noise"; it is not an answer to a contradiction met before there is
-anything to dismiss. The road is the tab bar.
-
-### Numbers
-
-- Stat values use **tabular figures** (`font-variant-numeric: tabular-nums`), so a number
-  that updates does not shift the ones beside it.
-- Counts ≥ 1000 carry locale-aware thousands separators. One shared helper, not a call-site
-  decision — `6431` and `6,431` appearing on the same screen is how that goes wrong.
-- Relative times under 7 days (`2d ago`), absolute beyond (`Jan 14, 2026`).
-- A percentage derived from a zero denominator is `0`, never `NaN` and never hidden.
-
-### Versioning is ambient, not modal
-
-Schema version state is a **persistent status line** — `Version 1 active · unsaved changes
-create v2` — and not a tooltip, a dialog, or a disabled save button. The user should never
-have to press something to discover what pressing it would do.
-
-Its corollary, from principle 9: **Save version is always enabled.** Pressing it with no
-changes shows a toast and issues no request. The editor it replaces rendered a permanently
-grey button on a project with nothing to save, which told the user their schema was broken.
-
-### Destructive actions state their blast radius
-
-A confirmation dialog names what will be destroyed, counted: *"Deletes the class and 4,372
-annotations across 3 versions."* A dialog that asks "are you sure?" without saying what
-`yes` costs is not a confirmation, it is a speed bump. Where the count cannot be obtained
-accurately, the action does not ship with a dialog that guesses.
-
-### Components
-
-Presentational contracts, all in `ui-core`, all data-only — no fetching, no router:
-
-| component | contract |
-|---|---|
-| `StatCard` | muted meta-size label above a large value, tinted surface, **no border**. Used in grids of 3–4. Optional context line under the value. |
-| `DistributionBar` | one row of a bar chart: swatch · fixed-width label · proportional bar in the class colour · right-aligned count. **All bars in one chart share a single max-value scale.** |
-| `ClassListRow` | swatch + name + a `geometry · count` secondary line. Selected = tinted background + 2px left accent rule, covering the row's full height whether it takes one line or two. The whole row is the click target and a real `<button>` — **except** when it carries shape chips, which are press targets and cannot nest inside a button: that row is a `role="group"` with an inner name button, addressed by the same `-name` handle in both markups. A row carrying a `refusal` never takes the group form, because only the button can be `disabled`. |
-| `EmptyState` | icon + a headline naming the space + one line of body + a verb-first CTA. Never a bare "No items". |
-| `ThumbnailGrid` | square tiles, 6px gap, `sm` radius. The last tile becomes a `+N` overflow linking onward. Missing thumbnails show a photo icon on `muted` — **never a broken-image glyph**. |
-| Chip | `primitives/Badge.tsx`, which already is one. It gains variants; it is not reimplemented. |
-
-**Class colour is data, not chrome.** It appears as a small swatch or a thin bar and never
-floods a card or a row — that is the accent rule (principle 3) applied to a colour the
-*kernel* chose. The single derivation lives in `frontend/ui-core/src/palette.ts`
-(`classColor`, schema colour first, else a name hash); a second path is what #162 was.
-
-**A geometry picker groups its options by category, and the category is presentation only**
-(#375, 2026-08-07) — the kernel takes no category concept, because "Robotics and AD" is a
-market segment and the domain does not hold one. The single map is
-`frontend/ui-core/src/data/geometryCategory.ts`, declared total over the generated
-`GeometryType` union so an uncategorised geometry fails the build rather than falling
-quietly out of a list; headings are non-selectable `SelectLabel`s and a category with
-nothing under it renders none.
-
-**An option that is an identifier plus the facts about it takes two lines** (#472,
-2026-08-09) — the identifier at the label role, the facts beneath it at the meta role in
-`muted-foreground`. It is `SelectItem`'s `meta` prop, so the closed trigger shows the same
-two lines the open list does; the trigger is `min-h-9` rather than `h-9` and grows to fit,
-which leaves every one-line select on the contract's 36px. **Nothing truncates**: an
-identifier cut off in the middle is not an identifier, so a long one wraps. The specimen is
-on the styleguide page.
-
-**Indeterminate progress renders as prose, never as a bar** (#494, 2026-08-10). `Progress`
-draws an indeterminate value as an empty track, and an empty track reads as *0%* — a lie in
-the one case where the truth is *this is going, and nobody can say how far*. So a run whose
-total is unknown gets the sentence and no bar at all; the bar appears when there is a
-fraction to draw. Giving the primitive an indeterminate animation would change this rule,
-which makes it a design decision and not a screen's to take in passing.
-
-### An indicator appears at once and leaves slowly
-
-**A wait is reported as soon as it starts, and once reported it stays for at least 250ms**
-(#541, 2026-08-11, amended 2026-08-12). Work that has begun and shows nothing is the state
-in which *working* and *broken* look alike, so the trigger is the request leaving, not the
-request having been out a while. The floor is the asymmetry: appearing is free, and
-disappearing after two frames is the glitch. Where a wait has a second threshold worth
-crossing, what appears is **prose**, never a second indicator — the no-bar-over-empty-track
-rule above, applied to the same problem from the other end.
-
-This supersedes a first attempt that suppressed the indicator for 200ms, on the theory that
-a fast answer would beat it and nothing would flash. It is recorded because the reasoning
-was sound and the premise was not: on a real machine the work in question never finished
-inside the window, so the delay suppressed nothing and bought a second state to hold. **A
-threshold that hides a state needs evidence that the state occurs**, and the place to get
-that is a real machine rather than an argument about perception.
-
-The worked example is the annotation editor's suggest tool (`docs/ui.md`): the panel says
-`Looking at that…` from the moment the request is dispatched, and past 1.5s adds a sentence
-saying that the first click on a frame is the slow one.
-
-**A wait is reported in one place, and never at the cursor** (#557, superseding #541's
-second surface). The suggest tool also drew a ring at the click point and put a busy cursor
-on the canvas; both were removed. An indicator sitting on the picture, next to the pointer,
-reads as the machine having *seized* rather than as work in progress — it is in the way of
-the thing being looked at, and it moves with the hand. The card is out of the way, says the
-same thing in words, and is where every other answer about this tool already appears. Two
-surfaces reporting one wait also had to share one clock to avoid disagreeing; one surface
-has nothing to disagree with.
-
-**An indicator is never coral.** The brand's two sites are above, and a spinner is not a
-third — a thing that appears on every slow click would spend more of the brand than the
-wordmark does. Quiet neutrals, at low opacity, at the place the person is already looking.
-
-### Lists and filtering
-
-Any list that can exceed ~20 rows carries a filter input. Filtering is client-side and
-instant, matches a name substring case-insensitively, and never hides the count of what it
-filtered out.
-
-### A list sectioned by what its rows enable
-
-Where the rows of a list are things a person configures so that *something else* becomes
-possible, the list is sectioned by the ability rather than sorted by the row — a heading
-naming the ability in a user's words, one line of prose naming the surface that consumes
-it, the rows serving it, and the section's own empty state. The Inference dashboard is the
-specimen: a flat table of names, kinds and model ids showed real data and answered none of
-*what can I do in the app with this?*
-
-Four rules make it honest, and each one exists because its opposite is a lie a screen can
-tell:
-
-- **The sections come from the data's own vocabulary**, never from a client-side reading of
-  what a row is. On Inference that is `capabilities`, which the server derives from the
-  model's weights.
-- **A section with a consuming surface invites; one without it only describes.** An ability
-  the product cannot yet use gets its heading, its prose and no control at all — a CTA
-  there is principle 9's dead button wearing a friendlier label, because what is missing is
-  the surface rather than the row.
-- **Nothing declared is invisible.** A value the build has no copy for gets a generic
-  section built from the value, and a row declaring no ability at all gets one too. A row
-  under no heading is a row nobody can act on.
-- **Section CTAs are `secondary`.** The view's one filled button stays in the header;
-  otherwise a page of empty sections is a page of competing primaries.
-
-A filter crossing such a list empties sections it does not match, and an emptied section
-says *nothing here matches* rather than showing its invitation — what somebody typed is not
-an occasion to invite them to configure something.
-
-### Copy
-
-- No exclamation marks. No "successfully". No "please".
-- An error is **what happened plus what to do**, one sentence each. The API's error contract
-  already separates the two (`docs/api.md`); the UI does not merge them back together.
-- An empty state is an **invitation**, not an apology: "Ingest your first batch to see stats
-  here", never "Nothing here yet".
-- Sentence case everywhere — buttons, tabs, labels, headings. "Add class", not "Add Class".
-
-## The annotation workspace
-
-The page the reference design shows (#56), with measurements verified in v1's source:
-
-- **Top bar**: one 44px (`h-11`) row on `card` with a `border-b`, 32px (`h-8`) controls,
-  in **three zones** since #368, regrouped by #416 — *where you are*, *what changes the
-  frame*, *the session*.
-
-  | Zone | Contents |
-  | --- | --- |
-  | Left | back · pinned `v{n}` badge · the frame's identity as a label (the content-hash head — there is no filename on the wire) · the frame microtext `● annotated · Saved` |
-  | Centre | the **navigation cluster**: `[⊞] [‹] n/m [›] │ [Skip] [Save and next] [Save and stay]` |
-  | Right | `n / m annotated` · the review move (outline) · overflow `⋯` |
-
-  **Everything that changes the picture on screen is in the centre cluster, and nothing
-  else is** (#416). The gallery and `‹` `›` used to sit at the far left beside the back
-  arrow, and **Skip** and **Save and next** at the far right beside the overflow: two
-  motion clusters at opposite ends of a 44px row, same destination, different meanings,
-  with nothing on screen to say which was which. Adjacency is the explanation. One
-  `h-5 w-px` divider separates the two sub-groups — **browse | resolve** — so the
-  difference between *look at another frame* and *finish this one* is a hairline rather
-  than something learned.
-
-  **The class field is not on the bar** (#420). #368 put it here and #416 gave it a 192px
-  reservation in the middle of the cluster; it is a list in the side panel now, and the
-  bar is navigation only. The width it gives back is what pays for the right zone's two
-  controls being visible buttons again at every supported width.
-
-  `‹` `›` **browse**: they move without settling progress, under the same save-first
-  guard back and the gallery use. `n/m` renders between them in `tabular-nums`, so
-  walking a job does not shuffle the arrows under a cursor that has not moved.
-
-  **The centre is anchored on the bar's geometric centre**, not balanced between two flex
-  spacers: the header is a `1fr auto 1fr` grid, the two flexible tracks take an equal
-  share of what is left by definition, and the side tracks yield — a label truncates,
-  never a control. Two widths inside the cluster are pinned so it is the same size on
-  every frame: the resolution pair's `min-w-27` (`Skip` is 104px and `Un-skip` 96px) and
-  the flow verb's `min-w-36`, the widest of `Next` / `Save and next` / `Finish job` /
-  `Finished`. The cluster's controls therefore hold one screen position through every
-  frame state.
-
-  **Equal halves is what a centred bar costs, and the right zone is the heavier side.**
-  It is measured, not reasoned about. With the class field on the bar, chromium at 1440
-  gave left 290px, cluster 616px, right 460px — each side offered 382px against a right
-  wanting 460, so #416 had to send the two reabsorbable controls to the overflow one
-  breakpoint early. With the field in the side panel (#420) the cluster is **423px** and
-  each side is offered **462px** against the same 460px of demand, so both breakpoints are
-  back where they were. It clears by a pixel, which is why the readout that gives way is a
-  readout: `n / m annotated` truncates, and no button is ever clipped.
-
-  **The filled slot is the flow verb** (#383). After finishing a frame the right move is
-  *this one is done, show me the next* — and until #383 that had no button at all: the
-  navigator's `›` is chrome rather than a verb, so **Skip** was the most prominent thing
-  to press on a frame somebody had just annotated. **Skip and Save and next are
-  siblings** — two ways to resolve this frame, skipped or annotated, both advancing — and
-  neither ever collapses into the overflow.
-
-  `Save and next` is `go(1)`: the same save-first advance the navigator has always used,
-  so there is one save pipeline and one place principle 10 is enforced. It reads **`Next`
-  when no save will happen** — an untouched frame — because the button never promises a
-  save it will not perform, and once the *job* is closed it is **not rendered at all**
-  (#439): there is no save-first advance to offer on any frame of it, and `›` is what
-  moves there. See *The read-only mode* below.
-
-  **On the last frame `Finish job` takes the filled slot**, in place: `Save and next` is
-  not rendered there, and Finish job is not rendered anywhere else (#416). There is
-  nothing to advance to, and finishing is what the job is for. It used to render on every
-  frame, greyed with nothing attached for as long as one frame was unannotated — a bare
-  disabled control at 0 of 48, which principle 9 forbids. Where it does render it carries
-  why it cannot be pressed. The filled slot is therefore contended by nothing — which
-  frame you are on is this page's own arithmetic, not a declaration anything else can
-  co-claim — and the consequence is worth stating: `complete` is reachable from the last
-  frame only.
-
-  **The review move is an outline control**, chosen from the frame's own
-  `allowed_actions`: `submit_for_review`, else `accept`. The two are mutually exclusive by
-  construction — the kernel offers the first only from `annotated` and the second only
-  from `review_pending`. **`complete` is deliberately not in that list**: it is the
-  *job's* action, and it co-declares with `submit_for_review` on the commonest path there
-  is (an annotated frame in a job whose every frame is settled), so ranking them against
-  each other would hide Finish job exactly where most jobs end. Submitting carries a
-  tooltip saying what it means, because this product has **no annotator identity**
-  (cf. #282) — a submitted frame is marked for a review pass, not routed to a person.
-
-  **Save and stay is the second half of the forward gesture, and it sits beside the
-  first.** #368 removed the explicit save on the grounds that it duplicated an automatic
-  behaviour — ⌘S saves, navigating saves, settling saves — and dogfooding showed what that
-  missed: the chord is invisible, and the overflow put the one press meaning *store this
-  now, without going anywhere* two clicks from the work. #383 brought it back as a ghost
-  in the right zone, which fixed the reachability and left the reading wrong: *advance*
-  and *persist in place* are one decision read two ways, and they were a bar apart with
-  the second of them the quietest control on the row.
-
-  It is now the third member of the resolve group — `Skip · [primary next-action] · Save
-  and stay` — **filled in `success`**, which is the recorded exception to *one filled
-  button per view* above. It keeps the frame verbs' lifetime rather than the mode's: a
-  closed batch or a finished job has nothing to save on any frame, so it leaves with Skip
-  and the flow verb; inside a working job it holds its slot, disabled, so the cluster does
-  not change width as somebody walks a mixed job.
-
-  **Reabsorption order when the bar runs out of room**: `Save and stay` first (below
-  `xl`), the review move second (below `lg`), into the overflow; the Skip/Save-and-next
-  pair never collapses. Each reabsorbed control carries the exact inverse of its button's
-  breakpoint, so it exists in exactly one place at any width. The `n / m annotated`
-  readout has no overflow row and needs none — it truncates, which is what a sentence may
-  do and a button may not.
-
-  **Hotkey chips go on the ghost and outline controls and on nothing else** — `X` on
-  Skip, from `core/input/bindings.ts`. A chip is a muted box on a bordered ground, which
-  is a *lighter-than-the-surface* treatment: inside a filled control it inverts into a
-  dark box on a dark ground and reads as a smudge rather than as a key, so neither the
-  flow verb (#385) nor Save and stay carries one. Neither chord is the loser. `⌘S` is
-  taught by Save and stay's tooltip — the tool strip's own pattern (`Box (B)`) — and
-  `enter` is the one key with two meanings, the polygon ring close while a shape is in
-  progress and *finish the frame* otherwise. Both are in the shortcut sheet, which derives
-  its rows from the live registry rather than from a hand-written table.
-
-  **In-editor messages have one surface, top-right of the stage** (`EditorNotice`). Every
-  sentence the editor floats over the picture goes into one column inset 16px from the
-  stage's top and right edges: a suggest session, a refused save, a refused progress move,
-  and a batch or job that could not be opened. They were four placements in three
-  treatments — two destructive badges inside the top bar's microtext, a full-bleed strip
-  under the header, and the suggest card bottom-right — so *where* a sentence appeared
-  depended on which mutation produced it. Top-right is the corner nothing else occupies:
-  the tool strip is top-left, the object counter bottom-left, and the zoom cluster
-  bottom-right, which the suggest card had been clearing with a hard-coded offset. The
-  column is a stack, most-blocking first, because more than one of those can be true at
-  once. Its width is `max-w-md` and its body wraps mid-token — a model reference is one
-  unbroken string and **no fixed width guarantees the next one fits**, so wrapping is the
-  invariant and the width is comfort.
-
-  The top bar keeps the frame microtext `● annotated · Saved`, which says *where the work
-  is* and has three readings, not four: after a refused save the honest answer there is
-  `unsaved`, and the reason is a sentence in the notice column.
-
-  The frame microtext replaces the dot-with-a-tooltip: the word is on the bar beside the
-  save state, because **status is never colour alone** and a tooltip is a place a word
-  goes to not be read.
-
-  The reference draws three more controls between the navigator and the save state —
-  version select (GitBranch), create-branch (GitBranchPlus) and **Merge** (GitMerge).
-  **They are not rendered**, because the model they operate does not exist: the
-  branch-and-merge question was settled on 2026-08-10 as superseded by the batch, review
-  and release model the product already has (cf. #127). They were drawn disabled
-  until 2026-08-05 to hold the design's shape, which principle 9 forbids — the only
-  honest tooltip for them is "this feature does not exist", and that is not an
-  explanation of what would enable the button.
-- **Classes region** (#368 as a top-bar field, #420 as the panel's upper region): where
-  class selection lives. It was the side panel's Labels tab, then a `Combobox` in the
-  centre of the top bar, and it is a **list** now — because what is being chosen between
-  is the ontology, and a picker keeps all of it one click away, so the answer to *what can
-  I draw here* was never on screen. Rows carry swatch · name · geometries · hotkey badge, in
-  the **schema's authored order and only that**: a persistent list that reordered itself
-  by recency would move rows under the cursor, and the digits are schema positions, so a
-  recency-ordered list would print `3` against the row sitting first. `c` focuses its
-  filter, Enter takes the first match, digits 1–9 activate directly, and the derived tool
-  follows the class as it always has. When nothing matches what was typed the last row is
-  `Create class "<text>"`, which opens the add-a-class dialog on that name; an empty schema
-  renders an invitation instead of an empty list. **It shows the drawing class and never
-  follows the selection** — re-classing an existing annotation is an object row's menu, a
-  different question about a different object. On a frame nothing can be drawn on the list
-  still renders — which classes exist stays true there — with every row disabled *and
-  carrying why*, which is principle 9 rather than a grey box.
-
-  **The drawing class's lifetime is the job**, not the frame: it survives moving to the
-  next asset, because somebody labelling one class across a clip picks it once, and it
-  survives a re-pin, which is what makes "you are drawing with the class you just made"
-  a promise the page can keep. It stops at the job's edge, the same scope the clipboard
-  has (#123) and for the same reason — a paste and a drawing class both belong to one
-  pinned schema.
-
-  **Every row's shapes are chips, and every chip is a press target.** A class accepts a
-  *set* of geometries, so arming one no longer picks the shape — and the only place that
-  answer used to live was the tool strip at the far left of the canvas while the class was
-  chosen on the right: one decision split across the width of the picture, in a loop
-  repeated hundreds of times a job. One chip per **drawable** geometry, labelled with the
-  geometry **word**. Glyphs were tried and reverted: a square, a spline and a waypoint node
-  are not self-describing at chip size on the one row whose job is telling shapes apart,
-  and the strip can afford them only because it is five controls learned once.
-
-  What a press does depends on the row, and the two readings are one rule — *this class,
-  this shape*:
-
-  - On the **armed** row the active chip is lit and pressing another switches the tool and
-    **never the class**, which is the same retarget rule the strip holds. Changing shape
-    must not move somebody's labels to a class they did not choose.
-  - On an **unarmed** row no chip is lit — a chip drawn as chosen on a class nothing is
-    armed to would claim a state the canvas is not in — and pressing one arms the class
-    *with that shape*, in one press where it used to be two.
-  - Pressing the **name** arms the class with its first drawable shape.
-
-  The cost is that a row carrying chips is a `role="group"` with an inner name button
-  rather than one row-wide `<button>` — HTML forbids interactive descendants inside a
-  button — and the `-name` handle addresses that button in both markups. A row carrying a
-  **refusal** never picks: it falls back to the plain button, the only one that can be
-  `disabled`, so principle 9 stays *explained and inert*.
-
-  Geometry words are **display labels, never wire values** — `box`, not `bbox`; `tag`, not
-  `classification_tag`. One map, `GEOMETRY_LABELS`, shared with the tool strip, which
-  capitalises at its own control; lowercase, because the same word is read as a chip in a
-  row and inside a sentence. A set joins with `·` wherever it is still spelled as words.
-
-  **What gives way, stated**: the row's *height*. The chips wrap beneath the name, so a
-  long name gets the whole first line — and they stay **right-aligned**, in the same column
-  every unwrapped row's chips sit in. A wrapped line that started under the name would read
-  as a different kind of row and break the one vertical edge the list is scanned down. The name gave way once, then the shape list did; neither is available now that each
-  shape is a control, because truncating a control is worse than truncating a label. A row
-  is therefore `min-h-9` rather than 36px exactly, and the classes region absorbs the
-  difference in the scroller it already has — see the height rule above.
-
-  **A class that declares only `classification_tag` is not in this list at all.** It has no
-  canvas gesture; the Tags section is where it is assigned. It is also excluded from the
-  count the height rule reads, so it does not size a region it has no row in.
-- **Pinned version badge** (#229, made an answer by #368): `v{n}` in the left zone names
-  the version *this batch is judged against* — not the project's active one, since #229
-  made the pin movable. Pressing it opens a small panel that says whether that is still
-  the current version and, when it is not, **what arrived since**, in the kernel's own
-  words for the change. Nothing about the active version is fetched until it is opened:
-  the editor is judged against the pin, and a page that read the active version on
-  arrival would be one refactor from offering classes the API then refuses. A hand-built
-  disclosure rather than a Popover, for the `Combobox`'s reason — the annotator reads the
-  keyboard off its own root, so focus has to come back to the canvas.
-- **Add-a-class dialog** (#233, made a session by #368): **one sitting is one published
-  schema version.** `Create and add another` (⌘↵) banks the class and clears the form;
-  the primary publishes everything banked plus whatever is still in the form, so nobody
-  has to press *and another* before finishing. The banked classes show as chips that can
-  be taken back out, the auto-written description names them all, and the primary says
-  how many it will publish (`Add 3 classes`). Opened from the class list's create row it
-  starts on the name that was typed; opened from the tool strip's `+` or the region's own
-  `+` it starts empty,
-  because that press means "I want a class", not a particular one. **A name the published
-  version already declares is an offer, not an error** (#584): the dialog says what that
-  class accepts today and what publishing would add, and the primary reads `Add polygon to
-  "sign"`. It carries the existing class's colour and attributes, so a form opened to make a
-  new class cannot quietly overwrite what the old one declared. A name typed twice in one
-  sitting stays a refusal, because both are being written now and merging them would be
-  guessing which was meant. When it lands, the
-  **last** class written becomes the drawing class and a toast says so — a session
-  publishes one version and arms one class, neither of which anybody watched happen.
-  Cancelling with classes banked **asks**, and it asks on Escape and the overlay too:
-  everything a session holds lives in the browser, so closing loses exactly what was
-  typed and nothing else. It is the only question this dialog asks. What did not change:
-  the save-then-publish-then-repin order, the `canRepin` preflight that says *before* the
-  press when a completed batch will keep its version, and the refusal that names the
-  Schema tab when somebody else narrowed the schema past the pin.
-- **Version history grouping** (#368): the project's Schema tab ends in a ledger of every
-  version. Since the annotator publishes versions too, a flat table buries the curated
-  milestones somebody opened it to read under a run of `Added class "cone" from the
-  annotation view`. So **consecutive versions whose `provenance` is `annotation` collapse
-  into one expandable row** — `v3–v5`, how many, when the run ended, and the contract it
-  left behind — while `curated` and a null from before the field existed always render
-  individually. A run of one is not a run: collapsing a single version saves no space and
-  makes the commonest case the least readable. Expanding gives back exactly the rows a
-  flat table would have had, indented.
-- **Tool strip**: floating at the canvas's left edge — 48px (`w-12`) column, `muted`
-  surface, `border`, 12px radius, 8px padding; 36px icon buttons; **active tool = primary
-  variant** (the near-black), inactive = ghost; a `h-px w-6` divider; help at the bottom.
-  Tooltips open right with the shortcut ("Select (V)", "Box (B)", "Polygon (P)").
-  Icons: MousePointer2 / Square / Spline; only tools the schema's geometries allow — and,
-  **with a class selected, only that class's own** (#584). A class accepts a set of
-  geometries, so what can be drawn depends on which class is held: offering a polygon
-  button under a boxes-only class would answer *what can I draw here* with a lie. With no
-  class selected it is the schema's union, which is still the right answer to *what does
-  this project label*. Switching to a class that forbids the active tool never strands it —
-  `toolFor` resolves to the class's first allowed shape — and the route to a different
-  class's geometry is the class list, which is where choosing a class belongs.
-  **Last of them, below the `+`, the hand** (#576, `Hand`, `H`) — the one button here that
-  the schema does not gate, because it answers a question about the *device* rather than
-  about the project: a pan had exactly one spelling, a middle- or secondary-button drag,
-  and a trackpad, a tablet and a pen have no second button to offer. Cursor `grab`, and
-  `grabbing` while a drag is under way. It sat *above* the strip for a release, as the one
-  control that does not draw, which read as a heading over the tools rather than as one of
-  them. **The hand and the derived tool are one lit button, not two**: while the hand is on
-  no tool row reads as active, because the canvas answers a primary press with a pan before
-  the machine ever hears it, and pressing any tool — including the one already derived —
-  puts the hand down. Reaching for a class puts it down too, through the one funnel every
-  route to a class already goes through. **Suggest is not in that group**: it is a mode over
-  the class it borrows, so it is legitimately lit beside a tool and keeps its own state.
-  The canvas says the same thing the strip does: while the hand is on there is **no crosshair
-  and no highlighted grip**, because the next press is answered by a pan and both would be
-  offers it cannot keep.
-  Below a second divider, **undo and redo** (#368): the chords have worked since #46 and
-  had no representation on screen at all, so the annotator's headline capability over v1
-  was invisible to anybody who did not already know it. Disabled *with the reason*
-  (`Nothing to undo`) rather than hidden, because an empty history is a state a person is
-  in constantly — every freshly opened frame — and a control that vanished and reappeared
-  as they worked would be worse than one that explains itself.
-- **Side panel** (#126, reshaped by #368, split in two by #420): 288px (`w-72`) column,
-  **320px (`2xl:w-80`) from 1536px** — headroom for a class naming three shapes, not a fix,
-  and withheld below that on purpose: `ANNOTATOR_MIN_VIEWPORT_PX` is 768, where a collapsed
-  rail already leaves a 384px stage, and a width chosen on a large monitor must not be
-  charged to the smallest screen the editor opens on at all. `EditorNotice`'s clearance
-  arithmetic is stated at 1280px and is unaffected. Otherwise:
-  `muted` surface, `border`, 12px radius. **Three stacked regions, no tabs and no
-  splitter** — Classes, Tags, Annotations. It was Objects | Labels tabs until #368, which
-  sent class selection to the top bar; #420 brings it back and deliberately does not bring
-  the tabs with it. A tab is a claim that things are alternatives, and these are three
-  answers about one frame, read top to bottom: *what may I draw*, *what is true of the
-  whole picture*, *what have I drawn*. All three are on screen at once.
-
-  **A region with nothing to show is not rendered**, and its divider goes with it: no
-  class anything can be drawn with, or no class declaring a tag. A heading over an empty
-  box is a claim that something is missing. Annotations is the exception and always
-  renders — an empty frame is the normal state of a fresh one, and it says so in words.
-
-  **Classes (upper).** Header — the word `Classes`, the class count in muted meta, and a
-  24px `+` opening the add-a-class dialog; then a 32px `Filter classes…` input; then the
-  rows described under **Classes region** above. Its height is **content-driven and stated
-  in rows**: a floor of 3 rows' worth, one row per class after that, a ceiling of 8, after
-  which the region is fixed and the list scrolls inside it. A small ontology gets a region
-  proportional to what it holds; a large one cannot push the objects region off the bottom.
-  The count it is computed from is the **schema's drawable classes**, never the filtered
-  ones — a height that tracked the filter would reflow the region below it on every
-  keystroke — and a row that wrapped its chips to a second line is absorbed by the same
-  scroller a ninth class is, rather than by a rule that would have to measure. The header
-  and the filter are not rows and do not scroll away.
-
-  **Tags (middle).** Rendered only when the pinned schema declares a `classification_tag`
-  class. Header — the word `Tags` and the assigned count in muted meta — then one line of
-  meta-size prose, `Tags apply to the whole image.`, which is the whole difference between
-  this region and the two around it. Then the chips: rounded-full, swatch, name, and
-  either the hotkey digit or a check, `primary/10` with a `primary` border when assigned
-  and outlined muted when not. **Multi-select and unbounded**: an image carries one tag per
-  tag-capable class and as many classes as the schema declares, which is the kernel's own
-  rule (`DuplicateClassificationTag` is keyed `(asset, class)`), so the chips enforce
-  nothing the kernel would contradict. `shrink-0` with a capped scroller of its own, so
-  thirty tag classes cannot push the objects region off the panel.
-
-  **No filter, and it is the one place the lists rule is not applied.** That rule is about
-  *rows* — a vertical list where the twenty-first is a scroll away and indistinguishable
-  from the twentieth. These are chips in a wrapping cloud: twenty of them are about seven
-  short lines, read at a glance, and each carries a colour and a digit. A third filter
-  input inside a 288px panel that already has two would cost more attention than it saves.
-  Revisit if a real schema arrives with enough tag classes to disprove it.
-
-  **Annotations (lower).** Takes all remaining height and scrolls independently, and holds
-  **drawn shapes only** — a tag has no coordinates, renders in neither canvas layer, and is
-  assigned in the region above; counting it here gave a tagged-but-undrawn frame `1 object`
-  and offered it a hide button that hides nothing. Top to bottom: **header** (the word
-  `Annotations`, the object count in muted meta text, the all-visibility toggle); the
-  **filter**, a 32px input that is *always* rendered, because a control that appears once a
-  list is long enough is a control nobody finds; then the **object rows**:
-  `rounded-md border px-1.5 py-1`, meta-size text
-  `N. class`; **selected = `border-primary` + `bg-primary/10`**; hidden = 50% opacity;
-  per-row tag, eye and trash as 24px ghost icon buttons.
-
-  The split between them is a **1px rule, not a handle**. The classes region decides its
-  own height by the rule above and the objects region takes the rest; a draggable splitter
-  would add a third piece of per-user state to a surface whose whole value is being the
-  same on every frame. The two regions' selected treatments are deliberately different —
-  a class row is a left accent rule plus a tint, an object row is a full border — because
-  they are selections of different kinds of thing and a person reads both at once.
-  **The number is draw order and filtering does not renumber it** — it is the object's
-  identity on the canvas, and a panel that renumbered as somebody typed would disagree
-  with the picture about which shape is "3".
-  The per-row **tag icon** opens class reassignment: every class the schema declares, with
-  the ones whose geometry does not match this annotation disabled and **carrying the
-  reason** (`needs a polygon`). Listed-and-refused rather than filtered out, which is what
-  shipped before: a short list with no explanation reads as a schema missing its classes,
-  and the rule — the kernel judges geometry per class — is invisible exactly when somebody
-  is hunting for the class that is not there. Applied on selection, not behind an Apply: a
-  menu commits on Enter or a click, so there is no per-keystroke state to keep out of the
-  undo history. Each item that *can* be picked shows its **class hotkey**, and pressing
-  that digit while the menu is open reassigns; a disabled item spends the same slot on
-  the reason instead, because a key chip on a row that refuses the key is a lie.
-- **Class picker, second anchor** (#380): the same menu, on the shape. With exactly one
-  shape selected a 24px tag button rides **above its top-right corner** — above rather
-  than on it, because that corner belongs to the resize grip — and a **right-click on the
-  shape** opens it there too, selecting the shape on the way. Same component, so the class
-  list, the disabled-with-reason rendering, the hotkeys and the apply are one spelling and
-  cannot drift between the two anchors; the panel row keeps its own. It is **absent**, not
-  disabled, when the frame is read-only, when nothing or more than one thing is selected,
-  and for a classification tag, which the canvas draws nowhere.
-- **Frame gallery** (#390): the grid button opens the job's frames as a thumbnail
-  overlay over the workspace — the `ThumbnailGrid` pattern, square tiles with the
-  photo-icon fallback, each carrying its frame number and its status dot in the
-  status tokens above, with the **word** in the tile's accessible name and tooltip
-  because a tile has no room for prose. The current frame is marked (`border-primary`
-  + `bg-primary/10`) and takes the focus on open, which is also what scrolls it into
-  view. Above the grid, the batch view's own four-segment filter
-  (`All / Unannotated / In review / Done`), counted over *this job's* frames.
-  **One press opens a frame** — no select-then-open — through the same save-first
-  path `‹` / `›` use, so a refused save keeps the work and the frame. Escape or the
-  scrim returns to exactly the frame, zoom, pan and armed class that were there.
-  **No batch actions of any kind**: no approve, no promote, no selection, no bulk
-  bar. It is a switcher.
-- **Zoom widget**: floating **bottom-right of the stage** since #368, opposite the tool
-  strip and sharing its chrome — `− / readout / + / fit / fullscreen`. It was in the top
-  bar, which said something false about it: a workflow action changes the work, zoom
-  changes only how the work is being looked at. Fullscreen is requested on the **stage**
-  element rather than on the document, so the tool strip and the widget go with it, and
-  it is **absent rather than disabled** where the browser has no Fullscreen API — unlike
-  a capability the wire withholds, there is no state a person could change to get it.
-  **5%–800%**, percent readout between the −/+ buttons, showing the capped value
-  exactly at each end. The floor is not v1's 30%: an 8K frame does not *fit* a laptop pane
-  above about 18%, so a 30% floor makes "zoom out until you can see the whole thing"
-  unreachable (`MIN_ZOOM`, since #49). The ceiling is 8x, where one asset pixel is an
-  eight-pixel block and the picture has nothing further to show (#228); above 4x the image
-  renders `image-rendering: pixelated`, so depth shows real pixel blocks rather than
-  interpolated blur. Both bounds are **disabled with the reason** per principle 9 — the
-  `−`/`+` carry `aria-disabled` and a tooltip naming the limit, never a press that silently
-  does nothing. `docs/annotations.md` carries the argument.
-- **Navigating the picture is one model across every device** (#576). Pan: a two-finger
-  trackpad scroll, a middle- or right-button drag, `Space` held with any drag, or the hand
-  tool. Zoom: a mouse wheel, a trackpad pinch, `Ctrl`/`Cmd` with a scroll, the widget's
-  `−`/`+`, and `mod+0` to fit. On a touchscreen one finger draws — or pans while the hand
-  is on — and two fingers pinch and drag together. **A bare wheel event is answered by
-  device**: a two-finger scroll pans, a wheel notch zooms. That split is what makes a
-  trackpad workable without costing the mouse the gesture it has always had — a two-finger
-  scroll is how anybody moves around a canvas and a notch is how anybody zooms, and a rule
-  serving one leaves the other with nothing. No browser reports the device, so the test is
-  a heuristic and **everything uncertain is read as a trackpad**: a mouse it declines still
-  zooms with the modifier and the buttons, where a trackpad that zoomed by accident would
-  be the defect over again. The shortcut sheet's **Navigate** section is the one place this
-  is written for a user, and it is hand-written rather than derived — a gesture has no
-  chord to be read off.
-- **Where one event cannot name the device, assume the mouse and make the trackpad prove
-  itself.** A high-resolution wheel — the MX Master class, and increasingly the default —
-  reports a fraction of a detent, which is the shape a trackpad reports on the same axis in
-  the same units; the kernel specification declines to bound that fraction, so no arithmetic
-  on a single event separates them. The evidence that does separate them is **travel on both
-  axes at once**, which drifting fingers produce constantly and no wheel can produce at all —
-  a vertical wheel is always `deltaX === 0` and a thumb or tilt wheel always `deltaY === 0`,
-  each being one physical wheel. Reading the horizontal axis *alone* would condemn a mouse for
-  a nudge of its own thumb wheel. The burden of proof sits this way round because the mistakes
-  are different sizes: a wrongly-assumed mouse costs a trackpad one gesture before it corrects
-  itself, while a wrongly-assumed trackpad costs a mouse its zoom **permanently**, since a
-  wheel emits nothing that could ever overturn the guess. A recoverable error beats an
-  unrecoverable one. The sighting is persisted per browser, so a trackpad pays that gesture
-  once and never again. **There is no setting for this** — an inference that is right without
-  being asked does not need a control, and one was drafted and cut for exactly that reason.
-
-### The read-only mode
-
-The workspace opens as a **viewer** whenever the wire withholds `annotate` on the
-frame — a completed batch, a **finished job**, or a settled frame inside an open
-one. The mode is the frame's own declaration (`allowed_actions`), never this
-page's arithmetic; it was made a mode at all by audit F2, which found "open it
-and let the saves fail" shipping as the behaviour.
-
-**It is also a transition, not only an entry state** (decision of 2026-08-08,
-#439). Pressing `Finish job` turns the workspace into a viewer **in place** —
-same window, no navigation away, no reload — across every frame of the job and
-not only the last. That works for one reason and it is worth stating: the
-mutation invalidates the frames' declarations, the wire's answer moves because
-the *kernel's* did (`asset_actions` reads the job's state), and the page
-re-derives. Nothing here mirrors a rule. A job completing does not complete its
-batch, so before #439 the wire's answer did not move and the workspace stayed an
-editor over work it had just been told was over.
-
-The press says so out loud — a toast, the add-a-class chain's idiom — because
-everything else it does is a subtraction, and a screen with less on it is not an
-explanation.
-
-What a viewer is (decisions of 2026-08-07, #426, and 2026-08-08, #439):
-
-- **One explanation surface.** The banner under the top bar says `Viewing only.`
-  with the cause, and — when the wire declares `create_correction` — the route
-  onward: `Correct this batch`. It renders on every frame of a closed batch or a
-  finished job, including skipped ones (#423, #439), where the skipped notice
-  would otherwise promise an Un-skip the wire withholds. Three causes, three
-  sentences, ranked: a **closed batch** carries the correction route; a
-  **finished job** names itself and offers nothing, because `JOB_TRANSITIONS` has
-  no way back and the batch is still open; a **settled frame** in an open batch
-  points at the control on this very toolbar.
-- **No classes region.** The side panel is the objects region alone, at full
-  height — the region, its filter, its quick-create and its hotkey badges are
-  absent, not disabled, and `C` and the digits do nothing. This supersedes #420's
-  render-classes-as-information direction: *what may I draw* is not a question a
-  viewer can ask.
-- **Selection highlights; it does not advertise.** A selected shape renders the
-  selected treatment — stroke 3, the label — with **no grips and no vertex
-  dots**, and the cursor is the **default arrow everywhere**: no resize keywords,
-  because no such gesture exists. Since #567 the editor also shows the plain arrow
-  over a shape, so what separates the modes is the grips rather than the cursor.
-- **The tool strip renders, carrying navigation and nothing else** (#576). It used
-  to be absent entirely, and the reason held while it was true: every control on it
-  picked a *drawing* tool, and a tool palette over a canvas that cannot be drawn on
-  explains nothing. The hand is not a drawing tool — it is what a person reaches for
-  when the picture is in the wrong place — and navigating a batch nobody may edit is
-  most of what a viewer does, so the strip keeps the hand and the shortcut sheet and
-  loses every other button. The banner still carries the reason, once.
-- **Selection is one state, reflected everywhere.** A press on a shape selects
-  it — the one pointer gesture a viewer keeps, resolved by the same hit rule the
-  right-click menu uses — and the objects panel's row highlights and scrolls
-  into view. That reflection is both modes' behaviour, not the viewer's alone.
-  DOM focus stays with the canvas, which reads its chords off its own root.
-- **Once the job is closed, the frame's own verbs go with it — and the job's
-  does not.** `Skip` / `Un-skip` and the flow verb (`Save and next` / `Next`)
-  stop rendering on every frame of a completed batch or a finished job: the tool
-  strip's rule applied to the bar, since all three only ever move *this frame*
-  and there is no move behind any of them there. The `browse | resolve` divider
-  goes with them.
-
-  **The gate is the job, never the frame**, and both halves of that are load
-  bearing. A merely *settled* frame inside a working job keeps the pair, greyed —
-  because the cluster is measured to one width (above) and a slot that emptied
-  and refilled as somebody walked a mixed job would move the arrows under their
-  cursor, and because `Un-skip` is the one way back out of a skipped frame, which
-  is itself read-only. A closed job withholds every move on every frame alike, so
-  the cluster is uniformly narrower and nothing jitters.
-
-  **`Finish job` stays** on the last frame: `complete` is the *job's* declaration
-  rather than the frame's, and a job whose last frame happens to be `accepted`
-  would otherwise have no way to be finished at all. Once it is finished it reads
-  `Finished`, which is this page's standing statement that the work is over.
-- **Navigation stays whole.** `‹` `›`, the `n/m` counter and the frame gallery
-  all work, and no save-first guard engages — there is nothing to save. Only
-  editing dies; moving between pictures does not.
-- **Reads stay live.** Zoom, pan, fullscreen, visibility toggles, the object
-  filter, and copy (`⌘C`) — the road a box takes into a correction batch — all
-  work; paste and every other write is refused at the engine (`readOnly` on the
-  canvas, `READ_ONLY_KINDS` for the keyboard).
-
-### The canvas surround
-
-The area around the asset is **`stage`** (`#e1e6eb`), never `muted` and never a dark
-surface (#185). It is a role of its own for two reasons. A dark surround shifts the
-perceived contrast and colour of the photograph inside it, which is a real cost on a
-tool whose whole job is looking closely at pixels — and it was also the only dark
-surface in the product outside the rail, so the one screen somebody sits in front of
-for an hour read as a different application.
-
-It must stay distinguishable from `background` as well as from the image: an asset
-with white borders has to show where it ends. That rules out `background`, `card` and
-`muted`, whose closest channel is five short of white; `stage` clears the same
-measurement by twenty, and `e2e/annotate.spec.ts` asserts the gap rather than the hex.
-
-**The rail keeps its dark treatment.** This is not a theme change.
-
-### Annotation shape rendering (canvas)
-
-One class-color rule shared by the canvas, the side panel swatches (#126), and the
-gallery badges (#55) — and it **already exists, shipped and unit-tested**:
-`classColor` in `frontend/annotator/src/adapters/react/paint.ts` (#47). ui-core
-**imports it**; nothing respells it (#128's gate):
-
-- A class **with a schema color** (`LabelClass.color`) uses it — the kernel's own
-  docstring settles the precedence. Fill is the same color at an opacity the shape
-  applies (alpha is never baked in, because the kernel accepts any CSS color spelling).
-- A class **without one** falls back to a deterministic FNV-1a hash of the name →
-  `hsl(hash % 360 72% 58%)` — stable per class, per session, per machine, with no
-  palette prop to thread down. (v1's fallback used a different hash and a four-value
-  palette; not ported — the shipped rule is tested, and a fallback hue is arbitrary,
-  not brand.)
-- A control that can only take `#rrggbb` — `<input type="color">` in the schema editor — shows
-  the same answer **converted**, never a substitute. `hexColor` in `frontend/ui-core/src/palette.ts`
-  changes the notation and nothing else; it returns `null` for a CSS spelling it cannot convert,
-  and the caller shows a neutral for that case alone. #162: binding such an input to the *stored*
-  colour rendered every derived class grey beside a dot showing the real one.
-- v1's shape metrics, kept as the reference: stroke width 2, selected 3; vertices render
-  **while selected, or while the shape is a suggestion preview**, radius 5 (7 when the
-  vertex itself is selected), with a 2px white outline; the class label renders only while
-  selected, 11px / 700, anchored at the first vertex, never a pointer target.
-
-  **The preview is a third visual state, not a shape marked selected** (#557). Selection
-  carries the panel row, the delete key and the keyboard rules a proposal must not have, so
-  it gets its own rule rather than borrowing one. Its vertices are up the whole time it is
-  on screen, undecimated at every detail step, because where precision was gained or lost
-  *is* what the detail control is about — a live vertex count beside the slider and nothing
-  on the picture made it a control somebody moved blind. Its outline is dashed and an
-  accepted annotation's is solid, which is what tells proposed from committed at a glance.
-
-**The cursor promises the common outcome, not the rare one** (#567). In Select mode,
-hovering a shape — its body, its edge band, or a vertex — is the **plain arrow**: a press
-there *selects*, and only becomes a move if the pointer then travels. What reports which
-shape a press would take is the hover **highlight**, not the cursor. The four-arrow `move`
-appears only while a drag is actually in flight, and the directional resize keywords only on
-a selected box's grips, where they name an axis the arrow cannot.
-
-**The canvas label is part of what selection looks like.** A frame carrying forty boxes drew
-forty class names over the picture at all times, which hides the asset behind the annotations
-of it. The panel is the full inventory; the canvas answers *what is this one* for the shape
-somebody picked, and an unselected shape is its box alone. This is also how a viewer's
-selection reads, since a read-only frame paints no grips.
-
-**A model's work is marked; a person's is not.** `provenance: "model"` earns a `Sparkles`
-glyph on the side-panel row, whose accessible name carries the claim in words and whose
-tooltip carries the full `model_ref`. That glyph is the *only* provenance signal in the
-editor — the canvas label is the class and nothing else. Never colour alone — class colour is
-already user data and cannot also mean provenance. **Absence is the human case**: no "manual"
-badge, no mark on the common path, because the row a reviewer sees a thousand times is the one
-that must stay quiet. `import` provenance is unmarked until there is an importer whose mark
-would mean something.
-
-**Confidence renders on the live suggestion preview and nowhere else in the editor.** The
-number tells somebody whether to accept a proposal; once accepted, the shape is a label like
-any other and the score is decoration on every subsequent reading of it. So no percentage on a
-canvas box, on a panel row, or in a tooltip. It is not discarded — `confidence` and
-`model_ref` are stored unchanged — and its home is the batch review loop, where a surface
-showing it must also name *what it measures*: a point-prompted mask score and a detection's
-prompt affinity are different quantities on different scales and cannot be pooled, thresholded
-or sorted together.
-
-**Where it is shown, it has one spelling, and that is whole percent.** `confidencePercent` in
-`frontend/annotator/src/adapters/react/paint.ts` — the same shared-helper rule as `classColor`
-above: whoever shows the number imports it rather than respelling it, because two notations
-for one quantity is a number that disagrees with itself. Two decimals would claim a precision
-a confidence does not have. A `null` confidence reads as absent — never as `0`, never as a low
-score.
-
-## Libraries
-
-| Concern | Choice | Status |
-|---------|--------|--------|
-| UI primitives | Radix (+ shadcn-style composition with `cva` and `cn`) | **shipped** (#128) |
-| Icons | lucide-react | **shipped** (#128) |
-| Styling | Tailwind v4, CSS-first `@theme` — **no `tailwind.config.js`, ever** | **shipped** (#128) |
-| Toasts | sonner | **shipped** (#128) |
-| Component tests | vitest + jsdom + @testing-library/react, in `ui-core` | **shipped** (#128) |
-| Server state | TanStack Query v5 | v1-verified default; pinned by #52 |
-| Uploads | react-dropzone | v1-verified default; pinned by #54 |
-
-Do not add a library for a covered concern without a documented reason.
-
-## Do's and Don'ts
-
-**Do**: consult this file before building or changing any UI; reuse primitives and
-extend with variants; keep the type scale and spacing rhythm; cover loading/empty/error;
-keep every interactive element keyboard-reachable with a visible focus ring.
-
-**Don't**: hardcode colors in components; fill large surfaces with the accent; introduce
-new colors, sizes, or libraries ad hoc; use `div onClick` for primary actions; add heavy
-shadows, gradients, or loud motion.
-
-## Where the contract lives
+Nested surfaces step down: a control inside a card is `small` on a `medium` parent.
+Arbitrary radii do not appear.
+
+### Materials and Elevation
+
+A surface's appearance is a **material**: one named combination of fill, border, radius,
+shadow, and contrast against the parent surface. Components pick a material; they never
+compose fills, borders, and shadows freehand — that is how a product ends up with nine
+almost-identical cards.
+
+```text
+material-base        the page itself — background, no border, no shadow
+material-small       inline raised elements: inputs, chips, quiet cards
+material-medium      standard cards and panels
+material-large       prominent floating surfaces
+material-tooltip     tooltips — smallest floating material, highest contrast text
+material-menu        menus and popovers
+material-modal       dialogs and sheets — strongest separation, with scrim
+material-fullscreen  a surface that temporarily is the app (the fullscreen stage)
+```
+
+Elevation is expressed *through* materials — in a light theme mostly by border and a
+restrained shadow, in a dark theme mostly by fill step — so "how raised is this" and
+"which shadow utility" are never asked separately. Exact values belong to the token
+implementation.
+
+### Iconography
+
+- **One icon set product-wide**, stroke-based, at a consistent stroke weight; mixing
+  sets or weights reads as broken. Which set is an architecture decision
+  ([`docs/architecture/frontend/ui-core.md`](docs/architecture/frontend/ui-core.md)),
+  not a per-screen one.
+- Icons align to the type grid: sized to the text tier they sit beside, optically
+  centred, tinted with the text's own colour role.
+- **An icon never carries meaning alone.** It accompanies a word, or carries an
+  accessible name and tooltip where there is genuinely no room for one — and "no room"
+  is a layout decision to justify, not a default.
+- Decorative icons are marked as such (`aria-hidden`); functional ones are labelled.
+
+### Motion
+
+- **Motion is functional**: it orients (where did this come from), confirms (this
+  registered), or directs attention (this changed). Decorative animation does not ship.
+- **Fast and quiet.** Transitions run in the 120–240ms range with standard easing; a
+  surface entering is subtler than a surface the user summoned; nothing bounces.
+- **Motion never blocks.** No interaction waits for an animation to finish.
+- **`prefers-reduced-motion` is honoured everywhere**: movement collapses to opacity
+  changes or nothing, with no loss of information.
+
+## Component Principles
+
+### Action Hierarchy
+
+**Every decision context has a clear action hierarchy.** Where there is a clear next
+step, prefer **one dominant action** — the filled, accent-coloured treatment — with
+supporting actions in secondary (outlined) or tertiary (ghost) treatments. Where a
+context genuinely offers peers, no action pretends to dominance.
+
+- Hierarchy is expressed by **treatment** (filled / outline / ghost), never by semantic
+  status colour. A save button is not green because saving is good; `success` describes a
+  resulting state, not an action's importance. A destructive action may use `error`
+  styling — there the colour *is* the semantics.
+- Row- and item-level actions inside tables and lists are never the view's dominant
+  action; they take secondary or tertiary treatments.
+- An overflow menu (`⋯`) is where the undominant rest lives; a view never lines up more
+  than a dominant action, one secondary, and the overflow.
+- Which action is dominant on which product screen — and how it tracks state — is
+  product behaviour: [`docs/ui/product-principles.md`](docs/ui/product-principles.md).
+
+### Forms
+
+- Labels sit above fields, in a label role, Title Case. A placeholder is a hint or an
+  example — never the label, because it vanishes exactly when the user starts answering.
+- Help text is `copy-13` in `foreground-secondary`, under the field; an error replaces or
+  joins it in `error`, adjacent to the field it concerns, and names both what is wrong
+  and what would fix it.
+- Inputs share one control height per density tier, one radius (`small`), one border
+  behaviour (`border` → `border-hover` → `border-active`/focus ring). A two-line option
+  (identifier plus its facts) grows the control; nothing truncates an identifier.
+- Submission follows the never-disable rule
+  ([`docs/ui/product-principles.md`](docs/ui/product-principles.md)): a submit control
+  stays pressable and explains, or explains what would enable it, or is not rendered.
+- Required is the default; optional fields are the ones marked.
+
+### Feedback
+
+Loading, empty, error, and success are **designed states**, specified with the screen —
+never leftovers. The baseline for async feedback:
+
+- **Short operations avoid loading flashes.** Work expected to finish within perception
+  is not announced retroactively.
+- **Transient loading UI appears after roughly 150–300ms** of unresolved wait — early
+  enough that working and broken never look alike, late enough that instant answers
+  never flicker. A surface may justify announcing immediately where measurement shows
+  the wait always crosses the threshold; **a threshold that hides a state needs evidence
+  that the state occurs.**
+- **Once shown, loading UI stays visible long enough not to flicker** (a floor on the
+  order of 250ms), because appearing is free and vanishing after two frames reads as a
+  glitch.
+- **Long-running operations get explicit progress or status prose** — a fraction when
+  one exists, a sentence when it does not. An unknown total is never drawn as an empty
+  progress track.
+- A wait is reported **in one place**, in the user's line of sight but out of the
+  content's way — never at the cursor, never on the data itself.
+- Skeletons preserve the layout they stand in for. Success feedback prefers the visible
+  result; a toast confirms only what the user cannot already see.
+
+### Status
+
+**Status is never communicated by colour alone.** The word, an icon, a shape, or another
+redundant channel always rides with the hue — a status vocabulary must survive a
+monochrome screen and a colour-blind reader.
+
+Five semantic families, product-wide:
+
+```text
+neutral   nothing has happened, or a decision was taken and nothing is wrong
+info      work is in flight; neutral-positive information
+success   settled, succeeded, done
+warning   something is waiting on a person
+error     failed, refused, destructive
+```
+
+As an illustration (the authoritative product mapping lives in
+[`docs/ui/product-principles.md`](docs/ui/product-principles.md)): an unannotated or
+skipped frame is `neutral`, a running job `info`, a frame awaiting review `warning`, a
+completed batch `success`, a failed export `error`. Two corollaries: `error` is for
+things that went wrong, never for decisions someone chose; and `warning` is not "in
+progress" — colouring the healthy majority state amber makes ordinary work read as a
+list of problems.
+
+### Overlays
+
+- Every floating surface is one of the floating materials (`tooltip`, `menu`, `modal`,
+  `fullscreen`) — no freehand popovers.
+- **Tooltips** hint and label; they never carry status, errors, or content the user must
+  read to proceed. If a word is load-bearing, it is on the surface.
+- **Menus** open adjacent to their trigger, are fully keyboard-operable, commit on
+  selection, and render an unavailable item disabled *with its reason* rather than
+  omitting it silently.
+- **Dialogs** are sized by their content's shape from a small fixed set of widths (the
+  set is a product decision); any dialog whose content grows with data scrolls *inside*
+  itself rather than growing past the viewport. A dialog that asks a question names the
+  consequence of yes. Focus moves in on open, is trapped while open, and returns to the
+  trigger on close; Escape and the scrim close anything non-destructive, and a dialog
+  holding unsaved user input asks first.
+- Stacking is exceptional: one modal at a time; a menu or tooltip may sit above it.
+
+## Responsive Design
+
+- Designed for mobile, laptop, desktop, and wide displays; the standard breakpoints are
+  640 / 768 / 1024 / 1280.
+- **Adaptation reflows; it does not amputate.** Content and controls remain reachable
+  and legible at every supported size — a chain collapses to its essential form, a bar
+  reabsorbs controls into an overflow in a stated order; nothing simply disappears.
+- Information density is preserved on data surfaces: small screens get the same data
+  with adapted layout, not a brochure.
+- Hit targets stay comfortable on touch (44px-order targets), whatever the pointer.
+- Layout adapts in CSS (container- and viewport-driven); JavaScript measurement is a
+  last resort with a stated reason.
+
+## Interaction
+
+- **Keyboard parity.** Everything a pointer can do, the keyboard can do: real
+  interactive elements, logical tab order, arrow-key movement inside composite widgets,
+  chords documented where they exist.
+- **Focus is visible, always** — a `focus-visible` ring in the accent, painted outside
+  the element so it survives any fill.
+- **Hover is quiet**: a `surface-hover` step or `border-hover`, never a colour change of
+  meaning. Pressed states darken one further step.
+- **The cursor promises the common outcome.** Default arrow for select, pointer for
+  links, text beam for text; specialised cursors (grab, resize axes) appear only where
+  the gesture is real and current.
+- **Selection is one state, reflected everywhere it is visible** — the canvas, the list
+  row, the count — never a per-surface impression.
+- Ongoing direct manipulation (drag, draw, pan) is never interrupted by background
+  updates; the interface defers reflow until the gesture ends.
+
+## Accessibility
+
+First-class, and part of every rule above rather than a section to satisfy afterwards:
+
+- Semantic HTML: real `<button>`/`<a>`, native form controls, lists as lists, one `<h1>`
+  and a meaningful heading hierarchy below it.
+- Full keyboard operability and correct focus management (see *Interaction*, *Overlays*).
+- Every interactive element has an accessible name; every form control a programmatic
+  label; icon-only controls a text alternative.
+- **No colour-only communication** — status, selection, validity, and provenance all
+  carry a redundant channel.
+- Text and essential UI meet contrast requirements in both themes; disabled-looking is
+  still legible.
+- Hit targets are large enough to press without aiming (44px-order for touch, 24px
+  minimum otherwise).
+- `prefers-reduced-motion` support (see *Motion*).
+- Dialogs, menus, and tooltips follow their ARIA patterns: roles, labelled-by
+  relationships, focus trap and return, Escape behaviour.
+- Async states are announced: loading and error regions use live regions where a sighted
+  user would notice the change peripherally.
+- Responsive accessibility: zoom to 200% and small viewports keep everything reachable.
+
+Verification mechanics (which suites, which tools) live with the tests and contributor
+documentation, not here.
+
+## Content and Copy
+
+- **Concise, active, verb-first.** Action labels start with a precise verb ("Create
+  Project", "Ingest Batch"); filler ("just", "simply", "please") does not ship.
+- **Capitalization has a hierarchy.** Title Case for interface labels: page titles,
+  section titles, buttons, form labels, menu items, tabs. Sentence case for prose:
+  descriptions, helper text, error descriptions, empty-state copy, toast bodies.
+- **Errors explain what happened and what the user can do next** — one sentence each.
+  The API's error contract already separates the two; the UI never merges them back.
+- **Empty states name the next useful action** when one exists (see the product
+  principles for the invitation pattern).
+- Consistent product terminology: one name per concept, the domain's own words
+  (`batch`, `schema version`, `release`), never internal codenames or raw backend codes
+  where human-readable copy exists.
+- State the result, not the ceremony: when the resulting state is already visible, the
+  copy does not also announce that it happened "successfully". Exclamation marks
+  virtually never earn their place; enthusiasm is not information.
+
+## Implementation Boundaries
+
+**What implements this contract today.**
 
 | | file |
-|---|---|
+| --- | --- |
 | Prose (this file) | `DESIGN.md` |
 | The running tokens | `frontend/ui-core/src/styles.css` — Tailwind v4 `@theme` |
 | The TypeScript mirror | `frontend/ui-core/src/tokens.ts` — for callers that cannot read CSS |
@@ -1416,37 +427,27 @@ shadows, gradients, or loud motion.
 | The class palette | `frontend/annotator/src/adapters/react/paint.ts`, re-exported by `ui-core/src/palette.ts` |
 | Rendered, to look at | `frontend/app/styleguide.html` (`pnpm --filter @visionset/app dev`) |
 
-The stylesheet and the mirror are gated against each other by `tokens.test.ts`, exact
-equality in both directions. Adding a token to one and not the other fails the suite.
-
-**A consumer imports one line** — `import "@visionset/ui-core/styles.css"` — and adds an
+The stylesheet and the mirror are gated against each other in both directions; a
+consumer imports one line — `import "@visionset/ui-core/styles.css"` — and adds an
 `@source` for its own sources.
 
-## Provenance
-
-Adapted from v1's `DESIGN.md` (`computer-vision-lab-app`, sibling checkout) on
-2026-07-30, with every value verified against `frontend/src/styles/global.css`,
-`components/annotations/annotation-utils.ts` (`getClassPalette`), and the annotation
-workspace components (`AnnotationToolHeader` / `AnnotationToolStrip` /
-`AnnotationSidePanel`). The reference screenshots are described in the 2026-07-30 design
-comment on #51. The version-control affordances (branch dropdown, Merge) are not part of
-this interface. Their top-bar slots were removed on 2026-08-05 (#354) — a disabled control
-whose only explanation is "this does not exist yet" is the thing principle 9 names — and
-the branch-and-merge model behind them was settled on 2026-08-10 as superseded by the
-batch, review and release model the product already has (cf. #127).
-
-**2026-08-01 (#206)** added principles 6–9, the whole of **Project surfaces**, and the
-qualification to principle 3, ahead of the project view redesign (#207–#213).
-
-That brief also specified a **second type scale** — 1200px content width, 20px page title,
-13px body, and "two weights only, no 500" — and it was **deliberately not adopted**. The
-shipped scale is 14px base, a 1.5rem title, `max-w-7xl`, and a 500-weight label role, and it
-is not prose: `styles.css` carries it as Tailwind `@theme` tokens, `tokens.ts` mirrors it,
-`tokens.test.ts` gates the two against each other in both directions, and
-`design_tokens.test.mjs` fails the build on a hardcoded colour. Adopting the other scale
-meant retuning the tokens and restyling every shipped screen — projects, gallery, dataset,
-ingest, batches, and the annotator — in order to change a page that had not been built yet.
-
-So the new **rules** landed on the existing **values**. Nothing in this revision changes a
-token, a size, or a weight. Recorded here rather than in a merged pull request body, because
-the next person to read the brief will find the same conflict and deserves the answer.
+**Standing invariants**, enforced in the test suites (the mechanics live there):
+
+- Raw colour values are not introduced outside approved token definitions; the one
+  sanctioned exception is an inline style carrying a schema-supplied class colour.
+- The tokens have exactly one home (no `tailwind.config.js`, ever).
+
+**Architecture boundaries this document leans on, owned elsewhere**
+([`docs/architecture/frontend/`](docs/architecture/frontend/README.md)):
+`@visionset/app` is the shell and router layer; `@visionset/ui-core` is the shared
+product UI layer and imports no router; `@visionset/annotator`'s core is headless and
+framework-independent. Library and primitive-stack choices are architecture decisions
+recorded there, not visual foundations.
+
+**Contract vs. implementation.** The running tokens and primitives still carry the
+previous visual language (system font stack, the `primary` near-black accent, the
+implementation-artifact tokens named under *Color*, per-component shadow utilities).
+This document states the target contract; the next phase implements it — semantic
+tokens per the alias model above, the Geist type roles, the material set, and the
+shadcn-derived primitive layer in `@visionset/ui-core` — without changing what the
+product's screens *do*.
diff --git a/docs-site/src/sidebar.mjs b/docs-site/src/sidebar.mjs
index c41710a7..79934f85 100644
--- a/docs-site/src/sidebar.mjs
+++ b/docs-site/src/sidebar.mjs
@@ -91,7 +91,15 @@ export const sidebar = [
       { slug: "api" },
       { slug: "auth" },
       { slug: "cli" },
-      { slug: "ui" },
+      {
+        label: "UI",
+        items: [
+          { slug: "ui" },
+          { slug: "ui/product-principles" },
+          { slug: "ui/navigation" },
+          { slug: "ui/annotator" },
+        ],
+      },
       { slug: "mcp" },
       { slug: "mcp-tools" },
       { slug: "mcp-walkthrough" },
diff --git a/docs/README.md b/docs/README.md
index 84185f06..1163e029 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,10 +9,13 @@ top down. It covers the layer stack, each package, and the enforcement points fo
 the architectural boundaries. The pages below are the behavioural reference; the
 architecture tree is the map.
 
-The **visual** contract is [DESIGN.md](../DESIGN.md) at the repository root. Read
-it *before* building any screen; `frontend/ui-core/src/styles.css` implements that
-contract. Read it alongside
-[annotations.md](annotations.md), which covers the annotator itself.
+The **visual** contract is [DESIGN.md](../DESIGN.md) at the repository root — the
+design foundations every screen builds on. The product-behaviour half lives here:
+[ui/product-principles.md](ui/product-principles.md) for what a screen must show and
+offer, [ui/navigation.md](ui/navigation.md) for how a person moves through the app,
+and [ui/annotator.md](ui/annotator.md) for the annotation workspace. Read them
+*before* building any screen, alongside [annotations.md](annotations.md), which
+covers the annotator's kernel-side behaviour.
 
 If you are new to VisionSet, start with [install.md](install.md), then continue to
 [tutorial.md](tutorial.md).
@@ -43,6 +46,9 @@ If you are new to VisionSet, start with [install.md](install.md), then continue
 | [mcp-tools.md](mcp-tools.md) | The complete tool listing, **generated** from the server's own descriptions so it cannot drift from what an agent is told |
 | [mcp-walkthrough.md](mcp-walkthrough.md) | A session over MCP, start to finish: the cycle in the order an agent meets it, and then what twelve real agent runs did with it - where the coordinate frame held, how refusals were read, and the two pieces of friction that changed the tools |
 | [ui.md](ui.md) | The browser client: why no screen calls `fetch`, how a refusal is read (branch on `code`, and the two codes the client adds), where the token is kept and the three alternatives that were rejected, why a 401 is handled in one subscription, the loading/empty/error component, polling, and the dev proxy that keeps CORS out of production |
+| [ui/product-principles.md](ui/product-principles.md) | VisionSet's product UI rules: data first, density on data surfaces, action-forward screens, never disabling without explanation, the product-wide status mapping, number formatting, list and section rules, and the screen rules for Home and the project view |
+| [ui/navigation.md](ui/navigation.md) | How a person moves through the app: ancestor chains and breadcrumbs, what the rail carries, what belongs in the URL, and why the browser's Back button stays correct |
+| [ui/annotator.md](ui/annotator.md) | The annotation workspace UX contract: the top bar's three zones, the side panel's three regions, the tool strip, the frame gallery, zoom and the device model, the read-only mode, the stage, and how shapes render |
 | [releasing.md](releasing.md) | Cutting a release: what ships, why the beta goes to PyPI as a pre-release, the npm scope, the order the steps have to happen in, and the one step that needs credentials this repository does not hold |
 | [inference.md](inference.md) | Where models run: the connections auto-labeling is configured against, why nothing is ever downloaded on your behalf, the two kinds and the parameters each carries, why the model revision is pinned, how weights are fetched and where they land, the `local-inference` extra, and why deleting a connection never touches the provenance on a label |
 | [cli.md](cli.md) | The command line: the whole cycle as a script, the three exit codes (and why one of them also means "no"), why stdout is data and stderr is prose, what `--json` promises and how it stays the API's shape, why `--workspace` follows the subcommand, and what `visionset init` and `visionset server` each do |
diff --git a/docs/annotations.md b/docs/annotations.md
index 6d077552..0bd0e33b 100644
--- a/docs/annotations.md
+++ b/docs/annotations.md
@@ -1024,8 +1024,8 @@ runner is not the machine above.
 
 The demo page at `/` is the annotator's public showcase, and #50 is what made it one. It
 is the same page the behavioural contract drives - the shape did not move - restyled onto
-the repo-root `DESIGN.md` and given the two pieces of the annotation workspace that cost
-nothing to bring forward.
+the product's visual contract and given the two pieces of the annotation workspace that
+cost nothing to bring forward.
 
 ### What is on it
 
@@ -1077,7 +1077,7 @@ Zoom **controls** - a `−`/`+` pair driving the stage from outside - need an im
 handle the adapter still does not publish. They land with the top bar that has somewhere to
 put them (#56). Until then the readout reports and the wheel, the pinch and `mod+0` drive.
 
-### The one deliberate departure from `DESIGN.md`
+### The one deliberate departure from the visual contract
 
 **The canvas well is dark.** Everything around the image follows the contract exactly -
 white cards, `#d0d7de` borders, Robomous orange strictly as an accent, one type scale - but
@@ -1195,7 +1195,7 @@ direction. `mousedown` is where a browser moves focus, so that is where it is
 refused.
 
 The shortcut in each tooltip is the **digit** `hotkeyForClass` answers, not v1's
-`B`/`P` that `DESIGN.md` still draws: this build binds classes to the digit row
+`B`/`P`: this build binds classes to the digit row
 (#46), and printing a key that does nothing would be worse than printing none.
 
 
diff --git a/docs/architecture/frontend/README.md b/docs/architecture/frontend/README.md
index b04efc58..bd6330c6 100644
--- a/docs/architecture/frontend/README.md
+++ b/docs/architecture/frontend/README.md
@@ -63,6 +63,9 @@ product.
 - [app.md](app.md) - the router shell.
 
 [`DESIGN.md`](../../../DESIGN.md) is the visual contract and the file to read
-before building any screen. [`docs/ui.md`](../../ui.md) covers how the browser
-client talks to the API. [`docs/annotations.md`](../../annotations.md) covers the
-annotator's own behaviour.
+before building any screen; the product's own UI rules are
+[`docs/ui/product-principles.md`](../../ui/product-principles.md),
+[`docs/ui/navigation.md`](../../ui/navigation.md) and
+[`docs/ui/annotator.md`](../../ui/annotator.md). [`docs/ui.md`](../../ui.md) covers
+how the browser client talks to the API. [`docs/annotations.md`](../../annotations.md)
+covers the annotator's own behaviour.
diff --git a/docs/architecture/frontend/ui-core.md b/docs/architecture/frontend/ui-core.md
index d9689c41..e422d348 100644
--- a/docs/architecture/frontend/ui-core.md
+++ b/docs/architecture/frontend/ui-core.md
@@ -81,6 +81,25 @@ the tokens would acquire a second home.
 `tests/scripts/design_tokens.test.mjs` scans every tracked frontend file for a hex
 or a `var()` colour in a class string and fails the build on one.
 
+## Libraries
+
+The primitive and utility stack is an architecture decision recorded here, not a
+visual-design rule. The current choices:
+
+| Concern | Choice |
+| --- | --- |
+| UI primitives | Radix (+ shadcn-style composition with `cva` and `cn`) |
+| Icons | lucide-react |
+| Styling | Tailwind v4, CSS-first `@theme` - no `tailwind.config.js`, ever |
+| Toasts | sonner |
+| Component tests | vitest + jsdom + @testing-library/react |
+| Server state | TanStack Query v5 |
+
+Do not add a library for a covered concern without a documented reason. The intended
+direction - documented, not yet implemented - is to adopt shadcn-derived, project-owned
+primitives in this package while preserving its public APIs, implementing the
+foundations [`DESIGN.md`](../../../DESIGN.md) documents.
+
 ## Related
 
 [`DESIGN.md`](../../../DESIGN.md) is the contract this package implements.
diff --git a/docs/ui.md b/docs/ui.md
index a77d6cf1..b3adf2b9 100644
--- a/docs/ui.md
+++ b/docs/ui.md
@@ -433,7 +433,7 @@ the way to reach `annotated` from `skipped` is to un-skip and annotate, which is
 what the machine says. The zoom `−`/`%`/`+` and fit drive
 `AnnotatorCanvas`'s new `viewRef` handle, whose `fit` is the same implementation
 `mod+0` reaches, which is why that chord stays intercepted rather than forwarded.
-The version dropdown and Merge that `DESIGN.md` draws are **not on the bar**. The
+The version dropdown and Merge that the original reference design draws are **not on the bar**. The
 branch-and-merge model behind them was settled on 2026-08-10 as superseded by the
 batch, review and release model the product already has (cf. #127), and until
 2026-08-05 they rendered disabled to keep the bar the shape the design shows. That
@@ -908,7 +908,8 @@ with one version renders no navigator at all.
 
 **Which version is being read is component state, not the URL.** `?tab=` carries the
 tab because a tab is a destination; a version somebody is glancing at is a lens on
-the tab they are already in. `DESIGN.md`'s navigation rules state the test.
+the tab they are already in. The navigation rules
+([`docs/ui/navigation.md`](ui/navigation.md)) state the test.
 
 The description is written once, in a field beside Save, and there is nowhere to edit
 one afterwards - no route, because no service method, because a version is immutable.
diff --git a/docs/ui/annotator.md b/docs/ui/annotator.md
new file mode 100644
index 00000000..d9c7cfe5
--- /dev/null
+++ b/docs/ui/annotator.md
@@ -0,0 +1,484 @@
+# The annotation workspace
+
+The UX contract for the one screen somebody sits in for an hour. The data flow behind it —
+queries, saving, review moves, the suggest tool's server side — is
+[`docs/ui.md`](../ui.md); the kernel's rules for the labels themselves are
+[`docs/annotations.md`](../annotations.md); the visual foundations are
+[`DESIGN.md`](../../DESIGN.md). This page describes the workspace as the current
+implementation renders it, using the current implementation's token names.
+
+## The workspace is self-sufficient
+
+No flow may force navigation out of the editor, and no exit may lose work. Back saves
+first; a class the schema lacks is created from the class list without leaving the page;
+looking at the job's other frames is an **overlay, not an exit** — the grid button opens a
+gallery over the workspace and the URL does not move. Every trip out of the editor is a
+trip back through a list, a tab and a scroll position to the frame you were looking at,
+which is why this rule is immovable.
+
+## The top bar
+
+One 44px row on `card` with a bottom hairline, 32px controls, in **three zones** — *where
+you are*, *what changes the frame*, *the session*:
+
+| Zone | Contents |
+| --- | --- |
+| Left | back · pinned `v{n}` badge · the frame's identity as a label (the content-hash head — there is no filename on the wire) · the frame microtext `● annotated · Saved` |
+| Centre | the **navigation cluster**: `[⊞] [‹] n/m [›] │ [Skip] [Save and next] [Save and stay]` |
+| Right | `n / m annotated` · the review move (outline) · overflow `⋯` |
+
+**Everything that changes the picture on screen is in the centre cluster, and nothing else
+is.** One hairline divider separates the two sub-groups — **browse | resolve** — so the
+difference between *look at another frame* and *finish this one* is adjacency rather than
+something learned. `‹` `›` browse: they move without settling progress, under the same
+save-first guard as back and the gallery. `n/m` renders between them in tabular figures, so
+walking a job does not shuffle the arrows under a cursor that has not moved.
+
+**The centre is anchored on the bar's geometric centre** — the header is a `1fr auto 1fr`
+grid — and the side tracks yield: a label truncates, never a control. Two widths inside the
+cluster are pinned so it is the same size on every frame: the resolution pair's minimum
+(covering `Skip` and `Un-skip`) and the flow verb's minimum (the widest of `Next` /
+`Save and next` / `Finish job` / `Finished`). The readout that gives way is a readout:
+`n / m annotated` truncates, and no button is ever clipped.
+
+**The dominant slot is the flow verb.** After finishing a frame the right move is *this one
+is done, show me the next* — the navigator's `›` is chrome rather than a verb. **Skip and
+Save and next are siblings** — two ways to resolve this frame, skipped or annotated, both
+advancing — and neither ever collapses into the overflow.
+
+- `Save and next` is the same save-first advance the navigator uses, so there is one save
+  pipeline and one place the no-lost-work rule is enforced. It reads **`Next` when no save
+  will happen** — an untouched frame — because the button never promises a save it will not
+  perform, and once the job is closed it is not rendered at all: there is no save-first
+  advance to offer, and `›` is what moves there.
+- **On the last frame `Finish job` takes the dominant slot**, in place: `Save and next` is
+  not rendered there, and Finish job is not rendered anywhere else. Where it renders and
+  cannot be pressed, it carries why. The consequence is worth stating: `complete` is
+  reachable from the last frame only.
+- **The review move is an outline control**, chosen from the frame's own `allowed_actions`:
+  `submit_for_review`, else `accept` — mutually exclusive by construction. `complete` is
+  deliberately not ranked against them: it is the *job's* action, and it co-declares with
+  `submit_for_review` on the commonest path, so ranking them would hide Finish job exactly
+  where most jobs end. Submitting carries a tooltip saying what it means, because this
+  product has no annotator identity — a submitted frame is marked for a review pass, not
+  routed to a person.
+- **Save and stay is the second half of the forward gesture, and it sits beside the
+  first** as the third member of the resolve group — `Skip · [flow verb] · Save and stay`.
+  *Advance* and *persist in place* are one decision read two ways, so they are adjacent
+  rather than a bar apart. In the current implementation the flow verb is filled in
+  `primary` and Save and stay is filled in `success`; colour is what separates their
+  intent, since a second `primary` beside the first would read as a bar that could not
+  decide. It keeps the frame verbs' lifetime rather than the mode's: a closed batch or a
+  finished job has nothing to save on any frame, so it leaves with Skip and the flow verb;
+  inside a working job it holds its slot, disabled, so the cluster does not change width as
+  somebody walks a mixed job.
+- **Reabsorption order when the bar runs out of room**: Save and stay first (below `xl`),
+  the review move second (below `lg`), into the overflow; the Skip/Save-and-next pair never
+  collapses. Each reabsorbed control carries the exact inverse of its button's breakpoint,
+  so it exists in exactly one place at any width.
+- **Hotkey chips go on the ghost and outline controls and on nothing else** — `X` on Skip,
+  from `core/input/bindings.ts`. A chip is a lighter-than-the-surface treatment: inside a
+  filled control it inverts and reads as a smudge rather than as a key, so neither filled
+  control carries one. `⌘S` is taught by Save and stay's tooltip — the tool strip's own
+  pattern (`Box (B)`) — and `enter` is the one key with two meanings, the polygon ring
+  close while a shape is in progress and *finish the frame* otherwise. Both are in the
+  shortcut sheet, which derives its rows from the live binding registry rather than from a
+  hand-written table.
+- The bar carries the frame microtext `● annotated · Saved`, which says *where the work
+  is*. The word is on the bar beside the save state because **status is never colour
+  alone**, and a tooltip is a place a word goes to not be read. After a refused save the
+  honest answer there is `unsaved`, and the reason is a sentence in the notice column.
+
+## In-editor messages, and waits
+
+**In-editor messages have one surface, top-right of the stage** (`EditorNotice`). Every
+sentence the editor floats over the picture goes into one column inset 16px from the
+stage's top and right edges: a suggest session, a refused save, a refused progress move,
+and a batch or job that could not be opened. Top-right is the corner nothing else occupies:
+the tool strip is top-left, the object counter bottom-left, the zoom cluster bottom-right.
+The column is a stack, most-blocking first, because more than one of those can be true at
+once. Its body wraps mid-token — a model reference is one unbroken string and no fixed
+width guarantees the next one fits, so wrapping is the invariant and the width is comfort.
+
+**A wait is reported as soon as it starts, and once reported it stays for at least 250ms.**
+Work that has begun and shows nothing is the state in which *working* and *broken* look
+alike, so the trigger is the request leaving. The floor is the asymmetry: appearing is
+free, and disappearing after two frames is the glitch. Where a wait has a second threshold
+worth crossing, what appears is **prose**, never a second indicator. The worked example is
+the suggest tool: the panel says `Looking at that…` from the moment the request is
+dispatched, and past 1.5s adds a sentence saying that the first click on a frame is the
+slow one.
+
+**A wait is reported in one place, and never at the cursor.** An indicator sitting on the
+picture, next to the pointer, reads as the machine having *seized* rather than as work in
+progress — it is in the way of the thing being looked at, and it moves with the hand. The
+card is out of the way, says the same thing in words, and is where every other answer about
+the tool already appears. **An indicator is never brand-coloured**: quiet neutrals, at low
+opacity, at the place the person is already looking.
+
+## The classes region
+
+Class selection is a **list** in the side panel's upper region — what is being chosen
+between is the ontology, and a list keeps all of it one click away, so *what can I draw
+here* is always on screen. Rows carry swatch · name · geometry chips · hotkey badge, in the
+**schema's authored order and only that**: a persistent list that reordered itself by
+recency would move rows under the cursor, and the digits are schema positions. `c` focuses
+its filter, Enter takes the first match, digits 1–9 activate directly, and the derived tool
+follows the class. When nothing matches what was typed the last row is
+`Create class "<text>"`, which opens the add-a-class dialog on that name; an empty schema
+renders an invitation instead of an empty list. **It shows the drawing class and never
+follows the selection** — re-classing an existing annotation is an object row's menu, a
+different question about a different object. On a frame nothing can be drawn on, the list
+still renders — which classes exist stays true there — with every row disabled *and
+carrying why*.
+
+**The drawing class's lifetime is the job**, not the frame: it survives moving to the next
+asset, because somebody labelling one class across a clip picks it once, and it survives a
+re-pin. It stops at the job's edge, the same scope the clipboard has and for the same
+reason — a paste and a drawing class both belong to one pinned schema.
+
+**Every row's shapes are chips, and every chip is a press target.** A class accepts a *set*
+of geometries, so arming a class does not pick the shape by itself. One chip per
+**drawable** geometry, labelled with the geometry **word** — glyphs are not
+self-describing at chip size on the one row whose job is telling shapes apart. What a press
+does depends on the row, and the two readings are one rule — *this class, this shape*:
+
+- On the **armed** row the active chip is lit and pressing another switches the tool and
+  **never the class** — changing shape must not move somebody's labels to a class they did
+  not choose.
+- On an **unarmed** row no chip is lit, and pressing one arms the class *with that shape*,
+  in one press.
+- Pressing the **name** arms the class with its first drawable shape.
+
+The cost is that a row carrying chips is a `role="group"` with an inner name button rather
+than one row-wide `<button>` — HTML forbids interactive descendants inside a button. A row
+carrying a **refusal** never picks: it falls back to the plain button, the only one that
+can be `disabled`, so the rule stays *explained and inert*.
+
+Geometry words are **display labels, never wire values** — `box`, not `bbox`; `tag`, not
+`classification_tag`. One map, `GEOMETRY_LABELS`, shared with the tool strip; lowercase,
+because the same word is read as a chip in a row and inside a sentence.
+
+**What gives way, stated: the row's height.** The chips wrap beneath the name and stay
+right-aligned in the same column every unwrapped row's chips sit in, so a long name gets
+the whole first line and the list keeps the one vertical edge it is scanned down.
+Truncating a control is worse than truncating a label, and every chip is a control.
+
+**A class that declares only `classification_tag` is not in this list at all.** It has no
+canvas gesture; the Tags region is where it is assigned. It is also excluded from the count
+the region's height rule reads.
+
+## The side panel
+
+A 288px column (320px from 1536px — headroom for a class naming three shapes, withheld
+below that on purpose: the minimum supported viewport must not be charged for a width
+chosen on a large monitor). `muted` surface, hairline border, 12px radius. **Three stacked
+regions, no tabs and no splitter** — Classes, Tags, Annotations. A tab is a claim that
+things are alternatives, and these are three answers about one frame, read top to bottom:
+*what may I draw*, *what is true of the whole picture*, *what have I drawn*. All three are
+on screen at once.
+
+**A region with nothing to show is not rendered**, and its divider goes with it: no class
+anything can be drawn with, or no class declaring a tag. A heading over an empty box is a
+claim that something is missing. Annotations is the exception and always renders — an empty
+frame is the normal state of a fresh one, and it says so in words.
+
+**Classes (upper).** Header — the word `Classes`, the class count in muted meta, and a `+`
+opening the add-a-class dialog; then a `Filter classes…` input; then the rows described
+above. Its height is **content-driven and stated in rows**: a floor of 3 rows' worth, one
+row per class after that, a ceiling of 8, after which the region is fixed and the list
+scrolls inside it. The count it is computed from is the **schema's drawable classes**,
+never the filtered ones — a height that tracked the filter would reflow the region below it
+on every keystroke. The header and the filter are not rows and do not scroll away.
+
+**Tags (middle).** Rendered only when the pinned schema declares a `classification_tag`
+class. Header — the word `Tags` and the assigned count — then one line of meta prose,
+`Tags apply to the whole image.`, which is the whole difference between this region and the
+two around it. Then the chips: rounded-full, swatch, name, and either the hotkey digit or a
+check; tinted with an accent border when assigned and outlined muted when not.
+**Multi-select and unbounded**: an image carries one tag per tag-capable class and as many
+classes as the schema declares, which is the kernel's own rule, so the chips enforce
+nothing the kernel would contradict. The region has its own capped scroller, so thirty tag
+classes cannot push the objects region off the panel. **No filter** — the lists rule is
+about rows, and these are chips in a wrapping cloud, read at a glance; a third filter input
+inside a 288px panel that already has two would cost more attention than it saves. Revisit
+if a real schema arrives with enough tag classes to disprove it.
+
+**Annotations (lower).** Takes all remaining height and scrolls independently, and holds
+**drawn shapes only** — a tag has no coordinates, renders in neither canvas layer, and is
+assigned in the region above; counting it here would give a tagged-but-undrawn frame
+`1 object` and a hide button that hides nothing. Top to bottom: header (the word
+`Annotations`, the object count, the all-visibility toggle); the filter — *always*
+rendered, because a control that appears once a list is long enough is a control nobody
+finds; then the object rows: meta-size `N. class`, selected = accent border + tint, hidden
+= 50% opacity, per-row tag / eye / trash as small ghost icon buttons.
+
+The split between the regions is a **hairline, not a handle** — a draggable splitter would
+add per-user state to a surface whose whole value is being the same on every frame. The two
+regions' selected treatments are deliberately different — a class row is a left accent rule
+plus a tint, an object row is a full border — because they are selections of different
+kinds of thing and a person reads both at once. **The object number is draw order and
+filtering does not renumber it** — it is the object's identity on the canvas, and a panel
+that renumbered as somebody typed would disagree with the picture about which shape is "3".
+
+The per-row **tag icon** opens class reassignment: every class the schema declares, with
+the ones whose geometry does not match this annotation disabled and **carrying the reason**
+(`needs a polygon`). Listed-and-refused rather than filtered out: a short list with no
+explanation reads as a schema missing its classes, and the rule — the kernel judges
+geometry per class — is invisible exactly when somebody is hunting for the class that is
+not there. Applied on selection, not behind an Apply, so there is no per-keystroke state to
+keep out of the undo history. Each item that *can* be picked shows its class hotkey, and
+pressing that digit while the menu is open reassigns; a disabled item spends the same slot
+on the reason instead, because a key chip on a row that refuses the key is a lie.
+
+**Class picker, second anchor**: the same menu, on the shape. With exactly one shape
+selected a small tag button rides above its top-right corner — above rather than on it,
+because that corner belongs to the resize grip — and a right-click on the shape opens it
+there too, selecting the shape on the way. Same component, so the class list, the
+disabled-with-reason rendering, the hotkeys and the apply are one spelling and cannot drift
+between the two anchors. It is **absent**, not disabled, when the frame is read-only, when
+nothing or more than one thing is selected, and for a classification tag, which the canvas
+draws nowhere.
+
+## The pinned version, and adding a class
+
+**Pinned version badge.** `v{n}` in the left zone names the version *this batch is judged
+against* — not the project's active one, since the pin is movable. Pressing it opens a
+small panel that says whether that is still the current version and, when it is not, what
+arrived since, in the kernel's own words for the change. Nothing about the active version
+is fetched until it is opened: the editor is judged against the pin, and a page that read
+the active version on arrival would be one refactor from offering classes the API then
+refuses. A hand-built disclosure rather than a popover, because the annotator reads the
+keyboard off its own root and focus has to come back to the canvas.
+
+**Add-a-class dialog: one sitting is one published schema version.** `Create and add
+another` (⌘↵) banks the class and clears the form; the primary publishes everything banked
+plus whatever is still in the form. The banked classes show as chips that can be taken back
+out, the auto-written description names them all, and the primary says how many it will
+publish (`Add 3 classes`). Opened from the class list's create row it starts on the name
+that was typed; opened from a `+` it starts empty, because that press means "I want a
+class", not a particular one. **A name the published version already declares is an offer,
+not an error**: the dialog says what that class accepts today and what publishing would
+add, and the primary reads `Add polygon to "sign"`; it carries the existing class's colour
+and attributes, so a form opened to make a new class cannot quietly overwrite what the old
+one declared. A name typed twice in one sitting stays a refusal, because both are being
+written now and merging them would be guessing. When it lands, the **last** class written
+becomes the drawing class and a toast says so — a session publishes one version and arms
+one class, neither of which anybody watched happen. Cancelling with classes banked
+**asks**, on Escape and the overlay too: everything a session holds lives in the browser,
+so closing loses exactly what was typed and nothing else. The save-then-publish-then-repin
+order, the `canRepin` preflight that says *before* the press when a completed batch will
+keep its version, and the refusal that names the Schema tab are all described in
+[`docs/ui.md`](../ui.md).
+
+**Version history grouping.** The project's Schema tab ends in a ledger of every version,
+and the annotator publishes versions too, so consecutive versions whose `provenance` is
+`annotation` collapse into one expandable row — `v3–v5`, how many, when the run ended, and
+the contract it left behind — while `curated` versions (and those from before the field
+existed) always render individually. A run of one is not a run. Expanding gives back
+exactly the rows a flat table would have had, indented.
+
+## The tool strip
+
+Floating at the canvas's left edge — a 48px column on `muted`, hairline border, 12px
+radius, 8px padding; 36px icon buttons; **active tool = the filled action treatment**,
+inactive = ghost; a divider; help at the bottom. Tooltips open right with the shortcut
+("Select (V)", "Box (B)", "Polygon (P)"). Only tools the schema's geometries allow — and,
+**with a class selected, only that class's own**: offering a polygon button under a
+boxes-only class would answer *what can I draw here* with a lie. With no class selected it
+is the schema's union. Switching to a class that forbids the active tool never strands it —
+the derived tool resolves to the class's first allowed shape — and the route to a different
+class's geometry is the class list, which is where choosing a class belongs.
+
+**Last of the tools, below the `+`, the hand** (`H`) — the one button the schema does not
+gate, because it answers a question about the *device* rather than the project: a trackpad,
+a tablet and a pen have no second button to offer for panning. Cursor `grab`, `grabbing`
+while a drag is under way. **The hand and the derived tool are one lit button, not two**:
+while the hand is on, no tool row reads as active, because the canvas answers a primary
+press with a pan — and pressing any tool, or reaching for a class, puts the hand down.
+**Suggest is not in that group**: it is a mode over the class it borrows, so it is
+legitimately lit beside a tool and keeps its own state. While the hand is on there is no
+crosshair and no highlighted grip, because both would be offers the canvas cannot keep.
+
+Below a second divider, **undo and redo** — disabled *with the reason* (`Nothing to undo`)
+rather than hidden, because an empty history is a state a person is in constantly, and a
+control that vanished and reappeared as they worked would be worse than one that explains
+itself.
+
+The geometries with no tool behind them, `aria-disabled` rather than `disabled`, and the
+suggest tool's whole flow are in [`docs/ui.md`](../ui.md).
+
+## The frame gallery
+
+The grid button opens the job's frames as a thumbnail overlay over the workspace — square
+tiles with the photo-icon fallback, each carrying its frame number and its status dot, with
+the **word** in the tile's accessible name and tooltip because a tile has no room for
+prose. The current frame is marked and takes the focus on open, which is also what scrolls
+it into view. Above the grid, the batch view's own four-segment filter
+(`All / Unannotated / In review / Done`), counted over *this job's* frames. **One press
+opens a frame** — no select-then-open — through the same save-first path `‹` / `›` use, so
+a refused save keeps the work and the frame. Escape or the scrim returns to exactly the
+frame, zoom, pan and armed class that were there. **No batch actions of any kind**: no
+approve, no promote, no selection, no bulk bar. It is a switcher; the batch view stays the
+home of batch operations.
+
+## Zoom, pan, and the device model
+
+**Zoom widget**: floating bottom-right of the stage, opposite the tool strip and sharing
+its chrome — `− / readout / + / fit / fullscreen`. Zoom changes how the work is looked at,
+not the work, which is why it is not in the top bar. Fullscreen is requested on the
+**stage** element rather than the document, so the tool strip and the widget go with it,
+and it is **absent rather than disabled** where the browser has no Fullscreen API — there
+is no state a person could change to get it. **5%–800%**: an 8K frame does not fit a laptop
+pane above about 18%, so a higher floor makes "zoom out until you can see the whole thing"
+unreachable; the ceiling is where one asset pixel is an eight-pixel block and the picture
+has nothing further to show — above 4x the image renders `image-rendering: pixelated`, so
+depth shows real pixel blocks rather than interpolated blur. Both bounds are **disabled
+with the reason** — `aria-disabled` and a tooltip naming the limit, never a press that
+silently does nothing.
+
+**Navigating the picture is one model across every device.** Pan: a two-finger trackpad
+scroll, a middle- or right-button drag, `Space` held with any drag, or the hand tool. Zoom:
+a mouse wheel, a trackpad pinch, `Ctrl`/`Cmd` with a scroll, the widget's `−`/`+`, and
+`mod+0` to fit. On a touchscreen one finger draws — or pans while the hand is on — and two
+fingers pinch and drag together. **A bare wheel event is answered by device**: a two-finger
+scroll pans, a wheel notch zooms.
+
+**Where one event cannot name the device, assume the mouse and make the trackpad prove
+itself.** A high-resolution wheel reports a fraction of a detent, which is the shape a
+trackpad reports on the same axis in the same units, so no arithmetic on a single event
+separates them. The evidence that does is **travel on both axes at once**, which drifting
+fingers produce constantly and no wheel can produce at all — reading the horizontal axis
+*alone* would condemn a mouse for a nudge of its own thumb wheel. The burden of proof sits
+this way round because the mistakes are different sizes: a wrongly-assumed mouse costs a
+trackpad one gesture before it corrects itself, while a wrongly-assumed trackpad costs a
+mouse its zoom **permanently**, since a wheel emits nothing that could overturn the guess.
+The sighting is persisted per browser, so a trackpad pays that gesture once. **There is no
+setting for this** — an inference that is right without being asked does not need a
+control. The shortcut sheet's Navigate section is the one place this is written for a user,
+hand-written rather than derived, because a gesture has no chord to be read off.
+
+## The read-only mode
+
+The workspace opens as a **viewer** whenever the wire withholds `annotate` on the frame — a
+completed batch, a finished job, or a settled frame inside an open one. The mode is the
+frame's own declaration (`allowed_actions`), never this page's arithmetic.
+
+**It is also a transition, not only an entry state.** Pressing `Finish job` turns the
+workspace into a viewer **in place** — same window, no navigation, no reload — across every
+frame of the job: the mutation invalidates the frames' declarations and the page
+re-derives. The press says so out loud with a toast, because everything else it does is a
+subtraction, and a screen with less on it is not an explanation.
+
+What a viewer is:
+
+- **One explanation surface.** The banner under the top bar says `Viewing only.` with the
+  cause, and — when the wire declares `create_correction` — the route onward:
+  `Correct this batch`. It renders on every frame of a closed batch or a finished job,
+  including skipped ones, where the skipped notice would otherwise promise an Un-skip the
+  wire withholds. Three causes, three sentences, ranked: a closed batch carries the
+  correction route; a finished job names itself and offers nothing, because the job model
+  has no way back and the batch is still open; a settled frame in an open batch points at
+  the control on this very toolbar.
+- **No classes region.** The side panel is the objects region alone, at full height — the
+  region, its filter, its quick-create and its hotkey badges are absent, not disabled, and
+  `C` and the digits do nothing. *What may I draw* is not a question a viewer can ask.
+- **Selection highlights; it does not advertise.** A selected shape renders the selected
+  treatment — stroke 3, the label — with no grips and no vertex dots, and the cursor is the
+  default arrow everywhere: no resize keywords, because no such gesture exists.
+- **The tool strip renders, carrying navigation and nothing else.** The hand is not a
+  drawing tool — it is what a person reaches for when the picture is in the wrong place —
+  and navigating a batch nobody may edit is most of what a viewer does, so the strip keeps
+  the hand and the shortcut sheet and loses every other button.
+- **Selection is one state, reflected everywhere.** A press on a shape selects it, and the
+  objects panel's row highlights and scrolls into view. DOM focus stays with the canvas,
+  which reads its chords off its own root.
+- **Once the job is closed, the frame's own verbs go with it — and the job's does not.**
+  `Skip` / `Un-skip` and the flow verb stop rendering on every frame of a completed batch
+  or a finished job, along with the browse | resolve divider. **The gate is the job, never
+  the frame**, and both halves are load-bearing: a merely *settled* frame inside a working
+  job keeps the pair, greyed — the cluster is measured to one width, and `Un-skip` is the
+  one way back out of a skipped frame — while a closed job withholds every move on every
+  frame alike, so the cluster is uniformly narrower and nothing jitters. `Finish job` stays
+  on the last frame: `complete` is the *job's* declaration, and a job whose last frame
+  happens to be `accepted` would otherwise have no way to be finished. Once finished it
+  reads `Finished`, the page's standing statement that the work is over.
+- **Navigation stays whole.** `‹` `›`, the counter and the frame gallery all work, and no
+  save-first guard engages — there is nothing to save.
+- **Reads stay live.** Zoom, pan, fullscreen, visibility toggles, the object filter, and
+  copy — the road a box takes into a correction batch — all work; paste and every other
+  write is refused at the engine (`readOnly` on the canvas, `READ_ONLY_KINDS` for the
+  keyboard).
+
+## The stage
+
+The area around the asset is the **`stage`** token, never `muted` and never a dark surface.
+It is a role of its own for two reasons: a dark surround shifts the perceived contrast and
+colour of the photograph inside it, which is a real cost on a tool whose whole job is
+looking closely at pixels — and a lone dark surface would make the one screen somebody sits
+in front of for an hour read as a different application.
+
+It must stay distinguishable from the page background as well as from the image: an asset
+with white borders has to show where it ends. The e2e suite asserts the contrast gap rather
+than the hex. `stage` is a VisionSet-specific semantic token and is recorded as such in
+[`DESIGN.md`](../../DESIGN.md).
+
+## Shape rendering
+
+One class-colour rule shared by the canvas, the side panel swatches, and the gallery
+badges: `classColor` in `frontend/annotator/src/adapters/react/paint.ts`. `ui-core`
+**imports it**; nothing respells it.
+
+- A class **with a schema colour** uses it. Fill is the same colour at an opacity the shape
+  applies — alpha is never baked in, because the kernel accepts any CSS colour spelling.
+- A class **without one** falls back to a deterministic FNV-1a hash of the name →
+  `hsl(hash % 360 72% 58%)` — stable per class, per session, per machine, with no palette
+  prop to thread down.
+- A control that can only take `#rrggbb` — `<input type="color">` in the schema editor —
+  shows the same answer **converted**, never a substitute. `hexColor` in
+  `frontend/ui-core/src/palette.ts` changes the notation and nothing else; it returns
+  `null` for a CSS spelling it cannot convert, and the caller shows a neutral for that case
+  alone.
+- Shape metrics: stroke width 2, selected 3; vertices render while selected or while the
+  shape is a suggestion preview, radius 5 (7 when the vertex itself is selected), with a
+  2px white outline; the class label renders only while selected, 11px / 700, anchored at
+  the first vertex, never a pointer target.
+
+**The suggestion preview is a third visual state, not a shape marked selected.** Selection
+carries the panel row, the delete key and the keyboard rules a proposal must not have. Its
+vertices are up the whole time it is on screen, undecimated at every detail step, because
+where precision was gained or lost *is* what the detail control is about. Its outline is
+dashed and an accepted annotation's is solid, which is what tells proposed from committed
+at a glance.
+
+**The cursor promises the common outcome, not the rare one.** In Select mode, hovering a
+shape — its body, its edge band, or a vertex — is the plain arrow: a press there *selects*,
+and only becomes a move if the pointer then travels. What reports which shape a press would
+take is the hover **highlight**, not the cursor. The four-arrow `move` appears only while a
+drag is actually in flight, and the directional resize keywords only on a selected box's
+grips, where they name an axis the arrow cannot.
+
+**The canvas label is part of what selection looks like.** A frame carrying forty boxes
+must not draw forty class names over the picture — that hides the asset behind the
+annotations of it. The panel is the full inventory; the canvas answers *what is this one*
+for the shape somebody picked, and an unselected shape is its box alone.
+
+**A model's work is marked; a person's is not.** `provenance: "model"` earns a sparkles
+glyph on the side-panel row, whose accessible name carries the claim in words and whose
+tooltip carries the full `model_ref`. That glyph is the *only* provenance signal in the
+editor. Never colour alone — class colour is already user data and cannot also mean
+provenance. **Absence is the human case**: no "manual" badge, no mark on the common path,
+because the row a reviewer sees a thousand times is the one that must stay quiet. `import`
+provenance is unmarked until there is an importer whose mark would mean something.
+
+**Confidence renders on the live suggestion preview and nowhere else in the editor.** The
+number tells somebody whether to accept a proposal; once accepted, the shape is a label
+like any other and the score is decoration on every subsequent reading of it. It is not
+discarded — `confidence` and `model_ref` are stored unchanged — and its home is the batch
+review loop, where a surface showing it must also name *what it measures*: a point-prompted
+mask score and a detection's prompt affinity are different quantities on different scales
+and cannot be pooled, thresholded or sorted together. **Where it is shown, it has one
+spelling, and that is whole percent**: `confidencePercent` in
+`frontend/annotator/src/adapters/react/paint.ts` — whoever shows the number imports it,
+because two notations for one quantity is a number that disagrees with itself. A `null`
+confidence reads as absent — never as `0`, never as a low score.
diff --git a/docs/ui/navigation.md b/docs/ui/navigation.md
new file mode 100644
index 00000000..5338c107
--- /dev/null
+++ b/docs/ui/navigation.md
@@ -0,0 +1,90 @@
+# Navigation
+
+How a person moves through VisionSet, and how the interface says where they are. The
+canonical sitemap — every route, tab, entry point and back-link — is the
+[`information-architecture`](../../.agents/skills/frontend/information-architecture/SKILL.md)
+skill; the routing implementation is [`docs/ui.md`](../ui.md) and
+[`docs/architecture/frontend/app.md`](../architecture/frontend/app.md). This page owns the
+UX rules those must satisfy.
+
+VisionSet is an **application**, not a website. Somebody who walks into a sub-view has to
+be able to walk back out of it *from the screen*, without reaching for the browser and
+without knowing the URL scheme.
+
+## Breadcrumbs and ancestor chains
+
+- **Every sub-view declares its ancestor chain, and it is rendered in full.**
+  `navigate(-1)` is not an ancestor: it means the gallery when you clicked a tile, nothing
+  at all on a fresh tab, and one asset at a time after walking forward through a job. Every
+  destination has to be the same however the page was reached — clicked through, pasted,
+  reloaded, or walked forward from a sibling. The destinations live in one `PARENT` table
+  in `app/src/routes.tsx`, because a destination is a fact about the route table and
+  `ui-core` deliberately has no router.
+
+  A single-level control is not enough. A control reading `← road-signs` — the *project's*
+  name — while landing on the project's Batches tab was right in both halves and complete
+  in neither; only the chain says both, and it reads `Projects / road-signs / Batches`.
+- **Ancestors only. The current page is the `<h1>`, never a crumb** — which is also why no
+  crumb carries `aria-current`. A breadcrumb repeating the heading beneath it spends a line
+  telling somebody what they are already reading.
+- **A tab in the query string is a level.** Tabs live in the URL because somebody links to
+  one and returns to it — that makes it somewhere you were, so it is somewhere you can be
+  sent back to.
+- **The affordance names its destinations.** "Back" alone is a promise about history;
+  "Projects", or a project's own name, is a promise about structure — the one the control
+  can keep. A name that has not loaded yet falls back to the noun (`parentLabel`) rather
+  than to nothing, so the control does not change width under a cursor that is already
+  aiming at it. Each crumb truncates with its full label in `title`, and the row never
+  wraps to a second line at any width.
+- **Placement follows the pane.** On a padded page it is `patterns/Breadcrumb.tsx` directly
+  above the page header: meta-size, muted, `/` separators and no arrow, pulled left by the
+  gutter so the first crumb aligns with the `<h1>` beneath it. On the full-bleed annotation
+  editor there is **no chain** — the way out is the first control in the top bar, a ghost
+  back-arrow meaning *up*, because that bar's left zone is already truncating to hold the
+  navigation cluster on the bar's centre, and crumbs there would be paid for out of the
+  frame's identity readout.
+- **Below `lg` the same chain collapses to `← <immediate parent>`.** One component, one
+  items array, one set of destinations, two presentations — and the collapse is CSS on one
+  DOM node per crumb, never a second list, so nothing is read twice by a screen reader and
+  the two presentations have nowhere to drift apart.
+- **A screen takes navigation as optional callbacks, never a route.** `ui-core` may not
+  import a router, so a host that has nowhere to send anybody renders no control rather
+  than a dead one. A screen omits a level it has no callback for, which is what makes an
+  empty chain mean *nothing to offer*. The host spells every URL; the screen supplies every
+  label.
+
+## The rail
+
+- **The rail is for top-level destinations only.** Per-screen return navigation never lives
+  on it — that is what lets it name where it goes. A rail destination has no breadcrumb of
+  its own, for the reason a tab has none: the rail *is* its way out, and a second answer to
+  "where am I" inside the pane would contradict it.
+- **What earns a rail entry**: a workspace-level object every project uses, which has
+  nowhere else to live. Model connections carry no project id, so a project tab would state
+  a scope the object does not have. A destination that belongs to one project does not
+  qualify, however often it is visited. The current entries: logo, collapse toggle, Home,
+  Projects, Inference, account at the bottom — nothing else.
+- **Rail widths** (current implementation, a single source of truth): 240px, 60px
+  collapsed, 280px mobile.
+
+## The browser, and what belongs in the URL
+
+- **The browser's Back button stays correct, and is never the only way out.** Nothing here
+  replaces it; a `replace` navigation is still right where a change is a view of the same
+  resource rather than a place (a tab, or the annotator's current asset). A URL that no
+  longer describes what is on screen is not a place you can send somebody, and `replace` is
+  what stops Back from walking back through tabs — or one picture at a time through an
+  annotation session.
+- **A control that means "show me more of what I am already in" does not navigate.** The
+  annotation page's arrow means *up*: it exits to the batch, saving first. Its grid button
+  means *switch frames* — so it opens a gallery overlay inside the editor and the URL does
+  not move. Going up and looking at your own frames are different intentions, and only one
+  of them is a reason to leave. The overlay is a switcher and nothing else: no batch
+  actions, no selection, no route change.
+- **Not everything selectable is a place.** A tab is in the query string because somebody
+  links to it and returns to it; the schema version somebody is glancing at is component
+  state, because it is a lens on the tab they are already in. The test is whether the thing
+  survives being pasted to a colleague as a destination — if the answer is "they would want
+  the current one instead", it is view state and the URL should not carry it. Getting this
+  wrong in the other direction is worse than it looks: `ui-core` has no router, so every
+  URL-borne choice has to be threaded through the host as a prop and a callback.
diff --git a/docs/ui/product-principles.md b/docs/ui/product-principles.md
new file mode 100644
index 00000000..c76346be
--- /dev/null
+++ b/docs/ui/product-principles.md
@@ -0,0 +1,286 @@
+# Product UI principles
+
+VisionSet-specific product rules: how the interface behaves as a *dataset tool*, independent
+of the visual language. The visual foundations — colour, typography, spacing, materials,
+motion, accessibility — are [`DESIGN.md`](../../DESIGN.md) at the repository root. This page
+owns the rules that would survive a restyle: what a screen must show, offer, and refuse.
+
+Navigation behaviour is [navigation.md](navigation.md); the annotation workspace is
+[annotator.md](annotator.md); the data shell is [ui.md](../ui.md).
+
+## Principles
+
+1. **Data first.** VisionSet is a dataset tool, and every project-level screen surfaces real
+   data — counts, distributions, samples — before configuration. The test: if a screen would
+   render identically for an empty project and a 100k-image one, it is wrong. A schema
+   editor is the same document either way, which is why it cannot be a project's face.
+2. **Density over whitespace, on data surfaces.** Our users are ML engineers and
+   professional annotators working with large ontologies — a fifty-class ontology is
+   ordinary. Prefer compact lists, tables and two-panel layouts to spacious single-column
+   forms. This does not license crowding: it licenses showing more of the thing the user
+   came for.
+3. **Action-forward.** Every major screen answers "what do I do next?" with one clear
+   primary action. On a project page that action is annotating, never configuration.
+4. **Never disable without explanation.** A control either stays enabled and answers with a
+   message, or it carries an adjacent explanation of what would enable it, or it is not
+   rendered at all. A bare disabled grey button is forbidden — it is a question the
+   interface refuses to answer. The corollary runs the other way too: a control that exists
+   only because a callback might arrive renders nothing when the callback is absent, rather
+   than a dead button.
+5. **Destructive actions state their blast radius.** A confirmation dialog names what will
+   be destroyed, counted: *"Deletes the class and 4,372 annotations across 3 versions."* A
+   dialog that asks "are you sure?" without saying what yes costs is a speed bump, not a
+   confirmation. Where the count cannot be obtained accurately, the action does not ship
+   with a dialog that guesses.
+6. **Empty states invite.** An empty state names the space, explains it in one line, and
+   offers the next useful action with a verb-first label — "Ingest your first batch to see
+   stats here", never a bare "No items". A section with nothing in it is otherwise not
+   rendered at all: not a placeholder, not an apology.
+
+## Status semantics
+
+The visual foundation defines the status families and forbids colour-only status
+([`DESIGN.md`](../../DESIGN.md)); this is the product's authoritative mapping. A status
+picks an intent, never a colour, and there is **one mapping product-wide**:
+
+| Family | States |
+| --- | --- |
+| `success` | Done, settled, succeeded — `annotated`, `accepted`, batch `completed`, ingest `completed`, export `succeeded` |
+| `warning` | Waiting on a person — `review_pending` |
+| `error` | Failed — ingest `failed`, export `failed`, a corrupt file, a refusal |
+| neutral | Nothing has happened, or a decision was taken and nothing is wrong — `unannotated`, `skipped`, batch `draft`, export `queued`/`cancelled` |
+| `info` | Work is in flight — batch `in_annotation`, ingest `running`, export `running` |
+
+Three rules follow, and each was a real defect before it was a rule:
+
+1. **`error` styling is for errors only.** A `skipped` frame and a `cancelled` export are
+   *decisions*; painting them red tells somebody who chose an outcome that it went wrong.
+2. **`warning` means one thing: something is waiting on a person.** It is not "in
+   progress" — work in flight is the healthy majority state, and colouring the majority
+   state amber makes a list of ordinary work read as a list of problems.
+3. **"Finished" has one colour.** A completed batch and a completed ingest run are the same
+   fact about two nouns and read the same.
+
+**The word always rides with the colour.** The badge carries its label, the dot carries the
+word beside it, and where a dot has no room the accessible name and the tooltip carry it
+(`● annotated · Saved`). The per-asset dot also carries a second non-colour channel —
+`filled` / `ring` / `hollow` / `muted` says how far along a frame is — so the vocabulary
+survives a monochrome screen.
+
+The single spelling for the per-asset states is
+`frontend/ui-core/src/screens/batchState.ts` (`PROGRESS_TONE`, `progressDotClass`,
+`progressCellClass`). Every other family writes its own small map beside its own labels,
+typed against the shared `BadgeTone` union — so a new tone is a compile error rather than a
+diff nobody notices.
+
+## Numbers
+
+- Stat values use **tabular figures**, so a number that updates does not shift the ones
+  beside it.
+- Counts ≥ 1000 carry locale-aware thousands separators, through one shared helper —
+  `6431` and `6,431` on the same screen is how a call-site decision goes wrong.
+- Relative times under 7 days (`2d ago`), absolute beyond (`Jan 14, 2026`).
+- A percentage derived from a zero denominator is `0`, never `NaN` and never hidden.
+
+## Loading and async work
+
+The general feedback baseline (thresholds, minimum visibility, prose for long waits) is in
+[`DESIGN.md`](../../DESIGN.md). Two product rules sit on top of it:
+
+- **Indeterminate progress renders as prose, never as a bar.** An empty track reads as
+  *0%* — a lie in the one case where the truth is "this is going, and nobody can say how
+  far". A run whose total is unknown gets a sentence; the bar appears when there is a
+  fraction to draw.
+- **A threshold that hides a state needs evidence that the state occurs**, measured on a
+  real machine rather than argued from perception. A delay that suppresses nothing buys a
+  second state to maintain.
+
+## Lists and filtering
+
+Any list that can exceed ~20 rows carries a filter input. Filtering is client-side and
+instant, matches a name substring case-insensitively, and never hides the count of what it
+filtered out.
+
+### A list sectioned by what its rows enable
+
+Where the rows of a list are things a person configures so that *something else* becomes
+possible, the list is sectioned by the ability rather than sorted by the row — a heading
+naming the ability in a user's words, one line of prose naming the surface that consumes
+it, the rows serving it, and the section's own empty state. The Inference dashboard is the
+specimen. Four rules make it honest:
+
+- **The sections come from the data's own vocabulary**, never from a client-side reading of
+  what a row is. On Inference that is `capabilities`, which the server derives from the
+  model's weights.
+- **A section with a consuming surface invites; one without it only describes.** An ability
+  the product cannot yet use gets its heading, its prose and no control at all — a CTA
+  there is principle 4's dead button wearing a friendlier label.
+- **Nothing declared is invisible.** A value the build has no copy for gets a generic
+  section built from the value, and a row declaring no ability at all gets one too. A row
+  under no heading is a row nobody can act on.
+- **Section CTAs are secondary treatments.** The view's dominant action stays in the
+  header; otherwise a page of empty sections is a page of competing primaries.
+
+A filter crossing such a list empties sections it does not match, and an emptied section
+says *nothing here matches* rather than showing its invitation.
+
+## Tabs
+
+One tab shape, product-wide (`frontend/ui-core/src/primitives/Tabs.tsx`): a row on a
+full-width hairline; the active tab carries a 2px accent rule sitting on that hairline plus
+foreground text; an inactive tab carries no border, no fill and no shadow, and gets a
+subtle fill on hover or focus. The inactive tab keeps the same 2px border at `transparent`,
+so selecting one does not shift the row. There is deliberately **no extra weight bump** on
+the active tab — colour and the rule already carry it, and a second signal reflows the
+row's metrics for nothing.
+
+**The space between a tab bar and its content belongs to the primitive's content slot, and
+to nothing else** — one declaration, and a consumer must not add a gap of its own. The
+primitive owns it because that is the direction nobody can forget. Asserted by measurement
+rather than by a class string.
+
+No panel repeats its own tab's name as a heading: the tab already labels the panel, so a
+heading saying the same word is a stutter for a reader and for a screen reader both.
+
+## Screen rules
+
+### Home
+
+Home is the workspace's front page and answers a different question from a list: a list
+answers *what exists*; Home answers **what is waiting on me, and where do I carry on** —
+which no single project can answer. It carries nothing project-scoped; every row is a
+pointer, and pressing it goes to the screen that owns the thing.
+
+- **Two states.** A workspace with no projects renders one invitation and nothing else — a
+  headline, a line of body, the dominant **Create Project** action, and three quiet cards
+  naming the cycle (ingest, annotate, release) with no controls on them. Once a project
+  exists this state never returns, and the dashboard renders with real zeros wherever the
+  numbers are genuinely zero.
+- **A section with nothing in it is not rendered** — absent, not a placeholder. The stat
+  cards are the deliberate exception: a count of zero is a measurement, and cards that came
+  and went would make the aside jump on every visit.
+- **The resume card** names a project, a batch, a count in tabular figures, and a picture of
+  the frame it would open. It holds the view's dominant action. It is ranked by when
+  somebody last worked the batch; batches with no recorded work rank behind every batch
+  that has some, ordered among themselves by progress.
+- **The label is load-bearing, and the wire picks it.** The card renders one of three
+  promises: **Continue Annotating** (a frame nobody has judged), **Review Annotations**
+  (labeling done, frames waiting on a reviewer), **Open Batch** (nothing to open in the
+  editor). The first two go to the editor, the third to the gallery — a button claiming a
+  frame that does not exist would land somewhere empty. Which applies is decided by the
+  kernel and carried on the response, because a judgment spelled once in the kernel and
+  again in the browser is one that drifts.
+- **Attention rows** are one line each: a batch holding frames awaiting review, a failed
+  background job, a running background job. A review row links to its batch. A job row
+  links nowhere and says so by not being a link — no screen shows a background job, and
+  inventing a destination would be principle 4's dead button with a friendlier label.
+- **Activity** is a projection over timestamps that already exist, never an event log,
+  capped at about eight and newest first. The copy must not overstate what a timestamp
+  records: an ingest row reports *the last data that arrived*, not a run finishing, and a
+  schema row reports a version being created, because which version is active is derived.
+- **The dominant action tracks the state.** First run offers Create Project. A workspace
+  with somewhere to carry on offers whichever action the resume card resolved to, and the
+  header's own New Project steps back to a secondary treatment behind it. Only a workspace
+  with nothing open at all — every batch finished, nothing waiting on a reviewer — offers
+  New Project as the dominant action. The first-run CTA opens the same dialog the project
+  list's button opens, rather than navigating to the screen that carries it: a button
+  labelled *Create Project* that only moved somewhere else would promise an action it does
+  not perform.
+
+### Project surfaces
+
+The project view is the face of a project, and principle 1 is the rule it exists to keep.
+
+**The header** is four lines and two buttons, in this order: the breadcrumb (per
+[navigation.md](navigation.md)); the project name at the page-title role; the description
+**if there is one** — if not, render *nothing*, because "No description." spends a line
+telling somebody about a field rather than about their project; metadata chips (task type,
+sensor modality, active schema version, last ingest). **A chip with no data is omitted,
+never rendered as a placeholder** — inventing a field to fill a chip, or rendering
+`Unknown`, is the "No description." mistake with a border around it.
+
+Actions are right-aligned: one dominant action, one secondary, and an overflow menu (`⋯`)
+for the rest — never more than two visible buttons plus the overflow. On the project page
+the dominant action is **Annotate**, because principle 3 asks what the user came to do and
+the answer is never "rename this".
+
+**Annotate has three shapes, and the cost of the choice tracks the ambiguity.** With no
+batch open for annotation there is nowhere to send anybody, so the button is absent and
+Ingest takes the dominant slot — principle 4, rather than a disabled control that never
+says what would enable it. With exactly one, it jumps straight there. With two or more it
+reads `Annotate ▾` and opens a menu of those batches, each row carrying the batch name, its
+remaining count, and the schema version it is pinned to. The chevron is not decoration: a
+button that opens a choice must not be shaped like one that jumps. The pinned version earns
+its place because which batch you pick decides which schema you annotate under. Never a
+silent default, and never one remembered from last time: a control's destination may not be
+a function of session history.
+
+**The first run renders exactly one invitation, driven by the project's state.** No classes
+and no images invites the classes (naming the other order beneath it as prose, because both
+are legitimate); classes and no images invites the ingest; images and no classes invites
+the classes again. A project with both gets no invitation and is the dashboard. **It guides
+and never gates** — Ingest and Schema stay independently reachable throughout, and where
+the invitation holds the page's dominant action the header steps its own Ingest back to a
+secondary treatment.
+
+### Versioning is ambient, not modal
+
+Schema version state is a persistent status line — `Version 1 active · unsaved changes
+create v2` — never a tooltip, a dialog, or a disabled save button. The user should never
+have to press something to discover what pressing it would do. Its corollary, from
+principle 4: **Save Version is always enabled.** Pressing it with no changes shows a toast
+and issues no request.
+
+## Component contracts
+
+Presentational contracts, all in `ui-core`, all data-only — no fetching, no router:
+
+| Component | Contract |
+| --- | --- |
+| `StatCard` | Muted meta-size label above a large value, tinted surface, no border. Used in grids of 3–4. Optional context line under the value. |
+| `DistributionBar` | One row of a bar chart: swatch · fixed-width label · proportional bar in the class colour · right-aligned count. All bars in one chart share a single max-value scale. |
+| `ClassListRow` | Swatch + name + a `geometry · count` secondary line. Selected = tinted background + 2px left accent rule covering the row's full height. The whole row is the click target and a real `<button>` — except when it carries shape chips, which are press targets and cannot nest inside a button: that row is a `role="group"` with an inner name button, addressed by the same `-name` handle in both markups. A row carrying a refusal never takes the group form, because only the button can be disabled. |
+| `EmptyState` | Icon + a headline naming the space + one line of body + a verb-first CTA. Never a bare "No items". |
+| `ThumbnailGrid` | Square tiles, 6px gap, small radius. The last tile becomes a `+N` overflow linking onward. Missing thumbnails show a photo icon on a subtle fill — never a broken-image glyph. |
+| Chip | `primitives/Badge.tsx`, which already is one. It gains variants; it is not reimplemented. |
+
+**Class colour is data, not chrome.** It appears as a small swatch or a thin bar and never
+floods a card or a row — the content-over-chrome rule applied to a colour the *kernel*
+chose. The single derivation lives in `frontend/ui-core/src/palette.ts` (`classColor`,
+schema colour first, else a name hash); a second derivation path is a defect.
+
+**A geometry picker groups its options by category, and the category is presentation
+only** — the kernel takes no category concept, because a market segment is not a domain
+concept. The single map is `frontend/ui-core/src/data/geometryCategory.ts`, declared total
+over the generated `GeometryType` union so an uncategorised geometry fails the build rather
+than falling quietly out of a list; headings are non-selectable labels and a category with
+nothing under it renders none.
+
+**An option that is an identifier plus the facts about it takes two lines** — the
+identifier at the label role, the facts beneath it at the meta role. It is `SelectItem`'s
+`meta` prop, so the closed trigger shows the same two lines the open list does; the trigger
+grows to fit, leaving every one-line select on the contract's control height. **Nothing
+truncates**: an identifier cut off in the middle is not an identifier, so a long one wraps.
+
+## Layout specifics (current implementation)
+
+The visual foundation defines layout *principles* ([`DESIGN.md`](../../DESIGN.md)); the
+exact values below are screen-level decisions of the current implementation and are owned
+here.
+
+- **Page widths**: lists/dashboards/detail `max-w-7xl`; forms/settings `max-w-3xl`;
+  centered, `px-4 md:px-6 py-6`.
+- **Dialog widths**: the primitive's default `max-w-lg` for a confirmation or a form of
+  stacked single fields; `max-w-2xl` for a form whose fields sit side by side (its grid
+  splits on a *viewport* breakpoint, so the box must be wide enough for a split it cannot
+  prevent); `max-w-3xl` for a dialog whose content is a grid rather than a form. Three
+  sizes; a fourth needs a written reason rather than an eye-picked value. **Any dialog
+  whose content grows with the data carries `max-h-[85vh] overflow-y-auto`** — a centred
+  dialog taller than the viewport overflows off both edges and takes its own footer with
+  it, which is not a state a person can recover from.
+- **Page header**: title + subtitle left, actions right, hairline below, section-scale
+  margin beneath.
+- **Grids**: cards at `gap-6`, 2/3 columns by breakpoint; 16px is the default layout unit,
+  24px separates page sections. Detail two-column: `1fr / 320px`, stacking below `lg`.
+  Breakpoints 640 / 768 / 1024 / 1280.
+- **Rail widths** live with the rail's other rules in [navigation.md](navigation.md).