@felloinnovations/brand-kit 0.4.0 → 0.5.1

package/README.md

@@ -54,13 +54,14 @@ folder trust prompt once, and needs GitHub access to FelloInnovations, since the
 }
 ```
 
-The plugin carries the same `fello-brand-kit` skill as claude.ai, plus three commands:
+The plugin carries the same `fello-brand-kit` skill as claude.ai, plus four commands:
 
 | Command | What it does |
 | --- | --- |
 | `/brand-kit:brand-audit` | Read-only report: raw values, drift from tokens, pages that cannot scroll, fields with no white ground, small targets, contrast, console errors. |
 | `/brand-kit:brand-adopt` | Migrates an existing app onto the kit, in stages, building between each. |
 | `/brand-kit:brand-new` | Scaffolds a new app already on the kit. |
+| `/brand-kit:brand-feedback` | Sends what the kit was missing or got wrong as one issue per gap on this repo. The other skills offer it when they finish. |
 
 Audit before adopt, so someone who does not read code sees what is wrong before anything is rewritten.
 
@@ -74,12 +75,33 @@ bun add @felloinnovations/brand-kit
 ```
 
 ```css
+/* the font first: after Tailwind's rules a browser drops an @import, so fello.css's own one never loads here */
+@import url("https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400..700&display=swap");
 @import "tailwindcss";
 @import "@felloinnovations/brand-kit/tokens.css"; /* tokens as a Tailwind v4 @theme */
-@import "@felloinnovations/brand-kit/fello.css";  /* the whole kit: font, tokens, ws-* component classes */
+@import "@felloinnovations/brand-kit/fello.css";  /* the whole kit: tokens, ws-* component classes */
 @source "../node_modules/@felloinnovations/brand-kit/dist";
 ```
 
+`fello.css` sits inside Tailwind's own layers, so your utilities still win. Beyond `html` and `body`, it touches only
+elements with a `ws-*` class or inside one. Any unlayered CSS of yours (a bare `button` or `body` rule) also beats the
+kit now; keep such rules in a layer, or take the scoped build below.
+
+An app that lives inside a host it does not own (a platform's guest app, a bundle shared with other apps), or any
+Tailwind v3 app, takes the scoped build instead: every rule under a `.fello` root, nothing outside it changed.
+
+```tsx
+import { felloScopedCss } from '@felloinnovations/brand-kit/scoped';
+
+<div className="fello"><style>{felloScopedCss}</style>{/* the app */}</div>
+```
+
+The scoped build carries no font `@import`: link Instrument Sans in the app's head. `class="fello"` also goes on the root
+of every portal (a menu, a tooltip, a dialog rendered outside the app).
+
+Dark is opt-in: `<html data-theme="dark">`, or `data-theme="system"` to follow the person's setting; a page that sets
+nothing stays light.
+
 Then point the repo's agents at the guide: paste the block at the end of [AGENTS.md](AGENTS.md) into its `CLAUDE.md`.
 
 > A `github:FelloInnovations/brand-kit` git dependency does **not** work: the repo is private and bun resolves that
@@ -90,12 +112,12 @@ Then point the repo's agents at the guide: paste the block at the end of [AGENTS
 One line, pinned to a version:
 
 ```html
-<link rel="stylesheet" href="https://brand-kit-site-production.up.railway.app/v/0.4.0/fello.css">
+<link rel="stylesheet" href="https://brand-kit-site-production.up.railway.app/v/0.5.1/fello.css">
 ```
 
 Then use the `ws-*` classes and `var(--token)`; the markup for each component is in the gallery. `/latest/` exists
 too, but a live page should pin. A claude.ai artifact cannot link it (artifacts load stylesheets only from Google
-Fonts), which is why the skill carries `fello.css` and inlines it.
+Fonts), which is why the skill carries `fello-core.css` and each component's blocks, and inlines only those.
 
 ---
 
@@ -105,7 +127,9 @@ Fonts), which is why the skill carries `fello.css` and inlines it.
   the component catalog (`components/<Name>/README.md` and `preview.html`). Started from Lokesh's design system,
   built from the first product on the kit.
 - **`tokens/`**: generated token files. Every token and its value is in `tokens/tokens.md`.
-- **`dist/fello.css`**: the one stylesheet. **`tokens/tokens.css`**: tokens only, Tailwind v4.
+- **`dist/fello.css`**: the one stylesheet, in cascade layers. **`dist/fello.scoped.css`** and
+  `@felloinnovations/brand-kit/scoped`: the same under a `.fello` root. **`tokens/tokens.css`**: tokens only, Tailwind
+  v4. **`tokens/shadcn-compat.css`** and **`shadcn-compat.hsl.css`**: shadcn's variables pointed at the kit.
 - **React components**: `Button` · `Badge` · `Card` · `Input` · `Label` · `Checkbox` · `Radio` / `RadioGroup` ·
   `Tabs` · `Skeleton` · `Stat`, and `Toaster` from `@felloinnovations/brand-kit/toast` (needs `sonner`). Most are the
   marketing layer; product screens are built from the catalog. See [AGENTS.md](AGENTS.md) for which is which.
@@ -133,7 +157,8 @@ Two navies and two fonts, all shipping as "Fello". This package is the one copy.
 
 ## Known gaps
 
-- **No dark mode.** None was designed. Do not invent one.
+- **Dark is derived, not drawn.** The dark theme is Fello's shipped night and navy grounds; Seth has drawn no dark
+  frames, so the glass stage and the frame gradient in dark are a flat interim.
 - **Feedback colours are provisional.** `--color-feedback-*`, `--color-alert` and `--color-stat-positive` came from
   the HubSpot boilerplate and will change.
 - **The kit `Button`'s `tertiary` and `clean` themes are placeholders**: the Figma capture never specified their
@@ -158,11 +183,13 @@ is no longer maintained. Only the kit's owners (Amit and Arpan) change tokens.
 
 ## Releasing
 
-CI publishes. Bump `version` in `package.json` (and `plugin/.claude-plugin/plugin.json`, and the pinned `/v/` links
-in `skill/SKILL.md`), run `yarn build` and `yarn skill`, commit, then push a tag that matches:
+CI publishes. Before the bump, keep the released hosted tree: `yarn hosted`, then copy `site-dist/v/<released
+version>` to `hosted/v/` (the gallery serves every snapshot there, so pinned links keep working). Bump `version` in
+`package.json` and the pinned `/v/` links (`AGENTS.md`, `skill/SKILL.md`, this README, `Starter`, guide 01; the plugin is
+unversioned), run `yarn build` and `yarn skill`, commit, then push a tag that matches:
 
 ```sh
-git tag v0.4.0 && git push origin v0.4.0
+git tag v0.5.1 && git push origin v0.5.1
 ```
 
 `.github/workflows/publish.yml` checks the tag matches `package.json`, builds, and publishes to npm through npm's
@@ -179,4 +206,6 @@ yarn build          # tokens + dist
 yarn skill          # the skill zip and plugin/skills/brand-kit/
 yarn build:site     # static gallery into site-dist/
 yarn typecheck
+yarn check:geometry # every preview at 320, 390 and 1440 (--theme dark, --hover, --only Name1,Name2)
+yarn check:scope    # proves the scoped build changes nothing outside .fello, and fello.css's resets miss the host
 ```

package/design-system/01-how-claude-decides.md

@@ -14,10 +14,10 @@ below.
 3. **Pick components** from the tables in Choosing components and copy their preview markup: the kit's CSS styles every
    one (in an artifact, `fello-core.css` plus the styles each component's card lists). Never redraw a catalog piece.
 4. **Keep the five firm rules**: tokens only, never an invented value; one face per surface; colour means something
-   (salmon never a button or a word, never red, no AI colours outside the orb); one primary per card and per page;
-   honest data and plain words (no faked card or number, sentence case, no em dashes).
+   (salmon never a button or a word, red only for an alert, no AI colours outside the orb); one primary per card and
+   per page; honest data and plain words (no faked card or number, sentence case, no em dashes).
 5. **Run the quick check** in a browser at desktop (1440×900) and phone (390×844): no sideways scroll, nothing clipped,
-   your own text AA on its surface, one primary.
+   one content edge, your own text AA on its surface, one primary, focus visible.
 
 Open another chapter only when the job needs it: a chart, Charts; a form, Patterns; a public page, Public pages; a layout
 to start from, Page recipes.
@@ -44,10 +44,10 @@ rest; a mockup about to ship takes all steps.
 | | Product layer | Marketing layer |
 | --- | --- | --- |
 | When | after sign-in, or anything used to do work | before sign-in, or anything that sells |
-| Surface | the cream page and cream cards, a 0.5 px edge, 8 px corners, flat | the cream page, white `KitCard`s at 4 px, flat unless clickable |
-| The one act | a solid navy `Button`, 4 px corners | the salmon gradient `KitButton`, large (45 px), with its 3 px lift |
+| Surface | the cream page and rimmed cream cards (a 1 px grey rim, 8 px corners), flat | the cream page, white `KitCard`s at 4 px, flat unless clickable |
+| The one act | a solid navy `Button`, 6 px corners | the salmon gradient `KitButton`, large (45 px), with its 3 px lift |
 | Words | 14 px body, 22 px titles | 16 px body, an 18 px lead, headings on the kit's big steps (48 to 64) |
-| Targets | 32 px controls, 40 on touch | 44 px at least |
+| Targets | 32 px controls, 40 on touch, 24 for words that act | 44 px at least |
 | Pieces | the product components | `MarketingNav`, `Hero`, `FeatureGrid`, `Testimonial`, `PricingTable`, `Footer`, `KitButton`, `KitCard`, `KitInput`, `Stat` |
 | Decoration | none: colour is spent on data | the Felix orb and the dot grid only |
 | Rules | Colour to Checklist | Public pages, then Content, Accessibility, Checklist |
@@ -57,10 +57,13 @@ rest; a mockup about to ship takes all steps.
 | Where | Setup |
 | --- | --- |
 | A claude.ai artifact | inline `fello-core.css` plus the styles of only the components used, in one `<style>` (an artifact loads stylesheets only from Google Fonts; the whole `fello.css` is too big to paste) |
-| A plain HTML page or a static site | link the pinned file: `https://brand-kit-site-production.up.railway.app/v/0.4.0/fello.css` |
-| A Next, Vite or Turbo app | install `@felloinnovations/brand-kit`, import `fello.css` or `tokens.css` (Tailwind v4), read its `AGENTS.md` |
+| A plain HTML page or a static site | link the pinned file: `https://brand-kit-site-production.up.railway.app/v/0.5.1/fello.css` |
+| A Next, Vite or Turbo app that owns its page | install `@felloinnovations/brand-kit`, import `fello.css` (it sits in Tailwind's layers, so utilities win) or `tokens.css` (Tailwind v4), with the Instrument Sans `@import` first (before `@import "tailwindcss"`) or a `<link>`; read its `AGENTS.md` |
+| An app inside a host it does not own (a shared bundle, a platform's guest app), or any Tailwind v3 app | the scoped build: `fello.scoped.css`, or the string from `@felloinnovations/brand-kit/scoped` injected in a `<style>`, under `class="fello"` on the app's root and on every portal's root; nothing outside it changes; it carries no font, so link Instrument Sans (the `brand-adopt` skill has the steps) |
 | Claude Design or Slides | this system is the organisation's default; nothing to load |
 | An email | literal values from the kit's `tokens.ts`, inlined on each element (email clients drop custom properties) |
+| Dark (any of the above) | opt-in on the root: `data-theme="dark"`, or `"system"` to follow the person's setting; an artifact writes `"system"`. A page that sets nothing stays light (Colour) |
+| A palette (any of the above) | an app with its own slightly different colours: `data-palette="cool"` or `"warm"` on the root or the app's container, or its own palette from the contract, checked with `check-palette` and shipped as its `--emit` writes it (Palettes). Never its own values on `:root` |
 | The HubSpot site theme | out of scope: it carries its own tokens and rules |
 
 ## 1. Start from a real reference
@@ -111,14 +114,16 @@ Decisions with the rules it derives from, so the kit's owners can take it.
 ## 5. Apply the foundations
 
 Tokens for every value (Colour, Type, Space and layout); never invent one, and say so when none fits. The face's sizing
-profile (Sizing profiles). The scrolling rule (Scrolling): every page scrolls, and nothing is trapped behind an
-`overflow: hidden` or a fixed-height parent. Fields white on the cream (`ws-field`). One primary per card and per page. Say
-each thing once.
+profile (Sizing profiles). The scrolling rule (Scrolling): every page scrolls, the shell's body owns the scroll, nothing
+is squashed or trapped behind an `overflow: hidden` or a fixed-height parent. One content edge per surface and numbers in
+fixed columns (Space and layout). Fields white on the cream (`ws-field`). One primary per card and per page. Say each
+thing once.
 
 ## 6. Cover every state
 
-Default, loading (a skeleton, not a spinner), empty (first use, no matches, unavailable), error with recovery, pending on a
-press, success, long labels, narrow width, touch, reduced motion, keyboard. A public page adds the form's error and its
+Default, the interaction states (hover, press, focus, selected, pending, disabled: Patterns), loading (a shimmer over the
+ghost, not a spinner), empty (first use, no matches, unavailable), error with recovery, success, long labels, narrow
+width, touch, dark, reduced motion, keyboard. A public page adds the form's error and its
 success (with what happens next), a slow network, an image that fails, and a refused microphone or camera (how to allow it
 in that browser, and Try again). A screen with only its happy path is half a screen.
 
@@ -126,20 +131,24 @@ in that browser, and Try again). A screen with only its happy path is half a scr
 
 A screenshot proves how something looks, not that it works. Open it in a real browser at desktop 1440×900 and phone
 390×844 (a workspace also at 1280×800, 1920×1080 and the panel width; a Figma build at its frame sizes and the three sizes
-in step 1) and run the Checklist. An app with sign-in is crawled page by page as each role at both sizes; the bar is no
-console errors, no failed requests, no broken pages.
+in step 1) and run the Checklist, in light and, when the page opts in, dark. A component or a preview also passes the
+geometry check at 320, 390 and 1440 (`node scripts/check-geometry.mjs --only <Name>`, with `--theme dark`,
+`--hover`, then `--hover --motion`): open every screenshot it writes. An app with sign-in is crawled page by page as each role at both sizes; the bar is no console errors, no failed
+requests, no broken pages.
 
 ## 8. Show it back
 
 Build first, then show: the link, screenshots at desktop and phone, the rationale. Lead with the choice and the reason; name
 the face, the recipe and the components; list the states covered and what was measured; name what you left out and why;
-flag anything the system did not cover so it can be added. Never present a guess as a rule.
+flag anything the system did not cover so it can be added (offer to send each gap as an issue:
+`https://github.com/FelloInnovations/brand-kit/issues/new?template=feedback.yml`). Never present a guess as a rule.
 
 ## Three levels of freedom
 
 - **Firm** (never bend): tokens and their meanings; the two layers kept apart; the colour rules (salmon small in a product,
   the gradient only on the marketing act, no AI colours outside the orb, navy for the one product button, AA words beside
-  exact marks); native semantics; touch floors and focus; honest data from one source; no em dashes; nothing
+  exact marks); native semantics; touch floors and the visible focus ring; still under reduced motion; dark only when
+  the page opts in; honest data from one source; no em dashes; nothing
   developer-facing; one home per thing, one act per card; the performance budget on a public page.
 - **Defaults** (bend with a reason in the rationale): densities, gaps, widths, the number of cards, what sits above the
   fold, whether a region scrolls, which chart draws a figure, a public page's section rhythm.

package/design-system/02-principles.md

@@ -19,10 +19,12 @@ What the system optimises for, in the order it breaks ties. Each has a test.
    with it? If not, it should not have been coloured.
 6. **Compact components, breathing room between them** (the numbers are in Space and layout). Density comes from
    prioritising and grouping, never from shrinking words or clipping content. A public page is roomier (13).
-7. **Flat, with fine edges.** No float; lift is a signal reserved for a menu or a dialog (and a clickable card on a
-   public page).
-8. **Motion explains, never decorates**: short, from where the thing belongs, nothing looping but the one working beat,
-   still under reduced motion (Motion).
+7. **Flat, rimmed, one edge.** A cream surface in a fine grey rim, no float; lift is a signal reserved for what floats
+   (a menu, a tip, a dialog, a tile opened out of its slot, and a clickable card on a public page). Every block in a
+   surface starts on one edge, and numbers line up in their columns.
+8. **Motion explains, never decorates**: things grow from where they were and go back the same way, details settle
+   after their frame, hover is a colour, nothing that carries data loops, and everything is still under reduced motion
+   (Motion).
 9. **Words are AA, marks are exact.** The designer's salmon and teal stay on bars and dots; the words beside them take the
    AA step. A screen is not done until every text pair passes.
 10. **Honest data, one source** (How Claude decides, step 3). A comparison with a teammate is a role ("Team best"), never
@@ -32,7 +34,8 @@ What the system optimises for, in the order it breaks ties. Each has a test.
 13. **Fit the reader and the device**: compact for daily work at a desk, roomy and thumb-sized for a public page read
     once on a phone (Sizing profiles). Test: on a 390 px phone, can a thumb hit every act and the eye read every word?
 14. **Measured, not eyeballed.** "Matches the design" and "works" are claims proven in a browser at the sizes people use.
-    Test: was it run at desktop and phone, nothing clipped, every target and text pair checked?
+    Test: did the geometry check run at 320, 390 and 1440, light and dark, and was every screenshot looked at: nothing
+    clipped, every target and text pair checked?
 15. **Undo beats confirm; a skeleton beats a spinner; a banner beats a popup; a word beats an icon alone.**
 
 ## Anti-patterns (seen and removed)
@@ -41,4 +44,6 @@ White cards on the cream in a product; float shadows on every card; navy pills,
 buttons; a grey plate holding white rows; two lists of the same calls; a headline that repeats the card under it; a tab row
 with its own styles; a styled `<button>`; a purple glow or a rainbow ring to mean "AI"; red for a falling number; an
 "assistant" box on a page; a spinner where a skeleton belongs; a card invented to fill a gap in the data; an em dash; a total on screen that differs from the one sent; a field with no
-white ground; a page that cannot scroll; a reveal only on hover; two booking buttons on one phone screen.
+white ground; a page that cannot scroll; a reveal only on hover; two booking buttons on one phone screen; a card squashed
+to nothing by the scroller it sits in; insets that nearly agree (14, 16, 17 and 20 in one card); figures that do not line
+up down a list; a focus ring taken away; a hover that lifts a button; a dash standing in for a missing number.

package/design-system/03-colour.md

@@ -1,37 +1,74 @@
 # Colour
 
 The palette is the kit's; the rules are the product's. The balance fello.ai keeps is the rule: about 84% warm neutrals,
-navy for headings and a few large pieces, salmon small but on every screen, mid blue only as secondary text, teal for
-positive.
+navy for headings and a few large pieces, salmon small but on every screen, mid blue as secondary words, teal for
+positive. Marks keep Seth's exact tones; a word in a tone takes its AA step on the ground it sits on (D2).
 
 ## By role
 
-| Role | Token | Value |
+| Role | Token | Light |
 | --- | --- | --- |
-| The page, every card, a secondary button, a field at rest | `color-bg-page` | #FEFBF9 |
-| A plate, a track, a hover, the person's bubble, the footer band | `ws-surface-sunk`, `ws-chart-foot` | #F3F1EF |
+| The page, every card's surface, a secondary button, a filter's chip select | `color-bg-page` | #FEFBF9 |
+| What is white: a marketing card, a well row under the pointer, the person's chat bubble | `color-surface` | white |
+| A menu, a dialog, a panel, a popover, a tooltip | `ws-raised` | the cream |
+| A plate, the footer band | `ws-surface-sunk`, `ws-chart-foot` | #F3F1EF |
 | A row under a press | `ws-surface-press` | #E9E6E4 |
-| A field | `ws-field` | white |
-| A well behind rows | `ws-well` | #EDEDED |
+| The tray a card sits in (its rim and its foot), a well behind rows | `ws-tray`, `ws-well` | #EDEDED |
+| A rimmed card's rim under the pointer | `ws-well-hover` | #E4E2DF |
+| An empty track (a meter, an empty tick, an upload bar) | `ws-track` | #EDEDED |
+| A field's ground, also when focused | `ws-field` | white |
+| A field's words | `ws-field-ink` | #292929 |
 | The grey around the stage | `ws-page` | #E8E8E8 |
-| A card's, field's, tab track's edge | `ws-edge-card` at `ws-hairline` | #D3D3D3, 0.5 px |
-| A chip's edge | `ws-edge-chip` | #D9D5D0 |
-| A day cell's or empty tick's edge | `ws-edge-slot` | #E2E2E2 |
-| The band's top edge | `ws-edge-tray` | #D9D3CB |
-| Titles, a row's name, figures, the primary button, the tab thumb | `color-text-heading` | navy #093555 |
+| A divider between rows, a field's or control's edge, a chip's edge, a slot's edge | `ws-edge`, `ws-edge-card`, `ws-edge-chip`, `ws-edge-slot` | 0.5 px |
+| Titles, a row's name, figures, the primary button's fill, the thumb, navy marks | `color-text-heading` | navy #093555 |
+| Words and marks on the navy act fill | `ws-on-act` | white |
 | Body, a card's line, rows | `color-text-body` | #545454 |
-| Meta, labels, captions | `color-text-muted` | #6E6E6E |
-| A field's placeholder | `color-text-placeholder` | #6E6E6E |
-| Links, words that act, a falling number, "working", a field's focus edge | `color-text-interactive` | mid blue #495883 |
-| Good news in words | `ws-word-positive` | #09787F |
-| Something to fix in words | `ws-word-needs` | #B35040 |
-| Done, passed, positive marks | `ws-chart-finished` / `color-stat-positive` | teal #098486 |
+| Meta, labels, captions, placeholders | `color-text-muted`, `color-text-placeholder` | #666666, #6E6E6E |
+| Links, words that go somewhere, a falling number, "working", "getting there" | `color-text-interactive` | mid blue #495883 |
+| Good news in words | `ws-word-positive` | #09717A |
+| Something to fix in words, needs you | `ws-word-needs` | #A84B3C |
+| Needs work in words | `ws-word-needs-work` | #B42D68 |
+| An alert in words | `ws-word-alert` | #B1042F |
+| Past halfway in words | `ws-word-past-half` | #6D4FC2 |
+| Done, passed, positive marks | `ws-chart-finished`, `color-stat-positive` | teal #098486 |
 | Past halfway marks | `ws-chart-past-half` | purple #6D4FC2 |
-| Under halfway marks, needs-you dots | `ws-chart-under-half` / `color-brand-salmon` | salmon #FF725C |
-| A needs-you chip's tint | `ws-tint-needs` | #FFF1EF |
-| A done chip's tint | `ws-tint-live` | #E1F0F0 |
+| Under halfway marks, needs-you dots | `ws-chart-under-half`, `color-brand-salmon` | salmon #FF725C |
+| Needs work marks | `ws-chart-needs-work` | pink #F370A4 |
+| Alert marks | `ws-chart-alert` | #B1042F |
+| Chip tints: needs you, done, needs work | `ws-tint-needs`, `ws-tint-live`, `ws-tint-needs-work` | |
+| Hover washes (navy at .03, .05, .06) | `ws-hover-faint`, `ws-hover`, `ws-hover-strong` | |
+| The ink of a wash, a ring or a line of your own; the tint of a drop | `ws-ink`, `ws-shade` | navy (in dark, the heading's light ink and black) |
+| A floating navy message (a toast, the note tip) and the footer, and their words | `ws-inverse`, `ws-on-inverse` | the act and its words; in dark the brand navy and white |
+| An off control (a switch's track at rest) | `ws-control-off` | #7F7F7F |
+| The loading shimmer's ground: the ghost grey, with a lighter pass of the same grey (never a chart hue) | `ws-shimmer-ground` | #E3DFDB (`ws-ghost`) |
+| A hero's glows, an assistant's working orb | `ws-glow-rose`, `ws-glow-pink`, `ws-glow-blue`, `ws-orb` | from the chart tones |
+| Focus | `ws-focus-color` | navy |
 | Behind a dialog | `ws-scrim` | navy 35% |
 
+For your own wash or shadow, write `color-mix(in srgb, var(--ws-ink) 5%, transparent)` and the same with `--ws-shade`:
+they follow the theme and the palette. The 0.4 channels (`rgba(var(--ws-ink-rgb), a)`, `--ws-shade-rgb`) still paint,
+but follow only the theme, never a palette. Never `--color-white` for a surface, `--color-gray-2` for a track or
+`--color-brand-navy` for a mark; the semantic name is what turns in dark and in a palette. Brand artwork keeps the brand
+navy.
+
+Four kit names are aliases of product tokens, so they follow a palette too: `color-border-default` is `ws-edge`,
+`color-border-hairline` is `ws-edge-card`, `color-stat-positive` is `ws-chart-finished` and `color-text-brand-strong`
+is `ws-word-needs`.
+
+## Rating tones
+
+One scale for a rating (a score, a check, a grade), the same on every screen (D10).
+
+| Band | Mark | Words | Example |
+| --- | --- | --- | --- |
+| Strong | `ws-rating-strong` (teal) | `ws-word-positive` | "Strong", 72 of 100 |
+| Getting there (the middle) | `ws-rating-middle` (mid blue) | `color-text-interactive` | "Getting there" |
+| Needs work | `ws-rating-needs-work` (pink) | `ws-word-needs-work` | "Needs work", 39 of 100 |
+| Not checked | every mark on `ws-track` | `color-text-muted` | "Could not check" |
+
+A strip of ticks or a bar takes the band's one tone; its words take the band's word token. Salmon stays "needs you"
+(acts and alerts that wait on the person), never a rating.
+
 ## States, in colour and a word
 
 | State | How it shows |
@@ -41,42 +78,93 @@ positive.
 | Done, passed | teal mark, `ws-word-positive` words ("Passed") |
 | Not yet | mid blue words ("Not yet"), never red |
 | Settled, the same | grey |
+| Alert (something is wrong now) | an alert mark (`ws-chart-alert`) and `ws-word-alert` words |
 | Error | a salmon border on the field, a warning mark and `ws-word-needs` words under it |
 
 Never a state by colour alone: a word or a mark goes with it.
 
 ## Rules
 
-- **Navy is for words and the one button.** No navy pills, chips, badges or card buttons. The tab thumb and a selected
-  toggle are the two navy fills a control may wear.
-- **Salmon is a data tone and small marks.** Never a button, a wash, a card, a strip or a word.
+- **Navy is for words, the one button and a few named fills**: the tab or segmented thumb, a selected toggle, a checked
+  box, the navy note (a tooltip holding a question's full words), a count in the nav and a floating message (a toast, a
+  selection's ask). No navy pills, chips or badges scattered through content.
+- **Salmon is a data tone and small marks.** Never a button, a wash, a card or a strip. A word in salmon's hue is
+  `ws-word-needs`, never the raw salmon.
 - **Mid blue is never a fill.**
-- **Teal, purple and salmon are the goal gradient**: a strip of ticks runs salmon (start) through purple (past halfway) to
-  teal (finished); rows carry a stretch of it (`TickRow`). Never other gradients.
+- **The goal gradient** (salmon, purple, teal) belongs to `GoalTicks` and `TickRow`: a strip of ticks running from the
+  start to finished. A strip that shows a rating takes one tone (Rating tones); `TickStrip` is one tone. Never other
+  gradients.
+- **A falling number is mid blue**, never red. Alert red is for something wrong now (a count of reviews needing a
+  reply, a failed check), as a mark with its word.
 - **An assistant's mark** takes one of the four tones and keeps it; no other colour names it.
-- **The AI colours** (`color-ai-*`) exist only inside an assistant's orb mark, if the product has one, and as faint washes in
-  `ws-cool-glow` and `ws-team-glow` behind a page hero. No conic rings, purple glows or gradient text anywhere.
+- **The AI colours** (`color-ai-*`) exist only inside an assistant's orb mark, if the product has one, and as faint washes
+  in `ws-cool-glow` and `ws-team-glow` behind a page hero. No conic rings, purple glows or gradient text, except the
+  status line's word while an answer works (`StatusLine`, in the chart colours). The loading shimmer is one neutral
+  tone, the ghost grey and a lighter pass of it, never the chart colours (0.5.1).
 - **People are neutral**: a disc of `ws-surface-sunk` with navy initials.
 - **Marketing pages** keep the kit's own marketing colours (its gradient button, `color-text-primary`); they never enter a
   product screen.
+- **Map Figma by value, never by name**: Seth's variable "Gray 5" (#7F7F7F) is the kit's `color-gray-6` and his "Gray 6"
+  (#545454) is the kit's `color-gray-7`.
 
-## Contrast, measured on the cream (#FEFBF9)
+## Contrast: words AA on every ground
 
-| Pair | Ratio | Verdict |
-| --- | --- | --- |
-| navy on cream | 12.3 | AA, AAA |
-| gray-7 (#545454) on cream | 7.4 | AA, AAA |
-| mid blue on cream | 6.8 | AA |
-| purple #6D4FC2 on cream | 5.7 | AA (a word in purple is allowed) |
-| `ws-word-positive` #09787F on cream | 5.1 | AA |
-| `ws-word-needs` #B35040 on cream | 4.9 | AA |
-| teal #098486 on cream | 4.4 | marks only, not words |
-| `color-text-muted` #6E6E6E on cream | 4.95 | AA (5.1 on white, 4.5 on the sunk surface) |
-| gray-6 (#7F7F7F) on cream | 3.9 | a mark or a disabled control only, never words |
-| salmon #FF725C on cream | 2.6 | marks only |
-| `color-feedback-error` #EF6B51 on cream | 2.9 | a border only |
-| `color-text-placeholder` #6E6E6E on white | 5.1 | AA; still never the only label |
-| white on navy | 12.7 | AA, AAA |
-
-Every pair marked AA may carry words at any size, so muted words carry 12 and 13 px meta. gray-6 and the lighter greys
-are for marks, rules and disabled controls only, never words.
+Every word token passes 4.5:1 on all eight grounds a word can sit on, in light, night and the navy ground. The token
+generator computes it and stops the build on a fail; the full tables are in tokens.md. The light ratios:
+
+| Word | cream | white | plate | tray | raised | shell | press | well |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `color-text-heading` | 12.34 | 12.71 | 11.28 | 10.86 | 12.34 | 10.37 | 10.23 | 10.86 |
+| `color-text-body` | 7.35 | 7.57 | 6.72 | 6.47 | 7.35 | 6.18 | 6.10 | 6.47 |
+| `color-text-muted` | 5.57 | 5.74 | 5.10 | 4.90 | 5.57 | 4.69 | 4.62 | 4.90 |
+| `color-text-interactive` | 6.78 | 6.98 | 6.20 | 5.97 | 6.78 | 5.70 | 5.62 | 5.97 |
+| `ws-word-needs` | 5.45 | 5.62 | 4.99 | 4.80 | 5.45 | 4.59 | 4.52 | 4.80 |
+| `ws-word-positive` | 5.58 | 5.75 | 5.10 | 4.91 | 5.58 | 4.69 | 4.63 | 4.91 |
+| `ws-word-needs-work` | 5.80 | 5.97 | 5.30 | 5.10 | 5.80 | 4.87 | 4.81 | 5.10 |
+| `ws-word-alert` | 6.96 | 7.17 | 6.37 | 6.13 | 6.96 | 5.85 | 5.77 | 6.13 |
+| `ws-word-past-half` | 5.74 | 5.92 | 5.25 | 5.06 | 5.74 | 4.83 | 4.76 | 5.06 |
+
+On their own tints: needs words 5.11, positive words 4.90, needs-work words 4.80. A placeholder on a field 5.10. White
+on navy 12.71.
+
+- **A mark keeps its exact tone** and needs 3:1 where it carries meaning: teal #098486, salmon #FF725C, pink #F370A4 and
+  the alert red stay marks; the words beside them take the word token.
+- **Below AA is never a word**: Seth's #7F7F7F, #8A8A8A, #929292, raw teal, salmon and pink words become
+  `color-text-muted` or the tone's word token. `color-gray-6` and lighter greys are for marks, rules and disabled
+  controls only.
+- **A word on the tray's foot** uses these tokens; each one passes there.
+
+## Dark theme
+
+Opt-in, never automatic (D12). A page that sets nothing stays light.
+
+| Want | Set on `<html>`, or on any container |
+| --- | --- |
+| Light (the default) | nothing, or `data-theme="light"` |
+| Night, always | `data-theme="dark"` |
+| Follow the person's system | `data-theme="system"` |
+| The navy ground, for brand and event pages | `data-ground="navy"` beside `dark` or `system` |
+
+- **Night** is the product's dark: shell #0A1118, stage #0F1922, raised #16222D. **Navy** is for brand and event pages:
+  the ground #021A32 with white mixed in as things lift. Product apps use night. On a container, the theme holds for
+  everything inside it, and the nearest one wins (light inside dark works, and the reverse).
+- **Brand colours stay literal** in every theme: white is white, navy is navy, salmon is salmon. Only the semantic tokens
+  turn, which is why a component says `color-surface`, `ws-raised`, `ws-track`, `ws-field-ink`, `ws-on-act` and
+  `color-text-heading` rather than a palette colour.
+- **Prefer a token over a theme selector.** If a component must write one, it uses `[data-theme="dark"] .ws-x` (on any
+  element, not only `:root`) and repeats it for `system` inside `@media (prefers-color-scheme: dark)`. Never a colour
+  literal in a component's styles: `build-bundle --check` fails on one.
+- **Every word pair is AA in dark too** (the tables in tokens.md). In dark a navy mark is the heading's light ink; a
+  floating navy message (a note, a toast) keeps the brand navy with a faint light rim; the footer stays the navy band.
+- **Floating things in dark** sit on `ws-raised` with a 0.5 px light rim and a black shadow (the floating shadows carry
+  it). Cards stay flat with their rim.
+- **A person's choice** (System, Light, Dark) is `ThemeSwitch`: it reads the choice before first paint and turns every
+  surface at once.
+- **Check it**: `node scripts/check-geometry.mjs --theme dark` (Checklist).
+
+## Palettes
+
+An app with its own slightly different colours sets a palette, never its own values on `:root`: a built-in
+(`data-palette="cool"` or `"warm"`) or one it writes from the contract, checks with `check-palette` and ships as
+`check-palette --emit` writes it. A palette works on any element, light or dark, and every rule in this chapter holds
+in it (Palettes).

package/design-system/04-type.md

@@ -1,41 +1,63 @@
 # Type
 
-One family, Instrument Sans (`--font-body`), from Google Fonts. Three weights: 400 body, 500 rows, buttons and values,
-600 titles. Nothing bold (700). Tabular numerals on every figure.
+One family, Instrument Sans (`--font-body`), from Google Fonts. Three weights: 400 body and figures, 500 rows, controls
+and values, 600 titles. Nothing bold (700). Tabular numerals on every figure. Seth's steps (D6) are in the table.
 
 ## The hierarchy, by role
 
 | Role | Style | Size / line | Weight | Where |
 | --- | --- | --- | --- | --- |
-| A page's headline | `headline` | 26 / 32 | 600 | the app page's bar |
-| A hero's headline | `hero` | 40 / 48 | 600 | grows from 26 at the `lg` area (PageHero) |
-| The home greeting | `greeting` | 24 / 32 | 600 | "Morning, Ryan." |
-| A card's, pane's or dialog's title | `title` | 22 / 28, -0.5% | 600 | every card, side pane, panel |
-| A section inside a card, a tile's title | `section` | 16 / 20, -0.5% | 600 | "Where they came from" |
+| A report's score | `ws-figure--score` | 96 / 96, -3% | 400 | the one hero figure on a report (`ScoreHero`) |
+| A card's one number | `ws-display` | 72 / 80, -3% | 400 | GoalTicks; one per card |
+| A pane's figure | `ws-figure--pane` | 44 / 48, untracked | 400 | a drawer's score, "1 of 6", a vendor's yearly cost |
+| A big figure in a stat | `ws-figure` | 40 / 40, -3% | 400 | a metric tile, a card's stat |
+| A tile's figure | `ws-figure--tile` | 32 / 38, -3% | 400 | a `StatTiles` tile, an inbox tile ("5.0", "10") |
+| A row's figure | `ws-figure--row` | 28 / 32, -3% | 400 | a check row's score, right-aligned in its column |
+| A hero's headline | `hero` | 40 / 48 | 600 | grows from 26 at the `lg` area (PageHero); a dashboard home's greeting |
+| A page's headline | `headline` | 26 / 32 | 600 | a `PageHero` below the `lg` area |
+| The home greeting | `greeting` | 24 / 32 | 600 | "Morning, Ryan." on a chat-first home |
+| A card's, pane's or dialog's title | `ws-title` | 22 / 28, untracked, balanced | 600 | every card, drawer, panel; an area heading over its cards |
+| A thread or app page's title | `thread` | 16 / 22 | 600 | the 56 px header ("Audit report") |
+| A section, a finding, a fix, a column name, a stat's value | `ws-section` | 15 / 22, untracked, balanced | 600 | "Your AI visibility checks", "5 of 9" |
+| A row's name | `ws-row-name` | 15 / 20 | 500 | "Local search" in a check row |
 | A value in a row, a chart row's number, a band's line | `value` | 16 / 20 | 600 (500 on the band) | charts, bands |
 | A chart's values and labels | `chart` | 15 / 20 | 400 | "26 Total calls" |
-| The chat's words | `message` | 15 / 24 | 400 | an agent's plain text, the person's bubble |
-| A row's title | `row-title` | 14 / 20 | 600 | a person, a fix, an idea |
-| Body, a card's line, a field's words | `body` | 14 / 20 | 400 | everywhere |
-| A button's or link's words | `button` | 14 / 16 | 500 | every button |
-| A time, a header's second word, the band's "how" | `meta` | 13 / 16 | 400 | muted |
-| Labels, chips, a row's detail, field labels | `dense` | 12 / 16 | 400 (500 in a chip or a field label) | ws-muted |
-| The uppercase label above a group | `eyebrow` | 12 / 16, +1.2 px | 600 | ws-eyebrow |
-| A chart's axis letters | `micro` | 11 / 16 | 400 | M T W; the floor |
-| A big figure in a tile or score | `figure` | 40 / 40, -3% | 400 | StatTiles |
-| A card's one number | `display` | 72 / 80, -3% | 400 | GoalTicks; one per card |
+| The chat's words | `message` | 15 / 22 | 500 | an agent's answer, a step darker than body (`ChatTurn`); the person's bubble is 14 / 20 500 navy |
+| Body, a description, a card's line, a field's words | `ws-body` | 14 / 20 | 400 | everywhere |
+| Control words: tabs, buttons, tags, status words, stat labels | `ws-control-words` | 13 / 18 | 500 | "Refresh", "2 fixes", "Found" |
+| A time, a header's second word, the band's "how" | `ws-meta` | 13 / 16 | 400 | muted |
+| Labels, a row's detail, field labels | `ws-muted` | 12 / 16 | 400 (500 in a field label) | muted |
+| The uppercase label above a group | `ws-eyebrow` | 12 / 16, +1.2 px | 600 | muted |
+| A small sub-line under a name or a figure | `micro` | 11 / 13 | 400 or 500 | a list row's sub-line, a seat caption |
+| A chart's axis letters | `micro` | 11 / 16 | 400 | M T W |
+
+Tokens: `ws-text-score` and `ws-leading-score`, `ws-text-figure-lg`, `ws-text-figure`, `ws-text-figure-row` and their
+`ws-leading-*`; `ws-text-section` with `ws-leading-section` (and `ws-leading-row` for a row's name); `ws-text-control`
+with `ws-leading-control`; `ws-text-micro` with `ws-leading-micro` for a sub-line.
 
 ## Rules
 
 - **Every text takes its size from its role**, never from what its container leaves unsized (an unsized line inherits
   the page's 16 px).
-- **Nothing under 11 px**, and 11 only for a chart's axis letters. The kit's 10 px step is marketing only.
+- **Nothing under 11 px.** 11 is only for an axis letter, a sub-line under a name or a figure, a key cap (`Kbd`) and a
+  small head, count or note, each passing AA on its ground. The kit's 10 px step is marketing only.
 - **Titles say the answer**: a sentence in sentence case, no colon, no trailing period. One per card.
-- **One 72 px number per card**, regular weight, with its change chip beside it; a second big number is a second card.
-- **Links and buttons are medium**, never underlined at rest; underlined under the pointer.
-- **Line length**: the chat's column is 656 px; running text elsewhere stays under about 70 characters a line.
+- **Tracking**: only the figures are tightened (-3%: `ws-display`, `ws-figure` and the row, tile and score steps worn
+  with it); titles, sections and the pane's 44 are untracked, as Seth draws them. A long title or section balances its lines, so no word sits alone on the last.
+- **One hero figure per card and per screen region**: a 96 px score on a report, or a 72 px number on a card, with its
+  change chip or rating word beside or under it. Smaller figures in rows (28) and a pane (44) are allowed alongside,
+  each in its own column; a second hero is a second card.
+- **A figure keeps its size** at every width; what gives is the room around it.
+- **Links and quiet acts are medium**, never underlined at rest; underlined under the pointer.
+- **A cell whose full words show on hover or focus** carries a 1 px dotted underline, and the full words also show on
+  focus and on a tap (Accessibility).
+- **Line length**: the chat's column is its shell's (Space and layout, Layout widths); running text elsewhere stays
+  under about 70 characters a line.
 - **Truncation**: a row's title truncates with an ellipsis and carries its full words in `title`; a card's title wraps,
-  never truncates; a number never truncates (give it room or drop a word beside it).
+  never truncates; a number never truncates (give it room or drop a word beside it). A row stays one line so a narrow
+  column never pushes its button out; a sentence may wrap, its button never does (unless it opts in with `ws-btn--wrap`).
+- **Text in a clipping box** gets a line height that clears its ink (or clips sideways only), so descenders are never cut.
 - **Long translations and names**: a label may be twice as long; a layout that breaks at that length is wrong, not the
   label.
-- **Marketing pages** use the kit's bigger steps (`kit-lg` to `kit-8xl`); the product never goes above 72.
+- **A selected row keeps its type**: its weight may change, never its size or line height (Space and layout).
+- **Marketing pages** use the kit's bigger steps (`kit-lg` to `kit-8xl`); the product's largest figure is the 96 px score.