@radicool/throughline 0.19.0 → 0.20.0

package/adapters/cursor/.cursor/commands/document-component.md

@@ -27,6 +27,9 @@ Ask which component to document (e.g. "Button"), then:
    verify its returned summary and stamp `surfaces.docCard.{src,render,renderer}`
    from it), and (if the repo/code side exists) render MDX/JSDoc and run
    `docs:digest` per the `storybook-chromatic-builder` render step.
+   Before the Figma writes, run the active-file preflight in
+   `.throughline/references/figma-scripting.md` — this command writes
+   inline, so no executor checks the file for you.
 3. **Reconcile drift.** Before trusting `docs:check`, confirm the repo's copy of
    the doc scripts is current: compare `DOC_CARD_RENDERER_VERSION` in the repo's
    `scripts/lib/doc-card-plan.mjs` against the same constant in
@@ -36,7 +39,13 @@ Ask which component to document (e.g. "Button"), then:
    doc scripts from the plugin copy. Refresh the whole set and re-check the npm
    registrations, both per **Documentation scripts — install as a set** in
    `.throughline/scripts/README.md` — a refreshed file whose script was
-   never registered is the same failure in a new place. Run `docs:check` (with the
+   never registered is the same failure in a new place. Two of the registrations,
+   `adherence:check` and `verify:check`, carry placeholder paths and a
+   `--package` specifier: substitute the repo's real ones per the paragraphs under
+   that table, run each once, and use the documented `--skip` for a rule the
+   system doesn't fit, rather than registering a placeholder that fails every
+   run. A repo refreshed from before 0.20.0 gets both for the first time, so say
+   so. Run `docs:check` (with the
    refreshed scripts, if any). For each drifted surface, offer a per-item
    choice — **re-render** (canonical wins) or **pull-back**
    (fold the surface edit into the record) — and land the result as a reviewable

package/adapters/cursor/.cursor/rules/component-builder.mdc

@@ -109,6 +109,10 @@ component once its slice of the spec is complete enough to transcribe. **Keep th
 human checkpoint between components** — subagents run continuously within a
 component, but you pause for the human between them. If your host has no subagent
 dispatch, build and verify each component inline, sequentially, as before.
+Inline, run the active-file preflight in
+`.throughline/references/figma-scripting.md` before the first write and
+again before replacing anything — the executor's file check does not come with
+you.
 
 ## Step 3 — Build each component, bound to tokens/styles
 
@@ -256,7 +260,10 @@ reference register, not this skill's guide voice.
 2. **Enrich from the archetype knowledge base.** Match the component to the nearest
    archetype in `.throughline/references/component-doc-archetypes.md` and
    seed `dos`, `donts`, `accessibility`, `whenToUse`, `whenNotToUse`. Provenance
-   `best-practice` (or `w3c-apg` for the accessibility block).
+   `best-practice` (or `w3c-apg` for the accessibility block). Record the matched
+   archetype's id in the record's `archetype` field — one of `button`, `input`,
+   `choice`, `card`, `modal`, `badge`, `other` — so `verify:check` can read it
+   later rather than re-guessing from the name.
 3. **Specialize to `project.uiFramework`.** Align variant-meaning wording and the
    accessibility idiom to the target framework (the same field you read for variant
    vocabulary). Provenance `framework`.
@@ -351,6 +358,22 @@ any component built with the toggle + manual-swap fallback is listed in
 `components.instanceSwapUpgradePending`. Append `component-builder` to
 `completedSkills`.
 
+**Record the stage entry, one call per component that actually finished:**
+`node .throughline/scripts/verify-check.mjs --record --stage
+component-builder --subject <Name> --entry <tmp>.json`. Build `<tmp>.json` with
+`changed` (what was built), the attested checks `structural-read-back`,
+`state-baseline` and `figma-name` from what the `figma-executor` returned,
+`review` when a reviewer ran, `screenshot` when one was captured, and
+`advancedBecause`. The entry shape is
+`.throughline/references/proof-bundle.md` — don't restate it here. Write
+an entry only for a component that actually finished; a `BLOCKED` component gets
+none. Do this after adding the component to `components.built` above — by the
+time this loop runs, the whole run's components are already there, which is what
+lets this stage's first `--record` capture the full adoption batch; each record
+then removes its own subject from the captured `exempt` list, so running the
+loop over every finished component (not a one-shot write) is what un-grandfathers
+the rest of the batch.
+
 **Upgrade pass:** if `components.instanceSwapUpgradePending` is non-empty, re-resolve
 publish state (detect-or-ask per `.throughline/references/figma-publishing.md`);
 only when it is **confirmed published** (`figma.libraryPublished` true via a verified

package/adapters/cursor/.cursor/rules/icon-system-builder.mdc

@@ -184,6 +184,10 @@ needed here. Route per `.throughline/references/agent-routing.md`. If
 your host has no subagent dispatch, script the SVG-to-component pass inline,
 sequentially, with the user in the loop. Either way, follow
 `.throughline/references/figma-scripting.md`.
+Inline, run the active-file preflight in
+`.throughline/references/figma-scripting.md` before the first write and
+again before replacing anything — the executor's file check does not come with
+you.
 
 ## Step 3 — Normalize: page, naming, sizing, variants
 

package/adapters/cursor/.cursor/rules/storybook-chromatic-builder.mdc

@@ -31,9 +31,18 @@ system). Wire it to consume `packages/tokens` output so stories render with the
 real design tokens (import the generated CSS/theme). Checkpoint: confirm
 Storybook runs and shows the token-themed canvas.
 
-Install the documentation scripts alongside the token scripts: copy the five
-files and register the three npm scripts listed under **Documentation scripts —
-install as a set** in `.throughline/scripts/README.md`. That table is
+Install the documentation scripts alongside the token scripts: copy the twelve
+files and register the five npm scripts listed under **Documentation scripts —
+install as a set** in `.throughline/scripts/README.md`. `adherence:check`
+needs the repo's own values substituted in — the UI package's specifier for
+`--package`, and paths for `--root`/`--system` that match this repo's layout;
+registering it with the table's placeholders leaves a script that cannot run.
+`verify:check` needs the same treatment for its `--root` and `--tokens`, and
+registering it without `--tokens` is worse than leaving a placeholder: the script
+runs, and skips both `orphan-token` and `color-contrast` on every run. Pass **one
+`--tokens` flag per mode file** — `color-contrast` checks each file as its own
+mode, so a multi-mode system registered with a single `--tokens` silently checks
+only one of them. That table is
 the single source of truth for what a consuming repo gets; do not restate the
 list here.
 
@@ -248,13 +257,83 @@ step and/or a Turbo task). It compares every surface against its record and exit
 non-zero on drift; Figma surfaces report `edit-unverified` (checked live in a Figma
 session). Run `docs:check` once here and confirm it passes before handing off.
 
+Ensure `verify:check` is wired alongside it, with the repo's real `--tokens`
+paths — not the registered placeholder, and one flag per mode file — so
+`orphan-token` and `color-contrast` actually run instead of reporting as skipped.
+All four rules (`orphan-token`, `state-incomplete`, `name-drift`,
+`color-contrast`) go live now; if the orphan rule misfires on this repo,
+`--skip orphan-token` is the documented answer, and `--skip color-contrast` is
+the same answer on the same terms for a system whose colour roles are named
+differently. Both print on the report's
+`skipped:` line. Dropping `--tokens` is not an equivalent fix — that switches the
+rules off silently instead of visibly. **Run `verify:check` once here, before
+Step 6 promotes anything to `stable`, and confirm it passes before handing
+off — running it here rather than after Step 6 is deliberate, not an
+oversight**: this run's components are still `draft`, so
+`storybook-chromatic-builder` owes them no entry yet and the gate passes; Step 6
+is what promotes them to `stable`, and Step 7 is what records their entries.
+Moving this call after Step 6, or moving Step 7's recording ahead of it, would
+leave the components `stable`, owed an entry, and without one.
+
+**A contrast failure the user already accepted.** `token-builder` stops on a pair
+below 4.5:1, and a user may explicitly accept it anyway. That acceptance lives in
+`design-system/proof/token-builder.json` under the repo root, on the `system`
+entry's `contrast-baseline` check, as `accepted: [{ fg, bg, mode }]`. Read that
+file — it may not exist, in which case nothing is accepted and any failure stops
+this step as usual. Then compare **this run's live failures** against it: take
+the `[color-contrast]` lines off the report you just ran, and match each one's
+`fg` and `bg` — the canonical `CONTRAST_PAIRS` paths, identical on both sides and
+needing no translation — against each `accepted` entry's `fg`/`bg`, on the same
+normalized fold (lowercase, alphanumerics only). Then:
+
+- **every live failure is an accepted role pair** → register the `verify:check`
+  script in `package.json` with `--skip color-contrast`, and say in one line which
+  pair was accepted, that contrast is therefore **not checked in CI at all** while
+  that flag is there, and that deleting the flag is what re-enables it;
+- **no live failures** → register the script **without** the flag. The pair was
+  fixed, or never applied to this repo, and switching the rule off would hide a
+  future one;
+- **any live failure whose roles are not in `accepted`** → stop, exactly as this
+  step already does.
+
+**The live run is the condition, not the presence of the field.** `accepted`
+persists until `token-builder` is re-run, which nothing asks for — so keying off
+the field alone would switch CI's contrast rule off for a pair that now passes,
+while telling the user the flag is what re-enables it.
+
+**Matching on the roles, and ignoring the mode, is deliberate here.** `--skip` is
+rule-wide: there is no way to skip contrast in Dark and keep it in Light, so a
+per-mode test would decide nothing a role test does not. This skill also *cannot*
+translate a mode name — the recorded `mode` is the Figma name, and this skill
+neither read the Figma modes nor wrote the DTCG files. Only `token-sync-layer`,
+which did both, matches on the mode. The cost, stated rather than hidden:
+whenever an accepted pair's roles also fail in a mode the user did not accept,
+now or later, the roles still match and CI stays skipped. The sync is the
+backstop — it subtracts per mode, so it stops on that unaccepted mode, and every
+token change goes through it.
+
+**That backstop only holds on a tree the sync finished on.** A sync that stopped
+leaves both mode files written and the failure standing, and this skill running
+over that tree would see two failures, match both on roles, and register the flag
+over one nobody accepted. Do not wire the script on a tree whose last sync
+stopped: the pipeline stopped there too, and the fix belongs in Figma before the
+storying stage runs at all.
+
+This skill is where the registered script is created, so it is the only place
+that can apply this consequence — `token-builder` runs at folder stage, before
+any repo, and cannot edit a `package.json` that does not exist.
+
 ## Step 6 — Finalize component status (Figma write-back)
 
 A component built and storied here is now **done** — but its Figma doc card was
 stamped `draft` by component-builder and won't change on its own. Once the code
 component renders and its stories build (and the user has approved the result),
 **promote each finalized component to `stable`** so the design system tells the
-truth in both places.
+truth in both places. **This promotion is what makes a component owe a
+`storybook-chromatic-builder` proof entry** — the stage's lifecycle gate reads
+`components.meta[name].status`, and a component still at `draft` owes it
+nothing. Step 7's recording only follows this step for that reason: reorder them
+and a component would be `stable`, owed an entry, and recorded before it exists.
 
 **Confirm the write-back once, up front.** Before touching Figma, state the batched
 change in one line and get a yes — *"I'll update the N doc cards in Figma: flip the
@@ -267,15 +346,25 @@ For every component you finalized in this run, follow the **"Promoting a
 component's status (write-back on finalize)"** routine in
 `.throughline/references/figma-component-standards.md` (which also covers
 the `figma_execute` scripting gotchas — `getNodeByIdAsync` and an explicit
-`timeout` for the multi-card write):
+`timeout` for the multi-card write). This write runs inline, so run the
+active-file preflight in `.throughline/references/figma-scripting.md`
+before it:
 
 - Set `components.meta[name].status` = `"stable"` and refresh
-  `components.meta[name].updatedAt` to today.
+  `components.meta[name].updatedAt` to today — for every component this pass
+  promotes, including ones this run didn't build. **No verification gate reads
+  `updatedAt`.** A promotion run moves the timestamp of components other stages
+  own, so `proof-missing` scopes itself with the stage's captured `exempt` list
+  instead of a date comparison.
 - When promoting status (e.g. draft → stable), also set `status` + `updatedAt` in
   the component's `.doc.json`, recompute its fingerprint, re-run `docs:digest`, and
   re-render the affected surfaces so `docs:check` stays green.
 - If Figma is connected (per `figma.mechanism`), open the component's doc card and
-  update the `Status Label` text to `stable`, re-bind the `Status` chip fill to
+  locate its status chip under either header shape, as the routine describes: a
+  `Status` chip with a `Status Label` text node on to-spec cards, a `Status Pill`
+  with one text node on legacy cards. If neither is there, don't guess — tell the
+  user that card still shows the old status. Otherwise set the label text to
+  `stable`, re-bind the chip fill to
   the **success** semantic color variable (mode-aware, not a hardcoded hex), then
   re-run the canonical doc-card builder against the same card to refresh the
   header date from the `record.updatedAt` already set above (it locates the date
@@ -296,6 +385,24 @@ Set `storybook.initialized` = `true`, `storybook.chromatic` accordingly,
 Step 6.) Note the ongoing loop: new components flow through the
 component-pipeline orchestrator; token changes flow through `/sync-figma-tokens`.
 
+**Record the stage entry, one call per component finalized this run:**
+`node .throughline/scripts/verify-check.mjs --record --stage
+storybook-chromatic-builder --subject <Name> --entry <tmp>.json`. Build
+`<tmp>.json` with the attested checks `build` (the story build outcome) and
+`review`, `advancedBecause`, and **the two component-scoped derived results,
+`state-incomplete` and `name-drift`, read off the `verify:check` report Step
+5.5 already ran** — recorded with `method: "derived"`. This is one of two stages
+that record derived results, and it qualifies for the same reason the other does:
+it has already run the gate before recording, so it holds the result rather than
+asserting it (`.throughline/references/proof-bundle.md` names both); the
+entry shape is
+`.throughline/references/proof-bundle.md` — don't restate it here. As
+in `component-builder`, this run's components are already in
+`components.built` by the time this loop runs, so this stage's first `--record`
+captures the whole batch into `exempt`; looping over every finalized component
+here, rather than writing once, is what removes each one from that list instead
+of leaving the rest of the batch grandfathered.
+
 ## Brownfield: baseline before retrofit + the verification triad
 
 On a **retrofit** (`tokens.intakeMode: "retrofit"`), the order of operations and the

package/adapters/cursor/.cursor/rules/token-builder.mdc

@@ -70,6 +70,10 @@ human between them. Route per
 `.throughline/references/agent-routing.md`; never parallelize Figma
 work. If your host has no subagent dispatch, build and verify each tier inline,
 sequentially, as the steps below describe.
+Inline, run the active-file preflight in
+`.throughline/references/figma-scripting.md` before the first write and
+again before replacing anything — the executor's file check does not come with
+you.
 
 ## Step 1 — Brainstorm the structure (before building anything)
 
@@ -305,9 +309,84 @@ and later Device (`Spacing`/`Typography`). That's the cost of independent axes.
 Verify the aliases resolve — use `figma_get_variables` (filtered to the new
 semantic collection, `resolveAliases: true`) to confirm semantic tokens point at
 primitives, not literals; if you read via a `figma_execute` script instead, use
-the async APIs (see the dynamic-page note in Prerequisites). Then checkpoint:
-show the semantic layer and demonstrate the cascade if useful ("change `gray/50`
-and `bg/default` follows").
+the async APIs (see the dynamic-page note in Prerequisites).
+
+**Then assert contrast, before the checkpoint.** Using that same
+`figma_get_variables` read (filtered to `Color/Semantic`, `resolveAliases: true`),
+convert Figma's 0–1 RGBA channels to hex and **run the shipped module rather than
+doing the arithmetic in the transcript**: shape the per-mode values as
+`[{ mode, values: { "<dotted token path>": "#rrggbb" } }]` and pass them to a
+single `node` invocation that imports `CONTRAST_PAIRS`, `contrastRatio`,
+`composite` and `AA_NORMAL_TEXT` from
+`.throughline/scripts/lib/contrast.mjs` and prints one line per pair per
+mode:
+
+    node --input-type=module -e "<import the module, read the JSON from
+    process.argv[1], loop CONTRAST_PAIRS × modes, print mode/fg/bg/ratio>" '<the JSON>'
+
+The module ships precisely so the maths has one home: read the table and call the
+function, and restate neither. The pairs are the semantic roles the system
+already promises (`text/onEmphasis` on `bg/emphasis`, `text/primary` on
+`bg/default`, each status text on its own status background); a role this system
+does not have is not asserted.
+
+**The keys are dotted token paths, not Figma variable names.** Figma calls the
+role `text/onEmphasis` in the `Color/Semantic` collection; `CONTRAST_PAIRS`
+spells it `color.text.onEmphasis`, and no normalized fold bridges the two —
+`colorsemantictextonemphasis` is not `colortextonemphasis`. Apply the **Name
+mapping** rule the sync already defines
+(`.throughline/skills/token-sync-layer/SKILL.md`): the category drives
+the top-level group and the tier is dropped, so `Color/Semantic` +
+`text/onEmphasis` → `color.text.onEmphasis`. Both halves of this check have to
+agree on the spelling, or the Figma-time half asserts pairs the CLI half never
+sees, and the two never disagree because they never meet.
+
+**A failing pair stops the tier.** Do not proceed to the checkpoint or to Step 4
+with a pair below 4.5:1. Report it in guide voice
+(`.throughline/references/guide-voice.md`): name the two roles, the
+mode, the measured ratio and the required one, then give **one** recommended fix
+— re-point that mode's alias at a primitive with more separation, naming a
+specific step in the ramp that clears — rather than a menu of options. This is
+the "modes can't be built with poor colour contrast" promise, and it is the
+cheapest place in the whole system to catch it: the mode is being defined right
+now, and nothing is built on it yet.
+
+**If the user explicitly accepts a failing pair**, continue, and say plainly in
+the same breath what it costs downstream — describing the mechanism that actually
+exists, not a registration that cannot reach the sync:
+
+1. The acceptance is recorded in this stage's entry (`contrast-baseline` at
+   `result: "fail"`, `advancedBecause` naming it, and the pair itself listed in
+   `accepted`), and `token-sync-layer` subtracts exactly that pair from its own
+   gate run — so **the next token sync is not blocked** by it, while any *other*
+   failing pair, including one introduced later, still stops the sync.
+2. The repo's own registered `verify:check` — the one
+   `storybook-chromatic-builder` wires into CI later — derives the same ratio off
+   the DTCG source and would fail there. That skill runs the gate itself when it
+   wires the script, and if every failure it sees is a pair recorded here as
+   accepted, it registers the script with `--skip color-contrast` and says so at
+   the time; if the pair has since been fixed, it registers the script without the
+   flag. Nothing is owed to a script that does not exist yet, and nothing is
+   switched off on the strength of a record alone.
+
+Say both, in that order, and then say how each one ends, because they do not end
+the same way. Fixing the pair in Figma **retires the sync's side by itself**: the
+failure stops appearing, the recorded triple matches nothing, and the sync goes
+back to normal on its own — with one expected line on that first sync, where the
+previously recorded `fail` disagrees with a rerun that now passes. That line does
+not stop anything, and the same run re-records the pass. The registered
+`--skip color-contrast` does **not** heal: it is a line in the repo's
+`package.json` and stays until someone removes it, which is the one thing this
+override leaves behind. Say that plainly rather than letting them find it — a
+user who fixes the pair months later and still sees contrast skipped in CI has
+been told the gate is live when it is not. Say the scope too: `--skip` is
+rule-wide, so while that flag is registered CI checks **no** pair, including one
+introduced after the acceptance. The sync is what catches that one, since every
+token change goes through it — but the user should know CI is not the thing
+standing guard meanwhile.
+
+Then checkpoint: show the semantic layer and demonstrate the cascade if useful
+("change `gray/50` and `bg/default` follows").
 
 Update the manifest: `tokens.semanticBuilt` = `true`, add every semantic
 collection to `tokens.collections`.
@@ -347,6 +426,34 @@ Update the manifest: set `tokens.stylesBuilt` = `true` and record which style
 groups were created in `tokens.styleGroups`. Append `token-builder` to
 `completedSkills`.
 
+**Record the stage entry:** `node .throughline/scripts/verify-check.mjs
+--record --stage token-builder --entry <tmp>.json` (subject defaults to
+`"system"`; this stage is not per-component). Build `<tmp>.json` with `changed`
+summarizing the collections and modes created, the attested check
+`contrast-baseline` carrying `result` and a one-line `evidence` naming the
+tightest ratio per mode (`"Light 5.2:1, Dark 4.9:1 — tightest is
+text/onEmphasis on bg/emphasis"`), and `advancedBecause`.
+
+When the user accepted a failing pair, the check's `result` is `"fail"`,
+`advancedBecause` names the acceptance, and the check carries
+`accepted: [{ fg, bg, mode }]` — one entry per accepted pair, `fg` and `bg` as the
+dotted token paths `CONTRAST_PAIRS` uses, and `mode` as **the Figma mode name this
+skill just read** (`Light`, `Dark` — the names in the collection it built), not a
+file name. At this point in the pipeline no DTCG file exists to name a mode
+after: the sync writes those later and chooses their names, so a filename here
+would be a guess that never matches. The sync translates this name into its own
+file label before matching, and recording what was actually observed is what
+makes that translation possible. **Write the pair structurally as well as in
+prose** — `advancedBecause` is for whoever reads the bundle later, and `accepted`
+is what `token-sync-layer` matches against, so an acceptance recorded only in
+prose would stop the next sync exactly as if it had never been given. Accept only
+the pairs the user actually accepted; that list is the scope of the override.
+
+The entry shape is `.throughline/references/proof-bundle.md` — do not
+restate it here. Write the entry only when the tier actually completed: a run that
+stopped on a failing pair and was not resumed records nothing, the same rule
+`component-builder` follows for a `BLOCKED` component.
+
 ## Step 5 — Hand off
 
 Tell the user what's unlocked and offer natural next steps without forcing them:

package/adapters/cursor/.cursor/rules/token-crosswalk-builder.mdc

@@ -71,6 +71,8 @@ Copy these from `.throughline/scripts/` into the user's repo **verbatim**
 - `lib/crosswalk.mjs` → `packages/tokens/scripts/lib/crosswalk.mjs`
 - `lib/dtcg.mjs` → `packages/tokens/scripts/lib/dtcg.mjs` (required by
   `validate-crosswalk.mjs` — copying the validator without it breaks the gate at import)
+- `lib/source-scan.mjs` → `packages/tokens/scripts/lib/source-scan.mjs` (required by
+  `guard-token-removal.mjs` — copying the guard without it breaks it at import)
 - `validate-crosswalk.mjs` → `packages/tokens/scripts/validate-crosswalk.mjs`
 - `build-reverse-index.mjs` → `packages/tokens/scripts/build-reverse-index.mjs`
 - `guard-token-removal.mjs` → `packages/tokens/scripts/guard-token-removal.mjs`

package/adapters/cursor/.cursor/rules/token-sheet-builder.mdc

@@ -50,6 +50,10 @@ variables via `figma_get_variables`, not just a screenshot), gated by a
 `.throughline/references/agent-routing.md`; never parallelize Figma
 work. If your host has no subagent dispatch, build and verify the page inline,
 sequentially, as the steps below describe.
+Inline, run the active-file preflight in
+`.throughline/references/figma-scripting.md` before the first write and
+again before replacing anything — the executor's file check does not come with
+you.
 
 ## Step 1 — Brainstorm the layout (lightly)
 

package/adapters/cursor/.cursor/rules/token-sync-layer.mdc

@@ -103,9 +103,17 @@ Three rules for the multi-collection structure:
   and token-sync-layer are a **matched pair** on this — neither is correct alone.
 
 This DTCG JSON is the canonical intermediate. Write it to a known location in
-`packages/tokens/` (e.g. `packages/tokens/dtcg/tokens.json`). Do not trust the
-MCP's built-in CSS/Tailwind exporters for final output — route through Style
-Dictionary so the adapter system governs the result.
+`packages/tokens/`, **one file per mode**, because every gate downstream reads a
+file as a mode. A single-mode system writes `packages/tokens/dtcg/tokens.json`; a
+light/dark system writes `packages/tokens/dtcg/primitives.json`,
+`packages/tokens/dtcg/semantic.light.json` and
+`packages/tokens/dtcg/semantic.dark.json` — the ramps once, then each mode's
+semantic aliases in its own file. Nesting the modes as groups inside a single
+file (`color.light.*` / `color.dark.*`) is the layout `color-contrast` abstains
+on, and writing a multi-mode system to one `tokens.json` is what leaves the
+registered `verify:check` checking a single mode and reporting that it checked
+one. Do not trust the MCP's built-in CSS/Tailwind exporters for final output —
+route through Style Dictionary so the adapter system governs the result.
 
 ### Brownfield transforms (learned the hard way)
 
@@ -186,12 +194,12 @@ list. See `.throughline/references/native-adapter-config.md`.
 **Execution model — subagent dispatch with model routing.** Generating each
 platform's output is independent and verifiable. If your host supports subagent
 dispatch, dispatch **one `code-executor` per adapter** — each produces its
-platform's files and verifies them (for web: the config builds, the expected
-files appear, references resolve; for native: `tokens:validate-output` passes —
-"the config builds" is not verification, it is the condition under which all
-four known native failure modes ship silently) — then a **`reviewer`**
-to check each before combining. Choose each subagent's model from its role tier
-per `.throughline/references/agent-routing.md` (`code-executor` → fast,
+platform's files and verifies them (for web and native alike:
+`tokens:validate-output` passes — a clean build is not verification, it is the
+condition under which every known failure mode, web or native, ships silently)
+— then a **`reviewer`** to check each before combining. Choose each subagent's
+model from its role tier per
+`.throughline/references/agent-routing.md` (`code-executor` → fast,
 `reviewer` → balanced), and only dispatch once each adapter's spec is complete
 enough to transcribe. If your host has no subagent dispatch, generate and verify
 each adapter inline instead. For a single platform, run inline either way. This
@@ -205,23 +213,34 @@ as **build artifacts** — regenerated every sync, never hand-edited. Wire
 `packages/tokens/package.json` to export them so the UI package, Storybook, and
 any future app consume them.
 
-**Install the native token toolkit — all four files, as a set.** Copy
-`.throughline/scripts/validate-token-output.mjs` into
-`packages/tokens/scripts/`, and
-`.throughline/scripts/lib/dtcg.mjs`,
-`.throughline/scripts/lib/native-literal.mjs`, and
-`.throughline/scripts/lib/sd-native.mjs` into
-`packages/tokens/scripts/lib/`. `sd-native.mjs` and the validator both import
-`dtcg.mjs` and `native-literal.mjs`, so copying any of them without the others
-breaks at import. Then register the gate so it stays live on every future sync:
+**Install the token toolkit — all four files, as a set, for web and native
+targets alike.** Copy these from `.throughline/scripts/` into the
+user's repo verbatim:
+
+- `validate-token-output.mjs` → `packages/tokens/scripts/validate-token-output.mjs`
+- `lib/dtcg.mjs` → `packages/tokens/scripts/lib/dtcg.mjs`
+- `lib/native-literal.mjs` → `packages/tokens/scripts/lib/native-literal.mjs`
+- `lib/sd-native.mjs` → `packages/tokens/scripts/lib/sd-native.mjs`
+
+`sd-native.mjs` and the validator both import `dtcg.mjs` and
+`native-literal.mjs`, so copying any of them without the others breaks at
+import. Then register the gate so it stays live on every future sync:
 
 ```json
 "tokens:validate-output": "node scripts/validate-token-output.mjs --min-match 1"
 ```
 
 Invoke it once per native output file, passing the same `--source` list that
-file's build used. `--min-match 1` is what makes it a gate: the flag defaults to
-`0.5`, so without it a 60% match rate exits `0`.
+file's build used. For web output (`shadcn`, `tailwind`, `vanilla-css`), invoke
+it once per mode block instead: name the block with `--block` and pass the
+sources that block was built from. Pass the generated **CSS** file, the one that
+declares the custom properties. For `tailwind` that is the CSS the theme config
+points at, never the config itself: the gate reads custom properties, and a JS
+config has none, so it would match nothing and fail. A MUI theme, or a Tailwind
+build whose only output is a JS config, isn't checked yet (#127). The
+full contract is in `.throughline/scripts/README.md`. `--min-match 1`
+is what makes it a gate: the flag defaults to `0.5`, so without it a 60% match
+rate exits `0`.
 
 ## Step 4.5 — Icon code sync (install check + custom SVGR)
 
@@ -256,6 +275,69 @@ color.surface.default?`). Surface these prominently. Also surface plain
 deletions (consumers will break — that's intentional, but the human should see
 it).
 
+### Check contrast before it ships
+
+Run the gate once against the DTCG sources this sync just wrote — **always**, with
+no accepted-pair exception. The paragraphs below filter the result, never the run:
+
+```
+node .throughline/scripts/verify-check.mjs --root <repo root> \
+  --tokens <each DTCG source, one flag per mode file> \
+  --skip orphan-token --skip state-incomplete --skip name-drift
+```
+
+**One `--tokens` flag per mode file** — that is what makes each pair get checked
+in every mode. Passing a single file of a multi-mode system checks one mode, and
+says so on the report's `contrast:` line.
+
+**Why those three rules are skipped, so nobody removes the flags.** A sync that
+adds a token is adding one nothing in the repo names yet, which is
+`orphan-token`'s definition of an orphan — running it here would fail nearly
+every sync that does its job. `state-incomplete` and `name-drift` are about doc
+records and code surfaces this skill does not touch. All three stay live in
+`storybook-chromatic-builder`'s run of the same gate.
+
+**Honour an accepted pair, and only an accepted one.** After the gate has run,
+read `design-system/proof/token-builder.json` under the same `--root` (it may not
+exist, in which case there is nothing to honour). Collect the `accepted` array
+from its `system` entry's `contrast-baseline` check, then drop from this run's
+`color-contrast` failures every one whose `(fg, bg, mode)` matches an entry in it,
+comparing `fg` and `bg` on the same normalized fold the rule matches roles with
+(lowercase, alphanumerics only). **Translate `mode` before comparing it:** the
+recorded value is the Figma mode name `token-builder` saw (`Dark`), and the gate
+labels a mode by its DTCG file's basename (`semantic.dark`). This skill is the one
+that knows both — it read the Figma modes and it wrote the files — so map each
+Figma mode to the file it generated for that mode, and compare against that label.
+Untranslated, the triple can never match and the override path silently does not
+exist. Match the triple exactly, and subtract nothing else.
+
+**What this reads.** The gate has no machine-readable output, so this operates on
+`formatReport`'s failure lines — `<fg> on <bg> is <ratio>:1 in <mode> …` — which
+carry all three fields in fixed positions. That is machine-formatted output with a
+stated shape, not prose. Do **not** treat `result: "fail"` on its own as the
+condition, and do **not** pattern-match `advancedBecause`: the first switches off a
+whole rule on the strength of one pair, and the second reads prose written for a
+human as though it were a test.
+
+**Then judge what is left.** Nothing remaining → proceed, and say in one line which
+pair was accepted and is not being re-litigated, both in the sync's message and in
+the PR body. That line is where the override stays visible, and it is the only
+place, since a subtracted failure is by definition not on the report. Anything
+remaining → stop, exactly as if there had been no acceptance: a pair the user never
+saw, in any mode, is the case this rule exists for, and an acceptance given for one
+pair must not carry another one through. An `accepted` list that matches nothing —
+because the pair was fixed, or was never recorded properly — subtracts nothing and
+the sync behaves as though there were no acceptance at all, which is both the
+fail-safe direction and how an acceptance retires itself once the pair clears.
+
+**A `color-contrast` failure stops the sync.** Do not open the PR. Report the
+failing pair and mode in guide voice
+(`.throughline/references/guide-voice.md`), and say the fix is in Figma —
+re-point that mode's alias — not in the generated output, which is a build
+artifact. **Any other failure in the report does not stop the sync**: surface it to
+the user and summarize it in the PR body, but the token sync owns the token tier,
+and a component's missing proof entry is not its to block on.
+
 ## Step 6 — Land it as a reviewable PR (never silent)
 
 Never overwrite token files silently. The output of a sync is a **pull request**
@@ -278,6 +360,44 @@ TurboSnap section in `storybook-chromatic-builder`.
 Update the manifest: `sync.lastRun` (timestamp), `tokens.lastSync`, confirm
 `sync.platforms`. Append `token-sync-layer` to `completedSkills`.
 
+Alongside that, record the stage entry: `node
+.throughline/scripts/verify-check.mjs --record --stage
+token-sync-layer --entry <tmp>.json` (subject defaults to `"system"`, since this
+stage isn't per-component). Build `<tmp>.json` with `changed` summarizing tokens
+added, changed, deleted and probable renames, and the attested
+`tokens:validate-output` result as a check, plus `advancedBecause`. The entry
+shape is `.throughline/references/proof-bundle.md` — don't restate it
+here.
+
+The entry also carries the **derived** check `color-contrast`, its result read off
+the Step 5 report, with `evidence` naming the modes checked and the tightest
+ratio. Record it whenever the report's `contrast:` line compared at least one
+pair. When it compared none (the report says `contrast-rule-inert`, or the run
+passed `--skip color-contrast`) there is no result to record: omit the check, and
+say why in `advancedBecause`. A `pass` written there would describe a comparison
+that never happened, and the gate could never contradict it.
+
+**When a failure was subtracted, record `result: "fail"` — what the gate actually
+reported** — with `advancedBecause` naming the accepted pair as the reason the sync
+proceeded anyway, and `evidence` saying which pair was subtracted. Do not record
+`pass` on the grounds that nothing remained after subtraction: the gate does not
+know about subtraction, the pair still fails on disk, and the next sync's own gate
+run recomputes it, so a recorded `pass` would raise `proof-contradicted` on every
+later sync report. A stored result that disagrees with the file it claims to
+describe is an attestation wearing a derived label.
+
+**Expect one `proof-contradicted` line on the first sync after the user fixes the
+pair**, and say why when you relay it: the stored `fail` is now disagreed with by a
+rerun that passes, which `checkProof` reports in both directions. It does not stop
+the sync, and this step re-records the pass on that same run, so it clears itself
+in one pass. Relaying an expected, self-healing line as a problem is how a user is
+taught to distrust the gate.
+
+**The ordering is the point.** The gate runs in Step 5 and the record is written
+here in Step 6, and it is that order which makes recording a derived result honest:
+this stage has the gate's output in hand rather than asserting it, which is the one
+and only reason a stage may record `method: "derived"`.
+
 ## Step 7 — Install the `/sync-figma-tokens` command
 
 Set up the reusable command (the plugin ships it in `commands/`) so the user can

package/adapters/generic/commands/document-component.md

@@ -27,6 +27,9 @@ Ask which component to document (e.g. "Button"), then:
    verify its returned summary and stamp `surfaces.docCard.{src,render,renderer}`
    from it), and (if the repo/code side exists) render MDX/JSDoc and run
    `docs:digest` per the `storybook-chromatic-builder` render step.
+   Before the Figma writes, run the active-file preflight in
+   `.throughline/references/figma-scripting.md` — this command writes
+   inline, so no executor checks the file for you.
 3. **Reconcile drift.** Before trusting `docs:check`, confirm the repo's copy of
    the doc scripts is current: compare `DOC_CARD_RENDERER_VERSION` in the repo's
    `scripts/lib/doc-card-plan.mjs` against the same constant in
@@ -36,7 +39,13 @@ Ask which component to document (e.g. "Button"), then:
    doc scripts from the plugin copy. Refresh the whole set and re-check the npm
    registrations, both per **Documentation scripts — install as a set** in
    `.throughline/scripts/README.md` — a refreshed file whose script was
-   never registered is the same failure in a new place. Run `docs:check` (with the
+   never registered is the same failure in a new place. Two of the registrations,
+   `adherence:check` and `verify:check`, carry placeholder paths and a
+   `--package` specifier: substitute the repo's real ones per the paragraphs under
+   that table, run each once, and use the documented `--skip` for a rule the
+   system doesn't fit, rather than registering a placeholder that fails every
+   run. A repo refreshed from before 0.20.0 gets both for the first time, so say
+   so. Run `docs:check` (with the
    refreshed scripts, if any). For each drifted surface, offer a per-item
    choice — **re-render** (canonical wins) or **pull-back**
    (fold the surface edit into the record) — and land the result as a reviewable