@nurix/etna 0.18.20 → 0.18.22

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

@@ -0,0 +1,580 @@
+# design-tokens — schema `design-tokens/v1`
+
+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.
+
+---
+
+## 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.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. |
+
+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 eight `$type` values appear —
+**never invent a custom `$type`**:
+
+| `$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 |
+| `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 |
+
+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:
+
+| Key | Type | Legal values / shape |
+| --- | --- | --- |
+| `schema` | string | Literal `design-tokens/v1`. 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. |
+| `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`, ordered by strictly increasing intensity. |
+| `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
+`color` group, the font stacks from `primitive.font-sans` / `primitive.font-mono`, the icon stroke
+from `primitive.icon-stroke`.
+
+---
+
+## `primitive.*` — the 26 visual primitives
+
+One group, `primitive`, holding all 26 (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` |
+| | `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)` |
+| 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`, `--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.
+
+---
+
+## `color.*` — the 34 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`.
+
+- **Semantic (17):** `background` · `foreground` · `card` · `card-foreground` · `muted` ·
+  `muted-foreground` · `border` · `input` · `ring` · `primary` · `primary-foreground` · `accent` ·
+  `accent-foreground` · `destructive` · `destructive-foreground` · `success` · `warning`.
+- **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
+another (`"$value": "{color.primary}"`), in which case it takes the target's `.css`; mechanical
+conversion writes literals, aliases are for authored files.
+
+---
+
+## `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).
+
+**`typography.family.*`** — the heading/body pairing plus mono, all `$type: "fontFamily"`:
+
+| 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.ramp.*`** — six 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) |
+
+| 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 |
+
+---
+
+## 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.
+- **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.
+- **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.
+
+## 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.
+
+```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
+
+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 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.
+
+```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 34.)
+
+---
+
+## 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. **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"]`:
+
+```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>` (24 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 |
+| `verbosity` / `feedback` / `density-tier` | `<html data-verbosity / data-feedback / data-density>` |
+| `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` |
+
+---
+
+## 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.
+
+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
+   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.
+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.
+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`.
+9. **Parse-back** — for every token carrying `.css`, parsing the string reproduces `$value` and
+   re-serializing `$value` reproduces the 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
+    `$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.
+
+---
+
+## 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.
+
+```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",
+      "dtcg": "2025.10",
+      "product": "Nurix",
+      "provenance": "default",
+      "sourced": "2026-07-04",
+      "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"],
+        "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"
+    },
+    "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"
+    },
+    "sidebar-width-expanded": { "$type": "dimension", "$value": { "value": 248, "unit": "px" } },
+    "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)" } }
+    },
+    "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": {
+      "$type": "color",
+      "$value": { "colorSpace": "oklch", "components": [0.6089, 0.1109, 221.72] },
+      "$extensions": { "com.nurix.design": { "css": "oklch(0.6089 0.1109 221.72)" } }
+    },
+    "sidebar": {
+      "$type": "color",
+      "$value": { "colorSpace": "oklch", "components": [0.9842, 0.0034, 247.86] },
+      "$extensions": { "com.nurix.design": { "css": "oklch(0.9842 0.0034 247.86)" } }
+    }
+  },
+  "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}"
+        }
+      },
+      "body": {
+        "$type": "typography",
+        "$value": {
+          "fontFamily": "{typography.family.body}",
+          "fontSize": { "value": 14, "unit": "px" },
+          "lineHeight": 1.45,
+          "fontWeight": "{primitive.font-weight-normal}",
+          "letterSpacing": 0
+        }
+      },
+      "caption": {
+        "$type": "typography",
+        "$value": {
+          "fontFamily": "{typography.family.body}",
+          "fontSize": { "value": 12, "unit": "px" },
+          "lineHeight": 1.2,
+          "fontWeight": "{primitive.font-weight-strong}",
+          "letterSpacing": 0.02
+        },
+        "$description": "uppercase eyebrow — text case is a usage rule; the composite carries no case slot",
+        "$extensions": { "com.nurix.design": { "css": { "letterSpacing": "0.02em" } } }
+      }
+    }
+  }
+}
+```
+
+`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": [] } }
+  ]
+}
+```

package/data/harnesses/code/skills/design/data/design-tokens/airbnb/design.resolver.json

@@ -0,0 +1,20 @@
+{
+  "schema": "design-resolver/v1",
+  "sets": [
+    {
+      "name": "base",
+      "values": [
+        "design.tokens.json"
+      ]
+    }
+  ],
+  "modifiers": [
+    {
+      "name": "theme",
+      "default": "light",
+      "contexts": {
+        "light": []
+      }
+    }
+  ]
+}