@radicool/throughline 0.23.0 → 0.24.0

package/references/figma-component-standards.md

@@ -586,6 +586,14 @@ For each generated artboard / doc card / icon grid, read the nodes back (via
    - **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/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/scripts/README.md

@@ -23,15 +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, 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/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` 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) |
 
@@ -249,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.23.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

@@ -1,6 +1,7 @@
 // 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
+// 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.
@@ -10,40 +11,50 @@ 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 });';
+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/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).',
+  '     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`.',
+  '   `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',
@@ -66,20 +77,22 @@ const FOOTER = ['```', ''].join('\n');
 const stripExports = (src) =>
   src.replace(/^export const /gm, 'const ').replace(/^export function /gm, 'function ');
 
-export function buildFigmaChecks({ statesSource, checkerSource, readerSource }) {
+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], ['figma-checks.mjs', checker], ['figma-checks-read.figma.js', readerSource]]) {
+  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${checker}\n${BIND}\n\n${readerSource}${FOOTER}`;
+  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'),
   });

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

@@ -1,21 +1,60 @@
 // 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 and figma-checks.mjs into references/figma-checks.md, and
+// 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
-// resolved with getVariableByIdAsync and only for focus variants and their
-// controlLayer. Untested in Node, like the doc-card renderer; the pure checker
-// it feeds is unit-tested.
+// 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);
-  return variable ? variable.name : null;
+  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.
@@ -76,6 +115,7 @@ function groupProperties(set) {
 }
 
 async function readComponentSet(expect) {
+  readVariables.clear();
   await figma.currentPage.loadAsync();
   const frameName = `WIP: ${expect.name}`;
   const frame = figma.currentPage.findOne((n) => n.name === frameName);
@@ -106,10 +146,24 @@ async function readComponentSet(expect) {
     }
     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,
   };
 }
 

package/scripts/lib/figma-checks.mjs

@@ -1,26 +1,35 @@
 // The Figma stop conditions as a pure checker: the COMPONENT_SET assertion against
-// the full variant matrix, the state matrix, and the focus ring. ZERO imports,
+// the full variant matrix, the state matrix, the focus ring, and the focus ring's
+// contrast against the surfaces it sits on. ZERO imports,
 // `export const`/`export function` only. This module is inlined, with
-// component-states.mjs above it, into the generated Figma script
+// component-states.mjs and contrast.mjs above it, into the generated Figma script
 // (references/figma-checks.md) by build-figma-checks.mjs, so it must run in both
 // Node and the Figma plugin sandbox.
 //
 // The state table is not imported. `withTable({ resolveArchetype, BASELINE_STATES,
-// STATE_SYNONYMS, normalizeName })` takes it, and the fold, from the caller and
-// returns { checkSpec, checkBuilt }. In the generated script the caller passes the
+// STATE_SYNONYMS, normalizeName, contrastRatio, composite, parseHex, AA_NON_TEXT })`
+// takes it, the fold and the contrast maths from the caller and returns
+// { checkSpec, checkBuilt }. In the generated script the caller passes the
 // inlined component-states.mjs names; in tests it passes the module's own exports.
 //
 // Spec: docs/specs/2026-10-07-figma-checks-as-scripts.md
 // Rules: references/figma-component-standards.md (State handling; audit items 8, 9)
 //
-// EXPECT: { name, matrix: { axis: [values] }, uiFramework, controlLayer? }
+// Spec (focus contrast): docs/specs/2026-10-13-focus-ring-contrast.md
+//
+// EXPECT: { name, matrix: { axis: [values] }, uiFramework, controlLayer?, surfaces? }
+//   surfaces: colour-variable names of the page surfaces the component sits on.
 //
 // SNAPSHOT (what the reader returns for the COMPONENT_SET in `WIP: <name>`):
 //   {
 //     type,                               // the set's node type, 'COMPONENT_SET'
 //     variantGroupProperties: { Axis: { values: [...] }, ... },   // only the keys are read
-//     children: [ VARIANT, ... ]
+//     children: [ VARIANT, ... ],
+//     colors: { [variableName]: { modes: { [modeName]: '#rrggbb' | '#rrggbbaa' | null }, defaultMode } },
+//     missingSurfaces: [name, ...]          // EXPECT.surfaces names with no local colour variable
 //   }
+//   `colors` holds every colour variable read on focus variants and their
+//   controlLayer, plus each EXPECT.surfaces name that was found.
 //   VARIANT (every child):  { type, variantProperties: { Axis: 'Value' } }
 //   A VARIANT whose state value folds to `focus` also carries FOCUS NODE fields
 //   (below), plus `controlLayer` when EXPECT names one.
@@ -36,6 +45,8 @@
 //   Variable names are resolved by the reader and only for focus variants and their controlLayer.
 //
 // RESULT: { pass, checks: [{ name, result: 'pass' | 'fail' | 'skip', detail }] }
+//   built mode returns four checks: structural-read-back, state-baseline,
+//   focus-indicator, focus-contrast.
 //   `pass` ignores skips. A failed assertion is data; nothing here throws.
 
 // The in-scope `uiFramework` values and the focus recipe each one uses. An absent or
@@ -61,11 +72,17 @@ function frameworkRecipe(uiFramework) {
     : null;
 }
 
-// A focus variable is any variable whose name has a `focus` segment:
-// `border/focus`, `color/border/focus` and `color/focus/ring` count; `focusRing` and
-// a raw colour (null) do not.
+// A focus variable is any variable whose name has `focus` as a whole word: in a
+// `/` segment of its own, or inside one split on `-`, `_`, spaces or a camelCase
+// boundary. `border/focus`, `color/focus/ring`, `color/focusRing` and
+// `interaction/border-primary-focus` count; `color/bg/focused` and a raw colour
+// (null) do not.
 function isFocusVariable(name) {
-  return typeof name === 'string' && name.split('/').some((seg) => seg.trim().toLowerCase() === 'focus');
+  if (typeof name !== 'string') return false;
+  const words = name
+    .split('/')
+    .flatMap((seg) => seg.replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[\s_-]+/));
+  return words.some((word) => word.toLowerCase() === 'focus');
 }
 
 // A choice control may carry selection on its own axis instead of as a `selected`
@@ -102,7 +119,34 @@ function lacksRing(target, recipe, isInput) {
       ];
 }
 
-export function withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName }) {
+// The focus-variable names that make up the ring `lacksRing` accepted, for the
+// contrast check. Same recipes, same tests.
+function ringVariables(target, recipe, isInput) {
+  const children = target.children ?? [];
+  const focusStrokes = (node) => (node.strokeVariables ?? []).filter(isFocusVariable);
+  if (recipe === 'mui' && isInput) return focusStrokes(target);
+  if (recipe === 'outline') {
+    return [target, ...children].filter((n) => n.strokeAlign === 'OUTSIDE').flatMap(focusStrokes);
+  }
+  const shadows = (target.effects ?? [])
+    .filter((e) => e.type === 'DROP_SHADOW' && e.visible !== false && e.spread > 0 && isFocusVariable(e.colorVariable))
+    .map((e) => e.colorVariable);
+  const ringChildren = children
+    .filter((c) => c.layoutPositioning === 'ABSOLUTE' && c.strokeAlign === 'OUTSIDE')
+    .flatMap(focusStrokes);
+  return [...shadows, ...ringChildren];
+}
+
+export function withTable({
+  resolveArchetype,
+  BASELINE_STATES,
+  STATE_SYNONYMS,
+  normalizeName,
+  contrastRatio,
+  composite,
+  parseHex,
+  AA_NON_TEXT,
+}) {
   const fold = normalizeName;
   const foldState = (value) => {
     const name = fold(value);
@@ -122,6 +166,10 @@ export function withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, n
       .map(([k, v]) => `${k}=${v}`)
       .join(', ');
 
+  const isFocusVariant = (child) =>
+    child.type === 'COMPONENT' &&
+    Object.entries(child.variantProperties ?? {}).some(([k, v]) => fold(k) === 'state' && fold(v) === 'focus');
+
   function crossProduct(matrix) {
     let combos = [{}];
     for (const [axis, values] of Object.entries(matrix ?? {})) {
@@ -199,9 +247,6 @@ export function withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, n
     if (recipe === null) {
       return { name, result: 'skip', detail: `uiFramework "${expect.uiFramework}" is out of scope for the focus check` };
     }
-    const isFocusVariant = (child) =>
-      child.type === 'COMPONENT' &&
-      Object.entries(child.variantProperties ?? {}).some(([k, v]) => fold(k) === 'state' && fold(v) === 'focus');
     const variants = (snapshot.children ?? []).filter(isFocusVariant);
     if (variants.length === 0) {
       return { name, result: 'fail', detail: 'no COMPONENT variant has a state of focus, so no ring can be read; the state check stops on this' };
@@ -224,6 +269,100 @@ export function withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, n
       : { name, result: 'pass', detail: `all ${variants.length} focus variants carry a ${recipe}-recipe focus indicator` };
   }
 
+  // WCAG 1.4.11: each ring colour against each named surface, in every mode either
+  // side has. Runs only on a ring focusIndicator accepted.
+  function focusContrast(snapshot, expect, indicator) {
+    const name = 'focus-contrast';
+    if (indicator.result !== 'pass') {
+      return { name, result: 'skip', detail: 'focus-indicator did not pass, so there is no ring to measure' };
+    }
+    const surfaces = expect.surfaces ?? [];
+    if (surfaces.length === 0) {
+      return {
+        name,
+        result: 'skip',
+        detail: 'no surfaces named; the architect names the colour variables of the surfaces the component sits on',
+      };
+    }
+    const missing = snapshot.missingSurfaces ?? [];
+    if (missing.length) {
+      return { name, result: 'fail', detail: `no local colour variable named: ${missing.join(', ')}` };
+    }
+
+    const recipe = frameworkRecipe(expect.uiFramework);
+    const isInput = resolveArchetype({ name: expect.name }) === 'input';
+    const hasLayer = expect.controlLayer !== undefined && expect.controlLayer !== null;
+    const rings = new Set();
+    for (const variant of (snapshot.children ?? []).filter(isFocusVariant)) {
+      const target = hasLayer ? variant.controlLayer : variant;
+      if (target) for (const ring of ringVariables(target, recipe, isInput)) rings.add(ring);
+    }
+
+    const colors = snapshot.colors ?? {};
+    // A mode's value: the same-named mode after the fold, else the default.
+    const valueIn = (entry, foldedMode) => {
+      const modes = entry?.modes ?? {};
+      const hit = Object.keys(modes).find((m) => fold(m) === foldedMode);
+      if (hit !== undefined) return modes[hit];
+      return entry?.defaultMode !== undefined ? modes[entry.defaultMode] ?? null : null;
+    };
+    const skipped = { unresolved: 0, translucentSurface: 0 };
+    const failures = [];
+    const modesSeen = new Set();
+    let pairs = 0;
+    for (const ring of [...rings].sort()) {
+      for (const surface of [...surfaces].sort()) {
+        const ringEntry = colors[ring];
+        const surfaceEntry = colors[surface];
+        // Modes come from the side(s) with more than one: a single-mode collection
+        // reads the same value in every mode, so its own mode name adds nothing.
+        // When both are single-mode, the ring's one mode is the only comparison.
+        const entries = [ringEntry, surfaceEntry];
+        const multi = entries.filter((e) => Object.keys(e?.modes ?? {}).length > 1);
+        const single = Object.keys(ringEntry?.modes ?? {}).length ? [ringEntry] : [surfaceEntry];
+        const modeNames = new Map();
+        for (const entry of multi.length ? multi : single) {
+          for (const m of Object.keys(entry?.modes ?? {})) if (!modeNames.has(fold(m))) modeNames.set(fold(m), m);
+        }
+        if (modeNames.size === 0) {
+          skipped.unresolved += 1;
+          continue;
+        }
+        for (const [foldedMode, mode] of [...modeNames].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))) {
+          const ringHex = valueIn(ringEntry, foldedMode);
+          const surfaceHex = valueIn(surfaceEntry, foldedMode);
+          const surfaceParsed = parseHex(surfaceHex);
+          if (parseHex(ringHex) === null || surfaceParsed === null) {
+            skipped.unresolved += 1;
+            continue;
+          }
+          if (surfaceParsed.a < 1) {
+            skipped.translucentSurface += 1;
+            continue;
+          }
+          const surfaceOpaque = surfaceHex.slice(0, 7);
+          const ratio = contrastRatio(composite(ringHex, surfaceOpaque), surfaceOpaque);
+          pairs += 1;
+          modesSeen.add(foldedMode);
+          if (ratio < AA_NON_TEXT) {
+            const shown = (Math.floor(ratio * 100) / 100).toFixed(2);
+            failures.push(`${ring} on ${surface} in ${mode}: ${shown}:1, needs ${AA_NON_TEXT}:1`);
+          }
+        }
+      }
+    }
+    const skipNote = [
+      skipped.unresolved && `${skipped.unresolved} skipped as unresolved or not a colour`,
+      skipped.translucentSurface && `${skipped.translucentSurface} skipped for a translucent surface`,
+    ].filter(Boolean);
+    if (failures.length) return { name, result: 'fail', detail: failures.join('; ') };
+    if (pairs === 0) {
+      return { name, result: 'skip', detail: `no ring/surface pair could be compared: ${skipNote.join(', ') || 'no ring colour found'}` };
+    }
+    const passed = `${pairs} ring/surface pair(s) clear ${AA_NON_TEXT}:1 across ${modesSeen.size} mode(s)`;
+    return { name, result: 'pass', detail: skipNote.length ? `${passed}; ${skipNote.join(', ')}` : passed };
+  }
+
   // Before anything is written: the matrix the spec asks for against the state table.
   function checkSpec(expect) {
     const entries = Object.entries(expect.matrix ?? {}).flatMap(([axis, values]) => values.map((v) => [axis, v]));
@@ -233,7 +372,13 @@ export function withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, n
   // After the build: the node as read.
   function checkBuilt(snapshot, expect) {
     const entries = (snapshot.children ?? []).flatMap((c) => Object.entries(c.variantProperties ?? {}));
-    return result([structural(snapshot, expect), stateBaseline(expect, entries), focusIndicator(snapshot, expect)]);
+    const indicator = focusIndicator(snapshot, expect);
+    return result([
+      structural(snapshot, expect),
+      stateBaseline(expect, entries),
+      indicator,
+      focusContrast(snapshot, expect, indicator),
+    ]);
   }
 
   return { checkSpec, checkBuilt };

package/scripts/lib/fixtures/figma-checks/avatar-not-in-table.json

@@ -38,6 +38,7 @@
   "expected": {
     "structural-read-back": "pass",
     "state-baseline": "skip",
-    "focus-indicator": "skip"
+    "focus-indicator": "skip",
+    "focus-contrast": "skip"
   }
 }

package/scripts/lib/fixtures/figma-checks/button-ios-swift-skipped.json

@@ -80,6 +80,7 @@
   "expected": {
     "structural-read-back": "pass",
     "state-baseline": "pass",
-    "focus-indicator": "skip"
+    "focus-indicator": "skip",
+    "focus-contrast": "skip"
   }
 }

package/scripts/lib/fixtures/figma-checks/button-missing-default.json

@@ -66,6 +66,7 @@
   "expected": {
     "structural-read-back": "pass",
     "state-baseline": "fail",
-    "focus-indicator": "pass"
+    "focus-indicator": "pass",
+    "focus-contrast": "skip"
   }
 }

package/scripts/lib/fixtures/figma-checks/button-mui-ring.json

@@ -87,6 +87,7 @@
   "expected": {
     "structural-read-back": "pass",
     "state-baseline": "pass",
-    "focus-indicator": "pass"
+    "focus-indicator": "pass",
+    "focus-contrast": "skip"
   }
 }

package/scripts/lib/fixtures/figma-checks/button-no-focus-variant.json

@@ -66,6 +66,7 @@
   "expected": {
     "structural-read-back": "pass",
     "state-baseline": "fail",
-    "focus-indicator": "fail"
+    "focus-indicator": "fail",
+    "focus-contrast": "skip"
   }
 }

package/scripts/lib/fixtures/figma-checks/button-plain-frames.json

@@ -87,6 +87,7 @@
   "expected": {
     "structural-read-back": "fail",
     "state-baseline": "pass",
-    "focus-indicator": "fail"
+    "focus-indicator": "fail",
+    "focus-contrast": "skip"
   }
 }

package/scripts/lib/fixtures/figma-checks/button-ring-child-not-absolute.json

@@ -89,6 +89,7 @@
   "expected": {
     "structural-read-back": "pass",
     "state-baseline": "pass",
-    "focus-indicator": "fail"
+    "focus-indicator": "fail",
+    "focus-contrast": "skip"
   }
 }

package/scripts/lib/fixtures/figma-checks/button-ring-hidden.json

@@ -87,6 +87,7 @@
   "expected": {
     "structural-read-back": "pass",
     "state-baseline": "pass",
-    "focus-indicator": "fail"
+    "focus-indicator": "fail",
+    "focus-contrast": "skip"
   }
 }

package/scripts/lib/fixtures/figma-checks/button-ring-unbound-colour.json

@@ -1,5 +1,5 @@
 {
-  "covers": "shadow with a raw colour and a variable with no focus segment",
+  "covers": "shadow with a raw colour and a variable with no focus word",
   "expect": {
     "name": "Button",
     "matrix": {
@@ -66,7 +66,7 @@
             "type": "DROP_SHADOW",
             "visible": true,
             "spread": 3,
-            "colorVariable": "color/focusRing"
+            "colorVariable": "color/border/default"
           }
         ],
         "strokeAlign": "INSIDE",
@@ -93,6 +93,7 @@
   "expected": {
     "structural-read-back": "pass",
     "state-baseline": "pass",
-    "focus-indicator": "fail"
+    "focus-indicator": "fail",
+    "focus-contrast": "skip"
   }
 }

package/scripts/lib/fixtures/figma-checks/button-shadcn-filled.json

@@ -87,6 +87,7 @@
   "expected": {
     "structural-read-back": "pass",
     "state-baseline": "pass",
-    "focus-indicator": "pass"
+    "focus-indicator": "pass",
+    "focus-contrast": "skip"
   }
 }