@radicool/throughline 0.20.0 → 0.21.0

package/README.md

@@ -204,7 +204,7 @@ Future improvements and planned capabilities. Have a request? **[Open an issue](
 - **Deeper Code Connect coverage** — richer Figma-to-code mappings as more plans support it.
 - **Expanded component starters** — a larger foundational kit out of the box.
 - **Richer status & auditing** — more from `/design-system-status`, including drift detection between Figma and code.
-- **Built-in accessibility checks** — the color half is shipped. Eight semantic text-on-surface pairs are checked against WCAG AA's 4.5:1 when tokens are created in Figma, and derived again from the token source when they sync to code — in every mode, so a system that clears in light and fails in dark fails. A failing pair stops the build rather than warning. Component-level accessibility is the half still ahead: focus indicators, status conveyed by more than color, text alternatives.
+- **Built-in accessibility checks** — the color half is shipped. Eight semantic text-on-surface pairs are checked against WCAG AA's 4.5:1 when tokens are created in Figma, and derived again from the token source when they sync to code — in every mode, so a system that clears in light and fails in dark fails. A failing pair stops the build rather than warning. Components are checked too: on web frameworks, a Figma build stops when a focus state has no visible ring, and in JSX code the adherence gate fails an icon-only button with no accessible name and a status badge that relies on color alone. Still ahead: focus-ring contrast (WCAG's 3:1 for non-text).
 - **Token fan-out to more platforms** — the DTCG token source is platform-neutral, and web targets are in daily use. Every target is **validated per build, not assumed**: `tokens:validate-output` checks generated output against its source, native Swift and Kotlin as well as web CSS, because the stock transforms have been measured emitting wrong-but-compiling values. iOS/Swift is a curated adapter whose Style Dictionary configuration ships as tested code, and Android/Kotlin uses the same configuration through the Tier 2 protocol. JavaScript theme output (MUI, a Tailwind v3 config) isn't checked yet.
 - **Native component code generation** — producing a SwiftUI view or a Compose composable the way Storybook components are produced for React. This does not exist yet; it is a separate, larger effort than token fan-out, and the two were previously described as one roadmap item.
 

package/adapters/codex/prompts/component-builder.md

@@ -171,7 +171,9 @@ deterministic naming):
   visual-validation loop (screenshot → fix any overlaps/misalignment →
   re-screenshot) **and its "Post-build audit (REQUIRED before handoff)"
   read-back checklist** (container type, auto layout, bound variables,
-  deterministic names) before the checkpoint.
+  deterministic names) before the checkpoint. When you build inline, with no
+  `figma-executor`, that includes item 9's `focus-indicator` check: a miss stops
+  the build, as it would for the executor.
 
 Checkpoint after each component: show all variants, confirm before the next.
 
@@ -357,8 +359,10 @@ any component built with the toggle + manual-swap fallback is listed in
 **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,
+`at` (an ISO timestamp you supply), `changed` (what was built), the attested checks `structural-read-back`,
+`state-baseline` and `figma-name` from what the `figma-executor` returned (or
+what your inline read-back found), `focus-indicator` when that check ran and
+passed (not when it was skipped),
 `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

package/adapters/codex/prompts/storybook-chromatic-builder.md

@@ -384,7 +384,7 @@ 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
+`<tmp>.json` with `at` (an ISO timestamp you supply), 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

package/adapters/codex/prompts/token-builder.md

@@ -424,8 +424,8 @@ groups were created in `tokens.styleGroups`. Append `token-builder` to
 
 **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
+`"system"`; this stage is not per-component). Build `<tmp>.json` with `at` (an ISO
+timestamp you supply), `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`.

package/adapters/codex/prompts/token-sync-layer.md

@@ -359,7 +359,7 @@ Update the manifest: `sync.lastRun` (timestamp), `tokens.lastSync`, confirm
 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
+stage isn't per-component). Build `<tmp>.json` with `at` (an ISO timestamp you supply), `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

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

@@ -175,7 +175,9 @@ deterministic naming):
   visual-validation loop (screenshot → fix any overlaps/misalignment →
   re-screenshot) **and its "Post-build audit (REQUIRED before handoff)"
   read-back checklist** (container type, auto layout, bound variables,
-  deterministic names) before the checkpoint.
+  deterministic names) before the checkpoint. When you build inline, with no
+  `figma-executor`, that includes item 9's `focus-indicator` check: a miss stops
+  the build, as it would for the executor.
 
 Checkpoint after each component: show all variants, confirm before the next.
 
@@ -361,8 +363,10 @@ any component built with the toggle + manual-swap fallback is listed in
 **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,
+`at` (an ISO timestamp you supply), `changed` (what was built), the attested checks `structural-read-back`,
+`state-baseline` and `figma-name` from what the `figma-executor` returned (or
+what your inline read-back found), `focus-indicator` when that check ran and
+passed (not when it was skipped),
 `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

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

@@ -388,7 +388,7 @@ 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
+`<tmp>.json` with `at` (an ISO timestamp you supply), 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

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

@@ -428,8 +428,8 @@ groups were created in `tokens.styleGroups`. Append `token-builder` to
 
 **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
+`"system"`; this stage is not per-component). Build `<tmp>.json` with `at` (an ISO
+timestamp you supply), `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`.

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

@@ -363,7 +363,7 @@ Update the manifest: `sync.lastRun` (timestamp), `tokens.lastSync`, confirm
 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
+stage isn't per-component). Build `<tmp>.json` with `at` (an ISO timestamp you supply), `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

package/adapters/generic/skills/component-builder/SKILL.md

@@ -171,7 +171,9 @@ deterministic naming):
   visual-validation loop (screenshot → fix any overlaps/misalignment →
   re-screenshot) **and its "Post-build audit (REQUIRED before handoff)"
   read-back checklist** (container type, auto layout, bound variables,
-  deterministic names) before the checkpoint.
+  deterministic names) before the checkpoint. When you build inline, with no
+  `figma-executor`, that includes item 9's `focus-indicator` check: a miss stops
+  the build, as it would for the executor.
 
 Checkpoint after each component: show all variants, confirm before the next.
 
@@ -357,8 +359,10 @@ any component built with the toggle + manual-swap fallback is listed in
 **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,
+`at` (an ISO timestamp you supply), `changed` (what was built), the attested checks `structural-read-back`,
+`state-baseline` and `figma-name` from what the `figma-executor` returned (or
+what your inline read-back found), `focus-indicator` when that check ran and
+passed (not when it was skipped),
 `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

package/adapters/generic/skills/storybook-chromatic-builder/SKILL.md

@@ -384,7 +384,7 @@ 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
+`<tmp>.json` with `at` (an ISO timestamp you supply), 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

package/adapters/generic/skills/token-builder/SKILL.md

@@ -424,8 +424,8 @@ groups were created in `tokens.styleGroups`. Append `token-builder` to
 
 **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
+`"system"`; this stage is not per-component). Build `<tmp>.json` with `at` (an ISO
+timestamp you supply), `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`.

package/adapters/generic/skills/token-sync-layer/SKILL.md

@@ -359,7 +359,7 @@ Update the manifest: `sync.lastRun` (timestamp), `tokens.lastSync`, confirm
 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
+stage isn't per-component). Build `<tmp>.json` with `at` (an ISO timestamp you supply), `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Build a complete design system end to end — author in Figma, sync tokens to code, generate Storybook. Usable from Claude Code, Cursor, Codex, or any AGENTS.md agent.",
   "type": "module",
   "bin": {

package/references/figma-component-standards.md

@@ -571,6 +571,53 @@ For each generated artboard / doc card / icon grid, read the nodes back (via
    previously-built components too** — when you touch an existing one, a legacy padded
    wrapper, an inside-aligned stroke, or a transparent variant with no ring at all must
    be retrofitted to the current recipe (see "State handling").
+
+   **The `focus-indicator` check** is the programmatic half of this item. Run it
+   with `figma_execute`. What a miss does depends on who designed the ring:
+   - **`figma-executor` returns `BLOCKED`** on a miss, naming the variant. It
+     builds from an architect spec, and adding a ring the spec didn't give is a
+     design decision it doesn't make.
+   - **Building inline**, you designed the ring yourself, so a miss is a build
+     error: fix and re-audit like any other item. If the ring is still missing
+     when the pass budget below runs out, **stop the build** rather than hand off.
+   - **Scope.** It runs only for a component whose name folds (lowercase,
+     punctuation stripped) to a Button, an Input / text field, or a Checkbox /
+     radio / toggle / chip, the same exact-name match as the state check. A Switch
+     or a TextInput isn't in that list, so neither Figma check reads it (the CLI's
+     `state-incomplete` does). It also
+     needs `project.uiFramework` to be exactly `shadcn`, `tailwind`, `mui`,
+     `vanilla-css` or `vanilla`, or absent or `null`. Anything else (`ios-swift`,
+     a tier-2 library, any other value) is skipped, and the skip is said.
+   - **What it reads.** Every child `COMPONENT` of the set whose
+     `variantProperties` has a key folding to `state` with a value folding to
+     exactly `focus`. `Focused` or `focus-visible` isn't read. The ring is looked
+     for on that variant, or, where the variant wraps the control in other content
+     (an Input with a label or helper text), on the child frame that is the
+     control, the node the recipe above puts the ring on. Reading **zero** focus
+     variants on an in-scope component is not a pass: it means the `state` axis
+     has no `focus` value, which the state check stops on.
+   - **A focus variable** is any variable whose name has a `focus` segment:
+     `border/focus`, `color/border/focus`, `color/focus/ring` and
+     `color/focus/ringOnFill` all count. Systems name their ring role differently,
+     and a collection prefix is common. A raw colour, or a variable with no `focus`
+     segment, doesn't count.
+   - **Ring recipes** (`shadcn`, `tailwind`, absent or `null`; `mui` on anything
+     but an input). The control has either a `DROP_SHADOW` effect with
+     `visible !== false`, `spread > 0` and `boundVariables.color` on a focus
+     variable, or a direct child with `layoutPositioning = "ABSOLUTE"` and
+     `strokeAlign = "OUTSIDE"` whose stroke is bound to a focus variable.
+     `spread > 0` matters: binding an effect's colour can silently zero its spread
+     (see `figma-scripting.md`), which leaves a ring that is bound and invisible.
+     Only the ring is asserted. The recipe's border recolour is styling, and a
+     control whose border keeps its normal colour beside a correct ring passes.
+   - **`mui` inputs.** The control's own stroke is bound to a focus variable, and its
+     weight to a variable (the recipe's `width/focus`).
+   - **`vanilla-css` / `vanilla`.** The control or a direct child carries a stroke
+     bound to a focus variable with `strokeAlign = "OUTSIDE"`. The `offset/focus` gap
+     isn't asserted.
+   - **The result.** On a miss, stop and name the variant and what it lacks. On a
+     pass, `component-builder` records `focus-indicator` as an attested check. A
+     skip records nothing.
 10. **Visual** — the screenshot (from the validation loop) shows no overlaps,
    misalignment, lopsided hug/fill sizing, or clipped strokes/focus rings.
 11. **Usage band rendered by the builder** — the card's `Usage` frame was

package/references/proof-bundle.md

@@ -206,6 +206,7 @@ keyed by component?"
 | `structural-read-back` | attested | `component-builder` |
 | `state-baseline` | attested | `component-builder` |
 | `figma-name` | attested | `component-builder` |
+| `focus-indicator` | 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 |
@@ -277,6 +278,12 @@ One stage file with two subjects — `Button`, freshly built and reviewed, and
           "result": "pass",
           "evidence": "Figma node named Button"
         },
+        {
+          "name": "focus-indicator",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "shadcn: every focus variant carries a visible ring bound to a focus variable"
+        },
         {
           "name": "review",
           "method": "attested",

package/scripts/README.md

@@ -11,7 +11,7 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `build-reverse-index.mjs` | Emit a `codeToken -> newToken` map from the crosswalk to semi-automate SCSS/Tailwind swaps. | `tokens:reverse-index` |
 | `guard-token-removal.mjs` | Grep `.ts/.tsx` (minus generated + tests) for about-to-be-deleted symbols; blocks cleanup until zero references remain. | run during the cleanup phase |
 | `validate-token-output.mjs` | Assert generated token output — Swift, Kotlin, or web CSS custom properties — matches its DTCG source: authored-unit fidelity and no mode collisions everywhere, plus no leaked CSS syntax and no bare unit literals in Swift and Kotlin. Fails when no emitted symbol matches a source token, and reports match rate, unparsed lines, and unemitted tokens on every run. | `tokens:validate-output` |
-| `validate-adherence.mjs` | Assert the code *consuming* a design system still adheres to it: every referenced component exists, every literal variant value is one the system declares, and no colour, spacing, radius or type literal duplicates a token that already holds that value. Fails when an enabled rule had nothing to check, so a green run always means something was verified. | `adherence:check` |
+| `validate-adherence.mjs` | Assert the code *consuming* a design system still adheres to it: every referenced component exists, every literal variant value is one the system declares, and no colour, spacing, radius or type literal duplicates a token that already holds that value. `unnamed-control` fails a Button or IconButton (or a component whose doc record says `archetype: "button"`) with no accessible name: no text, and no `aria-label`, `aria-labelledby` or `title` on it or anything inside it. `colour-only-status` fails a Badge or Tag (or a record with `archetype: "badge"`) the same way, so its status isn't carried by colour alone. Both read script files only (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`), abstain rather than guess on anything they can't read, print how many elements they checked and abstained on, and can be switched off with `--skip`. Fails when an enabled rule had nothing to check, so a green run always means something was verified. | `adherence:check` |
 | `lib/source-scan.mjs` | Shared source-tree walker (`walk`, `DEFAULT_EXCLUDES`, `SOURCE_EXT`) plus `normalizeName`, the display-name-to-code-identifier fold. Every gate that scans a consumer's repo reads it from here rather than carrying its own copy. | copied alongside `guard-token-removal.mjs`, and in the documentation set for `validate-adherence.mjs` and `verify-check.mjs` |
 | `lib/crosswalk.mjs` | Shared loader + structural validation for `crosswalk.json` (used by the validator and reverse-index). | copied alongside |
 | `lib/dtcg.mjs` | Shared DTCG flatten + `{alias}` resolution. Dual-node aware: a node carrying both a `$value` and children yields its own value **and** is descended into. Used by `validate-crosswalk.mjs`, `validate-token-output.mjs`, `validate-adherence.mjs`, `verify-check.mjs`, and `lib/sd-native.mjs`. | copied alongside each of those |
@@ -26,7 +26,7 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `lib/doc-card-plan.mjs` | Pure layout planner for the doc card's `Usage` band + `DOC_CARD_RENDERER_VERSION` (single source of the layout version). Inlined into `references/doc-card-builder.md`; imported by `docs-check.mjs`. | copied alongside docs-check.mjs; also inlined into the generated builder |
 | `verify-check.mjs` | The verification proof bundle: records each stage's entry, and re-derives what it can rather than trusting the record. Fails on an orphaned token, a component documented without its archetype's baseline interaction states, a name that drifts between the manifest, its record and its code surface, or a recorded result the rerun contradicts. | `verify:check` |
 | `lib/proof.mjs` | The proof store's vocabulary and mechanics: the stage list, entry validation, latest-wins merge, and the fingerprint the manifest pointer carries. | copied alongside `verify-check.mjs` |
-| `lib/component-states.mjs` | The archetype table and resolver behind `state-incomplete` — which baseline interaction states each kind of component owes, and when to abstain. | copied alongside `verify-check.mjs` |
+| `lib/component-states.mjs` | The archetype table and resolver behind `state-incomplete` — which baseline interaction states each kind of component owes, and when to abstain. `validate-adherence.mjs` also uses it to find Badges. | copied alongside `verify-check.mjs` and `validate-adherence.mjs` |
 | `lib/contrast.mjs` | The WCAG contrast maths and the semantic colour pairs behind `color-contrast` — which text role must clear which surface, in every mode, and where the rule deliberately abstains. | copied alongside `verify-check.mjs` |
 | `build-doc-card-builder.mjs` | Generate `references/doc-card-builder.md` from the planner + the Figma renderer template (`lib/doc-card-render.figma.js`). `--check` gates CI. | plugin-internal (not installed) |
 | `build-native-adapter-config.mjs` | Generate `references/native-adapter-config.md` by slicing `lib/sd-native.mjs` on its `@doc-section` markers and interleaving each fragment under its prose. Fails when module code falls outside every section, so the doc cannot silently ship incomplete. `--check` gates CI. | plugin-internal (not installed) |
@@ -192,11 +192,13 @@ conflict, or remaining reference), `2` bad CLI arguments.
 
 ## How the skill installs these
 
-`token-crosswalk-builder` copies `lib/crosswalk.mjs`, `lib/dtcg.mjs`,
-`lib/source-scan.mjs`, `validate-crosswalk.mjs`, `build-reverse-index.mjs`,
-`guard-token-removal.mjs`, and
-`crosswalk.schema.json` into the user's `packages/tokens/scripts/` (schema beside `crosswalk.json`), then
-wires `packages/tokens/package.json`:
+The file lists live in the skills, as `src` → `dest` copy lines that
+`ci/validate-install-sets.mjs` checks. They are not repeated here, so they can't
+drift.
+
+`token-crosswalk-builder` copies the files in its Step 2 list
+(`skills/token-crosswalk-builder/SKILL.md`) into the user's `packages/tokens/`,
+then wires `packages/tokens/package.json`:
 
 ```jsonc
 "scripts": {
@@ -205,11 +207,11 @@ wires `packages/tokens/package.json`:
 }
 ```
 
-`token-sync-layer` copies `validate-token-output.mjs`, `lib/dtcg.mjs`,
-`lib/native-literal.mjs`, **and** `lib/sd-native.mjs`, and wires
-`"tokens:validate-output"`. All four travel together: `sd-native.mjs` and the
-validator both import `lib/dtcg.mjs` and `lib/native-literal.mjs`, so
-installing any one of them alone breaks at import time.
+`token-sync-layer` copies its token-toolkit list
+(`skills/token-sync-layer/SKILL.md`, Step 4) and wires `"tokens:validate-output"`.
+The files travel together: `sd-native.mjs` and the validator both import
+`lib/dtcg.mjs` and `lib/native-literal.mjs`, so installing any one of them alone
+breaks at import time.
 
 The scripts version with the user's repo so their CI runs them locally — a path
 inside the plugin install would not be reachable from the user's CI.

package/scripts/build-docs-digest.mjs

@@ -17,6 +17,7 @@ export function buildIndex(records) {
     generatedFrom: 'design-system/docs/components/*.doc.json',
     components: records.map((r) => ({
       name: r.name,
+      archetype: r.archetype ?? null,
       summary: r.summary ?? '',
       description: r.description ?? '',
       whenToUse: r.whenToUse ?? [],

package/scripts/validate-adherence.mjs

@@ -16,6 +16,7 @@ import { pathToFileURL } from 'node:url';
 import { join, dirname, relative, sep } from 'node:path';
 import { walk, normalizeName } from './lib/source-scan.mjs';
 import { flattenDtcg, flattenDtcgTypes, resolveValue } from './lib/dtcg.mjs';
+import { resolveArchetype } from './lib/component-states.mjs';
 
 // Named imports from one package, alias included: `{ Card as Panel }`.
 const IMPORT = /import\s*\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g;
@@ -217,6 +218,180 @@ export function templateView(text) {
   return out.join('');
 }
 
+// The JSX subtree reader (#140): docs/specs/2026-09-29-component-accessibility-checks.md.
+// It runs alongside ELEMENT, not in place of it: only the usage rules read it.
+// Every function returns null on anything it can't pair cleanly, and the caller
+// turns that into `paired: false`, never a guess.
+const IDENT_START = /[A-Za-z_$]/;
+const NAME_CHAR = /[\w$.:-]/;
+
+// i is at an opening quote; returns the index just past its close.
+function skipString(code, i) {
+  const q = code[i];
+  for (let j = i + 1; j < code.length; j++) {
+    if (code[j] === '\\') j++;
+    else if (q === '`' && code[j] === '$' && code[j + 1] === '{') {
+      const end = skipBraces(code, j + 1);
+      if (end === null) return null;
+      j = end - 1;
+    } else if (code[j] === q) return j + 1;
+  }
+  return null;
+}
+
+// i is at `{`; returns the index just past its matching `}`. JSX inside an
+// expression (`{ok && <Badge>Done</Badge>}`) is read as JSX, so an apostrophe
+// in its text isn't taken for a string. A `<` after an identifier character is
+// a comparison or a type argument.
+function skipBraces(code, i) {
+  let depth = 0;
+  for (let j = i; j < code.length; j++) {
+    const c = code[j];
+    if (c === '"' || c === "'" || c === '`') {
+      const end = skipString(code, j);
+      if (end === null) return null;
+      j = end - 1;
+    } else if (c === '<' && !/[\w$.)\]]/.test(code[j - 1] ?? '') && /[A-Za-z>]/.test(code[j + 1] ?? '')) {
+      const el = parseElement(code, j);
+      if (el === null) return null;
+      j = el.end - 1;
+    } else if (c === '{') depth++;
+    else if (c === '}' && --depth === 0) return j + 1;
+  }
+  return null;
+}
+
+// i is at `<`. Reads the name and attributes up to `>` or `/>`.
+function parseTag(code, i) {
+  let j = i + 1;
+  let name = '';
+  while (j < code.length && NAME_CHAR.test(code[j])) name += code[j++];
+  const attrs = [];
+  let spread = false;
+  for (;;) {
+    while (/\s/.test(code[j] ?? '')) j++;
+    if (j >= code.length) return null;
+    if (code.startsWith('/>', j)) return { name, attrs, spread, selfClosing: true, end: j + 2 };
+    if (code[j] === '>') return { name, attrs, spread, selfClosing: false, end: j + 1 };
+    if (code[j] === '{') {
+      const end = skipBraces(code, j);
+      if (end === null || !code.slice(j + 1, end - 1).trim().startsWith('...')) return null;
+      spread = true;
+      j = end;
+      continue;
+    }
+    if (!IDENT_START.test(code[j])) return null;
+    let attr = '';
+    while (j < code.length && NAME_CHAR.test(code[j])) attr += code[j++];
+    while (/\s/.test(code[j] ?? '')) j++;
+    if (code[j] !== '=') {
+      attrs.push({ name: attr, kind: 'bare', value: null });
+      continue;
+    }
+    j++;
+    while (/\s/.test(code[j] ?? '')) j++;
+    if (code[j] === '"' || code[j] === "'") {
+      const end = skipString(code, j);
+      if (end === null) return null;
+      attrs.push({ name: attr, kind: 'literal', value: code.slice(j + 1, end - 1) });
+      j = end;
+    } else if (code[j] === '{') {
+      const end = skipBraces(code, j);
+      if (end === null) return null;
+      attrs.push({ name: attr, kind: 'expr', value: null });
+      j = end;
+    } else return null;
+  }
+}
+
+// i is just past an opening tag named `name`; reads to its matching close.
+function parseChildren(code, i, name) {
+  const children = [];
+  let j = i;
+  while (j < code.length) {
+    if (code[j] === '<') {
+      if (code[j + 1] === '/') {
+        const close = code.indexOf('>', j);
+        if (close === -1 || code.slice(j + 2, close).trim() !== name) return null;
+        return { children, end: close + 1 };
+      }
+      const el = parseElement(code, j);
+      if (el === null) return null;
+      children.push({ type: 'element', name: el.name, attrs: el.attrs, spread: el.spread, selfClosing: el.selfClosing, children: el.children });
+      j = el.end;
+    } else if (code[j] === '{') {
+      const end = skipBraces(code, j);
+      if (end === null) return null;
+      // A JSX comment `{/* */}` is blank by now, and names nothing.
+      if (code.slice(j + 1, end - 1).trim()) children.push({ type: 'expr', value: code.slice(j + 1, end - 1) });
+      j = end;
+    } else {
+      let k = j;
+      while (k < code.length && code[k] !== '<' && code[k] !== '{') k++;
+      children.push({ type: 'text', value: code.slice(j, k) });
+      j = k;
+    }
+  }
+  return null;
+}
+
+function parseElement(code, i) {
+  const tag = parseTag(code, i);
+  if (tag === null) return null;
+  if (tag.selfClosing) return { ...tag, children: [] };
+  const body = parseChildren(code, tag.end, tag.name);
+  if (body === null) return null;
+  return { ...tag, children: body.children, end: body.end };
+}
+
+// One entry per opening tag ELEMENT matches on an imported name, nested ones
+// included: a Button inside a Card is its own entry and also one of the Card's
+// children. `code` is comment-blanked.
+export function readSubtrees(code, imported) {
+  const subtrees = [];
+  for (const el of code.matchAll(ELEMENT)) {
+    const declared = imported.get(el[1]);
+    if (!declared || el[2]) continue;
+    const line = lineOf(code, el.index);
+    let parsed;
+    try {
+      parsed = parseElement(code, el.index);
+    } catch (e) {
+      // Nesting past the stack's depth abstains like anything else unpaired.
+      if (!(e instanceof RangeError)) throw e;
+      parsed = null;
+    }
+    if (parsed === null) {
+      let tag = null;
+      try {
+        tag = parseTag(code, el.index);
+      } catch (e) {
+        if (!(e instanceof RangeError)) throw e;
+      }
+      subtrees.push({
+        component: declared,
+        line,
+        selfClosing: tag?.selfClosing ?? false,
+        paired: false,
+        attrs: tag?.attrs ?? [],
+        spread: tag?.spread ?? false,
+        children: [],
+      });
+      continue;
+    }
+    subtrees.push({
+      component: declared,
+      line,
+      selfClosing: parsed.selfClosing,
+      paired: true,
+      attrs: parsed.attrs,
+      spread: parsed.spread,
+      children: parsed.children,
+    });
+  }
+  return subtrees;
+}
+
 export function extract(text, pkg, path = '') {
   if (path.endsWith('.html')) text = templateView(text);
   const code = blankComments(text, path);
@@ -258,7 +433,9 @@ export function extract(text, pkg, path = '') {
     if (value) literals.push({ value, line: lineOf(colourText, m.index) });
   }
 
-  return { imported, elements, usages, literals, dimensions: extractDimensions(text, path) };
+  const subtrees = /\.(jsx?|tsx?|mjs|cjs)$/.test(path) ? readSubtrees(code, imported) : [];
+
+  return { imported, elements, usages, literals, dimensions: extractDimensions(text, path), subtrees };
 }
 
 // value -> the token paths that hold it. Repeatable --tokens, because a real
@@ -520,6 +697,72 @@ export function partOwner(name, built) {
   return best;
 }
 
+// The usage rules (#140). Both judge an element the same way and differ only in
+// which components they target. The order matters: abstain before naming, so a
+// spread that may carry the label is never read as unnamed.
+export const A11Y_RULES = ['unnamed-control', 'colour-only-status'];
+const NAMING = ['aria-label', 'aria-labelledby', 'title'];
+// On a descendant, a prop that may render text: an icon's `size` or `color`
+// can't, an i18n component's `i18nKey` or `id` can.
+const LABEL_LIKE = new Set(['label', 'alt', 'text', 'i18nKey', 'defaultMessage', 'message', 'id']);
+const isLabelLike = (name) => LABEL_LIKE.has(name) || /(Label|Text)$/.test(name);
+// On an element with nothing inside, props that can never be its label. An icon
+// prop takes a component, not text.
+const NEVER_LABEL = new Set([
+  'className',
+  'style',
+  'disabled',
+  'type',
+  'key',
+  'ref',
+  'id',
+  'aria-hidden',
+  'asChild',
+  'icon',
+  'leadingIcon',
+  'trailingIcon',
+  ...NAMING,
+]);
+
+function namesItself(attrs) {
+  return attrs.some((a) => NAMING.includes(a.name) && (a.kind === 'expr' || (a.kind === 'literal' && a.value.trim() !== '')));
+}
+
+function* descendants(children) {
+  for (const c of children) {
+    if (c.type !== 'element') continue;
+    yield c;
+    yield* descendants(c.children);
+  }
+}
+
+// JSX drops whitespace-only text, and an expression may be the label.
+function hasText(children) {
+  return children.some(
+    (c) => c.type === 'expr' || (c.type === 'text' && c.value.trim() !== '') || (c.type === 'element' && hasText(c.children)),
+  );
+}
+
+// 'named', 'unnamed', or 'abstain' when the name could arrive some way the
+// reader can't see.
+export function judgeName(el, record) {
+  if (!el.paired || el.spread) return 'abstain';
+  const inside = [...descendants(el.children)];
+  if (inside.some((d) => d.spread || d.attrs.some((a) => isLabelLike(a.name)))) return 'abstain';
+  if (namesItself(el.attrs) || inside.some((d) => namesItself(d.attrs))) return 'named';
+  if (hasText(el.children)) return 'named';
+  // `<Button label="Save"></Button>` has no children to judge by either, so it
+  // gets the same scrutiny as `<Button label="Save" />`. JSX drops whitespace-only
+  // text, so that counts as nothing inside too.
+  if (el.children.every((c) => c.type === 'text' && c.value.trim() === '')) {
+    // With no record there's no telling a variant from a label prop.
+    const modelled = new Set([...Object.keys(record?.variants ?? {}), ...Object.keys(record?.states ?? {})]);
+    const unknown = (a) => !modelled.has(a.name) && !NEVER_LABEL.has(a.name) && !/^on[A-Z]/.test(a.name) && !/^data-/.test(a.name);
+    if (el.attrs.some(unknown)) return 'abstain';
+  }
+  return 'unnamed';
+}
+
 export function validate({
   built = [],
   index = { components: [] },
@@ -557,9 +800,31 @@ export function validate({
     dynamic: 0,
     knownComponents: new Set(),
     undocumented: new Set(),
+    // No inert failure for these: an app with no Badge isn't misconfigured. A
+    // rule that checked nothing shows as 0 checked instead.
+    a11y: Object.fromEntries(A11Y_RULES.filter((rule) => !off.has(rule)).map((rule) => [rule, { checked: 0, abstained: 0 }])),
   };
 
-  for (const { path, elements = [], usages, literals, dimensions = [] } of files) {
+  for (const { path, elements = [], usages, literals, dimensions = [], subtrees = [] } of files) {
+    for (const el of subtrees) {
+      const key = normalizeName(el.component);
+      const record = records.get(key);
+      const targeted = {
+        'unnamed-control': key === 'button' || key === 'iconbutton' || record?.archetype === 'button',
+        'colour-only-status': resolveArchetype(record ?? { name: el.component }) === 'badge',
+      };
+      for (const rule of A11Y_RULES) {
+        if (!targeted[rule] || !stats.a11y[rule]) continue;
+        const verdict = judgeName(el, record);
+        if (verdict === 'abstain') {
+          stats.a11y[rule].abstained += 1;
+          continue;
+        }
+        stats.a11y[rule].checked += 1;
+        if (verdict === 'unnamed') failures.push({ rule, component: el.component, file: path, line: el.line });
+      }
+    }
+
     for (const e of elements) {
       stats.elements += 1;
       if (off.has('unknown-component') || builtKeys.has(normalizeName(e.component))) continue;
@@ -719,6 +984,10 @@ export function formatReport(r) {
     `  colour:       ${s.colourTokens} token values comparable, ${s.colourSkipped.unresolvable} skipped as unresolvable, ${s.colourSkipped.nonHex} skipped as non-hex`,
     `  dimensions:   ${dimensionTotal} token values comparable — ${DIMENSION_CATEGORIES.map((c) => `${c} ${s.dimensionTokens[c]}`).join(', ')}`,
   );
+  const a11y = Object.entries(s.a11y);
+  if (a11y.length) {
+    lines.push(`  a11y:         ${a11y.map(([rule, c]) => `${rule} ${c.checked} checked, ${c.abstained} abstained`).join('; ')}`);
+  }
   for (const e of r.excluded) {
     lines.push(`  excluded:     ${e.files} file(s) in ${e.dir}, the package that owns --tokens`);
   }
@@ -743,6 +1012,14 @@ export function formatReport(r) {
         lines.push(
           `  - [${f.rule}] ${f.category} ${f.written}${f.written === f.value ? '' : ` (${f.value})`} at ${f.file}:${f.line} — ${f.tokens.join(', ')} resolve${f.tokens.length === 1 ? 's' : ''} to exactly this value`,
         );
+      } else if (f.rule === 'unnamed-control') {
+        lines.push(
+          `  - [${f.rule}] <${f.component}> at ${f.file}:${f.line} — no accessible name: no text, and no aria-label, aria-labelledby or title on it or anything inside it`,
+        );
+      } else if (f.rule === 'colour-only-status') {
+        lines.push(
+          `  - [${f.rule}] <${f.component}> at ${f.file}:${f.line} — status in colour alone: no text, and no named icon inside it`,
+        );
       } else if (f.rule === 'nothing-scanned') {
         lines.push(
           `  - [${f.rule}] ${f.files} file(s) yielded no component reference, colour literal or dimension literal, so this run verified nothing. Check --root points at the consuming app, and that --package is the specifier that app actually imports from.`,
@@ -793,7 +1070,13 @@ export function formatReport(r) {
   return lines;
 }
 
-export const SKIPPABLE = ['unknown-component', 'unknown-variant-value', 'token-exists-for-literal', 'token-exists-for-dimension'];
+export const SKIPPABLE = [
+  'unknown-component',
+  'unknown-variant-value',
+  'token-exists-for-literal',
+  'token-exists-for-dimension',
+  ...A11Y_RULES,
+];
 
 function main() {
   let values;
@@ -871,9 +1154,9 @@ function main() {
     .map(([dir, n]) => ({ dir: join(values.root, relative(realRoot, dir)), files: n }));
 
   for (const path of scanned) {
-    const { elements, usages, literals, dimensions } = extract(readFileSync(path, 'utf8'), values.package, path);
-    if (elements.length || usages.length || literals.length || dimensions.length) {
-      files.push({ path, elements, usages, literals, dimensions });
+    const { elements, usages, literals, dimensions, subtrees } = extract(readFileSync(path, 'utf8'), values.package, path);
+    if (elements.length || usages.length || literals.length || dimensions.length || subtrees.length) {
+      files.push({ path, elements, usages, literals, dimensions, subtrees });
     }
   }
 

package/scripts/verify-check.mjs

@@ -313,6 +313,12 @@ export function checkProof({ manifest, root, derived = [], built = [], meta = {}
     }
 
     for (const check of recordedChecks(stageFile)) {
+      // An attested check is an agent's live observation. It is shown so a
+      // human can see what was claimed, and it never decides the run.
+      if (check.method === 'attested') {
+        informational.push({ rule: 'attested', stage, ...check });
+        continue;
+      }
       if (check.method !== 'derived') continue;
       const scope = DERIVED_RULE_SCOPE[check.name];
       // A rule this run did not compute cannot contradict anything, and
@@ -372,6 +378,8 @@ function informationalDetail(i) {
   switch (i.rule) {
     case 'archetype-unknown':
       return `${i.name} — neither an "archetype" field nor its name resolves to a known archetype, so no baseline states are asserted for it.`;
+    case 'attested':
+      return `${i.stage} · ${i.subject ?? '(stage)'} — ${i.name} ${i.result}${i.evidence ? `: ${i.evidence}` : ''}. Observed by an agent, not re-derived here.`;
     case 'proof-unadopted':
       return 'design-system.json has no "verification" key, so this system has not adopted the proof bundle and the proof-integrity checks are skipped. The first verify-check.mjs --record adopts it.';
     default: