@nurix/etna 0.19.3 → 0.19.4

package/data/harnesses/code/skills/design/references/personality.md

@@ -4,15 +4,21 @@
 DTCG JSON files whose grammar, payload, and resolution rules are the frozen transport schema,
 [SCHEMA.md](../data/design-tokens/SCHEMA.md). [`derive-personality.mjs`](../scripts/derive-personality.mjs)
 is the reference consumer: `--check` is the coverage gate that must pass before `--emit` writes
-`personality.css`, `globals.css`, and the `<html>` attributes. The emitted files *are* the state —
-no sidecar cache, no intermediate document. (The design.md format exists only as the library's
-curated documentation corpus, `data/design-md/library/`; the machine path reads token files.)
+`personality.css`, `globals.css`, `fonts.css`, and the `<html>` attributes. The emitted files *are*
+the state — no sidecar cache, no intermediate document. (The design.md format exists only as the
+library's curated documentation corpus, `data/design-md/library/`; the machine path reads token files.)
 
 The look comes entirely from the cascade. A surface composes in semantic tokens (`bg-card`,
 `text-foreground`) and reads its personality from the CSS variables emission writes. Swap the
 artifact, re-emit, and every surface re-skins with zero JSX edits — the invariant the exemplars are
 validated against.
 
+Emission is a **contract with checks**, not a template with hopes: every authored token group
+reaches consumable, renderable output, and each contract names the check that fails closed when it
+doesn't — the cascade armor (§4, verified rendered by cod-15 on the render rung), font binding
+(§5, cod-16 at `--emit`), emitter completeness (§6, at `--emit`), and the Tailwind compile smoke
+(`snapshot-goldens.mjs`, run at every goldens refresh).
+
 Every CSS and comment excerpt in this document is pasted from a real emission of the shipped Nurix
 default (`data/design-tokens/nurix/`); gate transcripts are from real runs, with scratch paths
 shown as `<artifact-dir>`.
@@ -21,32 +27,34 @@ shown as `<artifact-dir>`.
 
 ```
 design-tokens artifact ──▶ derive-personality.mjs --check ──▶ (green) ──▶ --emit <outdir>
-  design.tokens.json           the coverage gate (rules 1–12):             src/styles/personality.css
-  design.tokens.dark.json?     26 primitives + 2 dials + density tier      src/styles/globals.css
-  design.resolver.json         + 34 color roles + typography 3+6,          index-html-attributes.txt
+  design.tokens.json           the coverage gate (rules 1–15):             src/styles/personality.css
+  design.tokens.dark.json?     27 primitives + 2 dials + density tier      src/styles/globals.css
+  design.resolver.json         + 36 color roles + typography 3+7           src/styles/fonts.css
+                               + elevation 4 + optional wash,              index-html-attributes.txt
                                each assigned or hinted, or exit 1
 ```
 
 ```
-derive-personality.mjs <artifact-dir> [--check | --emit <outdir>] [--theme light|dark]
+derive-personality.mjs <artifact-dir> [--check | --emit <outdir> [--provisional]] [--theme light|dark]
 ```
 
 **The artifact.** Three files in one directory: `design.tokens.json` (the base set — primitives,
-color roles, typography, and the file-level `$extensions["com.nurix.design"]` payload carrying
-`product`, `provenance`, the dials, and the lever manifest), `design.tokens.dark.json` (only when
-the look has dark values), and `design.resolver.json`. The script resolves them in the resolver's
-deterministic order — concatenate the set files, overlay the selected theme context, resolve aliases
-after overlay — then validates or emits. File shapes, `$type` grammar, and payload spec live in
+color roles, typography, elevation, the optional wash pair, and the file-level
+`$extensions["com.nurix.design"]` payload carrying `product`, `provenance`, `theme-default`,
+`anchors`, the dials, and the lever manifest), `design.tokens.dark.json` (only when the look has
+dark values), and `design.resolver.json`. The script resolves them in the resolver's deterministic
+order — concatenate the set files, overlay the selected theme context, resolve aliases after
+overlay — then validates or emits. File shapes, `$type` grammar, and payload spec live in
 [SCHEMA.md](../data/design-tokens/SCHEMA.md); this document covers what emission does with a
 resolved artifact.
 
-**`--check` never best-efforts.** It runs the schema's rules 1–12 and exits non-zero naming every
+**`--check` never best-efforts.** It runs the schema's rules 1–15 and exits non-zero naming every
 offending path, so the fix is mechanical; the `tokens` phase gate (and the verify/pre-ship sweeps)
 stay shut until it is green. Over the shipped default, from the skill root,
 `node scripts/derive-personality.mjs data/design-tokens/nurix --check` prints:
 
 ```
-check PASSED (data/design-tokens/nurix): rules 1–11 OK — 26 primitives, 34 color roles, typography 3+6, payload/manifest/parse-back OK — provenance=default, style=nurix, theme=light
+check PASSED (data/design-tokens/nurix): rules 1–15 OK — 27 primitives, 36 color roles, typography 3+7, elevation 4, payload/manifest/parse-back OK — provenance=default, style=nurix, theme=light
 ```
 
 Rule 12 (the emission precondition) is enforced at emit time; `--check` surfaces it as the
@@ -59,9 +67,13 @@ check FAILED (<artifact-dir>): 1 issue(s)
 ```
 
 **`--emit <outdir>`** runs only over a passing artifact and refuses while any token carries a hint
-(§3). It writes three files: `<outdir>/src/styles/personality.css`, `<outdir>/src/styles/globals.css`,
-and `<outdir>/index-html-attributes.txt` — the attribute set the project's `index.html` `<html>` tag
-must carry. In real use `<outdir>` is the project root.
+(§3), while any authored group lacks an emitter (§6), or while any emitted stack family fails the
+font-binding gate (§5). It writes four files: `<outdir>/src/styles/personality.css`,
+`<outdir>/src/styles/globals.css`, `<outdir>/src/styles/fonts.css`, and
+`<outdir>/index-html-attributes.txt` — the attribute set the project's `index.html` `<html>` tag
+must carry. In real use `<outdir>` is the project root. `--provisional` (the golden/regression
+flow only, never shipped output) emits hinted tokens at their provisional `$values` and demotes the
+font-binding gate to a loud warning.
 
 ### The emitted header is the cache record
 
@@ -79,7 +91,7 @@ attributes carry the same state in markup:
  *   density:   standard   (<html data-density="standard">)
  *   verbosity: default   (<html data-verbosity="default">)
  *   feedback:  subtle   (<html data-feedback="subtle">)
- *   theme:     light   (<html data-theme="light">)   — light is the default; dark is opt-in
+ *   theme:     light   (<html data-theme="light">)   — the payload's theme-default decides the boot theme
  *   artifact:  design.tokens.json (resolved via design.resolver.json)   — provenance: default, sourced 2026-07-04
  *
  * Semantic-token doctrine: components name purpose (bg-card, text-foreground, border-border);
@@ -106,21 +118,26 @@ Recovery therefore reads two things: the token artifact (the source) and the emi
 
 ## 2. Derivation — token paths to emitted CSS variables
 
-Leaf names are law: a `primitive.*` or `color.*` token maps 1:1 to the CSS variable of the same
-name, without the leading `--`.
+Leaf names are law: a `primitive.*`, `color.*`, `elevation.*`, or `wash.*` token maps 1:1 to the
+CSS variable of the same name (elevation as `--shadow-<level>`, wash as `--wash-<slot>`).
 
 | Artifact source | Emitted target | Rule |
 | --- | --- | --- |
-| `primitive.<name>` (24 static) | `[data-style="<slug>"] { --<name>: … }` | 1:1 by leaf name |
+| `primitive.<name>` (25 static) | `[data-style="<slug>"] { --<name>: … }` | 1:1 by leaf name |
 | `primitive.density-gap` / `density-inset` | governed refs `var(--density-base-gap/inset)` in `[data-style]` | the density tier writes the base (§4) |
-| `color.<name>` (34) | `:root, :root[data-theme="light"] { --<name>: … }` | 1:1 by leaf name |
-| dark set `color.<name>` | `[data-theme="dark"] { --<name>: … }` | only when the dark file ships (§5) |
+| `color.<name>` (36) | `:root, :root[data-theme="light"] { --<name>: … }` | 1:1 by leaf name, armored (§4) |
+| dark set `color.<name>` (36) | `:root[data-theme="dark"] { --<name>: … }` | only when the dark file ships (§7); same 0,2,0 armor |
+| `elevation.<level>` (4) | `--shadow-sm/md/lg/overlay` in `[data-style]` **and** the `@theme` shadow utilities | every layer alpha rides `calc(… * var(--shadow-intensity))` |
+| `wash.<slot>` (≤ 2, optional) | `--wash-surface` / `--wash-emphasis` in `[data-style]` | consumed only on budget-granted surfaces (col-16) |
+| `typography.ramp.<step>` (7) | `@theme` text utilities `text-h1` … `text-display` (size / line-height / weight / tracking per step) | the ramp becomes *classes* — the type scale IS the ramp (typ-09) |
+| `primitive.stagger-unit` | `--stagger-delay` + the named motion classes `.motion-lift` / `.motion-stagger` | mot-08 caps the cascade; mot-03 gates it behind `prefers-reduced-motion` |
 | payload `product` | `<html data-style="<slug>">` | slugified (lowercase, non-alphanumeric runs → `-`) |
 | payload `verbosity` / `feedback` / `density-tier` | `<html data-verbosity / data-feedback / data-density>` | dial → attribute |
-| payload `product-traits` | read by the front gate; **not** emitted to CSS | — |
+| payload `theme-default` | `<html data-theme>` | the boot theme; the `theme.ts` helper round-trips the same attribute (§7) |
+| payload `product-traits` / `anchors` | read by the front gate and improve/judge runs; **not** emitted to CSS | — |
 | `primitive.font-sans` / `font-mono`, `font-weight-normal` | `[data-style]` **and** literals in `@theme inline` | §4, two-weight discipline / no self-reference |
-| `typography.family.*` / `typography.ramp.*` | data for emitters and exemplars | reaches CSS only through the primitives it aliases |
-| — (derived at emit) | `--ease-enter`, `--ease-exit`, `--stagger-delay` | computed from `ease-default` + `duration-unit` |
+| `typography.family.*` / `typography.ramp.*` fontFamily | data for emitters, exemplars, and the fonts.css derivation (§5) | reaches CSS variables only through the primitives it aliases |
+| — (derived at emit) | `--ease-enter`, `--ease-exit`, `--stagger-delay` | computed from `ease-default` + `stagger-unit` |
 
 **The preserved-css rule.** For every emitted value the emitters prefer the token's
 `$extensions["com.nurix.design"].css` — the exact source string — so output is byte-stable across
@@ -128,27 +145,49 @@ convert/emit round trips (an aliased token takes its target's `.css`). Absent `.
 deterministic serialization applies: `dimension`/`duration` as `<value><unit>`; `number`/`fontWeight`
 as the plain number; `cubicBezier` as `cubic-bezier(x1, y1, x2, y2)`; `fontFamily` as the families
 joined with `", "`, multi-word names double-quoted; `color` as the `hex` field when srgb, else
-`oklch(…)`. The parse-back check (rule 9) guarantees the two forms agree before anything is emitted.
+`oklch(…)`; `shadow` and `gradient` as their serialized composite byte forms. The parse-back check
+(rule 9) guarantees the two forms agree before anything is emitted.
 
-**Derived, never stored.** Three temporal variables are computed at emit from `ease-default` and
-`duration-unit` — they are not tokens, not authored, and not gated (do not add them to an artifact):
+**Derived, never stored.** Three temporal variables are computed at emit — they are not tokens, not
+authored beyond their sources, and not gated (do not add them to an artifact):
 
 - `--ease-exit: var(--ease-default)` — departure mirrors the neutral curve.
 - `--ease-enter` — the emphasized-decelerate arrival curve `cubic-bezier(0.16, 1, 0.3, 1)` (fast
   in, settles clean); `ease-default` is reused verbatim when it is already a decelerate curve
   (y1 ≥ 0.9).
-- `--stagger-delay` — `duration-unit × 0.15`, rounded, clamped 0–40ms; a snappier tempo staggers
-  less.
+- `--stagger-delay: var(--stagger-unit)` — the `.motion-stagger` cascade base, riding the authored
+  `primitive.stagger-unit` (legal 0–60ms). This is the feel calibration in one number: **30ms reads
+  polished; 0ms reads utilitarian.**
 
-Emitted into the `[data-style]` block, directly after `ease-default`:
+Emitted into the `[data-style]` block, directly after the temporal family:
 
 ```css
-  --ease-default: cubic-bezier(0.4,0,0.2,1);
   --ease-enter: cubic-bezier(0.16, 1, 0.3, 1);   /* derived from ease-default */
   --ease-exit: var(--ease-default);              /* derived: departure mirrors the neutral curve */
-  --stagger-delay: 8ms;                          /* derived: duration-unit × 0.15, clamped 0–40ms */
+  --stagger-delay: var(--stagger-unit);                     /* derived: the motion-stagger cascade base */
 ```
 
+### The emitted block order — law
+
+The runtime cascade carries **contexts only** — theme, density, and the behavioral dials; every
+value was already resolved at generation time into the artifact. The emitted `personality.css`
+blocks, in order:
+
+1. **Header comment** — provenance (artifact → emit command), the CASCADE CONTRACT (naming **both**
+   armors and the exact loss mode, §4), the regeneration instruction.
+2. **The `:root` system baseline** — the 27 primitives at neutral operator defaults, the safety net
+   if `<html>` ever carries no `data-style`.
+3. **The light theme context** — `:root, :root[data-theme="light"]`, all 36 color roles, armored.
+4. **`[data-style="<slug>"]`** — the 27 primitives + the derived temporals (with their derivation
+   comments), the four elevation composites, and the optional wash pair; the one block
+   improve/extract rewrites.
+5. **The dial and density contexts** — `[data-verbosity]` / `[data-feedback]` / `[data-density]` /
+   `[data-density-step]` attribute blocks.
+6. **The dark theme context** — `:root[data-theme="dark"]`, all 36 dark roles (when the dark set
+   ships; a placeholder comment otherwise), same armor.
+7. **Motion moments** — `.motion-lift` / `.motion-stagger`, behind `prefers-reduced-motion`.
+8. **Accessibility contexts** — `prefers-reduced-motion: reduce` and `prefers-contrast: more`.
+
 **Dial semantics.** The payload's two behavioral dials become `<html>` attributes, and
 `personality.css` carries one block per dial value setting the behavioral variables the lifecycle
 and interaction layers read:
@@ -176,6 +215,16 @@ the ring variables ([interaction.md](./interaction.md)). A component that must b
 on a dial reads the `<html>` attribute — it never duplicates the state. Density (`data-density`) is
 spatial chrome, not behavior — it composes with the dials, never replaces them (§4).
 
+**Motion moments exist in behavior, not just variables.** Emission writes two named classes
+consuming the temporal tokens — `.motion-lift` (hover: −1px translateY + `elevation.sm` at
+`duration-fast`/`ease-default`) and `.motion-stagger` (children arrival cascade at
+`--stagger-delay`, capped at 8 children, mot-08; children past the cap arrive with the 8th) — both
+inert under `prefers-reduced-motion` (mot-03). `scaffold.mjs` consumes them where the archetype
+calls for them (table rows ride `motion-lift`; brand-forward card grids ride `motion-stagger` —
+baseline-stamped surfaces skip arrival cascades), and the exemplars demonstrate the same
+consumption. The render rung audits rendered stagger containers against the cap and the 1s
+total-sequence budget.
+
 ## 3. Hints — provisional values that pass the gate but block emission
 
 Where a value needs judgment, the token carries a **valid provisional `$value`** plus
@@ -193,7 +242,7 @@ A hinted artifact is checkable — the pass line counts the outstanding hints (t
 copy of the default with a hint added to `primitive.contrast-boost`):
 
 ```
-check PASSED (<artifact-dir>): rules 1–11 OK — 26 primitives, 34 color roles, typography 3+6, payload/manifest/parse-back OK — provenance=default, style=nurix, theme=light, 1 hint(s) outstanding (emit will refuse)
+check PASSED (<artifact-dir>): rules 1–15 OK — 27 primitives, 36 color roles, typography 3+7, elevation 4, payload/manifest/parse-back OK — provenance=default, style=nurix, theme=light, 1 hint(s) outstanding (emit will refuse)
 ```
 
 — but not emittable. `--emit` over the same artifact:
@@ -206,81 +255,102 @@ emit REFUSED (<artifact-dir>): 1 unresolved hint(s) — rule 12: every gated tok
 
 Resolving a hint is exactly that three-step: set the real `$value`, delete the `hint` key, record
 the rationale in the token's `$description` — so the resolved artifact stays self-explaining and
-re-derivable. Judgment is recorded, never silent.
+re-derivable. Judgment is recorded, never silent. (`--emit --provisional`, the golden/regression
+flow, emits hinted tokens at their provisional `$values` instead — loudly, and never as shipped
+output.)
 
 ## 4. The substrate contracts — living with `@nurix/components`
 
-`@nurix/components/dist/styles.css` ships its own bare-`:root` token defaults and its own `@theme`
+`@nurix/components/styles.css` ships its own bare-`:root` token defaults and its own `@theme`
 radius scale. Two cascade contracts keep the personality in charge; both are hardened with the
-emitted in-CSS comments below and enforced by the code-and-token rules (`cod-*`) in
-[hard-rules.md](./hard-rules.md). The library's actual consumption is enumerated in
-[the substrate audit](../../../docs/history/brainstorms/design/u1-audit-report.md).
+emitted in-CSS comments below, enforced by the code-and-token rules (`cod-*`) in
+[hard-rules.md](./hard-rules.md), and verified **rendered** by the render rung's per-theme drift
+check (cod-15). Measured at `@nurix/components@0.14.0`, the library directly consumes 15 of the 17
+v1 semantic color roles but only one personality primitive (`--radius`) — everything else reaches
+it through the consumer Tailwind build this file feeds (shadows, weights, tracking, and the density
+remap below).
 
-**CASCADE CONTRACT 1 — the specificity/attribute pair.** The color tokens are emitted under a
-doubled selector, and `<html>` must carry `data-theme="light"`:
+**CASCADE CONTRACT 1 — both theme blocks carry the same armor.** Light emits as
+`:root, :root[data-theme="light"]` and dark as `:root[data-theme="dark"]` — both specificity
+(0,2,0):
 
 ```css
 /* ── Semantic + substrate color tokens — light theme. ──
- * CASCADE CONTRACT 1: the doubled selector out-specifies the library's bare
- * :root defaults in @nurix/components/styles.css — but ONLY because <html> carries
- * data-theme="light". A bare :root here loses to the later library import. All 34
- * tokens are set (D6): no consumed token falls back to a shadcn-gray default. */
+ * CASCADE CONTRACT 1: both theme blocks carry the same 0,2,0 armor — light as
+ * :root, :root[data-theme="light"] and dark as :root[data-theme="dark"] — because
+ * a bare :root or a lone attribute selector loses to the library's later :root
+ * block in @nurix/components/styles.css by source order. All 36 tokens are set
+ * (D6): no consumed token falls back to a shadcn-gray default. */
 :root,
 :root[data-theme="light"] {
 ```
 
-*Failure mode:* a bare `:root { --background: … }` is specificity `(0,1,0)` — the library's own
-`:root { --background: … }` is also `(0,1,0)` and imported *later*, so it wins and every surface
-silently reverts to shadcn gray. The `:root[data-theme="light"]` arm is `(0,2,0)` and out-wins — but
-only if `data-theme="light"` is actually on `<html>`; drop the attribute and the arm never matches,
-leaving only the losing bare `:root`. Both halves are load-bearing together.
+*The exact loss mode:* a bare `:root { --background: … }` is specificity `(0,1,0)` — the library's
+own `:root { --background: … }` is also `(0,1,0)` and imported *later*, so it wins by source order
+and every surface silently reverts to shadcn gray. A lone `[data-theme="dark"]` attribute selector
+is the same `(0,1,0)` and loses the same way — the historical dark defect was exactly that
+unarmored selector, shipped while every static gate stayed green. The `:root[data-theme="…"]` arm
+is `(0,2,0)` and out-wins — but only if `<html>` actually carries the attribute; scaffold writes it
+from the payload's `theme-default`, and the render rung's cod-15 measures the rendered
+`--background`/`--foreground`/`--primary` per declared theme context against the authored values,
+so a cascade-dead theme block can no longer pass.
 
-**CASCADE CONTRACT 2 — the four-step import order.** The emitted `globals.css` opens:
+**CASCADE CONTRACT 2 — the five-step import order.** The emitted `globals.css` opens:
 
 ```css
 /* src/styles/globals.css — Tailwind v4 glue + @theme inline mappings (emitted). */
 
-/* CASCADE CONTRACT 2: this four-step order is LOAD-BEARING. The library's
- * styles.css ships its own :root token defaults and its own @theme radius scale;
- * our @theme MUST come AFTER the import to win the radius scale and own every
- * mapping. rules/frontend.md states the same order — co-authority. */
-@import "./personality.css";          /* 1. token source (must be first) */
-@import "tailwindcss";                /* 2. framework */
-@import "@nurix/components/styles.css"; /* 3. library (before our @theme) */
-
-@theme inline {                       /* 4. consumer theme — AFTER the library, so it wins */
+/* CASCADE CONTRACT 2: this five-step order is LOAD-BEARING. fonts.css registers the
+ * @fontsource faces before any stack consumes them; the library's styles.css ships
+ * its own :root token defaults and its own @theme radius scale, so our @theme MUST
+ * come AFTER the import to win the radius scale and own every mapping.
+ * rules/frontend.md states the same order — co-authority. */
+@import "./fonts.css";                /* 1. font registration (faces before stacks) */
+@import "./personality.css";          /* 2. token source */
+@import "tailwindcss";                /* 3. framework */
+@import "@nurix/components/styles.css"; /* 4. library (before our @theme) */
+
+@theme inline {                       /* 5. consumer theme — AFTER the library, so it wins */
 ```
 
 *Failure mode:* put `@theme inline` (or the whole consumer theme) *before* the library import and
 the library's own `@theme` radius scale (`--radius-lg: var(--radius)`, its own offsets) comes later
 and wins — the personality `--radius` stops driving the scale and archetype radius switching breaks.
-`rules/frontend.md` states this same order — co-authority, not a restatement to
-drift from. `@theme inline` inlines each value into the generated utilities (so `bg-card` compiles
-to `background-color: var(--card)`).
-
-**The gray-fallback trap — all 34 roles, always.** Beyond the 15 semantic color tokens it maps
-(888 semantic-token class uses), the library consumes **16 more shadcn tokens** — `--popover(-foreground)`,
-`--secondary(-foreground)`, `--chart-1..5`, and the `--sidebar` family — that silently fall back to
-the shadcn-gray defaults inside `dist/styles.css` when unset: popovers, menus, secondary buttons,
-sidebars, and charts render visibly off-palette next to personality surfaces. The artifact's
-substrate group carries 17 roles covering them, and emission sets all 34 color roles every time.
-`--color-destructive-foreground` is mapped explicitly in `@theme` because the library leaves it
-unmapped.
+The library also ships a `.dark`-class `@custom-variant`; the consumer's later redefinition (§7) is
+what makes library `dark:` utilities follow the `data-theme` attribute. `rules/frontend.md` states
+this same order — co-authority, not a restatement to drift from. `@theme inline` inlines each value
+into the generated utilities (so `bg-card` compiles to `background-color: var(--card)`).
+
+**The derivation-comment landmine.** Emitted comments explain derivations — and a CSS comment
+containing the literal sequence `p-*/gap-*` **closes the comment early** (`*/`) and breaks every
+consuming project's build. Emitters write "`p-*` and `gap-*`" instead; never paste a
+`utility-*/utility-*` pair into an emitted CSS comment. Goldens hash bytes and never compile them,
+so only the Tailwind compile smoke (`snapshot-goldens.mjs`, emission contract 5) catches this class
+of defect — it is part of every goldens refresh, not optional.
+
+**The gray-fallback trap — all 36 roles, always.** Beyond the semantic color tokens it maps, the
+library consumes shadcn tokens — `--popover(-foreground)`, `--secondary(-foreground)`,
+`--chart-1..5`, and the `--sidebar` family — that silently fall back to the shadcn-gray defaults
+inside its `styles.css` when unset: popovers, menus, secondary buttons, sidebars, and charts render
+visibly off-palette next to personality surfaces. The artifact's substrate group carries 17 roles
+covering them, the semantic group carries 19 (including the `surface-raised`/`surface-overlay` dark
+ladder), and emission sets all 36 color roles every time. `--color-destructive-foreground` is
+mapped explicitly in `@theme` because the library leaves it unmapped.
 
 **Coverage — every token the library consumes is emitted.**
 
 | Library consumes | How | Emitted at |
 | --- | --- | --- |
-| `--radius` (283 `rounded-*`) | direct primitive + `@theme` radius scale | `[data-style]` · `@theme` |
-| shadow (`shadow-xs/sm/md/lg`, 58) | `--shadow-*` alpha rides `--shadow-intensity` | `@theme` |
-| font weight (`font-medium/semibold/bold/normal`, 139) | two-weight map to `--font-weight-strong` | `@theme` |
-| tracking (`tracking-*`, 13) | `--tracking-tight/tighter → --heading-tracking` | `@theme` |
-| spacing (all `p-*`/`gap-*`) | `--spacing` density remap | `@theme` |
-| `font-mono` (9) / `font-sans` | literal font stacks | `@theme` |
-| 15 semantic colors (888 uses) | direct token values | `:root[data-theme=light]` |
-| `--success`, `--warning` | direct token values (library ignores today — upstream gaps) | `:root[data-theme=light]` |
+| `--radius` (`rounded-*`) | direct primitive + `@theme` radius scale | `[data-style]` · `@theme` |
+| shadows (`shadow-*`) | the four `elevation.*` composites; every alpha rides `--shadow-intensity` | `[data-style]` · `@theme` |
+| font weight (`font-medium/semibold/bold/normal`) | two-weight map to `--font-weight-strong` | `@theme` |
+| tracking (`tracking-*`) | `--tracking-tight/tighter → --heading-tracking` | `@theme` |
+| spacing (all `p-*` and `gap-*`) | `--spacing` density remap | `@theme` |
+| `font-sans` / `font-mono` | literal font stacks (faces registered by `fonts.css`, §5) | `@theme` |
+| type ramp (`text-h1` … `text-display`) | the seven authored steps as text utilities | `@theme` |
+| 19 semantic colors | direct token values | `:root, :root[data-theme="light"]` (+ dark armor) |
+| 17 substrate colors (`popover`/`secondary`/`chart-1..5`/`sidebar` family) | direct token values | same theme blocks |
 | `--destructive-foreground` (unmapped by library) | explicit `--color-destructive-foreground` map | `@theme` |
-| 17 substrate (`popover`/`secondary`/`chart-1..5`/`sidebar` family) | direct token values | `:root[data-theme=light]` |
 | `--sidebar-width` / `--sidebar-width-icon` | SidebarProvider `style` prop | shell (below) |
 
 **Density — global tier composed with a per-surface relative step.** Two composed levels, pure
@@ -296,25 +366,17 @@ emitted by `scaffold.mjs`) and re-derives one relative step off whatever tier th
 [data-density="dense"]    { --density-base-gap: 0.85; --density-base-inset: 0.85; }
 [data-density="standard"] { --density-base-gap: 1;    --density-base-inset: 1; }
 [data-density="spacious"] { --density-base-gap: 1.15; --density-base-inset: 1.15; }
-
-/* ── Per-archetype density modifier (D31) — relative step on the tier, pure cascade, no JS. ──
- * A surface element carries data-density-step; it re-derives one step off the
- * inherited base. Reads --density-base-* (never itself) so it composes with the
- * tier and never absolutely overrides it. The recomputed --density-gap flows into
- * the library's p-*/gap-* through the @theme --spacing remap. */
-[data-density-step="tighter"] { --density-gap: calc(var(--density-base-gap) * 0.85); --density-inset: calc(var(--density-base-inset) * 0.85); }
-[data-density-step="looser"]  { --density-gap: calc(var(--density-base-gap) * 1.15); --density-inset: calc(var(--density-base-inset) * 1.15); }
 ```
 
 A log-stream inside a `standard` app resolves one step denser without pinning an absolute value.
-Both levels reach the library's internals through one `@theme` line — every library `p-*`/`gap-*`
-is `calc(var(--spacing) × N)`, and `--density-gap` resolves per element (respecting a
+Both levels reach the library's internals through one `@theme` line — every library padding and gap
+utility is `calc(var(--spacing) × N)`, and `--density-gap` resolves per element (respecting a
 `data-density-step` ancestor):
 
 ```css
-  /* density remap — the single line that scales ALL library spacing. Every p-*/gap-*
-   * is calc(var(--spacing) × N); driving --spacing off --density-gap flows the tier
-   * AND the per-surface density step into the library's internals. */
+  /* density remap — the single line that scales ALL library spacing. Every p-* and
+   * gap-* is calc(var(--spacing) x N); driving --spacing off --density-gap flows the
+   * tier AND the per-surface density step into the library's internals. */
   --spacing: calc(0.25rem * var(--density-gap));
 ```
 
@@ -349,36 +411,98 @@ primitives in:
 >
 ```
 
-**Upstream gaps — expected, never worked around.** Some values live in `@nurix/components` JS, not
-CSS, so they do not follow tokens until the library adopts them. This is user-owned upstream work —
-never patched with brittle per-instance overrides:
-
-- **Chart palettes** — the d3 family hardcodes oklch/hex and ignores `--chart-1..5`; color props are
-  per-instance overridable, but the defaults are upstream. Emit `--chart-1..5` regardless, so
-  adoption is a drop-in.
-- **Status literals** — `changes-list` and `statistics` hardcode emerald/amber/sky rather than
-  `--success`/`--warning`.
-- **Motion & icon stroke** — `duration: .2/.3` and `strokeWidth: 2/1.75` are JS numbers;
-  `--duration-*` and `--icon-stroke` reach consumer-emitted markup but not library internals.
+**Substrate limits — expected, never worked around.** Some values live in `@nurix/components` JS,
+not CSS, so they do not follow tokens until the library adopts them (measured at 0.14.0; re-verify
+on upgrades). This is user-owned upstream work — never patched with brittle per-instance overrides:
+
+- **Chart palettes** — the d3 family's *defaults* embed literals, but the chart components accept
+  color props: scaffold's `src/lib/chart-colors.ts` wires `var(--chart-1..5)` through the series
+  props and the status roles (`--success`/`--warning`/`--destructive` + the accent/muted homes for
+  info/empty) through the BarGraph map, so charts inherit the theme today. Chart *chrome*
+  (gridlines, axis labels) stays hardcoded — a substrate limit, filed, never a v3 bug.
+- **Motion & icon stroke** — JS motion durations and icon `strokeWidth` numbers; `--duration-*` and
+  `--icon-stroke` reach consumer-emitted markup but not library internals. The density dial also
+  no-ops inside library tables (`h-8` row height).
 - **Filled-control foreground** — `text-white` pinned on filled primary/destructive; the mapped
   `--destructive-foreground` waits on the library reading it.
 
 The stance: emit the complete token surface so the library "just works" the moment it adopts each
 token; do not build an override layer that fights the library and rots.
 
-## 5. Dark and themes — the base set is light
+## 5. Fonts — one derivation, not two authored artifacts (contract 2)
+
+The artifact's font stacks and the project's installed fonts drift when they are two authored
+artifacts — a package registering `"Inter Variable"` while the stack says `"Inter"` means the
+flagship font silently never renders. Emission therefore derives both from one source:
+
+- `--emit` additionally writes **`src/styles/fonts.css`** — the `@fontsource` import list
+  **generated from the artifact's `fontFamily` tokens**, resolved through `typography.csv`'s
+  `css-import` column (paste-ready static packages, registering the plain family names) with
+  `fonts-known.json` as the resolver fallback. The emitted stacks use the **registered** family
+  names. `globals.css` loads it first (Cascade Contract 2), so faces register before any stack
+  consumes them.
+
+```css
+/* Inter — @fontsource/inter */
+@import '@fontsource/inter/400.css';
+@import '@fontsource/inter/500.css';
+@import '@fontsource/inter/600.css';
+@import '@fontsource/inter/700.css';
+
+/* Geist Mono — @fontsource/geist-mono */
+@import '@fontsource/geist-mono/400.css';
+```
+
+**The check (cod-16, fail-closed at `--emit`).** Every family name in every emitted stack either
+(a) matches a family registered by a generated import whose package exists in the emit target's
+`package.json` (when the target is a project; a standalone target degrades to import-list
+validation), or (b) is a recognized system/generic family (`system-ui`, `ui-monospace`,
+`sans-serif`, `serif`, `monospace`, `ui-sans-serif`, the conventional OS fallback faces, …the
+vocabulary is shared with the source-shell check in `lib/checks.mjs`). Failure exits non-zero
+naming the unbound family and the exact package to install:
+
+```
+emit FAILED (<artifact-dir>): font binding (cod-16) — 1 unbound family
+  - "Inter" (emitted --font-sans stack): its registering import needs @fontsource/inter, absent from package.json — npm install @fontsource/inter
+```
+
+A consumer that installed the variable package instead (`@fontsource-variable/<slug>`, registering
+the `"<Family> Variable"` name) also binds — the slug match strips the ` Variable` suffix. Brand
+fonts with no `@fontsource` package fail the gate by design: swap to a bindable family, or register
+the face via `@font-face` and record the deviation.
+
+## 6. Emitter completeness — no authored group vanishes (contract 3)
+
+Every authored token group has a named consumer in the emitted output; `--emit` fails if it
+recognizes a group it has no emitter for — machinery that accepts data it never emits is a silent
+contract breach (an authored ramp with no emitter simply vanishes). The registry: `primitive` (the
+`[data-style]` block), `color` (the armored theme blocks), `typography` (the `@theme` ramp text
+utilities; subgroups `family`/`ramp`), `elevation` (the shadow composites + utilities), `wash` (the
+wash pair — optional presence). Against a scratch artifact carrying an unconsumed `spacing` group:
+
+```
+emit FAILED (<artifact-dir>): 1 issue(s)
+  - emitter completeness — authored token group "spacing" has no emitter (contract 3): an authored group with no emitter simply vanishes; add its emitter to this script or remove the group. Emitters exist for: primitive, color, typography, elevation, wash.
+```
+
+## 7. Dark and themes — the base set is light; the brief's theme binds
 
 The base token set **is** the light rendering — light is never omitted, and the resolver's `light`
-context is always the empty overlay. A look with dark values ships `design.tokens.dark.json` —
-exactly the `color` group, all 34 roles, nothing else — named by the resolver's `dark` context and
-overlaid per the resolution order. When it ships, emission adds a `[data-theme="dark"]` block
-remapping all 34 roles:
+context is always the empty overlay. **The brief's stated theme is binding**: a dark-first look
+sets `theme-default: dark` (payload and resolver both), scaffold writes `<html data-theme="dark">`,
+and the app boots dark; light is the default only when the brief is silent. A look with dark values
+ships `design.tokens.dark.json` — exactly the `color` group, all 36 roles, nothing else — named by
+the resolver's `dark` context and overlaid per the resolution order. When it ships, emission adds
+the armored dark context remapping all 36 roles (including the `surface-raised`/`surface-overlay`
+lightness ladder — raised surfaces get *lighter* in dark, the physics shadows cannot fake):
 
 ```css
 /* ── Dark theme — OPT-IN ONLY (this look ships a dark overlay). ──
- * design.tokens.dark.json remaps all 34 color tokens; <html data-theme="dark">
- * opts in. Light stays the default. */
-[data-theme="dark"] {
+ * CASCADE CONTRACT 1b: :root[data-theme="dark"] (0,2,0) — a lone [data-theme="dark"]
+ * attribute selector (0,1,0) loses to the library's later bare :root block by source
+ * order. design.tokens.dark.json remaps all 36 color tokens; <html data-theme="dark">
+ * opts in (theme-default decides the boot attribute). */
+:root[data-theme="dark"] {
 ```
 
 For a light-only artifact (the shipped default is one), the emitted file carries a placeholder
@@ -386,43 +510,66 @@ comment instead:
 
 ```css
 /* ── Dark theme — OPT-IN ONLY. ──
- * Emitted only when the artifact ships a design.tokens.dark.json dark overlay.
- * Light stays the default; this block never appears for a light-only project.
-[data-theme="dark"] {
-  --background: ...; --foreground: ...; ... all 34 tokens remapped ...
+ * Emitted only when the artifact ships a design.tokens.dark.json dark overlay,
+ * as :root[data-theme="dark"] (0,2,0 — armored against the library's later :root).
+ * This block never appears for a light-only project.
+:root[data-theme="dark"] {
+  --background: ...; --foreground: ...; ... all 36 tokens remapped ...
 } */
 ```
 
 `--theme dark` selects the dark context and sets `<html data-theme="dark">` in the emitted
-attributes (the header's `theme:` line follows). The default is `light`; requesting dark from a
-light-only artifact fails cleanly —
-`node scripts/derive-personality.mjs data/design-tokens/nurix --check --theme dark` prints:
+attributes (the header's `theme:` line follows). Requesting dark from a light-only artifact fails
+cleanly — `node scripts/derive-personality.mjs data/design-tokens/nurix --check --theme dark`
+prints:
 
 ```
 check FAILED (data/design-tokens/nurix): 1 issue(s)
-  - rule 1 — resolver: --theme dark requested but the resolver carries no dark context
+  - rule 1 — resolver: theme dark selected but the resolver carries no dark context
 ```
 
-The library's `dark:` utilities are class-based; a dark-shipping project redefines the variant to
-follow the attribute. `globals.css` carries the instruction as a comment, enabled only when dark
-ships:
+**The `@custom-variant dark` line is always active.** The library's `dark:` utilities are
+class-based; the emitted `globals.css` redefines the variant to follow the attribute — always, not
+only when dark ships (the line is inert until `<html data-theme="dark">`, and library `dark:`
+utilities — legal *inside* the library, banned in project JSX by the no-literals rule cod-05 —
+must follow the same attribute the moment a dark set arrives):
 
 ```css
-/* dark variant — emitted ONLY when the project ships dark; redefines the library's
- * class-based dark to follow data-theme so the library's dark: utilities honor our
- * convention. Absent for a light-only project.
-@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *)); */
+/* dark variant — ALWAYS ACTIVE: redefines the library's class-based dark: variant to
+ * follow the data-theme attribute, so library dark: utilities (legal inside the library,
+ * banned in project JSX by the no-literals rule) track the same attribute the theme
+ * blocks armor. Inert until <html data-theme="dark">; harmless for a light-only project. */
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
 ```
 
+**The `theme.ts` helper — one selector convention, four writers, zero disagreement.** Scaffold
+emits `src/lib/theme.ts`: `getTheme`/`setTheme`/`toggleTheme` write the same `data-theme` attribute
+the armor selectors and the `@custom-variant` read, persisting the preference; `initTheme()`
+(called by `main.tsx` before mount) applies a stored preference over the boot attribute. Code is
+the cache: the attribute is the single runtime theme state — the helper never keeps a parallel
+copy. The four writers of the one convention: `personality.css` (the armored blocks), scaffold's
+`<html data-theme>` (the boot value from `theme-default`), the `@custom-variant dark` line, and
+`theme.ts` (the runtime toggle).
+
+**The check (cod-15, on the render rung).** With the app rendered and `data-theme` flipped through
+each theme context the resolver declares, the rendered
+`getComputedStyle(document.documentElement).getPropertyValue('--background')` — plus
+`--foreground`/`--primary` — must equal that context's authored values: rendered token drift is
+measured *per theme context*, not just for the boot theme. Create runs invoke the rung with
+`--require` (no headless browser → exit non-zero with the exact install command); improve keeps
+graceful degradation, but its skip lands as a named finding, never a one-line notice.
+
 Components never use `dark:` prefixes or literal colors regardless — the semantic tokens remap and
 every surface follows (the semantic-token doctrine in the emitted header).
 
-## 6. Precedence and provenance — which artifact gets emitted
+## 8. Precedence and provenance — which artifact gets emitted
 
 Look resolution is project-first: a `project` or `extracted` artifact wins outright; a `library`
 entry serves only when the brief names or resembles the product and the user confirms; the Nurix
 default (`data/design-tokens/nurix/`) is worn when nothing else speaks. The origin is the payload's
 `provenance` field, and the emitted header's `artifact:` line records it alongside the `sourced`
-date — so the emitted CSS always says where its look came from. The full precedence table, payload
-spec, and per-value provenance convention (`$description`) are
-[SCHEMA.md](../data/design-tokens/SCHEMA.md).
+date — so the emitted CSS always says where its look came from. Create-authored artifacts may also
+persist the full intake **look block** (`payload.look` — theme/anchors/delight/resolution/
+resolution-mode, enum-checked when present); `theme-default` and the top-level `anchors` remain the
+canonical projections emission consumes. The full precedence table, payload spec, and per-value
+provenance convention (`$description`) are [SCHEMA.md](../data/design-tokens/SCHEMA.md).