@radicool/throughline 0.19.0 → 0.20.0

package/references/figma-component-standards.md

@@ -372,8 +372,20 @@ re-describing it:
    `${CLAUDE_PLUGIN_ROOT}/references/figma-scripting.md` — `getNodeByIdAsync`, and
    an explicit `timeout` since multi-card font-loading writes blow past the default
    ~5s budget), then inside it:
-   - set the `Status Label` text to the new status (e.g. `stable`);
-   - re-bind the `Status` chip fill to the matching semantic color variable
+   - locate the status chip under either header shape, the way the doc-card
+     builder's header guard does: find the header band structurally (the card's
+     child frame that is neither `Usage` nor the specimen nor an ancestor of it),
+     then search its first child, the title row, for a descendant named `Status`
+     (to-spec cards) or `Status Pill` (legacy cards). The chip's label is its
+     `Status Label` text node; a legacy pill has no named label, so use its one
+     TEXT descendant. If no chip is found, or the label doesn't resolve to exactly
+     one text node, **skip that card** without writing anything to it and record
+     its name — catch per card, so one miss never aborts the rest of a multi-card
+     write. After the loop, tell the user by name every card that still shows the
+     old status in Figma — the manifest already says `stable`, so a silent skip
+     leaves the card lying;
+   - set the label text to the new status (e.g. `stable`);
+   - re-bind the chip fill to the matching semantic color variable
      (`stable` → success, `draft`/`beta` → warning, `deprecated` → neutral/danger)
      — re-bind the variable, don't hardcode a hex, so it stays mode-aware.
    Then re-run the canonical doc-card builder

package/references/figma-scripting.md

@@ -51,8 +51,9 @@ wrong document.
 
 **So the preflight must assert the active file's *identity*, not just connection:**
 
-1. **Know your target `fileKey`** before writing (the one your architect read, or
-   the one the workflow is scoped to).
+1. **Know your target `fileKey`** before writing. It is `figma.fileKey` in
+   `design-system.json` at the working-directory root. If that field is absent,
+   stop and ask which file to write to — do not assume the active one is right.
 2. **Read the active file and compare.** `figma_get_status` reports
    `currentFileKey` / `currentFileName`; `figma_list_open_files` shows every
    connected file and which is active. Confirm the active `fileKey` equals your
@@ -61,6 +62,15 @@ wrong document.
 3. **If it drifted, navigate — don't just retry.** `figma_navigate` to the target
    file URL, then re-read status to confirm the switch took, then write. A bare
    re-run without navigating will hit the wrong file again.
+4. **If it still doesn't match, stop.** Name both files. The usual cause is that
+   the target file does not have the Desktop Bridge plugin open.
+
+Run this before the first write, and again right before any replace — the
+build-verify-then-replace finalize deletes the existing node, so it is the write
+that destroys work in the wrong file. The `figma-executor` agent runs it as step 1
+of its contract. **When a skill builds inline instead** (a host with no subagent
+dispatch, or a write-back the skill does itself), nothing runs it for you: the
+skill has to.
 
 This is the file-level analogue of the live-instance discipline above: the
 instance preflight guards against *two* live bridges; this guards against the *one*

package/references/manifest-schema.md

@@ -11,11 +11,11 @@ what changed. Gating decisions are made by reading this file: if a prerequisite
 field is unset, the skill **offers** to run the prerequisite skill rather than
 bailing or running silently.
 
-## Schema (schemaVersion 6)
+## Schema (schemaVersion 7)
 
 ```json
 {
-  "schemaVersion": 6,
+  "schemaVersion": 7,
   "user": {
     "codingLevel": "new"
   },
@@ -102,6 +102,7 @@ bailing or running silently.
     "completedAt": null,
     "journalScaffolded": false
   },
+  "verification": null,
   "completedSkills": []
 }
 ```
@@ -346,6 +347,41 @@ retrofit stands so a later session can resume.
 - `journalScaffolded` — whether the `docs/design-system/` decision journal has been
   created for this retrofit (offered default-on by `retrofit-planner`).
 
+### `verification`
+The pointer at the folder-resident proof store, where each stage records what it
+changed, which checks ran and why it was allowed to advance. `null` until the
+first stage records an entry. See
+`${CLAUDE_PLUGIN_ROOT}/references/proof-bundle.md`.
+- `path` — the store directory (`design-system/proof`).
+- `stages` — object keyed by stage name, each holding
+  `{ at, adoptedAt, exempt?, fingerprint }`.
+- `fingerprint` — computed over the **whole** stage file, so a hand-edited entry
+  is caught (`proof-stale`), the same way `docs:check` catches a hand-edited
+  surface.
+- `at` — the latest recorded entry's timestamp. It moves with every record.
+- `adoptedAt` — the first entry's timestamp: **write-once**, never rewritten, the
+  human-readable "when did this system opt in". No gate reads it.
+- `exempt` — present only on the per-component stages (`component-builder`,
+  `storybook-chromatic-builder`) and **capture-once-then-shrink**: the stage's
+  first record captures every name then in `components.built`, and every record,
+  the first included, removes its own subject. The list never gains a name. It is
+  what scopes the per-component `proof-missing` rule to components the stage has
+  not yet proven, so adopting the bundle does not light up a failure for every
+  component built before it existed. A listed stage with **no** `exempt` key
+  exempts **nothing**, not everything — a missing list makes the gate louder, not
+  quieter.
+
+**Pointers and hashes, never entries** — the entries themselves live in the
+store, for the same reason `components.meta[name].doc` keeps content out of the
+manifest. Skills write all of this only through `verify-check.mjs --record`; none
+hand-writes a stage file or computes a fingerprint by hand.
+
+No gate compares `components.meta[name].updatedAt` against `adoptedAt`. That
+field is refreshed by a status promotion as well as by a rebuild, so a stage
+other than the one that owes the entry can move it — and a date comparison would
+fail a pre-existing component the first time an unrelated storying run promotes
+it.
+
 ### `completedSkills`
 - Append-only list of skill identifiers that have run to completion at least
   once. Useful for the `/design-system-status` command and for friendly
@@ -379,3 +415,7 @@ are authored. Bump `schemaVersion` to `5`. No existing field changes.
 **v5 → v6 migration:** add `figma.docCardVariables` (default `null`), populated
 on the first doc-card render. Bump `schemaVersion` to `6`. No existing field
 changes.
+
+**v6 → v7 migration:** add `verification` (default `null`), populated on the
+first recorded stage entry. Bump `schemaVersion` to `7`. No existing field
+changes.

package/references/proof-bundle.md

@@ -0,0 +1,305 @@
+# The verification proof bundle (`design-system/proof/`)
+
+Each stage of the system leaves a durable record of what it changed, which checks
+ran, what each one found, and why it was allowed to advance. That record is the
+proof bundle. It exists because "run it twice, get the same structure" proves
+idempotency, not quality — and because the checks that do prove quality (the
+Figma read-back, a reviewer verdict, a build result) are prose today, and prose
+evaporates when the run ends.
+
+The bundle is **the record, not the enforcement mechanism**. Gates enforce:
+`docs:check` owns documentation drift, the `figma-executor` read-back owns
+structure, `adherence:check` owns code adherence. The bundle persists what each
+gate found. The `verify:check` gate reads it, recomputes what it can off disk,
+and fails when a stored result and a fresh run disagree.
+
+## Where it lives
+
+`design-system/proof/<stage>.json` — one file per stage, in the user's working
+folder, from the first component built. It is folder-resident exactly like
+`design-system/docs/` (see
+`${CLAUDE_PLUGIN_ROOT}/references/component-doc-schema.md`), so a stage can
+record an entry during the Figma-only *folder* stage, before any repo exists.
+The path is stable across folder→repo; files never move.
+
+## The file shape
+
+`{ "stage": "<name>", "subjects": { "<subject>": <entry> } }`
+
+A **subject** is the thing the entry is about: a component name for a
+per-component stage, or the literal `"system"` for a stage that is not
+per-component. One entry per stage-and-subject, latest wins — the store models
+current state, not history, the same way the manifest does.
+
+## The entry shape
+
+`{ at, changed, checks, screenshot?, advancedBecause }`
+
+- `at` — ISO timestamp, **supplied by the caller**. `Date.now()` is not available
+  in every execution context a skill runs in, so the recorder never invents it.
+- `changed` — array of one-line strings saying what this stage changed. May be
+  empty.
+- `checks` — non-empty array of `{ name, method, result, evidence }`, where
+  `method` is `"derived"` or `"attested"`, `result` is `"pass"` or `"fail"`, and
+  `evidence` is a string.
+- `checks[].accepted` — optional, and only on a check. An array of
+  `{ fg, bg, mode }` naming pairs a user explicitly accepted as failing. Only
+  `contrast-baseline` uses it today.
+- `screenshot` — optional pointer: a Figma node id, or a repo-relative path.
+- `advancedBecause` — one line saying why the stage was allowed to advance.
+
+**`accepted`, and why its two readers disagree.** `fg` and `bg` are the dotted
+`CONTRAST_PAIRS` paths, compared after the `normalizeText` fold, so
+`color.text.onEmphasis` and `color.text.on-emphasis` are one role. `mode` is the
+**Figma** mode name `token-builder` saw — `Light`, `Dark` — because at folder
+stage no DTCG file exists yet to name a mode after. A reader that matches on
+`mode` must translate it into that run's file label first.
+
+Two skills read the field, and they match on different things:
+
+- `token-sync-layer` drops from its own gate run's `color-contrast` failures
+  every one whose `(fg, bg, mode)` triple matches an entry. It is the only reader
+  that matches on the mode, because it is the only one that knows both names: it
+  read the Figma modes and it wrote the DTCG files.
+- `storybook-chromatic-builder` compares its own live run's failures against the
+  `fg`/`bg` **roles alone**, to decide whether the `verify:check` it registers
+  carries `--skip color-contrast`. A per-mode test would decide nothing there —
+  `--skip` is rule-wide, so there is no way to skip contrast in Dark and keep it
+  in Light — and that skill could not translate a mode name anyway, having
+  neither read the Figma modes nor written the DTCG files.
+
+The rule that keeps the field honest: **it is data a caller subtracts, never
+something `verify-check.mjs` reads.** The gate does not know the field exists, and
+an attested `fail` never switches a derived rule off inside it — that would be
+the self-attestation this store exists to avoid. A triple that no longer matches
+any failure is inert, which is how an acceptance retires itself once the pair is
+fixed.
+
+**Pointers, never content.** `evidence` and `screenshot` point at things; they do
+not carry them. This is the same rule `components.meta[name].doc` follows, for
+the same reason: the store is committed to the repo and read by humans. A diff
+of a stage file should be legible, and a design system's history should not carry
+inlined screenshots or file contents.
+
+## `derived` vs. `attested`
+
+This is the load-bearing distinction in the whole store, and the two are not
+equal.
+
+- **`derived`** — `verify:check` recomputes the check off disk on every run. The
+  stored result is a **cache**. When the rerun disagrees with it, the run fails as
+  `proof-contradicted`. A derived result is trustworthy because it is not
+  trusted.
+- **`attested`** — an agent observed it live, somewhere the CLI cannot look:
+  Figma, a build it ran, a review it received. It is printed on the report's
+  informational line and is **never the reason a run passes**.
+
+The house precedent for the honest half is `edit-unverified` in
+`${CLAUDE_PLUGIN_ROOT}/references/component-doc-schema.md` — `docs:check` records
+what it cannot read without pretending it verified it. Attested checks are the
+same posture: recorded, visible, never load-bearing.
+
+## The manifest pointer
+
+`design-system.json` carries a top-level `verification` key — `null` until the
+first stage records an entry. Content on disk, pointers and hashes in the
+manifest, exactly as `components.meta[name].doc` does it. See
+`${CLAUDE_PLUGIN_ROOT}/references/manifest-schema.md`.
+
+```json
+{
+  "verification": {
+    "path": "design-system/proof",
+    "stages": {
+      "component-builder": {
+        "at": "2026-09-12T18:04:00.000Z",
+        "adoptedAt": "2026-09-12T17:41:00.000Z",
+        "exempt": ["Card"],
+        "fingerprint": "3f9c1a7b2d4e6058"
+      },
+      "token-sync-layer": {
+        "at": "2026-09-12T18:20:00.000Z",
+        "adoptedAt": "2026-09-12T18:20:00.000Z",
+        "fingerprint": "8ab240df1c9e5567"
+      }
+    }
+  }
+}
+```
+
+- `path` — the store directory.
+- `fingerprint` — computed over the **whole stage file**, so a hand-edited entry
+  is caught (`proof-stale`), the same way `docs:check` catches a hand-edited
+  surface.
+- `at` — the timestamp of the latest entry recorded for that stage. It moves with
+  every record.
+- `adoptedAt` — **write-once**. Set on a stage's first recorded entry and never
+  rewritten: the human-readable "when did this system opt in". No gate reads it.
+- `exempt` — the names this stage has not yet proven. Present only on the
+  per-component stages; a system-wide stage omits the key entirely.
+
+**Skills write all of this only through `verify-check.mjs --record`.** No skill
+hand-writes a stage file, and none computes a fingerprint by hand — that is how
+the pointer and the file are kept from drifting apart.
+
+### `exempt` is capture-once-then-shrink
+
+Both halves of the rule are load-bearing, and a reader who implements only the
+first grandfathers the whole adoption batch:
+
+1. On a stage's **first** record, `exempt` captures **every** name then in
+   `components.built`, sorted.
+2. On **every** record, the first included, the record's own subject is removed
+   from `exempt`.
+
+The list never gains a name. It can only narrow. It is what scopes the
+per-component `proof-missing` rule to components the stage has not yet proven:
+an existing system that adopts the bundle does not light up with a failure for
+every component built before the bundle existed, and a name leaves the list the
+moment the stage actually proves that component.
+
+Capture has to read the whole of `components.built` rather than "everything but
+this subject", because a run's entire batch is already in `built` before the
+record loop reaches the first component. A capture that excluded only its own
+subject would permanently exempt its batch-mates — build four components on the
+upgrade run and three of them are never owed proof again.
+
+A stage listed in `verification.stages` with **no** `exempt` key at all exempts
+**nothing**, not everything. A missing list makes the gate louder, not quieter.
+
+### No gate compares `updatedAt` against `adoptedAt`
+
+However natural it looks, nothing in the verification gate compares
+`components.meta[name].updatedAt` against `adoptedAt`. That field has more than
+one writer: `storybook-chromatic-builder` refreshes it when it promotes a
+component to `"stable"`, which is a different stage from the one that owes the
+entry. So a single storying run drags every pre-existing component's timestamp
+past `component-builder`'s adoption moment, and a date gate would fail a system
+where nothing went wrong. A captured list of names cannot be moved by another
+stage's write, and it is readable in the manifest: the exemption is stated
+rather than inferred.
+
+For the same reason, neither `adoptedAt` nor `exempt` is derived from the stage
+file. Entries are latest-wins, so "the earliest `at` in the file" slides forward
+every time the earliest subject is rebuilt.
+
+## The stage vocabulary (v1)
+
+| Stage | Subject |
+|---|---|
+| `component-builder` | component name |
+| `storybook-chromatic-builder` | component name |
+| `token-sync-layer` | `"system"` |
+| `token-builder` | `"system"` |
+
+The machine-readable copy of that split is `PER_COMPONENT_STAGES` in
+`scripts/lib/proof.mjs`, and the full list is `STAGES` beside it. **A change here
+must change those constants** — they are what `verify:check` asks "is this stage
+keyed by component?"
+
+`/document-component` and the retrofit phases do not emit entries in v1.
+
+## The check names (v1)
+
+| Check | Method | Recorded by |
+|---|---|---|
+| `structural-read-back` | attested | `component-builder` |
+| `state-baseline` | attested | `component-builder` |
+| `figma-name` | attested | `component-builder` |
+| `review` | attested | the dispatching skill |
+| `build` | attested | `storybook-chromatic-builder` |
+| `orphan-token` | derived | not recorded: re-derived on every `verify:check` run |
+| `state-incomplete` | derived | `storybook-chromatic-builder` |
+| `name-drift` | derived | `storybook-chromatic-builder` |
+| `contrast-baseline` | attested | `token-builder` |
+| `tokens:validate-output` | attested | `token-sync-layer` |
+| `color-contrast` | derived | `token-sync-layer` |
+
+**Two stages record derived results — `storybook-chromatic-builder` and
+`token-sync-layer`** — and each qualifies for one reason and only that reason: it
+runs `verify:check` before it records, so it has the result in hand rather than
+asserting it. That is a property of what the stage does, not of which stage it
+is; a stage that does not run the gate never qualifies. `component-builder` and
+`token-builder` both run at folder stage, with no repo to scan, so they record
+attested checks only.
+
+A derived result sitting in a stage file is a cache the next run recomputes. A
+disagreement is `proof-contradicted`.
+
+### Contrast: two checks, two methods
+
+`contrast-baseline` and `color-contrast` ask the same question in two places,
+and neither substitutes for the other.
+
+- **`contrast-baseline`** — attested, recorded by `token-builder`. The ratio an
+  agent computed in Figma from the resolved variable values, per mode, at the
+  moment the semantic tier was built. Attested because the CLI cannot read Figma.
+- **`color-contrast`** — derived, recorded by `token-sync-layer`. The same
+  question recomputed off the DTCG source by `verify:check`, which can read it.
+
+This is the `state-baseline` / `state-incomplete` pairing one layer down: the
+agent asserts in the place where the thing is built, the CLI re-derives
+independently off disk, and a system wants both. Catching a bad pair at creation
+time is the point of the first; not having to take that catch on trust is the
+point of the second.
+
+## A worked example
+
+One stage file with two subjects — `Button`, freshly built and reviewed, and
+`Card`, rebuilt without a review:
+
+```json
+{
+  "stage": "component-builder",
+  "subjects": {
+    "Button": {
+      "at": "2026-09-12T17:41:00.000Z",
+      "changed": [
+        "Built Button as a COMPONENT_SET with 18 variants",
+        "Bound fills, strokes and radius to semantic variables"
+      ],
+      "checks": [
+        {
+          "name": "structural-read-back",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "COMPONENT_SET 41:207, 18 children, axes type/size/state"
+        },
+        {
+          "name": "state-baseline",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "state axis: default, hover, focus, active, disabled"
+        },
+        {
+          "name": "figma-name",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "Figma node named Button"
+        },
+        {
+          "name": "review",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "approved"
+        }
+      ],
+      "screenshot": "41:207",
+      "advancedBecause": "Read-back and review both passed; every variant resolves to bound variables."
+    },
+    "Card": {
+      "at": "2026-09-12T18:04:00.000Z",
+      "changed": ["Rebuilt Card with the elevation variant axis"],
+      "checks": [
+        {
+          "name": "structural-read-back",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "COMPONENT_SET 41:418, 6 children, axes elevation/padding"
+        }
+      ],
+      "advancedBecause": "Structure verified; no review requested for a variant-axis rebuild."
+    }
+  }
+}
+```

package/references/sync-adapters.md

@@ -57,39 +57,35 @@ The cause was the transform group, not the adapter concept. That configuration
 now ships as tested code at
 `${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs`, is installed into the
 consumer's repo, and is verified end to end against a real source (195 emitted
-symbols matched, zero rule failures under the shipping ruleset, on both light
-and dark builds). The badge is back on that basis.
+symbols matched, 107 of them with their magnitude also checked, zero rule
+failures under the shipping ruleset, on both light and dark builds).
+The badge is back on that basis. What "matched" does and does not check is in
+*Verify, always* in `${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`.
 
 **What the badge does not cover: nothing is compiled.** Every emitted value is
 checked to be a well-formed Swift or Kotlin *literal* — `tokens:validate-output`'s
 `invalid-literal` rule parses each one and fails on anything that is not
 (#53) — but no `swiftc` or `kotlinc` runs, so a type mismatch or a call to an
-undefined symbol would still pass. String-valued tokens (`fontFamily`, `string`,
-keyword `fontWeight`) are quoted by the module's own transforms, and a value with
-no native form at all — a CSS `linear-gradient(...)` — is filtered out of native
-output rather than emitted broken. That drop is reported as an unemitted token,
-not hidden.
+undefined symbol would still pass. Which values the module quotes, and which it
+drops for having no native form, is stated in §4 and §6 of
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`. A dropped token is
+not hidden: `tokens:validate-output` reports it as unemitted — see
+`${CLAUDE_PLUGIN_ROOT}/scripts/README.md`.
 
 Since 0.17.0 that gap is measured rather than assumed on ThroughLine's side:
 this project's end-to-end runs compile what they generate — `kotlinc` typechecks
 `Tokens.kt` against Compose stubs, `swiftc -parse` checks `Tokens.swift` —
-against a real 322-token system. That is evidence about the adapter shipped to
+against a real 318-token system. That is evidence about the adapter shipped to
 you, not a gate on your build, and it does not widen what the badge asserts
 about your output.
 
 `android-kotlin` uses the same module and stays Tier 2: its remaining unknowns
 are on the consumption side — Compose `dp`/`sp` behaviour against a real Compose
 app, resource-qualifier conventions, package layout — which building tokens does
-not exercise. The `dp`/`sp` split itself is no longer among them: font sizes and
-line heights whose role a DTCG source states — the `fontSize`, `letterSpacing`
-and `lineHeight` member names of §9.8's typography composite — now emit as
-`sp`. What remains is narrower and documented in
-`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`: a scale primitive
-**nothing references** carries no role and stays `dp`, named by a
-`tokens:validate-output` `unreferenced-text-sibling` advisory; and an `em`
-letterSpacing reaches Compose as a real `.em` TextUnit but is excluded from
-Swift deliberately, since letter spacing there needs a font size no constant
-Swift value could carry.
+not exercise. Which tokens emit as `sp`, and the text-unit limits that remain on
+each platform, are stated once, in §4 of
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`, which is generated
+from the module itself.
 `tokens:validate-output` remains what decides whether any adapter can be
 trusted, and re-promotion is available to any adapter that passes it against a
 real source.
@@ -144,6 +140,9 @@ emit as references to primitive vars rather than flattened literals.
   Tailwind tokens; the standalone `tailwind` adapter maps tokens into the
   Tailwind theme config directly; `mui` emits a JS theme object whose palette
   references preserve the cascade through object structure.
+  `tokens:validate-output` checks the generated CSS against its source too, and
+  only the CSS: for `tailwind`, the file declaring the custom properties, not the
+  theme config. See `${CLAUDE_PLUGIN_ROOT}/scripts/README.md`.
 - **Native adapters** (`ios-swift`, and generated native targets like
   Android/Kotlin): `outputReferences: false` — references resolve to literal
   values at build time, because the target language has no runtime var
@@ -154,45 +153,31 @@ emit as references to primitive vars rather than flattened literals.
 
 ## What the stock configuration gets wrong
 
-These are all legal in a real DTCG source, and a **stock** Style Dictionary
-transform group mishandles every one of them silently — emitting output that
-compiles and is wrong, which is why `tokens:validate-output` exists.
-
-**None of these are Style Dictionary limitations.** All four are fixed by
-roughly 80 lines of preprocessor and transform code, which ships as a tested
-module at `${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs` and is documented in
-`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`. Against a real
-322-token source it emitted 195 symbols that all map to a source token, 107 of
-them with their numeric magnitude additionally verified, with zero rule failures
-— colour and string values are matched by name only and are checked by no rule.
-**Import that module** rather than configuring a native adapter from a stock
-`transformGroup` or transcribing the reference doc.
-
-- **CSS expressions in a value** — `color-mix(in srgb, {color.brand.500} 12%,
-  transparent)` is a runtime CSS construct. Style Dictionary does no colour
-  math, so it resolves only the inner reference and leaves the function wrapper
-  in the output. *Fix: a transform that computes the blend to a literal.*
-- **Dual-node tokens** — a node carrying both a `$value` and children (`text.sm`
-  with `$value: "14px"` plus a `text.sm.lineHeight` child). Style Dictionary's
-  resolver will not traverse into one, so every alias to the child fails to
-  resolve and emits as a bare literal; its collector also stops there, so the
-  child is never emitted at all. *Fix: a preprocessor that resolves aliases and
-  hoists the children.*
-- **`%` and `em` dimensions** — parent-relative or container-relative, so there
-  genuinely is no build-time native magnitude. This one is a real limit rather
-  than a configuration gap. *Handling: filter them out of native builds — on the
-  authored value, since a `100%` token may be typed `string`, not `dimension`.*
+Real token sources carry all of these, and a **stock** Style Dictionary
+transform group mishandles them silently — emitting output that compiles and is
+wrong, which is why `tokens:validate-output` exists.
+
+The native fixes ship as a tested module at
+`${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs`. **Import that module** rather
+than configuring a native adapter from a stock `transformGroup` or transcribing
+the reference doc. What goes wrong in each case, and exactly what the module does
+about it, is stated once, in
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`, which is generated
+from the module and checked for freshness in CI. This list only points there:
+
+- **`px`-authored dimensions** — the stock groups assume `rem` and multiply by
+  16. See §1, *Read the authored unit*.
+- **CSS expressions in a value**, such as `color-mix()` — see §2, *Compute
+  `color-mix()` to a literal*.
+- **Dual-node tokens**, a node carrying both a `$value` and children — see §3,
+  *Resolve aliases and hoist dual-node children*.
+- **`%` and `em` dimensions** — see `nativeFilter` in §4, *Assemble the platform
+  from the stock list*.
 - **A third mode axis** — this reference models theme (`.dark` /
   `[data-theme]`) and brand (`[data-brand]`). A viewport axis carrying its own
   spacing and type scales is common and has no mapping here; on native it is
   size classes and resource qualifiers, resolved by a different mechanism
-  entirely.
-
-**Native dimension transforms must read the authored unit.** The stock
-`ios-swift` and `compose` transform groups assume `rem` input and multiply by
-16. Against a `px`-authored source that silently produces output at sixteen
-times scale which compiles and ships. Emit 1:1 for `px` and unitless ratios;
-×16 only for `rem`.
+  entirely. The module does not address this one.
 
 ## Brownfield value transforms