@radicool/throughline 0.23.0 → 0.25.0

package/scripts/README.md

@@ -23,15 +23,18 @@ 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, and the focus ring, 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.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/figma-variables-read.figma.js` | Figma helpers that resolve a colour variable's value in each mode, through aliases. Inlined into both `references/figma-checks.md` and `references/figma-adherence.md`; never executed as a module. | plugin-internal (not installed) |
+| `lib/figma-adherence.mjs` | Pure checker for the Figma screen adherence gate: detached components, and raw colours, gaps, padding and radii that a variable has. A raw value no variable has is an advisory. Inlined into `references/figma-adherence.md`; unit-tested against `lib/fixtures/figma-adherence/`. | plugin-internal (not installed) |
+| `lib/figma-adherence-read.figma.js` | Figma reader that turns the screens on one page into the adherence checker's snapshot JSON, read-only. Inlined into `references/figma-adherence.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` and `lib/figma-checks.mjs` above the reader (`lib/figma-checks-read.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`, `lib/figma-checks.mjs` and `lib/figma-variables-read.figma.js` above the reader (`lib/figma-checks-read.figma.js`); and `references/figma-adherence.md`, the screen adherence gate, from `lib/figma-adherence.mjs`, `lib/figma-variables-read.figma.js` and `lib/figma-adherence-read.figma.js`. `--check` gates CI on both. | 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) |
 
@@ -249,7 +252,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.23.0 init --target=cursor|codex|generic
+    npx @radicool/throughline@0.25.0 init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
 

package/scripts/build-figma-checks.mjs

@@ -1,53 +1,85 @@
-// Generates references/figma-checks.md — the canonical figma_execute snippet
-// that runs the Figma stop conditions (COMPONENT_SET assertion, state matrix,
-// focus ring) — by inlining the state table (lib/component-states.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.
+// Generates the two canonical figma_execute snippets by inlining tested Node
+// modules above their Figma readers:
+//   references/figma-checks.md — the Figma stop conditions (COMPONENT_SET
+//     assertion, state matrix, focus ring, focus-ring contrast): the state table
+//     (lib/component-states.mjs), the contrast maths (lib/contrast.mjs) and the pure
+//     checker (lib/figma-checks.mjs), then lib/figma-variables-read.figma.js and the
+//     reader (lib/figma-checks-read.figma.js).
+//   references/figma-adherence.md — the screen adherence gate: the pure checker
+//     (lib/figma-adherence.mjs), then lib/figma-variables-read.figma.js and the
+//     screen reader (lib/figma-adherence-read.figma.js).
+// Mirrors build-doc-card-builder.mjs: run bare to write both, run with --check to
+// gate CI on both. 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 VARIABLES = join(REPO_ROOT, 'scripts', 'lib', 'figma-variables-read.figma.js');
+const ADHERENCE = join(REPO_ROOT, 'scripts', 'lib', 'figma-adherence.mjs');
+const ADHERENCE_READER = join(REPO_ROOT, 'scripts', 'lib', 'figma-adherence-read.figma.js');
 const OUT = join(REPO_ROOT, 'references', 'figma-checks.md');
+const ADHERENCE_OUT = join(REPO_ROOT, 'references', 'figma-adherence.md');
 
-const BIND = 'const { checkSpec, checkBuilt } = withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName });';
+const BIND = 'const { checkSpec, checkBuilt, checkExisting } = 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/figma-checks.mjs` (the pure checker, unit-tested in',
-  '> Node) + `scripts/lib/figma-checks-read.figma.js` (the Figma reader). Regenerate with',
+  '> (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, and the focus ring. The script is the rule; do not re-write these checks',
-  'by hand.',
+  '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 }` — `name` is the',
+  '   - `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).',
-  '   - `const MODE = \'spec\'` or `\'built\'`.',
+  '     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\'`, `\'built\'` or `\'existing\'`.',
   '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`.',
+  '   `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.',
+  '5. `\'existing\'` checks a set already in the library, read-only: the first',
+  '   COMPONENT_SET whose name matches `name` ignoring case and punctuation. Add',
+  '   `page` to `EXPECT` (the page holding the components) so only that page is',
+  '   loaded; without it every page loads in turn, which on a large file can stall',
+  '   the bridge. `matrix` is not needed. There is no spec to copy `controlLayer` and',
+  '   `surfaces` from, so the caller names them: `surfaces` as for a build, and',
+  '   `controlLayer` for a wrapped control whose ring sits on an inner layer (without',
+  '   it, a correct ring on an inner layer reads as missing). It runs the state,',
+  '   focus-ring and focus-contrast checks against the set\'s own variants, not the',
+  '   structural check. A set whose focus state is drawn some other way, such as an',
+  '   INSIDE stroke, fails the focus-ring check and skips contrast. It throws when no',
+  '   set has that name.',
   '',
   '```js',
   'const EXPECT = { name: \'Chip\', matrix: { state: [\'default\', \'hover\'] }, uiFramework: \'shadcn\' };',
@@ -61,38 +93,117 @@ const HEADER = [
   '```js',
 ].join('\n');
 
+const ADHERENCE_HEADER = [
+  '# Figma screen adherence gate (GENERATED)',
+  '',
+  '> **GENERATED FILE — do not edit by hand.** Sources: `scripts/lib/figma-adherence.mjs`',
+  '> (the pure checker, unit-tested in Node), `scripts/lib/figma-variables-read.figma.js`',
+  '> (colour-variable resolution) + `scripts/lib/figma-adherence-read.figma.js` (the',
+  '> screen reader). Regenerate with `node scripts/build-figma-checks.mjs`; CI gates',
+  '> freshness with `--check`.',
+  '',
+  'The canonical `figma_execute` snippet that checks Figma screens against the design',
+  'system, read-only. It fails a frame detached from a component, a raw colour that a',
+  'colour variable has (opacity included), and a raw gap, padding or corner radius',
+  'that a spacing or radius variable has, naming the variable to bind. A number',
+  'variable counts by its scope (`GAP`, `CORNER_RADIUS`), or, left at `ALL_SCOPES`,',
+  'by a name that says spacing or radius. A raw value no variable has is an',
+  'advisory, not a failure. A rule that had nothing to compare against fails by name',
+  '(`nothing-scanned`, `colour-rule-inert`, `dimension-rule-inert`). The script is the',
+  'rule; do not re-write it by hand.',
+  '',
+  '## How to call it',
+  '',
+  '1. Paste the snippet below into `figma_execute`, with the two slots filled above it:',
+  '   - `const TARGET = { page, screens, fileKey }` — `page` is the page name (an exact',
+  '     match, or else the one page whose name matches once leading and trailing',
+  '     spaces are trimmed); `screens` is an optional list of screen names (top-level',
+  '     frames, or frames directly inside a top-level section), and without it every',
+  '     screen on the page is read; `fileKey` is `figma.fileKey` from',
+  '     `design-system.json`, used for the links.',
+  '   - `const SKIP = []` — rule names to switch off (`detached-component`,',
+  '     `raw-colour`, `raw-dimension`); a skipped rule\'s inert check is skipped too.',
+  '2. End the script with `return await runScreenGate(TARGET, SKIP);` and pass',
+  '   `timeout: 30000`.',
+  '3. Read the result, `{ pass, failures, advisories, counts, skipped }`. Each failure',
+  '   and advisory has `rule`, `path`, `detail` and a `link` to the node. Report every',
+  '   failure with its link. Never edit the file to make it pass.',
+  '4. Only the named page is loaded, and tokens are the file\'s local variables. A file',
+  '   whose variables all come from a published library fails as inert.',
+  '',
+  '```js',
+  'const TARGET = { page: \'Templates\', fileKey: \'<figma.fileKey>\' };',
+  'const SKIP = [];',
+  '// … the generated snippet …',
+  'return await runScreenGate(TARGET, SKIP);',
+  '```',
+  '',
+  '## 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, checkerSource, readerSource }) {
-  const states = stripExports(statesSource);
-  const checker = stripExports(checkerSource);
-  for (const [name, src] of [['component-states.mjs', states], ['figma-checks.mjs', checker], ['figma-checks-read.figma.js', readerSource]]) {
+function assertInlinable(sources) {
+  for (const [name, src] of sources) {
     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${checker}\n${BIND}\n\n${readerSource}${FOOTER}`;
+}
+
+export function buildFigmaChecks({ statesSource, contrastSource, checkerSource, variablesSource, readerSource }) {
+  const states = stripExports(statesSource);
+  const contrast = stripExports(contrastSource);
+  const checker = stripExports(checkerSource);
+  assertInlinable([['component-states.mjs', states], ['contrast.mjs', contrast], ['figma-checks.mjs', checker], ['figma-variables-read.figma.js', variablesSource], ['figma-checks-read.figma.js', readerSource]]);
+  return `${HEADER}\n${states}\n${contrast}\n${checker}\n${BIND}\n\n${variablesSource}\n${readerSource}${FOOTER}`;
+}
+
+export function buildFigmaAdherence({ checkerSource, variablesSource, readerSource }) {
+  const checker = stripExports(checkerSource);
+  assertInlinable([['figma-adherence.mjs', checker], ['figma-variables-read.figma.js', variablesSource], ['figma-adherence-read.figma.js', readerSource]]);
+  return `${ADHERENCE_HEADER}\n${checker}\n${variablesSource}\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'),
+    variablesSource: readFileSync(VARIABLES, 'utf8'),
     readerSource: readFileSync(READER, 'utf8'),
   });
+  const adherence = buildFigmaAdherence({
+    checkerSource: readFileSync(ADHERENCE, 'utf8'),
+    variablesSource: readFileSync(VARIABLES, 'utf8'),
+    readerSource: readFileSync(ADHERENCE_READER, 'utf8'),
+  });
+  const outputs = [
+    [OUT, result, 'references/figma-checks.md', 'figma checks'],
+    [ADHERENCE_OUT, adherence, 'references/figma-adherence.md', 'figma adherence'],
+  ];
   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);
+    let stale = false;
+    for (const [path, content, label, what] of outputs) {
+      let onDisk = null;
+      try { onDisk = readFileSync(path, 'utf8'); } catch { /* missing counts as drift */ }
+      if (onDisk !== content) {
+        console.error(`✗ ${label} out of date; run: node scripts/build-figma-checks.mjs`);
+        stale = true;
+      } else {
+        console.log(`✓ ${what} in sync`);
+      }
     }
-    console.log('✓ figma checks in sync');
+    if (stale) process.exit(1);
   } else {
-    writeFileSync(OUT, result);
-    console.log('✓ wrote references/figma-checks.md');
+    for (const [path, content, label] of outputs) {
+      writeFileSync(path, content);
+      console.log(`✓ wrote ${label}`);
+    }
   }
 }

package/scripts/install.mjs

@@ -102,7 +102,8 @@ function stagePayload(srcRoot, destRoot, skip) {
 // 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
+// references/doc-card-builder.md, references/figma-checks.md and
+// references/figma-adherence.md). Test fixtures
 // under lib/fixtures/ are dropped too.
 const PLUGIN_INTERNAL = new Set([
   'install.mjs',
@@ -112,6 +113,9 @@ const PLUGIN_INTERNAL = new Set([
   'build-figma-checks.mjs',
   'lib/figma-checks-read.figma.js',
   'lib/figma-checks.mjs',
+  'lib/figma-variables-read.figma.js',
+  'lib/figma-adherence.mjs',
+  'lib/figma-adherence-read.figma.js',
 ]);
 
 export const skipScript = (relPosix) =>

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-adherence-read.figma.js

@@ -0,0 +1,207 @@
+// Figma plugin-API reader for the screen adherence gate. This file is NOT a Node
+// module — build-figma-checks.mjs concatenates it after the inlined
+// figma-adherence.mjs and figma-variables-read.figma.js into
+// references/figma-adherence.md, and the result runs inside figma_execute.
+// Constraints honored here (see references/figma-scripting.md): async getters
+// only; only the target page is loaded; overridden nodes are found inside their
+// instance, never with getNodeByIdAsync in a loop (that stalled the bridge on a
+// large file). Read-only: nothing here writes to the file. Untested in Node
+// beyond the generator's snippet test; the pure checker it feeds is unit-tested.
+//
+// In-scope globals when assembled: checkScreens and dimensionBuckets (figma-adherence.mjs),
+// colorHex and variableColors (figma-variables-read.figma.js), and the caller-filled slots
+// TARGET = { page, screens?, fileKey } and SKIP = [rule, ...]. The snapshot shape is
+// documented at the top of scripts/lib/figma-adherence.mjs.
+
+const CORNERS = [
+  ['topLeftRadius', 'top-left'],
+  ['topRightRadius', 'top-right'],
+  ['bottomRightRadius', 'bottom-right'],
+  ['bottomLeftRadius', 'bottom-left'],
+];
+const SIDES = [
+  ['paddingTop', 'top'],
+  ['paddingRight', 'right'],
+  ['paddingBottom', 'bottom'],
+  ['paddingLeft', 'left'],
+];
+
+function solidPaints(node, field, kind) {
+  const list = node[field];
+  if (!Array.isArray(list)) return [];
+  const bound = (node.boundVariables && node.boundVariables[field]) || [];
+  const styleId = field === 'fills' ? node.fillStyleId : node.strokeStyleId;
+  const styled = typeof styleId === 'string' && styleId !== '';
+  const out = [];
+  list.forEach((paint, i) => {
+    if (paint.visible === false || paint.type !== 'SOLID') return;
+    // The paint's opacity goes into the hex the way colorHex writes a translucent
+    // variable, so a 50% black matches a 50% black token and not the opaque one.
+    const opacity = paint.opacity === undefined ? 1 : paint.opacity;
+    out.push({
+      kind,
+      hex: colorHex({ r: paint.color.r, g: paint.color.g, b: paint.color.b, a: opacity }),
+      bound: Boolean(bound[i]),
+      styled,
+    });
+  });
+  return out;
+}
+
+function gapOf(node) {
+  if (!node.layoutMode || node.layoutMode === 'NONE') return null;
+  const inFlow = (node.children || []).filter((c) => c.visible !== false && c.layoutPositioning !== 'ABSOLUTE');
+  return {
+    value: node.itemSpacing,
+    bound: Boolean(node.boundVariables && node.boundVariables.itemSpacing),
+    renders: inFlow.length >= 2 && node.primaryAxisAlignItems !== 'SPACE_BETWEEN',
+  };
+}
+
+function paddingOf(node) {
+  if (!node.layoutMode || node.layoutMode === 'NONE') return [];
+  const bound = node.boundVariables || {};
+  return SIDES.map(([field, side]) => ({ side, value: node[field], bound: Boolean(bound[field]) }));
+}
+
+function radiusOf(node) {
+  if (!('cornerRadius' in node)) return [];
+  const bound = node.boundVariables || {};
+  if (node.cornerRadius !== figma.mixed) {
+    return [{ corner: 'all', value: node.cornerRadius, bound: Boolean(bound.topLeftRadius) }];
+  }
+  return CORNERS.map(([field, corner]) => ({ corner, value: node[field], bound: Boolean(bound[field]) }));
+}
+
+function detachedOf(node, page) {
+  let info = null;
+  try {
+    info = node.detachedInfo;
+  } catch {
+    return null;
+  }
+  if (!info) return null;
+  if (info.type === 'library') return { kind: 'library', name: null, id: null, key: info.componentKey };
+  const main = page.findOne((n) => n.id === info.componentId);
+  return { kind: 'local', name: main ? main.name : null, id: info.componentId, key: null };
+}
+
+function overriddenRecords(instance, path, underDetached) {
+  const records = [];
+  for (const entry of instance.overrides || []) {
+    const fields = entry.overriddenFields.filter((f) => f === 'fills' || f === 'strokes');
+    if (!fields.length) continue;
+    const node = entry.id === instance.id ? instance : instance.findOne((n) => n.id === entry.id);
+    if (!node) continue;
+    records.push({
+      id: node.id,
+      path: node === instance ? path : `${path} / ${node.name}`,
+      isRoot: false,
+      inInstance: true,
+      underDetached,
+      overridden: fields,
+      paints: [...solidPaints(node, 'fills', 'fill'), ...solidPaints(node, 'strokes', 'stroke')],
+      mixedPaints: false,
+      gap: null,
+      padding: [],
+      radius: [],
+      detached: null,
+    });
+  }
+  return records;
+}
+
+function screensOn(page, names) {
+  const all = [];
+  for (const top of page.children) {
+    if (top.type === 'FRAME') all.push(top);
+    else if (top.type === 'SECTION') for (const c of top.children) if (c.type === 'FRAME') all.push(c);
+  }
+  if (!names || !names.length) return all;
+  return names.map((name) => {
+    const hit = all.find((s) => s.name === name);
+    if (!hit) throw new Error(`no screen named "${name}" on page "${page.name}"`);
+    return hit;
+  });
+}
+
+async function readTokens() {
+  const colours = {};
+  for (const variable of await figma.variables.getLocalVariablesAsync('COLOR')) {
+    const { modes } = await variableColors(variable);
+    for (const hex of Object.values(modes)) {
+      if (!hex) continue;
+      const names = colours[hex] || (colours[hex] = []);
+      if (!names.includes(variable.name)) names.push(variable.name);
+    }
+  }
+  const gap = {};
+  const radius = {};
+  const add = (table, value, name) => {
+    if (typeof value !== 'number') return;
+    const names = table[String(value)] || (table[String(value)] = []);
+    if (!names.includes(name)) names.push(name);
+  };
+  for (const variable of await figma.variables.getLocalVariablesAsync('FLOAT')) {
+    const buckets = dimensionBuckets(variable.name, variable.scopes || []);
+    for (const value of Object.values(variable.valuesByMode)) {
+      if (buckets.gap) add(gap, value, variable.name);
+      if (buckets.radius) add(radius, value, variable.name);
+    }
+  }
+  return { colours, gap, radius };
+}
+
+// Exact name first. Page names often carry decoration nobody types (01. Design
+// System's are "    ↳ Templates"), so a unique match on the trimmed name also counts.
+function findPage(name) {
+  const exact = figma.root.children.find((p) => p.name === name);
+  if (exact) return exact;
+  const trimmed = figma.root.children.filter((p) => p.name.trim() === String(name).trim());
+  if (trimmed.length === 1) return trimmed[0];
+  throw new Error(`no page named "${name}"`);
+}
+
+async function readScreens(target) {
+  const page = findPage(target.page);
+  await page.loadAsync();
+  const screens = screensOn(page, target.screens);
+  const nodes = [];
+  const walk = (node, path, isRoot, insideDetached) => {
+    if (node.visible === false) return;
+    if (node.type === 'INSTANCE') {
+      nodes.push(...overriddenRecords(node, path, insideDetached));
+      return;
+    }
+    const mixedPaints = node.fills === figma.mixed;
+    const detached = detachedOf(node, page);
+    const underDetached = insideDetached || detached !== null;
+    nodes.push({
+      id: node.id,
+      path,
+      isRoot,
+      inInstance: false,
+      underDetached,
+      overridden: [],
+      paints: [...solidPaints(node, 'fills', 'fill'), ...solidPaints(node, 'strokes', 'stroke')],
+      mixedPaints,
+      gap: gapOf(node),
+      padding: paddingOf(node),
+      radius: radiusOf(node),
+      detached,
+    });
+    for (const child of node.children || []) walk(child, `${path} / ${child.name}`, false, underDetached);
+  };
+  for (const screen of screens) walk(screen, `${page.name.trim()} / ${screen.name}`, true, false);
+  return {
+    // The caller passes the fileKey from design-system.json: figma.fileKey is only
+    // exposed to private plugins.
+    fileKey: target.fileKey || figma.fileKey,
+    nodes,
+    tokens: await readTokens(),
+  };
+}
+
+async function runScreenGate(TARGET, SKIP) {
+  return checkScreens(await readScreens(TARGET), { skip: SKIP || [] });
+}