@nurix/etna 0.19.11 → 0.19.12

package/data/harnesses/code/skills/design/data/design-tokens/SCHEMA.md

@@ -1,695 +0,0 @@
-# design-tokens — schema `design-tokens/v2`
-
-A look travels as a **design-tokens artifact**: three JSON files in the pinned **DTCG 2025.10 Stable**
-grammar (W3C Design Tokens Community Group — the dated snapshot; the live drafts carry the spec's own
-"do not implement" warning). The artifact is exact, queryable, and diffable — no consumer interprets
-prose. [`derive-personality.mjs`](../../scripts/derive-personality.mjs) is the reference consumer:
-`--check` is the coverage gate, `--emit` writes `personality.css` / `globals.css` / the `<html>`
-attributes. The check engine ([`lib/checks.mjs`](../../scripts/lib/checks.mjs), fired at the phase
-gates and the verify/pre-ship sweeps) reads the lever manifest from the artifact's `$extensions` payload.
-
-The token files are a project's **canonical look state**. Create writes them, improve rewrites them,
-extraction on a foreign UI recovers them. No readable design.md view is generated from the token
-files — the nine-section [design.md format](../design-md/SCHEMA.md) serves only as the library's
-documentation format.
-
-**One schema, every origin.** A project's own artifact, an extracted artifact, a shipped library
-entry, and the Nurix default all use this identical shape; only the payload's `provenance` varies.
-
-**v1 → v2 in one line:** everything structural survives; the vocabulary grows — **expression arrives
-as tokens** (27 primitives, 36 color roles, a 7-step ramp, 4 elevation composites, an optional wash
-pair, and the `theme-default` / `anchors` payload keys), so the no-literals rule and the token-lock
-now guard a vocabulary with range. Existing v1 artifacts migrate mechanically:
-`convert-design-md.mjs --upgrade-v2` (idempotent; the Migration section below).
-
----
-
-## The three files
-
-| File | Ships | Contents |
-| --- | --- | --- |
-| `design.tokens.json` | always | The base/light set: the 27 visual primitives, the 36 color roles, the typography composites, the 4 elevation composites, the optional wash pair, and the file-level `$extensions["com.nurix.design"]` payload. The base set **is** the light rendering — light is never omitted, even when `theme-default` is `dark`. |
-| `design.tokens.dark.json` | only when the look has dark values | The dark modifier set: the `color` group remapped, nothing else. |
-| `design.resolver.json` | always | Sets, modifiers, and resolution order. The theme modifier's `default` mirrors the payload's `theme-default`. |
-
-The three files sit together in one directory: a project's artifact lives at the repo root; a library
-entry lives at `data/design-tokens/<product-slug>/`; the Nurix default at `data/design-tokens/nurix/`.
-
-Look resolution is project-first — `project`/`extracted` artifacts win outright; a `library` entry
-serves only on confirmed match; the `default` serves when nothing else does. The origin is recorded in
-the payload's `provenance` field:
-
-| `provenance` | Origin | Precedence |
-| --- | --- | --- |
-| `project` | The project's own artifact, written by a create run. | Wins outright when present. |
-| `extracted` | Recovered from a UI this skill did not build. | Same tier as `project`. |
-| `library` | A shipped library entry. | Serves only when the brief names or resembles the product and the user confirms. |
-| `default` | The Nurix default. | Worn when there is no project artifact and no confirmed library match. |
-
----
-
-## DTCG grammar in this artifact
-
-A token is an object with `$type` and `$value`, plus optional `$description` and `$extensions`.
-Groups nest; the file root is a group and carries the file-level `$extensions`. An alias is the
-string `"{path.to.token}"` and may appear anywhere a value of the target's type is legal, including
-composite sub-values; alias chains are legal, cycles are not. Exactly ten `$type` values appear —
-**never invent a custom `$type`** (`shadow` and `gradient` are DTCG 2025.10 composite types, not
-inventions):
-
-| `$type` | `$value` shape | Used by |
-| --- | --- | --- |
-| `color` | `{ "colorSpace": "oklch"\|"srgb", "components": [n, n, n], "alpha"?: n, "hex"?: "#rrggbb" }` | the 36 color roles, shadow layer colors, gradient stop colors |
-| `dimension` | `{ "value": n, "unit": "px" }` (`px`\|`rem` per spec; this artifact always writes `px`) | `radius`, `border-weight`, `icon-size-base`, the 8 layout primitives, ramp `fontSize`, shadow lengths |
-| `duration` | `{ "value": n, "unit": "ms" }` | the 4 duration primitives, `stagger-unit` |
-| `cubicBezier` | `[x1, y1, x2, y2]` (numbers; x in 0–1) | `ease-default` |
-| `fontFamily` | array of family-name strings | `font-sans`, `font-mono`, `typography.family.*` |
-| `fontWeight` | number 100–900 | `font-weight-normal`, `font-weight-strong`, ramp `fontWeight` |
-| `number` | plain JSON number | `shadow-intensity`, `density-gap`, `density-inset`, `heading-tracking`, `contrast-boost`, `icon-stroke`, ramp `lineHeight` / `letterSpacing` |
-| `typography` | composite `{ fontFamily, fontSize, fontWeight, letterSpacing, lineHeight }` | the 7 ramp steps |
-| `shadow` | composite **array of layers** `{ color, offsetX, offsetY, blur, spread }` (color/dimension sub-value shapes as above) | the 4 `elevation.*` tokens |
-| `gradient` | composite **array of stops** `{ color, position }` (position a number 0–1) | the ≤ 2 `wash.*` tokens |
-
-Color rules: an oklch source stays `"colorSpace": "oklch"` with `components` carrying the literal
-`[L, C, H]` numbers from the source string; a hex/rgba (or any other CSS color) source becomes
-`"colorSpace": "srgb"` with `components` as `[r, g, b]` in 0–1 (at most 5 decimals), the `hex`
-fallback field, and `alpha` when the source carries one:
-
-```json
-{
-  "$type": "color",
-  "$value": { "colorSpace": "srgb", "components": [0.3098, 0.2745, 0.898], "alpha": 1, "hex": "#4f46e5" },
-  "$extensions": { "com.nurix.design": { "css": "#4f46e5" } }
-}
-```
-
-**One documented deviation.** The spec's `dimension` carries only `px`|`rem`, so an `em` tracking
-value cannot be a dimension. `heading-tracking` is therefore a `number` token (an em multiplier) with
-its exact source string preserved (the preserved-css pattern, below), and a typography composite's
-`letterSpacing` sub-value is a number (em multiplier) or an alias to one — not a spec dimension.
-Everything else in the artifact is spec-shaped.
-
----
-
-## The file-level payload — `$extensions["com.nurix.design"]`
-
-One vendor namespace, reverse-domain, on the **base file's root group only** (the dark file carries no
-payload; the resolver has no `$extensions`). It holds everything the look needs that is not a design
-token — twelve keys in v2, plus the optional `look` record:
-
-| Key | Type | Legal values / shape |
-| --- | --- | --- |
-| `schema` | string | Literal `design-tokens/v2`. A parser refuses an unknown value. |
-| `dtcg` | string | Literal `2025.10` — the pinned DTCG snapshot this artifact conforms to. |
-| `product` | string | The product name; slugified (lowercase, non-alphanumeric runs → `-`) it becomes the `data-style` value. |
-| `provenance` | enum | `project` \| `extracted` \| `library` \| `default` |
-| `sourced` | string | ISO date the artifact was authored, extracted, or last re-sourced. |
-| `theme-default` | enum | `light` \| `dark` — which context the app boots in: scaffold writes it to `<html data-theme>`, and the resolver's `theme.default` mirrors it. **The brief's explicit theme direction is binding.** Absent → `light`. The base set remains the light rendering either way. |
-| `anchors` | string[] | 2–3 non-empty entries — the named real-product anchors from intake ("Linear", "Stripe Dashboard"), recorded so improve/judge runs critique against the same gestalt targets create aimed at. **Required on `provenance: project` artifacts**; optional on library/default/extracted. |
-| `look` | object | **Optional.** The full intake look block persisted by create-authored artifacts — `theme` (`light` \| `dark` \| `both`), `anchors` (2–3 named products), `delight` (`baseline` \| `expressive`), `resolution` (`project` \| `library:<slug>` \| `seed:<style>+<palette>` \| `default`), `resolution-mode` (`confirmed` \| `recorded`). A provenance record, not a projection: `theme-default` and the top-level `anchors` remain the canonical keys emission consumes. Enum-checked when present (rule 2; the enums mirror the intake gate's `validateLookBlock`). Conforming tools preserve unknown payload keys — this one included. |
-| `verbosity` | enum | `full` \| `default` \| `compact` \| `expert` — emits `data-verbosity` on `<html>`. |
-| `feedback` | enum | `subtle` \| `minimal` — emits `data-feedback`. |
-| `density-tier` | enum | `spacious` \| `standard` \| `dense` — emits `data-density`; drives the density base multipliers. |
-| `product-traits` | array | Non-empty list of product-type trait slugs the front gate reads — e.g. `["review-queue", "case-detail", "fintech"]`. Never emitted to CSS. |
-| `lever-manifest` | object | The drift-check allowlist (below). |
-
-Payload fields are always concrete — the hint mechanism (below) exists only on tokens.
-
-### The lever manifest
-
-The machine-readable allowlist the drift check reads: the check engine flags any emitted value outside
-this vocabulary — a radius not on `radius-scale`, a spacing off `spacing-scale`, a motion duration off
-`motion.durations`.
-
-| Key | Shape | Rule |
-| --- | --- | --- |
-| `spacing-scale` | number[] (px) | Non-empty, ascending — on-scale values only. |
-| `radius-scale` | number[] (px) | Non-empty, ascending. |
-| `shadow-levels` | string[] | Non-empty; names drawn from `none` `2xs` `xs` `sm` `md` `lg` `xl` `2xl` `overlay`, ordered by strictly increasing intensity. The Nurix default's vocabulary is `["none", "sm", "md", "lg", "overlay"]`. |
-| `motion` | `{ "durations": number[], "easings": string[] }` | Durations in ms, non-empty, ascending; easings non-empty CSS easing strings. |
-| `icons` | `{ "family": string }` | The icon family, e.g. `lucide`. |
-| `accent-count` | number | ≥ 1. |
-
-The manifest carries only vocabulary that is not already a token — **it never restates a token
-value**. The allowlists that are tokens are read from the tokens: the 36 color values from the
-`color` group, the font stacks from `primitive.font-sans` / `primitive.font-mono`, the icon stroke
-from `primitive.icon-stroke`, and the elevation/wash color literals from those groups' preserved
-byte forms.
-
----
-
-## `primitive.*` — the 27 visual primitives
-
-One group, `primitive`, holding all 27 (leaf names are law — they map 1:1 to the emitted CSS
-variables, without the leading `--`). Every token is either concrete or hinted.
-
-| Family | Token (`primitive.…`) | `$type` | Notes | Example (source form) |
-| --- | --- | --- | --- | --- |
-| geometric | `radius` | `dimension` | | `6px` |
-| | `shadow-intensity` | `number` | 0–1 master multiplier on every emitted `--shadow-*` alpha; 0 legally flattens everything (flat looks stay expressible). New looks default 1.0 — the elevation composites carry designed alphas. | `0.4` |
-| | `border-weight` | `dimension` | | `1px` |
-| | `density-gap` | `number` | multiplier on the `0.25rem` spacing base | `1` |
-| | `density-inset` | `number` | multiplier on component insets | `1` |
-| typographic | `font-sans` | `fontFamily` | carries `.css` | `Inter, system-ui, sans-serif` |
-| | `font-mono` | `fontFamily` | carries `.css` | `Geist Mono, ui-monospace, SFMono-Regular, monospace` |
-| | `font-weight-normal` | `fontWeight` | | `400` |
-| | `font-weight-strong` | `fontWeight` | | `600` |
-| | `heading-tracking` | `number` | em multiplier; carries `.css` | `-0.01em` |
-| temporal | `duration-unit` | `duration` | the tempo base | `50ms` |
-| | `duration-fast` | `duration` | | `100ms` |
-| | `duration-normal` | `duration` | | `150ms` |
-| | `duration-slow` | `duration` | | `250ms` |
-| | `ease-default` | `cubicBezier` | carries `.css` | `cubic-bezier(0.4,0,0.2,1)` |
-| | `stagger-unit` | `duration` | motion-moment base, authored per look; legal 0–60ms, default 30 (reads polished; 0 reads utilitarian) | `30ms` |
-| surface | `contrast-boost` | `number` | multiplier, 1 = default | `1` |
-| iconography | `icon-stroke` | `number` | px stroke-width | `1.75` |
-| | `icon-size-base` | `dimension` | | `16px` |
-| layout | `sidebar-width-expanded` | `dimension` | | `248px` |
-| | `sidebar-width-collapsed` | `dimension` | | `56px` |
-| | `topbar-height` | `dimension` | | `52px` |
-| | `side-panel-width` | `dimension` | | `420px` |
-| | `side-panel-width-rich` | `dimension` | | `640px` |
-| | `modal-width-max` | `dimension` | | `560px` |
-| | `form-max-width` | `dimension` | | `640px` |
-| | `table-row-height` | `dimension` | | `40px` |
-
-**Derived, never stored.** Emission computes `--ease-enter` and `--ease-exit` from `ease-default`,
-and `--stagger-delay` from `stagger-unit` (`--stagger-delay: var(--stagger-unit)` — the
-`.motion-stagger` cascade base). They are not tokens, not authored, and not part of the coverage
-gate. Do not add them.
-
----
-
-## `color.*` — the 36 color roles
-
-One flat group, `color`, holding all 36 (leaf names map 1:1 to the emitted `--<name>` variables).
-Every token is `$type: "color"` with a typed `$value` **and** mandatory preserved `.css` (an aliased
-role takes both from its target).
-
-- **Semantic (19):** `background` · `foreground` · `card` · `card-foreground` · `muted` ·
-  `muted-foreground` · `border` · `input` · `ring` · `primary` · `primary-foreground` · `accent` ·
-  `accent-foreground` · `destructive` · `destructive-foreground` · `success` · `warning` ·
-  `surface-raised` · `surface-overlay`.
-- **Substrate (17):** `popover` · `popover-foreground` · `secondary` · `secondary-foreground` ·
-  `chart-1` · `chart-2` · `chart-3` · `chart-4` · `chart-5` · `sidebar` · `sidebar-foreground` ·
-  `sidebar-primary` · `sidebar-primary-foreground` · `sidebar-accent` · `sidebar-accent-foreground` ·
-  `sidebar-border` · `sidebar-ring`.
-
-**`surface-raised` / `surface-overlay` — the dark ladder.** In light looks the two roles may alias
-`{color.card}` / `{color.popover}` — zero visual change. In dark looks they carry the
-**surface-lightness elevation ladder** (raised surfaces get *lighter*, ~+4–6 L points per step, hue
-held — the physics dark cannot fake with shadows). Components express elevation as
-`bg-surface-raised` / `bg-surface-overlay` instead of shadow-only. Both appear in the dark set (dark
-completeness counts 36).
-
-No consumed token falls back to a shadcn-gray default: emission sets all 36. A color token may alias
-another (`"$value": "{color.primary}"`), in which case it takes the target's `.css`; mechanical
-conversion writes literals, aliases are for authored files and the two ladder roles.
-
----
-
-## `typography.*` — families and the ramp
-
-The first-class machine form of the type scale, in two subgroups. It reaches CSS variables only
-through the primitives it aliases; emitters read the ramp as data and materialize it as the seven
-`text-*` utilities (the type-scale rule's fixed scale *is* the ramp — typ-09).
-
-**`typography.family.*`** — the heading/body pairing plus mono, plus an optional display slot, all
-`$type: "fontFamily"`. The three-*job* rhythm is display / body / numeric-mono (typ-06: ≤ 3 families,
-each with a distinct job); `heading` stays for compat and typically aliases `display` or `body`:
-
-| Token | Value |
-| --- | --- |
-| `typography.family.heading` | `"{primitive.font-sans}"` — or its own stack when the look pairs a distinct heading family. |
-| `typography.family.body` | `"{primitive.font-sans}"` |
-| `typography.family.mono` | `"{primitive.font-mono}"` |
-| `typography.family.display` | **optional** third-slot member; may alias `heading`. |
-
-**`typography.ramp.*`** — seven fixed step names, each `$type: "typography"` carrying all five
-sub-values:
-
-| Step | Role |
-| --- | --- |
-| `h1` | page title |
-| `h2` | section head |
-| `h3` | card / group head |
-| `body` | UI + prose |
-| `small` | labels, meta, dense table |
-| `caption` | uppercase eyebrow (text case is a usage rule; the composite carries no case slot) |
-| `display` | the scale-drama step: KPI numerals, the one focal metric, a brand-forward page title. `fontSize` guidance 32–48px; `fontFamily` may alias `typography.family.display`. Usage is rule-gated, not schema-gated: display-step elements only on `brand-forward` surfaces, ≤ 1 per surface (typ-20). Baseline surfaces keep the 24px-h1 world. |
-
-| Sub-value | Shape |
-| --- | --- |
-| `fontFamily` | alias to a `typography.family.*` token |
-| `fontSize` | `dimension` (px) |
-| `lineHeight` | number (unitless multiplier) |
-| `fontWeight` | alias to `primitive.font-weight-strong` / `primitive.font-weight-normal`, or a number |
-| `letterSpacing` | number (em multiplier) or alias to `primitive.heading-tracking` — the documented deviation |
-
----
-
-## `elevation.*` — depth as a designed system
-
-Four tokens, each `$type: "shadow"`, `$value` an **array of layers** (`{ color, offsetX, offsetY,
-blur, spread }` per layer — the DTCG shadow shape; color sub-values follow the color rules incl.
-`alpha`). Leaf names are law → emitted as `--shadow-sm`, `--shadow-md`, `--shadow-lg`,
-`--shadow-overlay`, plus the matching `@theme` shadow utilities.
-
-| Token | Role | Authoring guidance (seeds carry real values) |
-| --- | --- | --- |
-| `elevation.sm` | hairline lift — hover on rows/cards | 1–2 layers, y ≤ 2px, blur ≤ 4px |
-| `elevation.md` | raised panel, dropdown | 2 layers (ambient + key) |
-| `elevation.lg` | brand-forward feature panel | 2–3 layers, tinted |
-| `elevation.overlay` | side panel / dialog scrim companion | widest blur; the only level a modal may use |
-
-Rules:
-
-- Shadow color is **brand-tintable** — a low-alpha tint toward the brand hue (e.g.
-  `rgba(0,55,112,0.08)`), never pure black at alpha ≥ 0.15.
-- `primitive.shadow-intensity` stays the master multiplier: emission wraps every layer alpha as
-  `calc(<alpha> * var(--shadow-intensity))`, so `prefers-contrast: more` (which zeroes the
-  multiplier) and flat looks keep working.
-- The **token-level `.css`** is the full serialized shadow list — the preserved byte form, carrying
-  every layer color's byte form inside it (composite sub-values have no `$extensions` slot of their
-  own). Zero lengths serialize bare `0`; the alpha may ride the `calc(… * var(--shadow-intensity))`
-  wrapper in the byte form — parse-back strips it to the layer alpha.
-- The lever manifest's `shadow-levels` key is unchanged in shape; `overlay` joins its legal name
-  vocabulary.
-
----
-
-## `wash.*` — the tasteful-gradient path (optional group)
-
-At most two tokens, `$type: "gradient"` (the DTCG stops array; each stop's color follows the color
-rules, `position` in 0–1). Emitted as `--wash-surface` / `--wash-emphasis`. **Optional presence**: a
-look that declares no washes omits the group entirely — the coverage gate validates shape when
-present, never requires it. The token-level `.css` carries the authored gradient (the stop list holds
-no geometry — angle and shape live in the byte form). Consumption is budget-gated (only
-`brand-forward` surfaces), and the anti-slop gradient ban (col-12 — neon purple/blue glows,
-purple-on-white) applies to wash values: a wash is a low-chroma tint ramp, not a hero gradient.
-
----
-
-## The preserved-css pattern
-
-Every formatting-sensitive value carries **two forms that must agree**: the typed `$value` (the
-queryable semantic) and `$extensions["com.nurix.design"].css` — the exact source CSS string.
-Emitters prefer the preserved string, so output is byte-stable across convert/emit round trips.
-
-- **Mandatory `.css`:** every `color` token; `heading-tracking` (sources vary — `0`, `0em`,
-  `-0.015em`); `ease-default`; any `fontFamily` token carrying its own stack; every `elevation.*`
-  token (the serialized shadow list); every `wash.*` token (the authored gradient).
-- **Omitted where serialization is deterministic:** `dimension` and `duration` serialize as
-  `<value><unit>`; `number` and `fontWeight` as the plain number; `cubicBezier` (absent `.css`) as
-  `cubic-bezier(x1, y1, x2, y2)`; `fontFamily` (absent `.css`) as the families joined with `", "`,
-  multi-word names double-quoted.
-- **On a composite token**, `.css` is an object keyed by sub-value name for `typography` (present
-  for formatting-sensitive inline sub-values, e.g. `{ "letterSpacing": "0.02em" }`; an aliased
-  sub-value takes its `.css` from the alias target) and a single string — the full serialized value —
-  for `shadow` and `gradient`.
-- **Parse-back verification is a converter requirement:** whatever writes a token must verify that
-  parsing `.css` reproduces `$value` exactly, and that re-serializing `$value` reproduces the byte
-  form — oklch components are the literal source numbers; srgb components round-trip through the
-  `hex` field; a shadow's `.css` parses back to its layer array (the intensity `calc` wrapper strips
-  to the layer alpha); a gradient's `.css` must contain each stop color's byte form. The gate
-  re-verifies.
-
-## Hints and the coverage tri-state
-
-DTCG has no hint concept; this is the convention. Where a value needs judgment, the token carries a
-**valid provisional `$value`** plus `$extensions["com.nurix.design"].hint` — the intent in plain
-words. 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 | — |
-
-Resolving a hint deletes the `hint` key and records the rationale in the token's `$description`, so
-the resolved artifact is self-explaining and re-derivable. Judgment is recorded, never silent.
-(`--emit --provisional` — the golden/regression flow only — emits hinted tokens at their provisional
-`$values` instead of refusing; it never ships output.)
-
-```json
-{
-  "$type": "number",
-  "$value": 1,
-  "$extensions": { "com.nurix.design": { "hint": "nudge borders up a step so the dense table grid reads as a grid" } }
-}
-```
-
-resolves to:
-
-```json
-{
-  "$type": "number",
-  "$value": 1.1,
-  "$description": "derived: dense-grid brief, one step up (was hint)"
-}
-```
-
-## Per-value provenance — the layer vocabulary
-
-A value's provenance rationale — why it diverges from a brand default, what judgment resolved its
-hint — lives in the token's `$description`. Mechanical conversion moves source comments here.
-
-**The layer tags.** A `$description` that opens with a tag names the composition layer that set the
-value (the layer model's audit surface): **`source:`** (the resolved source), **`brief:`** (a brief
-binding), **`deviation:`** (a recorded deviation — the only layer that may contradict a domain owner
-or leave the tables entirely; every such value carries its reason). Untagged values are inherited
-from the resolved source or defaults. The mechanical-annotation prefixes the converters write
-(`derived:`, `corpus:`, `rationale:`, `note:`, `synthesized:`, `brand:`, `dark:`) remain legal; any
-other opening tag fails the gate. **Every off-manifest value carries `deviation:`** — an artifact
-base value off its own lever-manifest allowlist without one fails rule 8. The artifact root's
-`$description` carries the resolution record (which source won, the runner-up, the deciding
-evidence).
-
----
-
-## The dark set — `design.tokens.dark.json`
-
-Ships **only when the look has dark values**; light is never omitted — the base set is the light
-rendering (even for a `theme-default: dark` look; only the boot attribute and resolver default move).
-When it ships:
-
-- It carries exactly the `color` group, all 36 roles, same shape rules (typed `$value` + `.css`;
-  aliases legal — they resolve after overlay, so `"{color.card}"` in the dark file resolves to the
-  dark card) — and nothing else: no primitives, no typography, no elevation, no payload (the base
-  file is the payload's single carrier).
-- Emission targets `:root[data-theme="dark"]` (specificity 0,2,0 — the same armor as the light
-  block; a lone attribute selector loses to the component library's later `:root` by source order),
-  remapping all 36; when the file is absent, no dark block is emitted and the project is light-only.
-- The `surface-raised` / `surface-overlay` roles carry the dark surface-lightness ladder (above).
-
-```json
-{
-  "color": {
-    "background": { "$type": "color", "$value": { "colorSpace": "oklch", "components": [0.2077, 0.0398, 265.75] }, "$extensions": { "com.nurix.design": { "css": "oklch(0.2077 0.0398 265.75)" } } },
-    "foreground": { "$type": "color", "$value": { "colorSpace": "oklch", "components": [0.9842, 0.0034, 247.86] }, "$extensions": { "com.nurix.design": { "css": "oklch(0.9842 0.0034 247.86)" } } }
-  }
-}
-```
-
-(Fragment — a real dark file carries all 36.)
-
----
-
-## The resolver — `design.resolver.json`
-
-The DTCG resolver document has no stable snapshot, so this shape is **ours-until-standardized** — the
-exact minimal shape the scripts implement, confined to this file so a future spec shift lands in one
-place.
-
-| Key | Shape |
-| --- | --- |
-| `schema` | Literal `design-resolver/v1`. |
-| `sets` | Array of `{ "name": string, "values": [file, …] }` — the base token files, in load order. |
-| `modifiers` | Array of `{ "name": string, "default": string, "contexts": { <context>: [file, …] } }`. Exactly one modifier today: `theme`. |
-
-**Resolution order (deterministic):** concatenate the set files in array order; select one context
-per modifier (the `default` when unstated); overlay the context's files in order — a later file
-overrides an earlier one per token path, and an overlay may only override paths that exist in the
-base, never introduce new ones. Aliases resolve after overlay. **The base set is always the light
-rendering:** the `light` context is always the empty overlay `[]`, and `theme.default` mirrors the
-payload's `theme-default` (`light` when absent — a dark-first look sets both to `dark`). A light-only
-look carries only the `light` context; a look with dark adds `"dark": ["design.tokens.dark.json"]`:
-
-```json
-{
-  "schema": "design-resolver/v1",
-  "sets": [{ "name": "base", "values": ["design.tokens.json"] }],
-  "modifiers": [
-    { "name": "theme", "default": "light", "contexts": { "light": [], "dark": ["design.tokens.dark.json"] } }
-  ]
-}
-```
-
----
-
-## Emission mapping
-
-The slug is the payload's `product`, slugified. Emission order is this document's enumeration order
-(mirrored by the consumer's arrays); JSON key order carries no meaning.
-
-| Source | Emitted target |
-| --- | --- |
-| `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)`); the tier writes the base |
-| `color.<name>` (36) | `:root, :root[data-theme="light"] { --<name>: … }` |
-| dark set `color.<name>` | `:root[data-theme="dark"] { --<name>: … }` — only when the dark file ships |
-| `elevation.<level>` (4) | `--shadow-<level>` in the `[data-style]` block **and** the `@theme` shadow utilities (`shadow-sm` … `shadow-overlay`); every alpha rides `calc(… * var(--shadow-intensity))` |
-| `wash.<slot>` (≤ 2, optional) | `--wash-surface` / `--wash-emphasis` in the `[data-style]` block — consumed only on budget-granted surfaces |
-| `typography.ramp.<step>` (7) | `@theme` text utilities `text-h1` … `text-display` carrying size / line-height / weight / tracking per step — the ramp becomes *classes* (typ-09: the fixed scale IS the ramp) |
-| `primitive.stagger-unit` | `--stagger-delay: var(--stagger-unit)` (derived) + the named motion classes `.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), both inert under `prefers-reduced-motion` (mot-03) |
-| `verbosity` / `feedback` / `density-tier` | `<html data-verbosity / data-feedback / data-density>` |
-| `theme-default` | `<html data-theme>` (the boot theme; the toggle round-trips the same attribute) |
-| `product` | `<html data-style="<slug>">` |
-| `product-traits` / `anchors` | read by the front gate and improve/judge runs; never emitted |
-| `typography.family.*` | data for emitters and exemplars; reaches CSS only through the primitives it aliases |
-| — (derived at emit) | `--ease-enter`, `--ease-exit` from `ease-default`; `--stagger-delay` from `stagger-unit` |
-
----
-
-## Validation — what `--check` enforces
-
-The coverage gate. It exits non-zero and **names every offending path** so the fix is mechanical; an
-artifact that passes is guaranteed derivable. Rules 1–12 keep their v1 numbering (amended where the
-surface grew); rules 13–15 are the v2 additions.
-
-1. **Files** — `design.tokens.json` and `design.resolver.json` present and parse as JSON; every file
-   the resolver references exists beside it; `design.tokens.dark.json` exists exactly when the
-   resolver's `dark` context names it.
-2. **Payload** — the base file's root `$extensions["com.nurix.design"]` present with: `schema` literal
-   `design-tokens/v2`; `dtcg` literal `2025.10`; `product` non-empty; `provenance` legal; `sourced` an
-   ISO date; `verbosity` / `feedback` / `density-tier` legal enum values (never hinted);
-   `product-traits` a non-empty array; `lever-manifest` carrying all six keys; `theme-default` legal
-   when present and mirrored by the resolver's theme default; `anchors` an array of 2–3 non-empty
-   strings when present — **required for `provenance: project`** artifacts; the optional `look`
-   block enum-checked when present (theme / delight / resolution-mode enums, 2–3 named anchors,
-   the resolution shape).
-3. **Primitive coverage** — all 27 `primitive.*` tokens present with the exact `$type` this schema
-   assigns, each assigned or hinted; `stagger-unit` within 0–60ms; fails naming every absent, empty,
-   or mistyped key.
-4. **Color coverage** — all 36 `color.*` tokens present, `$type: "color"`, `colorSpace` one of
-   `oklch` | `srgb`, `.css` present (via the target when aliased), each assigned or hinted; fails
-   naming every missing token.
-5. **Typography coverage** — `typography.family.heading|body|mono` present (`fontFamily`;
-   `family.display` optional but shape-checked when present);
-   `typography.ramp.h1|h2|h3|body|small|caption|display` present (`typography`), each composite
-   carrying all five sub-values.
-6. **Alias integrity** — every `{path}` reference resolves within the artifact to a token of the
-   required type; no cycles.
-7. **Manifest scales** — `spacing-scale`, `radius-scale`, `motion.durations` non-empty and ascending;
-   `motion.easings` non-empty; `shadow-levels` non-empty, drawn from the legal vocabulary (`overlay`
-   included), strictly increasing in intensity; `icons.family` non-empty; `accent-count` ≥ 1.
-8. **Manifest consistency** — the look's own base values sit on its own allowlist: `radius` ∈
-   `radius-scale`; `duration-fast` / `duration-normal` / `duration-slow` ∈ `motion.durations`;
-   `ease-default`'s serialization ∈ `motion.easings`. An off-manifest value is legal **only** with a
-   `deviation:` `$description` (the recorded-deviation rule).
-9. **Parse-back** — for every token carrying `.css`, parsing the string reproduces `$value` and
-   re-serializing `$value` reproduces the byte form; a shadow `.css` parses back to its layer array
-   (the intensity `calc` wrapper strips to the layer alpha); a gradient `.css` contains each stop
-   color's byte form.
-10. **Dark completeness** — the dark file, when present, carries exactly the `color` group with all
-    36 roles under the same shape rules (aliases legal), and nothing else.
-11. **Spec conformance** — only the ten `$type` values this schema uses appear; no invented
-    `$type`; unknown `$extensions` namespaces are preserved, never authored.
-12. **Emission precondition** — `--emit` runs only over a passing artifact and refuses while any
-    token carries a `hint`, naming every hinted path (`--provisional` — golden/regression flows
-    only — emits provisional values instead).
-13. **Elevation coverage** — all four `elevation.*` present, `$type: "shadow"`, ≥ 1 layer each,
-    every layer color rule-conformant (typed oklch|srgb; never pure black at alpha ≥ 0.15), lengths
-    dimension-shaped, the token-level `.css` present; each assigned or hinted; no level outside
-    `sm|md|lg|overlay`.
-14. **Wash shape** — when the `wash` group exists: ≤ 2 tokens, slots ⊆ `surface|emphasis`,
-    `$type: "gradient"`, ≥ 2 stops each with a rule-conformant color and a position in 0–1, `.css`
-    present. Presence is never required.
-15. **Provenance vocabulary** — a per-value `$description` opening with a tag uses a legal one
-    (`source:` / `brief:` / `deviation:` layer tags, or a mechanical-annotation prefix; untagged =
-    inherited); rule 8 enforces the off-manifest `deviation:` requirement.
-
-Font binding and emitter completeness run at `--emit`, not `--check` — they compare the artifact
-against emitted output and project dependencies (the emission contracts, not this file's gate).
-
----
-
-## Migration — v1 artifacts to v2
-
-`convert-design-md.mjs --upgrade-v2` is the mechanical, **idempotent** v1→v2 upgrade (it runs over
-`data/design-tokens/*/`; the converter also applies the same transform to every fresh conversion):
-
-1. `schema` literal → `design-tokens/v2`.
-2. `elevation.*` derived from the v1 hardcoded slate recipes × the twin's `shadow-intensity` —
-   value-preserving (the emitted `--shadow-sm/md/lg` for an untouched twin are byte-identical before
-   and after migration, because the composites carry the recipe alphas and the intensity stays the
-   runtime `calc` multiplier), tagged `$description: "derived: v1 shadow-intensity migration"`.
-   Library entries whose design.md names real shadow values get **hinted** elevation instead,
-   resolved from the design.md prose at the data build.
-3. `color.surface-raised` / `surface-overlay` → aliases to `{color.card}` / `{color.popover}` (in
-   the dark file too, where they resolve to the dark card/popover; the +4–6 L ladder is owed at
-   budget-time).
-4. `typography.ramp.display` → **hinted** (provisional: h1 scaled ×1.75, weight from
-   `font-weight-strong`), hint text "display step unset — resolve from the product's design.md or
-   leave for budget-time". The Nurix default adopts the provisional derivation as its own look,
-   assigned.
-5. `primitive.stagger-unit` → 30ms default (the prior derived clamp's value).
-6. `theme-default` → `light` everywhere except twins whose design.md declares dark-first (only
-   twins carrying dark sets qualify; their design.md decides); the resolver's theme default mirrors
-   it.
-7. Re-run parse-back verification + the v2 gate over every migrated twin.
-
-Because migration is deterministic + hint-carrying, no hand-rewrite of the library is needed; hints
-surface exactly where judgment is owed.
-
----
-
-## Worked example — the Nurix default (abbreviated)
-
-`data/design-tokens/nurix/design.tokens.json`, abbreviated to a representative subset of each token
-family — the real file carries all 27 primitives, all 36 color roles, the full seven-step ramp, and
-the four elevation composites. Nurix ships no dark set, so `design.tokens.dark.json` is absent and
-the resolver carries only the `light` context.
-
-```json
-{
-  "$description": "Nurix default — the look a zero-input project wears. Abbreviated here; the shipped file is complete.",
-  "$extensions": {
-    "com.nurix.design": {
-      "schema": "design-tokens/v2",
-      "dtcg": "2025.10",
-      "product": "Nurix",
-      "provenance": "default",
-      "sourced": "2026-07-04",
-      "theme-default": "light",
-      "product-traits": ["operator-console", "crm", "queue", "dashboard", "admin"],
-      "verbosity": "default",
-      "feedback": "subtle",
-      "density-tier": "standard",
-      "lever-manifest": {
-        "spacing-scale": [2, 4, 8, 12, 16, 24, 32, 48, 64],
-        "radius-scale": [0, 4, 6, 12, 9999],
-        "shadow-levels": ["none", "sm", "md", "lg", "overlay"],
-        "motion": { "durations": [100, 150, 250], "easings": ["cubic-bezier(0.4,0,0.2,1)"] },
-        "icons": { "family": "lucide" },
-        "accent-count": 1
-      }
-    }
-  },
-  "primitive": {
-    "radius": {
-      "$type": "dimension",
-      "$value": { "value": 6, "unit": "px" },
-      "$description": "brand default 12px is marketing-surface soft; operator default tightens for a denser, engineered read"
-    },
-    "shadow-intensity": {
-      "$type": "number",
-      "$value": 0.4,
-      "$description": "brand is predominantly flat; shadow only lifts true overlays"
-    },
-    "font-sans": {
-      "$type": "fontFamily",
-      "$value": ["Inter", "system-ui", "sans-serif"],
-      "$description": "brand's body font; the single sans slot serves dense body/table chrome",
-      "$extensions": { "com.nurix.design": { "css": "Inter, system-ui, sans-serif" } }
-    },
-    "heading-tracking": {
-      "$type": "number",
-      "$value": -0.01,
-      "$description": "em multiplier; brand display tracks 0 — at operator heading sizes Inter reads tighter",
-      "$extensions": { "com.nurix.design": { "css": "-0.01em" } }
-    },
-    "ease-default": {
-      "$type": "cubicBezier",
-      "$value": [0.4, 0, 0.2, 1],
-      "$extensions": { "com.nurix.design": { "css": "cubic-bezier(0.4,0,0.2,1)" } }
-    },
-    "stagger-unit": {
-      "$type": "duration",
-      "$value": { "value": 30, "unit": "ms" },
-      "$description": "derived: v1→v2 migration — the 30ms default stagger base (0–60ms legal)"
-    },
-    "table-row-height": {
-      "$type": "dimension",
-      "$value": { "value": 40, "unit": "px" },
-      "$description": "comfortable at standard density; dense archetypes step down via the surface catalog"
-    }
-  },
-  "color": {
-    "background": {
-      "$type": "color",
-      "$value": { "colorSpace": "oklch", "components": [1, 0, 0] },
-      "$extensions": { "com.nurix.design": { "css": "oklch(1 0 0)" } }
-    },
-    "primary": {
-      "$type": "color",
-      "$value": { "colorSpace": "oklch", "components": [0.5211, 0.2145, 263.89] },
-      "$description": "brand #245AE2 — the one accent",
-      "$extensions": { "com.nurix.design": { "css": "oklch(0.5211 0.2145 263.89)" } }
-    },
-    "surface-raised": {
-      "$type": "color",
-      "$value": "{color.card}",
-      "$description": "derived: v1→v2 migration — light aliases card; dark looks carry the surface-lightness ladder"
-    },
-    "surface-overlay": {
-      "$type": "color",
-      "$value": "{color.popover}",
-      "$description": "derived: v1→v2 migration — light aliases popover; dark looks carry the surface-lightness ladder"
-    }
-  },
-  "typography": {
-    "family": {
-      "heading": { "$type": "fontFamily", "$value": "{primitive.font-sans}" },
-      "body": { "$type": "fontFamily", "$value": "{primitive.font-sans}" },
-      "mono": { "$type": "fontFamily", "$value": "{primitive.font-mono}" }
-    },
-    "ramp": {
-      "h1": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "{typography.family.heading}",
-          "fontSize": { "value": 24, "unit": "px" },
-          "lineHeight": 1.25,
-          "fontWeight": "{primitive.font-weight-strong}",
-          "letterSpacing": "{primitive.heading-tracking}"
-        }
-      },
-      "display": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "{typography.family.heading}",
-          "fontSize": { "value": 42, "unit": "px" },
-          "lineHeight": 1.25,
-          "fontWeight": "{primitive.font-weight-strong}",
-          "letterSpacing": "{primitive.heading-tracking}"
-        },
-        "$description": "derived: v2 display step — the provisional h1 × 1.75 derivation adopted as the default's own look (KPI numerals, the one focal metric)"
-      }
-    }
-  },
-  "elevation": {
-    "sm": {
-      "$type": "shadow",
-      "$value": [
-        { "color": { "colorSpace": "srgb", "components": [0.05882, 0.0902, 0.16471], "alpha": 0.1, "hex": "#0f172a" }, "offsetX": { "value": 0, "unit": "px" }, "offsetY": { "value": 1, "unit": "px" }, "blur": { "value": 3, "unit": "px" }, "spread": { "value": 0, "unit": "px" } },
-        { "color": { "colorSpace": "srgb", "components": [0.05882, 0.0902, 0.16471], "alpha": 0.1, "hex": "#0f172a" }, "offsetX": { "value": 0, "unit": "px" }, "offsetY": { "value": 1, "unit": "px" }, "blur": { "value": 2, "unit": "px" }, "spread": { "value": -1, "unit": "px" } }
-      ],
-      "$description": "derived: v1 shadow-intensity migration",
-      "$extensions": { "com.nurix.design": { "css": "0 1px 3px 0 rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 1px 2px -1px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)))" } }
-    }
-  }
-}
-```
-
-`data/design-tokens/nurix/design.resolver.json`:
-
-```json
-{
-  "schema": "design-resolver/v1",
-  "sets": [{ "name": "base", "values": ["design.tokens.json"] }],
-  "modifiers": [
-    { "name": "theme", "default": "light", "contexts": { "light": [] } }
-  ]
-}
-```