@radicool/throughline 0.21.4 → 0.22.0

package/README.md

@@ -73,7 +73,7 @@ Everything above was created during a single working session and synced directly
 
 | | |
 |---|---|
-| **A supported agent** | Required — [Claude Code](https://docs.claude.com/en/docs/claude-code) (native plugin), or **Cursor**, **Codex**, or any **AGENTS.md**-aware agent via `npx @radicool/throughline@0.21.4 init`. |
+| **A supported agent** | Required — [Claude Code](https://docs.claude.com/en/docs/claude-code) (native plugin), or **Cursor**, **Codex**, or any **AGENTS.md**-aware agent via `npx @radicool/throughline@0.22.0 init`. |
 | **Figma** | Required, **desktop app** (the browser version causes connection errors). **Professional plan or higher recommended** — multi-mode variables (Light/Dark, brand themes) need it. |
 | **Figma access token** | Optional — only for the few Figma calls the Desktop Bridge can't make, like reading a published library. Without it, you work through the bridge alone. The setup skill walks you through it; your token stays yours and is never shared in chat. |
 | **GitHub** (or similar) | Optional — only when you're ready to graduate to a real remote repo with PRs and CI. |
@@ -114,9 +114,9 @@ Update anytime with `/plugin marketplace update throughline-marketplace`.
 Run the installer in your project — it stamps in the skills, the reference docs, the scripts, and the Figma MCP config for your tool:
 
 ```
-npx @radicool/throughline@0.21.4 init --target=cursor    # → .cursor/rules + .cursor/mcp.json
-npx @radicool/throughline@0.21.4 init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
-npx @radicool/throughline@0.21.4 init --target=generic    # → skills/ + AGENTS.md index
+npx @radicool/throughline@0.22.0 init --target=cursor    # → .cursor/rules + .cursor/mcp.json
+npx @radicool/throughline@0.22.0 init --target=codex      # → prompts/ + AGENTS.md index + codex-mcp.toml
+npx @radicool/throughline@0.22.0 init --target=generic    # → skills/ + AGENTS.md index
 ```
 
 It's safe to re-run (it merges `AGENTS.md` and `.cursor/mcp.json` non-destructively) and stages everything the skills read into `.throughline/`. Then open the `figma-environment-setup` skill/rule/prompt for your tool to begin. For Codex, add the printed `codex-mcp.toml` block to your Codex config to enable Figma access.
@@ -162,7 +162,7 @@ For the technically curious — how the machine actually runs.
 
 **Modes, within Figma's limits.** Light/Dark lives on the semantic collections; brand variants live on the primitive palette. Splitting the two axes across two collections keeps each one under Figma's 4-modes-per-collection cap on the Professional plan while still resolving correctly (`bg/default` → `{gray/50}` → the active brand's gray).
 
-**Model routing.** ThroughLine routes work by *cognition, not guesswork* — the expensive thinking on the best model, the mechanical doing on a cheap one. Setup pins **Haiku** to keep first-run costs low. Inside a skill, the deciding — a token architecture, a variant matrix, a slot contract — is planned once on the strongest tier, while the long mechanical part — placing Figma nodes, transcribing component code, running SVGR — runs on a cheap tier and self-verifies. You get the best model where it matters and a cheap one where it doesn't, without micromanaging it. The recommended mapping is **Haiku → Sonnet → Opus** for the `fast < balanced < deep` tiers, but apart from setup's Haiku pin, nothing is hardcoded — the ladder resolves against whatever models your install actually has, and on hosts without subagents skills degrade cleanly to a single model. You can still steer the session yourself (`/model opus` for the heaviest authoring, back to `/model sonnet` after); nothing forces an expensive model on you.
+**Model routing.** ThroughLine routes work by *cognition, not guesswork* — the expensive thinking on the best model, the mechanical doing on a cheap one. Inside a skill, the deciding — a token architecture, a variant matrix, a slot contract — is planned once on the strongest tier, while the long mechanical part — placing Figma nodes, transcribing component code, running SVGR — runs on a cheap tier and self-verifies. You get the best model where it matters and a cheap one where it doesn't, without micromanaging it. The recommended mapping is **Haiku → Sonnet → Opus** for the `fast < balanced < deep` tiers, but nothing is hardcoded — the ladder resolves against whatever models your install actually has, and on hosts without subagents skills degrade cleanly to a single model. You can still steer the session yourself (`/model opus` for the heaviest authoring, back to `/model sonnet` after); nothing forces an expensive model on you.
 
 ## Who it's for
 

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

@@ -67,8 +67,9 @@ inconsistent output:
 - **Sizes** (sm, md, lg). Each size is its **own variant row**, not a state — see
   the layout law below.
 - **States** — **include the full relevant set, don't trim it.** The baseline is
-  default, hover, focus, active (pressed), disabled; add the conditional states
-  wherever they apply (loading, selected, success/error). Decide which conditional
+  the set `.throughline/references/state-baseline.md` owes that component
+  (default included); add the conditional states wherever they apply (loading,
+  success/error). Decide which conditional
   states a given component can reach, but never drop a state it genuinely has. See
   "State handling" in `.throughline/references/figma-component-standards.md`
   for the per-component checklist.
@@ -400,9 +401,9 @@ Offer next steps: build the code counterparts and stories
   auto-layout grid where **variants are rows and states are columns**: one row per
   variant (each `type`, and each `size`, since size is a variant) stepping through
   states across the columns, size groups stacked vertically (see the standards doc).
-- Never ship a component with only its `default` state — include the full relevant
-  state set (default/hover/focus/active/disabled plus applicable
-  loading/selected/success/error).
+- Never ship a component with only its `default` state — include every state
+  `.throughline/references/state-baseline.md` owes that component, plus
+  `default`, plus any applicable loading/success/error.
 - Never run the component header and the component area together with no division —
   every doc card segments the header from the component area with a divider line or
   a distinct header surface.

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

@@ -140,7 +140,10 @@ fit in the adapter output.
 
 ## Step 3 — Set up Style Dictionary + adapters
 
-Install and configure Style Dictionary v4 in `packages/tokens/`. For each chosen
+Install Style Dictionary pinned to an exact version with
+`pnpm add -D style-dictionary@4.4.0` (or the project's package manager) in
+`packages/tokens/`; the generated config is verified against 4.4.0, and a newer
+release can rename or add stock transforms. Then configure it. For each chosen
 platform, apply its adapter preset (per `.throughline/references/sync-adapters.md`):
 register the platform, transform group, format, and `outputReferences`
 (true for web → preserves the semantic→primitive cascade; false for native →

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

@@ -71,8 +71,9 @@ inconsistent output:
 - **Sizes** (sm, md, lg). Each size is its **own variant row**, not a state — see
   the layout law below.
 - **States** — **include the full relevant set, don't trim it.** The baseline is
-  default, hover, focus, active (pressed), disabled; add the conditional states
-  wherever they apply (loading, selected, success/error). Decide which conditional
+  the set `.throughline/references/state-baseline.md` owes that component
+  (default included); add the conditional states wherever they apply (loading,
+  success/error). Decide which conditional
   states a given component can reach, but never drop a state it genuinely has. See
   "State handling" in `.throughline/references/figma-component-standards.md`
   for the per-component checklist.
@@ -404,9 +405,9 @@ Offer next steps: build the code counterparts and stories
   auto-layout grid where **variants are rows and states are columns**: one row per
   variant (each `type`, and each `size`, since size is a variant) stepping through
   states across the columns, size groups stacked vertically (see the standards doc).
-- Never ship a component with only its `default` state — include the full relevant
-  state set (default/hover/focus/active/disabled plus applicable
-  loading/selected/success/error).
+- Never ship a component with only its `default` state — include every state
+  `.throughline/references/state-baseline.md` owes that component, plus
+  `default`, plus any applicable loading/success/error.
 - Never run the component header and the component area together with no division —
   every doc card segments the header from the component area with a divider line or
   a distinct header surface.

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

@@ -144,7 +144,10 @@ fit in the adapter output.
 
 ## Step 3 — Set up Style Dictionary + adapters
 
-Install and configure Style Dictionary v4 in `packages/tokens/`. For each chosen
+Install Style Dictionary pinned to an exact version with
+`pnpm add -D style-dictionary@4.4.0` (or the project's package manager) in
+`packages/tokens/`; the generated config is verified against 4.4.0, and a newer
+release can rename or add stock transforms. Then configure it. For each chosen
 platform, apply its adapter preset (per `.throughline/references/sync-adapters.md`):
 register the platform, transform group, format, and `outputReferences`
 (true for web → preserves the semantic→primitive cascade; false for native →

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

@@ -67,8 +67,9 @@ inconsistent output:
 - **Sizes** (sm, md, lg). Each size is its **own variant row**, not a state — see
   the layout law below.
 - **States** — **include the full relevant set, don't trim it.** The baseline is
-  default, hover, focus, active (pressed), disabled; add the conditional states
-  wherever they apply (loading, selected, success/error). Decide which conditional
+  the set `.throughline/references/state-baseline.md` owes that component
+  (default included); add the conditional states wherever they apply (loading,
+  success/error). Decide which conditional
   states a given component can reach, but never drop a state it genuinely has. See
   "State handling" in `.throughline/references/figma-component-standards.md`
   for the per-component checklist.
@@ -400,9 +401,9 @@ Offer next steps: build the code counterparts and stories
   auto-layout grid where **variants are rows and states are columns**: one row per
   variant (each `type`, and each `size`, since size is a variant) stepping through
   states across the columns, size groups stacked vertically (see the standards doc).
-- Never ship a component with only its `default` state — include the full relevant
-  state set (default/hover/focus/active/disabled plus applicable
-  loading/selected/success/error).
+- Never ship a component with only its `default` state — include every state
+  `.throughline/references/state-baseline.md` owes that component, plus
+  `default`, plus any applicable loading/success/error.
 - Never run the component header and the component area together with no division —
   every doc card segments the header from the component area with a divider line or
   a distinct header surface.

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

@@ -140,7 +140,10 @@ fit in the adapter output.
 
 ## Step 3 — Set up Style Dictionary + adapters
 
-Install and configure Style Dictionary v4 in `packages/tokens/`. For each chosen
+Install Style Dictionary pinned to an exact version with
+`pnpm add -D style-dictionary@4.4.0` (or the project's package manager) in
+`packages/tokens/`; the generated config is verified against 4.4.0, and a newer
+release can rename or add stock transforms. Then configure it. For each chosen
 platform, apply its adapter preset (per `.throughline/references/sync-adapters.md`):
 register the platform, transform group, format, and `outputReferences`
 (true for web → preserves the semantic→primitive cascade; false for native →

package/package.json

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

package/references/figma-component-standards.md

@@ -123,19 +123,17 @@ run, and it mirrors how the states/types map to code props.
 
 - **Always include every relevant state for the component — completeness is the
   default, not a judgment call.** A component's `state` axis must enumerate its full
-  applicable interaction surface, not just `default`. The baseline interactive set
-  is **default, hover, focus, active (pressed), disabled**; add the **conditional**
-  states whenever they apply to that component: **loading** (anything that triggers
-  async work — buttons, submit inputs), **selected** (toggles, segmented controls,
-  list/menu items, chips), and **success / error** (validated inputs, form fields,
-  async-result buttons). Decide *which* conditional states apply, but never drop a
-  state that does apply to keep the matrix small.
-  - **Button:** default, hover, focus, active (pressed), disabled — plus loading
-    (and selected / success / error where the button supports them).
-  - **Input / text field:** default, hover, focus, disabled — plus error, success,
-    and (where async) loading.
-  - **Checkbox / radio / toggle / chip:** default, hover, focus, active, disabled —
-    plus selected (and indeterminate where it applies).
+  applicable interaction surface, not just `default`. The states a component owes
+  come from the table in `references/state-baseline.md` (see below); add the
+  **conditional** states whenever they apply to that component: **loading** (anything
+  that triggers async work — buttons, submit inputs), **selected** for components the
+  table does not cover (segmented controls, list/menu items), and **success / error**
+  (validated inputs, form fields, async-result buttons). Decide *which* conditional
+  states apply, but never drop a state that does apply to keep the matrix small.
+  - **Which components owe which states is one table**, shared with the CLI's
+    `state-incomplete` check: `references/state-baseline.md`, generated from
+    `scripts/lib/component-states.mjs`. Add loading, success / error, and
+    indeterminate where they apply; those are not in the table.
 - Keep these on a `state` variant axis where they change appearance meaningfully;
   each becomes a column in the set per "Component set arrangement".
 - Distinguish *component states* (part of the component's definition) from
@@ -557,8 +555,8 @@ For each generated artboard / doc card / icon grid, read the nodes back (via
    a header container whose surface fill differs from the component area (both
    token-bound). A card with no header/component segmentation is a fail.
 8. **States complete** — each component set's `state` axis includes every relevant
-   state for that component (default/hover/focus/active/disabled plus the applicable
-   conditional states — loading/selected/success/error), with variants (incl. each
+   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.
 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
@@ -581,10 +579,10 @@ For each generated artboard / doc card / icon grid, read the nodes back (via
      error: fix and re-audit like any other item. If the ring is still missing
      when the pass budget below runs out, **stop the build** rather than hand off.
    - **Scope.** It runs only for a component whose name folds (lowercase,
-     punctuation stripped) to a Button, an Input / text field, or a Checkbox /
-     radio / toggle / chip, the same exact-name match as the state check. A Switch
-     or a TextInput isn't in that list, so neither Figma check reads it (the CLI's
-     `state-incomplete` does). It also
+     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.

package/references/figma-scripting.md

@@ -68,7 +68,8 @@ wrong document.
 Run this before the first write, and again right before any replace — the
 build-verify-then-replace finalize deletes the existing node, so it is the write
 that destroys work in the wrong file. The `figma-executor` agent runs it as step 1
-of its contract. **When a skill builds inline instead** (a host with no subagent
+of its contract; the `architect` and `reviewer` agents, which read Figma but cannot
+navigate, run the compare and return `BLOCKED` on a mismatch. **When a skill builds inline instead** (a host with no subagent
 dispatch, or a write-back the skill does itself), nothing runs it for you: the
 skill has to.
 

package/references/state-baseline.md

@@ -0,0 +1,25 @@
+<!-- GENERATED by scripts/build-state-baseline.mjs from scripts/lib/component-states.mjs. Do not edit; run: node scripts/build-state-baseline.mjs -->
+# State baseline
+
+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.
+
+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`.
+Matching is exact on purpose: `IconButton` matches nothing, and a component that
+matches nothing owes no states.
+
+| Archetype | Names | States owed |
+|---|---|---|
+| button | `button` | `hover`, `focus`, `active`, `disabled` |
+| 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
+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.
+
+Names that fold to `card`, `modal`, `dialog`, `badge`, `tag` owe none, so neither check asserts states on them.

package/scripts/README.md

@@ -29,6 +29,7 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `lib/component-states.mjs` | The archetype table and resolver behind `state-incomplete` — which baseline interaction states each kind of component owes, and when to abstain. `validate-adherence.mjs` also uses it to find Badges. | copied alongside `verify-check.mjs` and `validate-adherence.mjs` |
 | `lib/contrast.mjs` | The WCAG contrast maths and the semantic colour pairs behind `color-contrast` — which text role must clear which surface, in every mode, and where the rule deliberately abstains. | copied alongside `verify-check.mjs` |
 | `build-doc-card-builder.mjs` | Generate `references/doc-card-builder.md` from the planner + the Figma renderer template (`lib/doc-card-render.figma.js`). `--check` gates CI. | plugin-internal (not installed) |
+| `build-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) |
 
 **Documentation scripts — install as a set.** Copying these files without
@@ -245,7 +246,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.21.4 init --target=cursor|codex|generic
+    npx @radicool/throughline@0.22.0 init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
 

package/scripts/build-state-baseline.mjs

@@ -0,0 +1,69 @@
+// Generates references/state-baseline.md from scripts/lib/component-states.mjs.
+// The table is the one list of which components owe which interaction states:
+// `verify:check` reads the module, and `figma-executor` (which cannot import
+// JavaScript) reads this rendering. Mirrors build-native-adapter-config.mjs:
+// run bare to write, --check to gate CI. Zero dependencies.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ARCHETYPES, BASELINE_STATES, NAME_SYNONYMS, STATE_SYNONYMS } from './lib/component-states.mjs';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const OUT = join(REPO_ROOT, 'references', 'state-baseline.md');
+
+export function render(states = BASELINE_STATES, synonyms = NAME_SYNONYMS, archetypes = ARCHETYPES, stateSynonyms = STATE_SYNONYMS) {
+  const aliases = Object.keys(stateSynonyms).map((s) => `\`${s}\` counts as \`${stateSynonyms[s]}\``).join(', and ');
+  const owing = archetypes.filter((a) => (states[a] ?? []).length > 0);
+  const rows = owing.map((a) => {
+    const names = Object.keys(synonyms).filter((n) => synonyms[n] === a);
+    return `| ${a} | ${names.map((n) => `\`${n}\``).join(', ')} | ${states[a].map((s) => `\`${s}\``).join(', ')} |`;
+  });
+  const exempt = archetypes.filter((a) => !owing.includes(a) && a !== 'other');
+  const exemptNames = exempt.flatMap((a) => Object.keys(synonyms).filter((n) => synonyms[n] === a));
+  return `<!-- GENERATED by scripts/build-state-baseline.mjs from scripts/lib/component-states.mjs. Do not edit; run: node scripts/build-state-baseline.mjs -->
+# State baseline
+
+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.
+
+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\`.
+Matching is exact on purpose: \`IconButton\` matches nothing, and a component that
+matches nothing owes no states.
+
+| Archetype | Names | States owed |
+|---|---|---|
+${rows.join('\n')}
+
+Every state in the table must be a value on the component's \`state\` axis. 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.
+
+Names that fold to ${exemptNames.map((n) => `\`${n}\``).join(', ')} owe none, so neither check asserts states on them.
+`;
+}
+
+function main() {
+  const check = process.argv.includes('--check');
+  const rendered = render();
+  if (!check) {
+    writeFileSync(OUT, rendered);
+    console.log(`wrote ${OUT}`);
+    return;
+  }
+  const current = readFileSync(OUT, 'utf8');
+  if (current === rendered) {
+    console.log('references/state-baseline.md is up to date');
+    return;
+  }
+  console.error(
+    'references/state-baseline.md is stale.\n' +
+      'Run: node scripts/build-state-baseline.mjs',
+  );
+  process.exit(1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/scripts/lib/component-states.mjs

@@ -1,13 +1,18 @@
 // The archetype baseline for `state-incomplete` (`docs/specs/2026-09-12-verification-proof-bundle.md`,
-// step 3). Source of truth for the prose is `references/figma-component-standards.md:126-138`.
+// step 3). The prose in `references/figma-component-standards.md` (State handling) points at
+// `references/state-baseline.md`, which is generated from this file.
 //
 // `default` is deliberately excluded from every baseline below: documenting the
 // resting state is not documentation, and the Figma matrix requirement for it is
 // the executor's, not this table's. Conditional states (`loading`, `error`,
-// `success`, `selected`) are deliberately excluded too — whether one applies to a
-// given component is a design judgment, not something a baseline can assert.
+// `success`) are deliberately excluded too — whether one applies to a given
+// component is a design judgment, not something a baseline can assert. `selected`
+// is not conditional for a choice control: a checkbox, radio, toggle, switch or
+// chip that cannot be selected is not one.
 //
-// MAINTENANCE: a change to the prose baseline must change this table.
+// This table is the single source for both checks. `scripts/build-state-baseline.mjs`
+// 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';
 
@@ -16,7 +21,7 @@ export const ARCHETYPES = ['button', 'input', 'choice', 'card', 'modal', 'badge'
 export const BASELINE_STATES = {
   button: ['hover', 'focus', 'active', 'disabled'],
   input: ['hover', 'focus', 'disabled'],
-  choice: ['hover', 'focus', 'active', 'disabled'],
+  choice: ['hover', 'focus', 'active', 'selected', 'disabled'],
   card: [],
   modal: [],
   badge: [],
@@ -40,6 +45,14 @@ export const NAME_SYNONYMS = {
   tag: 'badge',
 };
 
+// Other names a recorded state goes by. shadcn and Radix call a checked checkbox
+// `checked` and a pressed-in toggle `on`; both are `selected` here. `pressed` is
+// not one: the standards use it for `active`.
+export const STATE_SYNONYMS = {
+  checked: 'selected',
+  on: 'selected',
+};
+
 export function resolveArchetype(record) {
   if (ARCHETYPES.includes(record.archetype)) return record.archetype;
   const bySynonym = NAME_SYNONYMS[normalizeName(record.name)];
@@ -51,6 +64,11 @@ export function missingStates(record) {
   if (archetype === null) return [];
   const baseline = BASELINE_STATES[archetype];
   if (baseline.length === 0) return [];
-  const recordedKeys = new Set(Object.keys(record.states ?? {}).map(normalizeName));
+  const recordedKeys = new Set(
+    Object.keys(record.states ?? {}).map((key) => {
+      const name = normalizeName(key);
+      return STATE_SYNONYMS[name] ?? name;
+    }),
+  );
   return baseline.filter((state) => !recordedKeys.has(normalizeName(state)));
 }