@nurix/etna 0.19.11 → 0.19.12

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

@@ -1,575 +0,0 @@
-# Personality — the look pipeline
-
-`design-tokens artifact → --check → --emit`. A look travels as a **design-tokens artifact** — three
-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`, `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>`.
-
-## 1. The pipeline — artifact in, CSS out
-
-```
-design-tokens artifact ──▶ derive-personality.mjs --check ──▶ (green) ──▶ --emit <outdir>
-  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> [--provisional]] [--theme light|dark]
-```
-
-**The artifact.** Three files in one directory: `design.tokens.json` (the base set — primitives,
-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–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–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
-outstanding-hint count (§3). A failing artifact names its gaps — this run is against a scratch copy
-of the default with one color token deleted:
-
-```
-check FAILED (<artifact-dir>): 1 issue(s)
-  - rule 4 — color.warning: missing
-```
-
-**`--emit <outdir>`** runs only over a passing artifact and refuses while any token carries a hint
-(§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
-
-There is no sidecar state file. The header comment of the emitted `personality.css` carries the
-active personality — dials, theme, and the artifact citation with its provenance — and the `<html>`
-attributes carry the same state in markup:
-
-```css
-/* src/styles/personality.css — operator-UI personality tokens (emitted; do not hand-edit).
- *
- * Active personality — code is the cache. These values and the <html data-*>
- * attributes in index.html are emitted from the design-tokens artifact. To change
- * the look, edit design.tokens.json and re-run derive-personality.mjs --emit.
- *   style:     nurix   (<html data-style="nurix">)   — the project's own personality (rosterless)
- *   density:   standard   (<html data-density="standard">)
- *   verbosity: default   (<html data-verbosity="default">)
- *   feedback:  subtle   (<html data-feedback="subtle">)
- *   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);
- * this file resolves those names to values. Components never use dark: prefixes or literal colors.
- */
-```
-
-Recovery therefore reads two things: the token artifact (the source) and the emitted attributes
-(the active state). `index-html-attributes.txt` from the same run:
-
-```html
-<!-- Personality state lives in these <html data-*> attributes — code is the cache.
-     The design-tokens artifact is the source. To change the look, edit design.tokens.json
-     and re-run derive-personality.mjs --emit; to nudge one axis, edit an attribute here. -->
-<html
-  lang="en"
-  data-style="nurix"
-  data-density="standard"
-  data-verbosity="default"
-  data-feedback="subtle"
-  data-theme="light"
->
-```
-
-## 2. Derivation — token paths to emitted CSS variables
-
-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>` (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>` (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 `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.*` 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
-convert/emit round trips (an aliased token takes its target's `.css`). Absent `.css`, the schema's
-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(…)`; `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 — 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: 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 the temporal family:
-
-```css
-  --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: 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:
-
-```css
-/* ── Behavioral dials (D4) — orthogonal to the visual primitives. ── */
-[data-verbosity="full"]    { --label-display: inline-flex; --helper-text-display: block; --tooltip-delay: 800ms; }
-[data-verbosity="default"] { --label-display: inline-flex; --helper-text-display: block; --tooltip-delay: 500ms; }
-[data-verbosity="compact"] { --label-display: none;        --helper-text-display: none;  --tooltip-delay: 200ms; }
-[data-verbosity="expert"]  { --label-display: none;        --helper-text-display: none;  --tooltip-delay: 0ms; }
-
-[data-feedback="subtle"]   { --feedback-press-scale: 0.99; --focus-ring-width: 2px; --focus-ring-offset: 1px; }
-[data-feedback="minimal"]  { --feedback-press-scale: 1;    --focus-ring-width: 1px; --focus-ring-offset: 0px; }
-```
-
-- `--label-display` / `--helper-text-display` — `compact`/`expert` verbosity collapse form labels
-  and helper text; `full`/`default` keep them. Field chrome reads these, not a JS branch.
-- `--tooltip-delay` — tightens with verbosity (`800ms → 0ms`).
-- `--feedback-press-scale`, `--focus-ring-width`, `--focus-ring-offset` — `minimal` feedback
-  flattens the press and thins the focus ring; `subtle` keeps the operator-default ring.
-
-The lifecycle pattern ([lifecycle.md](./lifecycle.md)) consumes the dials directly — empty-state
-richness scales with verbosity, confirmation depth rides feedback; focus and overlay discipline read
-the ring variables ([interaction.md](./interaction.md)). A component that must branch structurally
-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
-`$extensions["com.nurix.design"].hint` — the intent in plain words (the full convention, with the
-JSON shape, is SCHEMA.md's hint section; payload fields are always concrete — hints exist only on
-tokens). Every gated token is in exactly one state:
-
-| State | Marker | `--check` | `--emit` |
-| --- | --- | --- | --- |
-| **assigned** | real value, no `hint` key | passes | emits |
-| **hinted** | `hint` key present | passes | **refuses**, naming every hinted path |
-| **missing** | token absent | fails, naming the key | — |
-
-A hinted artifact is checkable — the pass line counts the outstanding hints (this run: a scratch
-copy of the default with a hint added to `primitive.contrast-boost`):
-
-```
-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:
-
-```
-emit REFUSED (<artifact-dir>): 1 unresolved hint(s) — rule 12: every gated token must be concrete before emission.
-  - primitive.contrast-boost: hint: nudge borders up a step so the dense table grid reads as a grid
-  Resolve each with judgment: set the real $value, delete the hint key, record the rationale in $description — then re-run --emit.
-```
-
-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. (`--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/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, 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
-shadcn-standard 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 — 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: 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"] {
-```
-
-*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 — and it ships while every static gate stays green,
-because no static check sees the cascade. 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 cannot pass.
-
-**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 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.
-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` (`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` |
-| `--sidebar-width` / `--sidebar-width-icon` | SidebarProvider `style` prop | shell (below) |
-
-**Density — global tier composed with a per-surface relative step.** Two composed levels, pure
-cascade, no JS. The payload's `density-tier` becomes `data-density` on `<html>`, and the emitted
-blocks write only the **base** multipliers; a surface carries `data-density-step` (from its
-surface-catalog `density-modifier`, [surface-catalog.md](../data/operator-pack/surface-catalog.md),
-emitted by `scaffold.mjs`) and re-derives one relative step off whatever tier the app runs:
-
-```css
-/* ── Density: global tier → base multipliers (D31). ──
- * The tier writes ONLY the base; --density-gap/inset resolve from it (above),
- * so a per-surface step can re-derive relative to the tier. */
-[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; }
-```
-
-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 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-* 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));
-```
-
-**The two-weight discipline.** Operator UI carries exactly two font weights; the `@theme` map folds
-the library's whole weight vocabulary onto them:
-
-```css
-  /* font weight — two-weight discipline: medium/semibold/bold all resolve to the
-   * single emphasis weight; operator UI carries no third weight. normal is emitted
-   * as a literal because its theme key and the primitive share a name (no self-ref). */
-  --font-weight-normal: 400;
-  --font-weight-medium: var(--font-weight-strong);
-  --font-weight-semibold: var(--font-weight-strong);
-  --font-weight-bold: var(--font-weight-strong);
-```
-
-Fonts follow the same no-self-reference rule: `--font-sans`/`--font-mono` are emitted into `@theme`
-as literal stacks (a font is not a runtime-toggled token, and the theme key shares the primitive's
-name), while `personality.css` carries the same variables for direct `var()` use.
-
-**Sidebar width — the style-prop seam.** The library hardcodes `--sidebar-width` /
-`--sidebar-width-icon` as inline styles, overridable only via the provider's `style` prop — the one
-layout primitive that cannot reach the library through `@theme`. The shell wires the personality
-primitives in:
-
-```tsx
-<SidebarProvider
-  style={{
-    "--sidebar-width": "var(--sidebar-width-expanded)",
-    "--sidebar-width-icon": "var(--sidebar-width-collapsed)",
-  } as React.CSSProperties}
->
-```
-
-**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 skill defect.
-- **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. 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. **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). ──
- * 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
-comment instead:
-
-```css
-/* ── Dark theme — OPT-IN ONLY. ──
- * 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). 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 selected but the resolver carries no dark context
-```
-
-**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 — 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).
-
-## 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. 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).