@nurix/etna 0.19.3 → 0.19.4

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

@@ -1,4 +1,4 @@
-# design-tokens — schema `design-tokens/v1`
+# 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
@@ -16,15 +16,21 @@ 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 26 visual primitives, the 34 color roles, the typography composites, and the file-level `$extensions["com.nurix.design"]` payload. The base set **is** the light rendering — light is never omitted. |
+| `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. Light-first. |
+| `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/`.
@@ -47,19 +53,22 @@ the payload's `provenance` field:
 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 eight `$type` values appear —
-**never invent a custom `$type`**:
+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 34 color roles |
-| `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` |
-| `duration` | `{ "value": n, "unit": "ms" }` | the 4 duration primitives |
+| `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 6 ramp steps |
+| `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
@@ -86,15 +95,18 @@ Everything else in the artifact is spec-shaped.
 
 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:
+token — twelve keys in v2, plus the optional `look` record:
 
 | Key | Type | Legal values / shape |
 | --- | --- | --- |
-| `schema` | string | Literal `design-tokens/v1`. A parser refuses an unknown value. |
+| `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. |
@@ -113,27 +125,28 @@ this vocabulary — a radius not on `radius-scale`, a spacing off `spacing-scale
 | --- | --- | --- |
 | `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`, ordered by strictly increasing intensity. |
+| `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 34 color values from the
+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`.
+from `primitive.icon-stroke`, and the elevation/wash color literals from those groups' preserved
+byte forms.
 
 ---
 
-## `primitive.*` — the 26 visual primitives
+## `primitive.*` — the 27 visual primitives
 
-One group, `primitive`, holding all 26 (leaf names are law — they map 1:1 to the emitted CSS
+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 multiplier on the emitted `--shadow-*` alpha | `0.4` |
+| | `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` |
@@ -147,6 +160,7 @@ variables, without the leading `--`). Every token is either concrete or hinted.
 | | `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` |
@@ -159,46 +173,59 @@ variables, without the leading `--`). Every token is either concrete or hinted.
 | | `form-max-width` | `dimension` | | `640px` |
 | | `table-row-height` | `dimension` | | `40px` |
 
-**Derived, never stored.** Emission computes `--ease-enter`, `--ease-exit`, and `--stagger-delay`
-from `ease-default` and `duration-unit`. They are not tokens, not authored, and not part of the
-coverage gate. Do not add them.
+**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 34 color roles
+## `color.*` — the 36 color roles
 
-One flat group, `color`, holding all 34 (leaf names map 1:1 to the emitted `--<name>` variables).
-Every token is `$type: "color"` with a typed `$value` **and** mandatory preserved `.css`.
+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 (17):** `background` · `foreground` · `card` · `card-foreground` · `muted` ·
+- **Semantic (19):** `background` · `foreground` · `card` · `card-foreground` · `muted` ·
   `muted-foreground` · `border` · `input` · `ring` · `primary` · `primary-foreground` · `accent` ·
-  `accent-foreground` · `destructive` · `destructive-foreground` · `success` · `warning`.
+  `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`.
 
-No consumed token falls back to a shadcn-gray default: emission sets all 34. A color token may alias
+**`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.
+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 and exemplars read the ramp as data (size, line-height,
-weight, tracking per step).
+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, all `$type: "fontFamily"`:
+**`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.*`** — six fixed step names, each `$type: "typography"` carrying all five
+**`typography.ramp.*`** — seven fixed step names, each `$type: "typography"` carrying all five
 sub-values:
 
 | Step | Role |
@@ -209,6 +236,7 @@ sub-values:
 | `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 |
 | --- | --- |
@@ -220,6 +248,48 @@ sub-values:
 
 ---
 
+## `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
@@ -227,18 +297,22 @@ queryable semantic) and `$extensions["com.nurix.design"].css` — the exact sour
 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.
+  `-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, present for
-  formatting-sensitive inline sub-values (e.g. `{ "letterSpacing": "0.02em" }`); an aliased sub-value
-  takes its `.css` from the alias target.
+- **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. The gate re-verifies.
+  `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
 
@@ -254,6 +328,8 @@ words. Every gated token is in exactly one state:
 
 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
 {
@@ -273,23 +349,38 @@ resolves to:
 }
 ```
 
-## Per-value provenance
+## 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. When it ships:
-
-- It carries exactly the `color` group, all 34 roles, same shape rules (typed `$value` + `.css`) —
-  and nothing else: no primitives, no typography, no payload (the base file is the payload's single
-  carrier).
-- Emission targets `[data-theme="dark"]`, remapping all 34; when the file is absent, no dark block is
-  emitted and the project is light-only.
+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
 {
@@ -300,7 +391,7 @@ rendering. When it ships:
 }
 ```
 
-(Fragment — a real dark file carries all 34.)
+(Fragment — a real dark file carries all 36.)
 
 ---
 
@@ -319,10 +410,10 @@ place.
 **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. **Light-first:** `theme.default` is
-always `light`, and the `light` context is always the empty overlay `[]` — the base set is the light
-rendering. A light-only look carries only the `light` context; a look with dark adds
-`"dark": ["design.tokens.dark.json"]`:
+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
 {
@@ -343,73 +434,134 @@ The slug is the payload's `product`, slugified. Emission order is this document'
 
 | Source | Emitted target |
 | --- | --- |
-| `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)`); the tier writes the base |
-| `color.<name>` (34) | `:root, :root[data-theme="light"] { --<name>: … }` |
-| dark set `color.<name>` | `[data-theme="dark"] { --<name>: … }` — only when the dark file ships |
+| `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` | read by the front gate; never emitted |
-| `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` from `ease-default` + `duration-unit` |
+| `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.
+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/v1`; `dtcg` literal `2025.10`; `product` non-empty; `provenance` legal; `sourced` an
+   `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.
-3. **Primitive coverage** — all 26 `primitive.*` tokens present with the exact `$type` this schema
-   assigns, each assigned or hinted; fails naming every absent, empty, or mistyped key.
-4. **Color coverage** — all 34 `color.*` tokens present, `$type: "color"`, `colorSpace` one of
-   `oklch` | `srgb`, `.css` present, each assigned or hinted; fails naming every missing token.
-5. **Typography coverage** — `typography.family.heading|body|mono` present (`fontFamily`);
-   `typography.ramp.h1|h2|h3|body|small|caption` present (`typography`), each composite carrying all
-   five sub-values.
+   `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, strictly
-   increasing in intensity; `icons.family` non-empty; `accent-count` ≥ 1.
+   `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`.
+   `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.
+   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
-    34 roles under the same shape rules, and nothing else.
-11. **Spec conformance** — only the eight `$type` values this schema uses appear; no invented
+    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.
+    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 26 primitives, all 34 color roles, and the full six-step ramp.
-Nurix ships no dark set, so `design.tokens.dark.json` is absent and the resolver carries only the
-`light` context.
+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/v1",
+      "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",
@@ -417,7 +569,7 @@ Nurix ships no dark set, so `design.tokens.dark.json` is absent and the resolver
       "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"],
+        "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
@@ -435,44 +587,28 @@ Nurix ships no dark set, so `design.tokens.dark.json` is absent and the resolver
       "$value": 0.4,
       "$description": "brand is predominantly flat; shadow only lifts true overlays"
     },
-    "border-weight": { "$type": "dimension", "$value": { "value": 1, "unit": "px" } },
-    "density-gap": { "$type": "number", "$value": 1 },
     "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" } }
     },
-    "font-mono": {
-      "$type": "fontFamily",
-      "$value": ["Geist Mono", "ui-monospace", "SFMono-Regular", "monospace"],
-      "$description": "Geist monospace sibling — IDs, codes, log lines",
-      "$extensions": { "com.nurix.design": { "css": "Geist Mono, ui-monospace, SFMono-Regular, monospace" } }
-    },
-    "font-weight-normal": {
-      "$type": "fontWeight",
-      "$value": 400,
-      "$description": "brand base 500 is display-tuned; dense operator body reads cleaner at 400"
-    },
-    "font-weight-strong": { "$type": "fontWeight", "$value": 600 },
     "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" } }
     },
-    "duration-unit": { "$type": "duration", "$value": { "value": 50, "unit": "ms" } },
     "ease-default": {
       "$type": "cubicBezier",
       "$value": [0.4, 0, 0.2, 1],
       "$extensions": { "com.nurix.design": { "css": "cubic-bezier(0.4,0,0.2,1)" } }
     },
-    "icon-stroke": {
-      "$type": "number",
-      "$value": 1.75,
-      "$description": "one step under lucide's 2 for a refined operator stroke"
+    "stagger-unit": {
+      "$type": "duration",
+      "$value": { "value": 30, "unit": "ms" },
+      "$description": "derived: v1→v2 migration — the 30ms default stagger base (0–60ms legal)"
     },
-    "sidebar-width-expanded": { "$type": "dimension", "$value": { "value": 248, "unit": "px" } },
     "table-row-height": {
       "$type": "dimension",
       "$value": { "value": 40, "unit": "px" },
@@ -485,42 +621,21 @@ Nurix ships no dark set, so `design.tokens.dark.json` is absent and the resolver
       "$value": { "colorSpace": "oklch", "components": [1, 0, 0] },
       "$extensions": { "com.nurix.design": { "css": "oklch(1 0 0)" } }
     },
-    "foreground": {
-      "$type": "color",
-      "$value": { "colorSpace": "oklch", "components": [0.2077, 0.0398, 265.75] },
-      "$extensions": { "com.nurix.design": { "css": "oklch(0.2077 0.0398 265.75)" } }
-    },
-    "border": {
-      "$type": "color",
-      "$value": { "colorSpace": "oklch", "components": [0.9288, 0.0126, 255.51] },
-      "$description": "brand #E2E8F0 — every separator, grid line, and field edge",
-      "$extensions": { "com.nurix.design": { "css": "oklch(0.9288 0.0126 255.51)" } }
-    },
     "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)" } }
     },
-    "primary-foreground": {
-      "$type": "color",
-      "$value": { "colorSpace": "oklch", "components": [1, 0, 0] },
-      "$extensions": { "com.nurix.design": { "css": "oklch(1 0 0)" } }
-    },
-    "warning": {
-      "$type": "color",
-      "$value": { "colorSpace": "oklch", "components": [0.6658, 0.1574, 58.32] },
-      "$extensions": { "com.nurix.design": { "css": "oklch(0.6658 0.1574 58.32)" } }
-    },
-    "chart-2": {
+    "surface-raised": {
       "$type": "color",
-      "$value": { "colorSpace": "oklch", "components": [0.6089, 0.1109, 221.72] },
-      "$extensions": { "com.nurix.design": { "css": "oklch(0.6089 0.1109 221.72)" } }
+      "$value": "{color.card}",
+      "$description": "derived: v1→v2 migration — light aliases card; dark looks carry the surface-lightness ladder"
     },
-    "sidebar": {
+    "surface-overlay": {
       "$type": "color",
-      "$value": { "colorSpace": "oklch", "components": [0.9842, 0.0034, 247.86] },
-      "$extensions": { "com.nurix.design": { "css": "oklch(0.9842 0.0034 247.86)" } }
+      "$value": "{color.popover}",
+      "$description": "derived: v1→v2 migration — light aliases popover; dark looks carry the surface-lightness ladder"
     }
   },
   "typography": {
@@ -540,29 +655,29 @@ Nurix ships no dark set, so `design.tokens.dark.json` is absent and the resolver
           "letterSpacing": "{primitive.heading-tracking}"
         }
       },
-      "body": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "{typography.family.body}",
-          "fontSize": { "value": 14, "unit": "px" },
-          "lineHeight": 1.45,
-          "fontWeight": "{primitive.font-weight-normal}",
-          "letterSpacing": 0
-        }
-      },
-      "caption": {
+      "display": {
         "$type": "typography",
         "$value": {
-          "fontFamily": "{typography.family.body}",
-          "fontSize": { "value": 12, "unit": "px" },
-          "lineHeight": 1.2,
+          "fontFamily": "{typography.family.heading}",
+          "fontSize": { "value": 42, "unit": "px" },
+          "lineHeight": 1.25,
           "fontWeight": "{primitive.font-weight-strong}",
-          "letterSpacing": 0.02
+          "letterSpacing": "{primitive.heading-tracking}"
         },
-        "$description": "uppercase eyebrow — text case is a usage rule; the composite carries no case slot",
-        "$extensions": { "com.nurix.design": { "css": { "letterSpacing": "0.02em" } } }
+        "$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)))" } }
+    }
   }
 }
 ```