@radicool/throughline 0.22.0 → 0.24.0

package/references/figma-component-standards.md

@@ -557,7 +557,9 @@ For each generated artboard / doc card / icon grid, read the nodes back (via
 8. **States complete** — each component set's `state` axis includes every relevant
    state for that component (every state the table in `references/state-baseline.md`
    owes it, plus default, plus the applicable loading/success/error), with variants (incl. each
-   size) as rows and states as columns. A set shipping only `default` is a fail.
+   size) as rows and states as columns. A set shipping only `default` is a fail. The
+   programmatic half (the state matrix and the `COMPONENT_SET` structure) is the
+   script in `references/figma-checks.md`; the script is the rule.
 9. **Focus state matches the library idiom** — the focus state is built as
    `project.uiFramework`'s real pattern (see "State handling"), not a house-style
    stroke, and with no padded wrapper inflating the component. Shadow-based recipes: a
@@ -570,52 +572,28 @@ For each generated artboard / doc card / icon grid, read the nodes back (via
    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:
+   **The `focus-indicator` check** is the programmatic half of this item, run by
+   the script in `references/figma-checks.md`; the script is the rule for which
+   frameworks and components it covers, how it finds the focus variants and the
+   control, what counts as a focus variable, and what each recipe must carry. 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 name in the table in `references/state-baseline.md`
-     (not its exempt list), the same
-     exact-name match as the state check and the same list the CLI's
-     `state-incomplete` reads. 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.
+
+   **The `focus-contrast` check** is the same script's measure of whether the ring
+   can be seen: each ring colour against each surface the architect names in
+   `surfaces`, at WCAG 1.4.11's 3:1, in every mode. The script is the rule for
+   which pairs and modes it compares and when it skips. A fail is a token problem,
+   not a build error: `figma-executor` returns `BLOCKED` at once, and inline you
+   stop the build. Neither changes a variable or swaps the ring to make it pass.
+   On a pass, `component-builder` records `focus-contrast` as an attested check.
 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/figma-scripting.md

@@ -330,12 +330,12 @@ uses **build-verify-then-replace**:
 2. **Verify the working frame green before touching anything real** — a
    screenshot alone is **insufficient**: 10 tone-colored frames render
    identically to 10 real variants, so a fast model can build plain frames and
-   self-report success. The gate is a **programmatic read-back** (`figma_execute`)
-   that asserts `node.type === 'COMPONENT_SET'` (never `'FRAME'`), the child count
-   matches the variant matrix with every child a `'COMPONENT'`,
-   `variantGroupProperties` names the expected axes, and a spot-check of ≥2
-   variants shows fills/strokes/radius bound to variables (not raw values) with
-   the expected `clipsContent`. A `figma_capture_screenshot` is a **secondary**
+   self-report success. The gate is a **programmatic read-back** (`figma_execute`):
+   for a component set, run the checks in `references/figma-checks.md` (the script
+   is the rule for the `COMPONENT_SET` structure, the state matrix and the focus
+   ring), plus a spot-check of ≥2 variants showing fills/strokes/radius bound to
+   variables (not raw values) with the expected `clipsContent`. A
+   `figma_capture_screenshot` is a **secondary**
    check (create → read-back → screenshot → iterate, max ~3), never the sole one.
 3. **Only then finalize:** remove/replace any existing same-named component,
    rename the working frame's component set to the real `<ComponentName>`, **and

package/references/proof-bundle.md

@@ -207,6 +207,7 @@ keyed by component?"
 | `state-baseline` | attested | `component-builder` |
 | `figma-name` | attested | `component-builder` |
 | `focus-indicator` | attested | `component-builder` |
+| `focus-contrast` | 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 |

package/references/state-baseline.md

@@ -3,8 +3,8 @@
 
 Which interaction states a component owes. This is the one list both checks read:
 `verify:check` (`state-incomplete`) reads it from `scripts/lib/component-states.mjs`,
-and `figma-executor` (its state check and the `focus-indicator` check) reads
-this table. CI fails when the table is stale.
+and the Figma checks script (`references/figma-checks.md`) inlines the same module,
+so this table is the human-readable view of both. CI fails when it is stale.
 
 A component name matches a row when it folds (lowercase, punctuation and spaces
 stripped) to exactly one of that row's names. `Text Field` folds to `textfield`.
@@ -17,7 +17,9 @@ matches nothing owes no states.
 | input | `input`, `textfield`, `textinput` | `hover`, `focus`, `disabled` |
 | choice | `checkbox`, `radio`, `toggle`, `switch`, `chip` | `hover`, `focus`, `active`, `selected`, `disabled` |
 
-Every state in the table must be a value on the component's `state` axis. On the
+Every state in the table must be a value on the component's `state` axis, with one
+exception in Figma: a choice control may carry `selected` on its own axis named
+`selected`, `checked` or `on`. On the
 Figma side the matrix also carries `default` as the resting state; the CLI does not
 count it. `checked` counts as `selected`, and `on` counts as `selected`, since that is what shadcn and Radix call it. Conditional states (`loading`, `error`, `success`) are not in the table:
 whether one applies is a design judgment.

package/scripts/README.md

@@ -23,12 +23,15 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `docs-lint.mjs` | Copy lint for .doc.json records — warnings only, always exits 0 on a parseable record; the mechanical subset of `references/doc-writing-standard.md`. | `docs:lint` |
 | `lib/doc-record.mjs` | Canonical record load + `canonicalFingerprint` (sha256 over the record minus `provenance`). The fingerprint every surface is stamped with. | copied alongside docs-check.mjs |
 | `lib/doc-card-render.figma.js` | Figma renderer template for the doc card's `Usage` band and header. Inlined into `references/doc-card-builder.md`; never executed as a module. | plugin-internal (not installed) |
+| `lib/figma-checks.mjs` | Pure checker for the Figma stop conditions: the COMPONENT_SET assertion against the full matrix, the state matrix, the focus ring, and the focus ring's 3:1 contrast against the surfaces it's named to sit on, plus the focus-framework rules. Inlined into `references/figma-checks.md`; unit-tested against `lib/fixtures/figma-checks/`. | plugin-internal (not installed) |
+| `lib/figma-checks-read.figma.js` | Figma reader that turns the live COMPONENT_SET into the checker's snapshot JSON. Inlined into `references/figma-checks.md`; never executed as a module. | plugin-internal (not installed) |
 | `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. `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` |
+| `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. Also inlined into `references/figma-checks.md` for the focus-ring contrast check. | copied alongside `verify-check.mjs`; also inlined into the generated Figma checks |
 | `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-figma-checks.mjs` | Generate `references/figma-checks.md`, the `figma_execute` snippet for the Figma stop conditions, by inlining `lib/component-states.mjs`, `lib/contrast.mjs` and `lib/figma-checks.mjs` above the reader (`lib/figma-checks-read.figma.js`). `--check` gates CI. | plugin-internal (not installed) |
 | `build-state-baseline.mjs` | Generate `references/state-baseline.md`, the table of which components owe which interaction states, from `lib/component-states.mjs`. The Figma executor reads the table; `verify:check` reads the module. `--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) |
 
@@ -246,7 +249,7 @@ the committed `adapters/<target>/` tree plus the runtime payload
 (`references/` + `scripts/`, minus `scripts/adapters/`) into `.throughline/`,
 rewriting `${CLAUDE_PLUGIN_ROOT}` → `.throughline`:
 
-    npx @radicool/throughline@0.22.0 init --target=cursor|codex|generic
+    npx @radicool/throughline@0.24.0 init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
 

package/scripts/build-figma-checks.mjs

@@ -0,0 +1,111 @@
+// Generates references/figma-checks.md — the canonical figma_execute snippet
+// that runs the Figma stop conditions (COMPONENT_SET assertion, state matrix,
+// focus ring, focus-ring contrast) — by inlining the state table
+// (lib/component-states.mjs), the contrast maths (lib/contrast.mjs) and the
+// pure checker (lib/figma-checks.mjs) above the Figma reader
+// (lib/figma-checks-read.figma.js). Mirrors build-doc-card-builder.mjs: run
+// bare to write, run with --check to gate CI. Zero dependencies.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const STATES = join(REPO_ROOT, 'scripts', 'lib', 'component-states.mjs');
+const CONTRAST = join(REPO_ROOT, 'scripts', 'lib', 'contrast.mjs');
+const CHECKER = join(REPO_ROOT, 'scripts', 'lib', 'figma-checks.mjs');
+const READER = join(REPO_ROOT, 'scripts', 'lib', 'figma-checks-read.figma.js');
+const OUT = join(REPO_ROOT, 'references', 'figma-checks.md');
+
+const BIND = 'const { checkSpec, checkBuilt } = withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName, contrastRatio, composite, parseHex, AA_NON_TEXT });';
+
+const HEADER = [
+  '# Figma stop-condition checks (GENERATED)',
+  '',
+  '> **GENERATED FILE — do not edit by hand.** Sources: `scripts/lib/component-states.mjs`',
+  '> (the state table), `scripts/lib/contrast.mjs` (the WCAG contrast maths),',
+  '> `scripts/lib/figma-checks.mjs` (the pure checker, unit-tested in Node) +',
+  '> `scripts/lib/figma-checks-read.figma.js` (the Figma reader). Regenerate with',
+  '> `node scripts/build-figma-checks.mjs`; CI gates freshness with `--check`.',
+  '',
+  'The canonical `figma_execute` snippet for the checks that can stop a component',
+  'build: the COMPONENT_SET assertion against the full variant matrix, the state',
+  'matrix, the focus ring, and the focus ring\'s contrast against the surfaces it',
+  'sits on (WCAG 1.4.11, 3:1, in every mode). The script is the rule; do not re-write',
+  'these checks by hand.',
+  '',
+  '## How to call it',
+  '',
+  '1. Paste the snippet below into `figma_execute`, with the two slots filled above it:',
+  '   - `const EXPECT = { name, matrix, uiFramework, controlLayer, surfaces }` — `name` is the',
+  '     component\'s real name; `matrix` is `{ axis: [values] }` for every axis of the',
+  '     set; `uiFramework` is `project.uiFramework` from `design-system.json`;',
+  '     `controlLayer` is the layer that is the actual control in a wrapped control,',
+  '     copied from the architect\'s spec when it gives one (omit it otherwise);',
+  '     `surfaces` is the list of colour-variable names of the page surfaces the',
+  '     component sits on, copied from the architect\'s spec. Without it the',
+  '     focus-contrast check is skipped. Surfaces are looked up among the file\'s',
+  '     local variables only.',
+  '   - `const MODE = \'spec\'` or `\'built\'`.',
+  '2. End the script with `return await runFigmaChecks(EXPECT, MODE);` and pass',
+  '   `timeout: 30000`.',
+  '3. Read the result, `{ pass, checks: [{ name, result, detail }] }`. `result` is',
+  '   `pass`, `fail` or `skip`; `pass` ignores skips. On `fail`, fix what each failing',
+  '   check\'s `detail` names and run it again, within the ~3-pass budget; after that,',
+  '   `BLOCKED` naming the failing checks\' `detail`. A `focus-contrast` fail is',
+  '   the exception: return `BLOCKED` at once, naming its detail. A ring below 3:1 is',
+  '   fixed by a token value, which no rebuild changes, and a missing surface is a',
+  '   wrong name in the spec. Never edit a variable to make it pass.',
+  '4. `\'spec\'` reads no node and runs before the first write. `\'built\'` reads the',
+  '   COMPONENT_SET inside the frame named `WIP: <name>` on the current page and runs',
+  '   in the self-verify loop. It throws only if that frame is missing; a frame with',
+  '   no set, or a set Figma reports as conflicting, fails the structural check.',
+  '',
+  '```js',
+  'const EXPECT = { name: \'Chip\', matrix: { state: [\'default\', \'hover\'] }, uiFramework: \'shadcn\' };',
+  'const MODE = \'spec\';',
+  '// … the generated snippet …',
+  'return await runFigmaChecks(EXPECT, MODE);',
+  '```',
+  '',
+  '## The snippet',
+  '',
+  '```js',
+].join('\n');
+
+const FOOTER = ['```', ''].join('\n');
+
+const stripExports = (src) =>
+  src.replace(/^export const /gm, 'const ').replace(/^export function /gm, 'function ');
+
+export function buildFigmaChecks({ statesSource, contrastSource, checkerSource, readerSource }) {
+  const states = stripExports(statesSource);
+  const contrast = stripExports(contrastSource);
+  const checker = stripExports(checkerSource);
+  for (const [name, src] of [['component-states.mjs', states], ['contrast.mjs', contrast], ['figma-checks.mjs', checker], ['figma-checks-read.figma.js', readerSource]]) {
+    if (/^\s*(import|export)\b/m.test(src)) {
+      throw new Error(`${name} must stay import-free (only top-level \`export const\`/\`export function\` allowed) — it is inlined into the Figma snippet where no module system exists`);
+    }
+  }
+  return `${HEADER}\n${states}\n${contrast}\n${checker}\n${BIND}\n\n${readerSource}${FOOTER}`;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = buildFigmaChecks({
+    statesSource: readFileSync(STATES, 'utf8'),
+    contrastSource: readFileSync(CONTRAST, 'utf8'),
+    checkerSource: readFileSync(CHECKER, 'utf8'),
+    readerSource: readFileSync(READER, 'utf8'),
+  });
+  if (process.argv.includes('--check')) {
+    let onDisk = null;
+    try { onDisk = readFileSync(OUT, 'utf8'); } catch { /* missing counts as drift */ }
+    if (onDisk !== result) {
+      console.error('✗ references/figma-checks.md out of date; run: node scripts/build-figma-checks.mjs');
+      process.exit(1);
+    }
+    console.log('✓ figma checks in sync');
+  } else {
+    writeFileSync(OUT, result);
+    console.log('✓ wrote references/figma-checks.md');
+  }
+}

package/scripts/build-state-baseline.mjs

@@ -25,8 +25,8 @@ export function render(states = BASELINE_STATES, synonyms = NAME_SYNONYMS, arche
 
 Which interaction states a component owes. This is the one list both checks read:
 \`verify:check\` (\`state-incomplete\`) reads it from \`scripts/lib/component-states.mjs\`,
-and \`figma-executor\` (its state check and the \`focus-indicator\` check) reads
-this table. CI fails when the table is stale.
+and the Figma checks script (\`references/figma-checks.md\`) inlines the same module,
+so this table is the human-readable view of both. CI fails when it is stale.
 
 A component name matches a row when it folds (lowercase, punctuation and spaces
 stripped) to exactly one of that row's names. \`Text Field\` folds to \`textfield\`.
@@ -37,7 +37,9 @@ matches nothing owes no states.
 |---|---|---|
 ${rows.join('\n')}
 
-Every state in the table must be a value on the component's \`state\` axis. On the
+Every state in the table must be a value on the component's \`state\` axis, with one
+exception in Figma: a choice control may carry \`selected\` on its own axis named
+\`selected\`, \`checked\` or \`on\`. On the
 Figma side the matrix also carries \`default\` as the resting state; the CLI does not
 count it. ${aliases}, since that is what shadcn and Radix call it. Conditional states (\`loading\`, \`error\`, \`success\`) are not in the table:
 whether one applies is a design judgment.

package/scripts/install.mjs

@@ -99,18 +99,23 @@ function stagePayload(srcRoot, destRoot, skip) {
   return written;
 }
 
-// Scripts that never run from a consuming repo: the installer itself, the two
-// reference-doc generators, and the renderer template one of them inlines (the
-// renderer reaches Figma pre-inlined inside references/doc-card-builder.md).
+// Scripts that never run from a consuming repo: the installer itself, the
+// reference-doc generators, and the Figma sources they inline (the doc-card
+// renderer and the Figma checks reach Figma pre-inlined inside
+// references/doc-card-builder.md and references/figma-checks.md). Test fixtures
+// under lib/fixtures/ are dropped too.
 const PLUGIN_INTERNAL = new Set([
   'install.mjs',
   'build-doc-card-builder.mjs',
   'build-native-adapter-config.mjs',
   'lib/doc-card-render.figma.js',
+  'build-figma-checks.mjs',
+  'lib/figma-checks-read.figma.js',
+  'lib/figma-checks.mjs',
 ]);
 
 export const skipScript = (relPosix) =>
-  relPosix.startsWith('adapters/') || relPosix.endsWith('.test.mjs') || PLUGIN_INTERNAL.has(relPosix);
+  relPosix.startsWith('adapters/') || relPosix.startsWith('lib/fixtures/') || relPosix.endsWith('.test.mjs') || PLUGIN_INTERNAL.has(relPosix);
 
 export function install({ target, dir, pkgRoot = PKG_ROOT }) {
   if (!TARGETS.includes(target)) {

package/scripts/lib/component-states.mjs

@@ -14,7 +14,10 @@
 // renders it into `references/state-baseline.md`, which the Figma executor reads;
 // CI fails when that file is stale. MAINTENANCE: change this table, then run it.
 
-import { normalizeName } from './source-scan.mjs';
+// Defined here rather than imported from source-scan.mjs so this module has no
+// imports and can be inlined into the Figma checks script. A test keeps the two
+// copies in step.
+const normalizeName = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
 
 export const ARCHETYPES = ['button', 'input', 'choice', 'card', 'modal', 'badge', 'other'];
 

package/scripts/lib/contrast.mjs

@@ -6,6 +6,8 @@
 // MAINTENANCE: a change to the semantic role set must change this table.
 
 export const AA_NORMAL_TEXT = 4.5;
+// WCAG 1.4.11 non-text contrast, used by the Figma `focus-contrast` check.
+export const AA_NON_TEXT = 3;
 
 // `text/disabled` is excluded: WCAG 1.4.3 exempts inactive user-interface
 // components from the contrast minimum, and a disabled role is deliberately
@@ -15,8 +17,9 @@ export const AA_NORMAL_TEXT = 4.5;
 // questions) — a system is free to use those roles for non-text surfaces, so
 // pairing them risks the first false failures in the table.
 //
-// `border/*` needs the 3:1 non-text threshold (WCAG 1.4.11) and is a separate
-// table; this one is text-on-surface only.
+// This table is text-on-surface only. Focus-ring contrast, the 3:1 non-text case
+// (WCAG 1.4.11), is checked in the Figma checks (`figma-checks.mjs`,
+// `focus-contrast`), where the build knows which ring sits on which surface.
 //
 // One threshold is applied to every pair because a colour role does not say
 // what text size it is used at — `text/primary` is body copy as well as

package/scripts/lib/figma-checks-read.figma.js

@@ -0,0 +1,174 @@
+// Figma plugin-API reader for the stop-condition checks. This file is NOT a
+// Node module — build-figma-checks.mjs concatenates it after the inlined
+// component-states.mjs, contrast.mjs and figma-checks.mjs into
+// references/figma-checks.md, and
+// the result runs inside figma_execute (dynamic-page mode). Constraints honored
+// here (see references/figma-scripting.md): async getters only, variable names
+// and per-mode colour values resolved with getVariableByIdAsync and only for
+// focus variants and their controlLayer, plus the EXPECT.surfaces names, which
+// are looked up among the file's LOCAL colour variables only (a surface from a
+// published library reads as missing). Untested in Node, like the doc-card
+// renderer; the pure checker it feeds is unit-tested.
+//
+// In-scope globals when assembled: normalizeName (inlined
+// component-states.mjs), checkSpec, checkBuilt (bound from withTable) and the
+// caller-filled slots EXPECT and MODE (passed to runFigmaChecks). The snapshot
+// shape is documented at the top of scripts/lib/figma-checks.mjs.
+
+// Colour variables read on focus nodes, by name, for the contrast check.
+const readVariables = new Map();
+
+async function variableName(alias) {
+  if (!alias || !alias.id) return null;
+  const variable = await figma.variables.getVariableByIdAsync(alias.id);
+  if (!variable) return null;
+  if (variable.resolvedType === 'COLOR') readVariables.set(variable.name, variable);
+  return variable.name;
+}
+
+function colorHex(value) {
+  if (!value || typeof value !== 'object' || !('r' in value)) return null;
+  const byte = (x) => Math.round(x * 255).toString(16).padStart(2, '0');
+  const alpha = value.a === undefined ? 1 : value.a;
+  return `#${byte(value.r)}${byte(value.g)}${byte(value.b)}${alpha < 1 ? byte(alpha) : ''}`;
+}
+
+// The value of `variable` in the mode named `modeName` (after the fold), else
+// its collection's default mode, following aliases up to 10 hops.
+async function resolveColor(variable, modeName, hops) {
+  if (!variable || hops > 10) return null;
+  const collection = await figma.variables.getVariableCollectionByIdAsync(variable.variableCollectionId);
+  if (!collection) return null;
+  const mode = collection.modes.find((m) => normalizeName(m.name) === normalizeName(modeName));
+  const value = variable.valuesByMode[mode ? mode.modeId : collection.defaultModeId];
+  if (value && value.type === 'VARIABLE_ALIAS') {
+    return resolveColor(await figma.variables.getVariableByIdAsync(value.id), modeName, hops + 1);
+  }
+  return colorHex(value);
+}
+
+// { modes: { [modeName]: hex | null }, defaultMode } over the variable's own collection.
+async function variableColors(variable) {
+  const collection = await figma.variables.getVariableCollectionByIdAsync(variable.variableCollectionId);
+  if (!collection) return { modes: {}, defaultMode: undefined };
+  const modes = {};
+  for (const mode of collection.modes) modes[mode.name] = await resolveColor(variable, mode.name, 0);
+  const fallback = collection.modes.find((m) => m.modeId === collection.defaultModeId);
+  return { modes, defaultMode: fallback ? fallback.name : undefined };
+}
+
+// The fields the focus check reads from a variant, a control layer or a direct child.
+async function readFocusNode(node, { withEffects }) {
+  const strokes = (node.boundVariables && node.boundVariables.strokes) || [];
+  const strokeVariables = [];
+  for (const alias of strokes) {
+    const name = await variableName(alias);
+    if (name !== null) strokeVariables.push(name);
+  }
+  const bound = node.boundVariables || {};
+  const out = {
+    strokeAlign: node.strokeAlign,
+    strokeVariables,
+    strokeWeightBound: Boolean(
+      bound.strokeWeight || bound.strokeTopWeight || bound.strokeRightWeight || bound.strokeBottomWeight || bound.strokeLeftWeight,
+    ),
+  };
+  if (withEffects) {
+    out.effects = [];
+    for (const effect of node.effects || []) {
+      const colorAlias = effect.boundVariables && effect.boundVariables.color;
+      out.effects.push({
+        type: effect.type,
+        visible: effect.visible,
+        spread: effect.spread,
+        colorVariable: await variableName(colorAlias),
+      });
+    }
+  } else {
+    out.layoutPositioning = node.layoutPositioning;
+  }
+  return out;
+}
+
+async function readFocusTree(node) {
+  const focus = await readFocusNode(node, { withEffects: true });
+  focus.children = [];
+  for (const child of node.children || []) {
+    focus.children.push(await readFocusNode(child, { withEffects: false }));
+  }
+  return focus;
+}
+
+// The getter throws when Figma flags the set as conflicting (duplicate variant
+// combinations). Fall back to the axes the children declare, so the structural
+// check names the duplicates instead of the read throwing.
+function groupProperties(set) {
+  try {
+    return set.variantGroupProperties;
+  } catch {
+    const axes = {};
+    for (const child of set.children) {
+      for (const axis of Object.keys(child.variantProperties || {})) axes[axis] = { values: [] };
+    }
+    return axes;
+  }
+}
+
+async function readComponentSet(expect) {
+  readVariables.clear();
+  await figma.currentPage.loadAsync();
+  const frameName = `WIP: ${expect.name}`;
+  const frame = figma.currentPage.findOne((n) => n.name === frameName);
+  if (!frame) throw new Error(`no node named "${frameName}" on the current page`);
+  const set = frame.type === 'COMPONENT_SET' ? frame : (frame.children || []).find((c) => c.type === 'COMPONENT_SET');
+  // A frame holding plain FRAMEs where the set should be is a failed assertion,
+  // not a missing target: report what is there so the structural check names it.
+  if (!set) {
+    const first = (frame.children || [])[0];
+    return { type: first ? first.type : 'NONE', variantGroupProperties: {}, children: [] };
+  }
+
+  const isFocusState = (props) =>
+    Object.entries(props || {}).some(([k, v]) => {
+      const state = normalizeName(v);
+      return normalizeName(k) === 'state' && state === 'focus';
+    });
+
+  const children = [];
+  for (const child of set.children) {
+    const read = { type: child.type, variantProperties: child.variantProperties };
+    if (child.type === 'COMPONENT' && isFocusState(child.variantProperties)) {
+      Object.assign(read, await readFocusTree(child));
+      if (expect.controlLayer !== undefined && expect.controlLayer !== null) {
+        const layer = child.findOne((n) => n.name === expect.controlLayer);
+        read.controlLayer = layer ? await readFocusTree(layer) : null;
+      }
+    }
+    children.push(read);
+  }
+  const colors = {};
+  for (const [name, variable] of readVariables) colors[name] = await variableColors(variable);
+  const missingSurfaces = [];
+  const surfaces = expect.surfaces || [];
+  if (surfaces.length) {
+    const local = await figma.variables.getLocalVariablesAsync('COLOR');
+    for (const name of surfaces) {
+      const variable = local.find((v) => v.name === name);
+      if (variable) colors[name] = await variableColors(variable);
+      else missingSurfaces.push(name);
+    }
+  }
+  return {
+    type: set.type,
+    variantGroupProperties: groupProperties(set),
+    children,
+    colors,
+    missingSurfaces,
+  };
+}
+
+async function runFigmaChecks(EXPECT, MODE) {
+  if (MODE === 'spec') return checkSpec(EXPECT);
+  if (MODE === 'built') return checkBuilt(await readComponentSet(EXPECT), EXPECT);
+  throw new Error(`MODE must be 'spec' or 'built', got ${JSON.stringify(MODE)}`);
+}