@motion-proto/live-tokens 0.96.0 → 0.98.2

package/.claude/skills/live-tokens-check-compliance/SKILL.md

@@ -26,6 +26,7 @@ Both checkers are static. They read the project's source, never open a browser,
     - the fixes the checkers applied, each with its count and any visible shift
     - the remaining changes by rule, each with its count and any visible shift
     - the findings left, each with its reason and any config entry the user chose
+    - the `a11y-*` alerts, each with its element and guidance, for the user to review
     - both checker commands with their exit codes
 
 `check-page <path>` scopes a run to one page. `check-component <id>` scopes a run to one component: its runtime, its editor, and its registration. The checkers read tokens.css from its default location.
@@ -50,6 +51,10 @@ Every finding's `repair` says what moving it costs.
 - **`choice`.** A role or an ambiguous value determines the fix, such as a color literal and the role it plays, or a spacing literal tied between two steps. `details` lists the candidates, and `guidance` says how to pick one.
 - **`authored`.** New code is the fix: a runtime that has to start behaving, an editor schema that has to name a token, a route that has to move. `guidance` names what to write. No candidate list applies.
 
+## Accessibility alerts
+
+A `--tests` run adds the `a11y-*` rules, which test the rendered page or component against WCAG 2 A and AA with axe, Siteimprove Alfa, the contract's keyboard cases, and the suite's own focus indicator, control boundary, text spacing, and reduced motion checks. Each reports at `warn` and blocks only under `--strict`. Every `a11y-*` finding is an alert the user reviews: list it in the reply, and repair it from its guidance when the repair scope includes warnings. An `a11y-review` finding marks a check axe could not decide, such as text over a gradient, and the user judges it by eye. Inside the live-tokens repository, an `a11y-component` finding with engine rule `aria-snapshot` marks an accessibility tree that changed since it was recorded; after a deliberate markup change, `check-component <id> --tests --update-aria` records it anew.
+
 ## Scope
 
 - Add no token to `tokens.css`. Map a literal with no matching token to the nearest existing token by role. When no token fits, leave the finding and say so.

package/.claude/skills/live-tokens-create-component/SKILL.md

@@ -161,11 +161,12 @@ The excerpt shows the chain for part of the property map. Every editable value r
 
 ## Component editor
 
-Create `src/system/components/StatCardEditor.svelte` beside the runtime file. The editor has three parts.
+Create `src/system/components/StatCardEditor.svelte` beside the runtime file. The editor has four parts.
 
 1. A `<script module>` block exports `component`, the id, and `allTokens`, one row per property in the map. A row is `{ label, variable, element? }`; `element` groups rows in the panel by part, and `label` names the property in the row.
 2. The instance script imports the runtime component and the editor primitives from the package's public paths, and maps the state being edited to preview props.
 3. The markup mounts `ComponentEditorBase` with one `VariantGroup` per variant, each rendering a preview.
+4. The same `<script module>` block exports `contrastPairs`, one pair for each foreground color and each backdrop it sits on, and the registration passes it as `contrastPairs`. Every `allTokens` color with a text or icon suffix (`-text`, `-label`, `-icon`, `-title`, `-body`, `-value`, and the other text roles in `references/token-naming.md`) is the foreground of at least one pair. A pair is `{ foreground, backdrop, role, fontSize?, fontWeight?, inactive?, context? }`. `backdrop` lists the properties the runtime paints behind the foreground, top layer first, and leaves out `--page-bg`, which the editor puts under the last layer. `role` is `'text'`, or `'non-text'` for an icon or another mark. A text pair names its `-font-size` property as `fontSize`, the smaller one when the text renders at two sizes, and its `-font-weight` property as `fontWeight`. A disabled state's pair sets `inactive: true`, because WCAG exempts disabled controls. A foreground over several backdrops takes one pair per backdrop, each with its own `context`. A pair names only properties in `allTokens` and intrinsic variables, and no two pairs share a foreground, a backdrop, and a context.
 
 ```svelte
 <script module lang="ts">
@@ -224,7 +225,7 @@ registerComponent({
 });
 ```
 
-Import the module from `src/main.ts`, before `bootLiveTokens` or `mount`, and name it as `registrySetup` in `live-tokens.testing.ts`. One module then serves the running app and `check-component --tests`, which imports it to see the registration without mounting the app. The component's contract, one `ComponentContract` in the module `contractsModule` names, is what the eight component suites run; without it `--tests` reports `contract-missing`. Read `references/contract-tests.md` for both. A component that declares intrinsics adds `intrinsics` to the entry. `check-component` finds the registration by the id literal inside the call.
+Import the module from `src/main.ts`, before `bootLiveTokens` or `mount`, and name it as `registrySetup` in `live-tokens.testing.ts`. One module then serves the running app and `check-component --tests`, which imports it to see the registration without mounting the app. The component's contract, one `ComponentContract` in the module `contractsModule` names, is what the eight component suites run; without it `--tests` reports `contract-missing`. Read `references/contract-tests.md` for both. An interactive component's contract declares a keyboard case for each key its WAI-ARIA pattern handles: Enter or Space activates, an arrow key moves where the pattern moves, and Escape closes an overlay. A component that declares intrinsics adds `intrinsics` to the entry. `check-component` finds the registration by the id literal inside the call.
 
 At boot the plugin reads the `:global(:root)` block and writes `component-configs/<id>/default.json`, one token per property. An edit in the editor writes `_working.json`; Save As writes a named config. The assignments stay token references through that flow.
 
@@ -239,7 +240,7 @@ A fixed overlay portals to `<body>`: read `references/fixed-overlays.md`. A cont
 ## Verification
 
 1. Run `npx live-tokens check-component <id> --tests --strict --json`. Inside the live-tokens repository, run `node bin/cli.mjs check-component <id> --tests --strict --json`. It applies every `auto` repair, runs the registry contract and, for a component with a contract in the module `contractsModule` names, the component contract suites, and returns the fixes it applied, the findings that remain, and coverage by rule. `--off=<rule>` silences a rule for one run, and `--no-fix` reports without editing.
-2. Each remaining finding carries a rule id, a line, and its `guidance`. Make each repair from its guidance, and run the command again until it exits 0 with complete applicable coverage and no disabled checks.
+2. Each remaining finding carries a rule id, a line, and its `guidance`. Make each repair from its guidance, and run the command again until it exits 0 with complete applicable coverage and no disabled checks. The `a11y-*` findings report accessibility at `warn`, and `--strict` makes them block with the rest. An `a11y-review` finding marks a check axe could not decide, such as text over a gradient: judge it by eye against its help page, and repair it when it fails. Name the ones that pass in the reply, and add `--off=a11y-review` to the final run, the one disabled check this step allows. Inside the live-tokens repository, an `aria-snapshot` finding marks an accessibility tree that changed since it was recorded; after a deliberate markup change, rerun with `--update-aria`.
 3. Run the project's Svelte check and its build.
 4. Reply with the files, the component id, the props, and the result of each check, naming any check the environment prevented.
 

package/.claude/skills/live-tokens-create-component/references/contract-tests.md

@@ -119,10 +119,10 @@ export const contracts: ComponentContract[] = [
     },
     theme: {
       theme: 'brand',
-      changed: ['--statcard-radius'],
-      unchanged: ['--statcard-padding'],
-      aliasedTo: { '--statcard-radius': '--radius-none' },
-      observe: { part: 'root', css: 'borderRadius', variable: '--statcard-radius' },
+      changed: ['--statcard-surface'],
+      unchanged: ['--statcard-radius', '--statcard-padding'],
+      aliasedTo: { '--statcard-surface': '--surface-neutral' },
+      observe: { part: 'root', css: 'backgroundColor', variable: '--statcard-surface' },
     },
     interaction: { applicable: false, reason: 'a stat card carries no interactive role' },
     sketch: {
@@ -145,18 +145,78 @@ Each obligation and what it needs from the project:
   forces. `applicable: false` when the editor renders no state strip.
 - `persistence`: an edit the run makes through the editor, saves, reloads, and
   reads back. `resetVariable` is a property one of the cases moves.
-- `theme`: a theme in the project's data tree whose block for the component
-  reassigns a property. Save one with the editor before the first run.
-  `changed` names the properties the theme moves, `unchanged` the ones it
-  leaves, and `aliasedTo` the design token each reassigned property resolves
-  to under it.
-- `interaction`: the interactive part's role and its cases. `applicable:
-  false` for a component with no interactive role.
+- `theme`: a saved theme in the project's data tree, previewed as it stands.
+  The run checks that the component follows the theme's design tokens.
+  `changed` names the properties the theme moves through its design tokens,
+  such as colors, shadows, and fonts, `unchanged` the ones it leaves, and `aliasedTo` the design token each
+  changed property resolves to under it. A theme assigns geometry steps only
+  to the components it holds a block for, so a new component's radius,
+  padding, and border width belong in `unchanged`.
+- `interaction`: the interactive part's role and its cases, keyboard cases
+  among them. See Keyboard cases below. `applicable: false` for a component
+  with no interactive role.
+- `boundaries`: optional. The parts that draw a control's visible edge,
+  such as a text field or a switch track, each with a label:
+  `[{ part: 'field', label: 'Field' }]`. The accessibility suite measures
+  each part's border and surface against the backdrop behind it at 3:1, per
+  WCAG 2.2 SC 1.4.11. A component with no control edge leaves it out.
 - `behavior`: what a callback prop does. See Behavior below.
 - `sketch`: a sketch style id and the fill and stroke each reserved-class part
   resolves to under it. `applicable: false` only for a component
   `references/sketch-mode.md` exempts.
 
+## Keyboard cases
+
+An interactive component declares one `press` case for each key its WAI-ARIA
+pattern handles: Enter or Space activates, an arrow key moves focus or value
+where the pattern moves it, and Escape closes an overlay. Each sets
+`rule: 'a11y-keyboard'`. A failed keyboard case reports `a11y-keyboard` at
+`warn` and lets the test pass; a case without `rule` fails as
+`contract-interaction`, an error.
+
+```ts
+interaction: {
+  part: 'secondTab',
+  role: 'button',
+  cases: [
+    {
+      name: 'Enter activates a tab',
+      rule: 'a11y-keyboard',
+      action: { kind: 'press', part: 'secondTab', key: 'Enter' },
+      expect: { kind: 'activated', part: 'secondTab' },
+    },
+    {
+      name: 'arrow right moves focus to the next tab',
+      rule: 'a11y-keyboard',
+      action: { kind: 'press', part: 'firstTab', key: 'ArrowRight' },
+      expect: { kind: 'focused', part: 'secondTab', value: true },
+    },
+  ],
+},
+```
+
+- `press` focuses `part` and sends `key`. Without `part`, the key goes to the
+  element that holds focus, such as an overlay that focused itself as it
+  opened.
+- `activated` passes when the key fired a click on the part, as a native
+  button does for Enter and Space. The preview never feeds a controlled
+  component's callback back into its props, so a click is the activation it
+  shows.
+- `focused` with `value: true` names the part an arrow key moves focus to.
+  Arrow cases need parts that keep their position as the selection moves,
+  such as `firstTab` and `secondTab`.
+- `present` with `value: false` passes when the part has left the document,
+  as a dialog's root does when Escape closes it:
+  `{ kind: 'present', part: 'root', value: false }`.
+
+The accessibility suite reads the same contract. It scans every view that
+`properties` and `states` name with axe and Siteimprove Alfa's rule SIA-R65,
+measures focus indicators and the `boundaries` parts at 3:1, checks text
+spacing and reduced motion, and reports each failure at `warn` under an
+`a11y-*` rule. Mark placeholder
+content the editor adds to its preview, such as a demo label, with
+`data-preview-demo`, and the scans skip it.
+
 ## Behavior
 
 `behavior` runs under Vitest with `mount` from Svelte and happy-dom, not in

package/CHANGELOG.md

@@ -1,5 +1,314 @@
 # Changelog
 
+## 0.98.2 — Accessibility testing
+
+The v0.98.0 and v0.98.1 tags never reached npm. Release checks stopped both:
+a test time limit and a rule count the accessibility suite outgrew.
+
+### Added
+
+- **`check-component --tests` scans components for accessibility.** A new
+  suite opens every variant and state a component's contract names and runs
+  axe-core against WCAG 2 A and AA and Siteimprove Alfa's focus-visibility
+  rule SIA-R65 over the preview. Findings report as `a11y-component`,
+  `a11y-focus-visible`, and `a11y-review`, the last for checks axe could not
+  decide, such as text over a gradient. Editor demo content marked
+  `data-preview-demo` stays out of the scan. The library's own test run
+  repeats axe's contrast rule under the eight preset themes.
+- **`check-page --tests` scans pages for accessibility.** Each page and
+  viewport gains three tests. `page-a11y` runs axe outside the shipped
+  components, with contrast left to `page-contrast`. `page-text-spacing`
+  reports overflow the WCAG 2.2 SC 1.4.12 text spacing override adds.
+  `page-reduced-motion` reports animations still running 200 ms after load
+  under `prefers-reduced-motion: reduce`. They report as `a11y-page`,
+  `a11y-review`, `a11y-text-spacing`, and `a11y-reduced-motion`.
+- **Accessibility findings alert by default.** All seven `a11y-*` rules
+  report at `warn`, and `--strict` makes them errors, as it does every other
+  warning. `--off` and `live-tokens.config.json` silence or raise each one.
+  A scan that crashes reports `tests-setup`.
+- **Each shipped component's accessibility tree is recorded.** The trees
+  live in `src/testing/contracts/__aria__/<id>.yml`, one block per view. A
+  run that reads a different tree reports `a11y-component` with engine rule
+  `aria-snapshot`, and `check-component --tests --update-aria` records the
+  trees anew after a deliberate markup change. A project's own components
+  get no recorded tree yet.
+- **Component contracts take keyboard cases.** An `InteractionCase` with
+  `rule: 'a11y-keyboard'` reports its failure as an `a11y-keyboard` warning
+  and lets the test pass. A `press` action may omit `part`
+  to send the key to whatever holds focus. `InteractionOutcome` gains
+  `activated`, for a key that fired a click on the part, and `present`, for
+  whether the part is in the document. The fifteen interactive shipped
+  components carry 27 keyboard cases for activation, arrow movement, and
+  Escape.
+- **The accessibility engines ship as optional peers.** `axe-core` 4.11.1 or
+  later, `@axe-core/playwright`, and seven `@siteimprove/alfa-*` packages at
+  0.119 join `peerDependencies` as optional, and the `create` template
+  installs them. Without one, the tests it drives report as inapplicable and
+  the run carries on.
+- **The editor gains an Accessibility view.** Run test checks every
+  component in the open theme as saved, in about three and a half minutes,
+  and lists each component's findings by repair. An overview opens the
+  report with the total, the count in each repair group, and a table of every
+  component with a finding, whose names scroll to their sections. Each
+  section's **Open component** opens the component's page at its
+  accessibility panel. "Fix with a property" holds
+  the colour pairs the editor's contrast checker finds below their floor and
+  the focus rings and control boundaries below 3:1. "Fix in the component's
+  code" holds every other finding: axe failures, unchanged focus styles,
+  failed keyboard cases, clipped text, and motion that ignores reduced
+  motion. Results to check by eye count in the totals and collect in one
+  closed list. Findings that share an engine rule, a help text, and their
+  traced properties merge into one row that names its element count and
+  views, and each traced property gets a "→". A row's right-hand link opens
+  the rule, success criterion, technique, or pattern the finding cites and
+  names its kind. A property's label leads with
+  the words from its variable name that the editor's label leaves out, such
+  as "Focused border color". With edits pending, Run test asks for a save and
+  starts nothing. A missing test tool shows its install command. The dev
+  server runs one check at a time and keeps the last report in
+  `test-results/live-tokens/a11y-report.json`.
+- **The editor marks the components the last run named.** Every finding
+  marks its component, results to check by eye included. The component list
+  leads each one's name with a warning triangle, in the sidebar, the narrow
+  menu, and the standalone component page. A condensed list shows the
+  triangle on the component's icon. Each one's page opens with a panel under its
+  title that lists its findings in three groups: "Fix with a property", "Fix
+  in the component's code", and "Check by eye". Each "→" in the panel opens
+  the tab holding the property, an intrinsic's hover tab included, and
+  highlights its row. The marks follow the last finished run; the contrast
+  readout on each colour row stays live.
+- **Property rows carry the run's findings.** A row whose property a finding
+  traces to shows a warning triangle beside its label, or a grey "?" when
+  every finding on it is a result to check by eye. The mark opens a popover that lists the
+  findings with their elements, views, help pages, and traced properties.
+  Token selectors, gradient editors, and toggle rows carry it. The editor's own
+  contrast failures add no row mark, because the live readout already shows
+  them.
+- **Accessibility findings name the properties that fix them.** The
+  component suite reads the CSS rules that match each failing element
+  through the Chrome DevTools protocol and follows each `var()` to the
+  component's semantic properties and intrinsics. `check-component --tests
+  --json` lists them, sorted, in each finding's `details.variables`, and
+  leaves the field out when the trace finds nothing. The field is additive.
+- **The component suite runs four more checks.** Focus indicator contrast
+  and control boundary contrast measure a focus ring and a control's edge at
+  3:1 against the backdrop, under WCAG 2.2 SC 1.4.11. Text spacing applies
+  the WCAG 2.2 SC 1.4.12 override inside each component and reports text
+  that clips under it. Reduced motion reports motion longer than 200 ms that
+  still runs under `prefers-reduced-motion: reduce`, after WCAG technique
+  C39 for SC 2.3.3. The results are warnings under the existing rules:
+  `a11y-component` (engine rules `focus-indicator-contrast` and
+  `control-boundary-contrast`), `a11y-review` for a ring or edge over a
+  gradient or image, `a11y-text-spacing`, and `a11y-reduced-motion`, which
+  `check-component` now reports too. `--strict` raises them with the rest.
+- **Component contracts take `boundaries`.** The optional field,
+  `{ part: string; label: string }[]`, lists the parts that draw a control's
+  visible edge, for the control boundary check. Input, RadioButton, Slider,
+  Toggle, and SegmentedControl declare it.
+- **Selected states join the control boundary check.** TabBar's selected
+  tab, SegmentedControl's selected option, and SideNavigation's selected
+  title, section, item, and footer show their state by surface and edge
+  alone, so their contracts list them in `boundaries`. Each measures against
+  the bar or panel behind it. A `boundaries` entry takes `when`, a selector
+  the part must also match, and the check reads an outline and every border
+  side and keeps the best. The trace follows only the winning declaration of
+  a private property, so a selected tab's finding names the selected tab's
+  properties alone.
+- **Image Lightbox's editor sets the tile fit.** The Tile tab gains a "tile
+  fit" row, Contain or Cover, which writes `--imagelightbox-tile-object-fit`
+  and carries the accessibility mark. ImageLightbox's `fit` prop no longer
+  defaults to `contain` on every tile, so a tile without it follows the
+  theme's value.
+- **`check-component --tests` takes `--a11y` and `--open-theme`.** `--a11y`
+  runs the accessibility suite and the keyboard cases alone, with no static
+  checks or fixes, and reports only `a11y-*` and `tests-*` findings.
+  `--open-theme` tests the theme the editor has open, as saved, and still
+  leaves every unsaved buffer out of the run.
+- **`--json` output names the tested theme and each finding's component.**
+  `check-component --tests --json` adds a top-level `theme`, and each
+  Playwright finding that names a component carries it in a `component`
+  field. Both fields are additive.
+- **The guide gains an Accessibility chapter.** It covers the suites, the
+  rules, the focus indicator, boundary, text spacing, and motion checks,
+  property tracing, review findings, the recorded trees, keyboard cases,
+  `boundaries`, the Accessibility view, the marks in the editor, the
+  engines, and the limits.
+- **The skills cover accessibility.** `live-tokens-check-compliance` lists
+  the `a11y-*` findings as alerts for the user to review.
+  `live-tokens-create-component` declares keyboard cases for a new component
+  and judges `a11y-review` findings by eye.
+- **Component editors show the contrast ratio of every foreground color.** A
+  color row whose variable paints text, an icon or another foreground mark
+  shows the WCAG ratio between that color and the layers behind it, down to the
+  page background. A pair below its floor turns amber and gains an exclamation
+  mark. Click the ratio to open the rule it tracks, each pair's measured ratio
+  and layers, and a link to the success criterion. A disabled state shows its
+  ratio in a dimmer gray, because WCAG exempts disabled controls. The readout
+  recomputes after every edit and theme load, and the rows keep their places.
+- **Editor modules and `registerComponent()` take `contrastPairs`.** Each pair
+  names a foreground variable, the variables that paint behind it top first, its
+  role (`text` or `non-text`), and for text its font size and weight. A pair
+  for a disabled state sets `inactive`. A foreground over several backdrops
+  takes one pair per backdrop, each with a `context`, and the readout shows the
+  pair closest to failing.
+- **`UITokenSelector` takes a `metaAfter` snippet.** It renders after the value
+  name in the same column, and the value name truncates first.
+
+### Changed
+
+- **Button's catalogue entry covers navigation.** A Button is a labelled
+  trigger that runs an action or opens another page, such as View details.
+  An anchor stays the choice for a link inside running text.
+
+### Fixed
+
+- **Check reports reach a pipe whole.** On macOS, `check-component` and
+  `check-page` cut piped output at 64 KiB, because the process exited before
+  the pipe drained. Both checkers now write their report synchronously, so
+  `--json` output read through a pipe parses.
+- **`page-overflow` passes a component inside a scrolling ancestor.** The
+  check reported a component as clipped by the nearest ancestor with any
+  overflow other than `visible`, so a Badge at the end of a Table row on a
+  phone failed against the Table's own `overflow-x: auto` wrapper. An
+  ancestor that scrolls sideways now keeps the component in reach, and only
+  one that hides overflow without scrolling clips it.
+- **The theme contract example tests adherence to a saved theme.** The
+  example in `live-tokens-create-component`'s `references/contract-tests.md`
+  expected a theme to move a new component's radius, which only a theme block
+  for that component can do, and told the agent to save one first. The
+  example now expects the theme to move a color property through its design
+  tokens and lists the component's radius and padding as unchanged.
+- **TabBar follows the WAI-ARIA tabs pattern.** The bar is a `tablist` of
+  `tab` elements that carry `aria-selected`. Tab reaches the selected tab
+  alone, the arrow keys move focus between enabled tabs and wrap, Home and
+  End jump to the first and last, and Enter or Space selects.
+- **TabBar's selected indicator meets 3:1.** `--tabbar-selected-border` maps
+  to `--border-brand-medium` in place of `--color-brand-500`, which lifts the
+  underline from 2.96:1 to 3.47:1 against the default theme's page.
+- **SegmentedControl follows the WAI-ARIA radio group pattern.** Tab reaches
+  the checked option alone, and the arrow keys move focus and selection to
+  the next or previous enabled option and wrap. A focused option shows a ring
+  outside its box in `--border-neutral-strong`, so focus on the selected
+  option reads apart from its brand outline.
+- **SegmentedControl's selected outline meets 3:1.**
+  `--segmentedcontrol-selected-border` maps to `--border-brand-medium` in
+  place of `--border-brand`, which lifts the outline from 2.67:1 to 4.31:1
+  against the default theme's bar.
+- **Control edges meet 3:1.** Input's field, RadioButton's circle in every
+  state, SegmentedControl's bar, Slider's track at both variants and Toggle's
+  track now draw their edge in `--border-neutral-medium`, in place of
+  `--border-neutral` (`--border-neutral-subtle` for Slider). Toggle's on
+  track and Slider's thumbs draw `--border-brand-medium` in place of
+  `--border-brand`. Against the default theme's page the neutral edges rise
+  from 2.42:1 to 3.97:1, Slider's track from 1.45:1, and Toggle's on track
+  from 2.14:1 to 3.47:1. Slider's focus ring, drawn in the thumb's border
+  colour, rises from 2.14:1 to 3.47:1.
+- **The preset themes carry the 3:1 control edges.** Each preset holds its
+  own copy of the component mappings, so the eight presets now carry the new
+  edges above and TabBar's and SegmentedControl's selected borders. In
+  autumn, ocean, royal-velvet, sketchy and spring-meadow every control edge
+  and selected indicator now measures 3:1 or more, where autumn's Slider
+  track measured 1.4:1 and its selected tab 2.47:1. Halloween,
+  midnight-study and sunset paint a gradient page, so their edges stay a
+  check by eye.
+- **VideoFrame, VideoLightbox and SlidePager draw a focus ring at 3:1.** The
+  trigger, the close button, the stage and the pager controls drew
+  `--ring-focus-md`, a brand colour at 10% opacity that measured 1.06:1 to
+  1.09:1. Each now draws the neutral ring SegmentedControl uses, a
+  `--border-width-2` box shadow in `--border-neutral-strong`.
+- **Badge, CornerBadge and Notification text meets 4.5:1.** The brand and
+  danger badges, and Notification's danger variant, sit on the next lower
+  surface step, `--surface-brand-low` and `--surface-danger-low`, which lifts
+  their text from 3.87:1 to 5.38:1 and from 3.30:1 to 4.56:1 on the default
+  theme. The canvas badges keep `--surface-canvas` and take
+  `--text-secondary`, since no canvas text step reaches 4.5:1 on a canvas
+  surface; they rise from 1.55:1 to 7.15:1. The eight presets carry the same
+  mappings, and under each of them axe reports no `color-contrast` failure
+  on the three components.
+- **Input shows focus in its error state.** The red error outline replaced
+  the focus outline, so focusing an invalid field changed nothing visible.
+  Focus now adds a `--border-neutral-strong` ring outside the red outline.
+- **Slider's thumbs take the pointer over 24px.** Each native thumb and its
+  input now measure `max(thumb size, --space-24)`, the WCAG 2.2 SC 2.5.8
+  minimum, while the visible cap keeps its own size. axe reported both range
+  thumbs under `target-size`, because their inputs share one box.
+- **RadioButton follows the WAI-ARIA radio group pattern.** Each option is a
+  `radio` with `aria-checked`. Tab reaches the checked option alone, and the
+  arrow keys move focus and selection to the next or previous option and
+  wrap. A group is the nearest `role="radiogroup"` ancestor, else the parent
+  the options share; wrap a set in a `radiogroup` with a name.
+- **TabBar's icon-only tabs carry a name.** With `iconOnly` set, each tab
+  takes its `label` as `aria-label`, and the icon is hidden from assistive
+  technology.
+- **CodeSnippet's code line takes keyboard focus.** A long snippet scrolls
+  sideways, so the code element now sits in the tab order and shows the
+  neutral focus ring, and the arrow keys scroll it.
+- **MenuSelect follows the WAI-ARIA listbox pattern.** The list items carry
+  `role="none"`, so each option sits directly in the listbox or menu. Tab
+  reaches the selected option alone, Up and Down move focus between enabled
+  options and wrap, and Home and End jump to the ends. A new optional
+  `ariaLabel` prop names the list; pass the text of the Button that opens
+  it.
+- **Dialog follows the WAI-ARIA dialog pattern.** The panel is a `dialog`
+  named by its title, and `aria-modal` outside the inline preview. Escape
+  takes the cancel path: it calls `cancel.onClick` when a cancel button is
+  set, else `onclose`, as the close icon does.
+- **Button's shimmer stops under reduced motion.** With
+  `prefers-reduced-motion: reduce`, the 500 ms sweep across a hovered
+  Button no longer draws. The `--button-shimmer` switch is unchanged.
+- **Image's hover zoom jumps under reduced motion.** With
+  `prefers-reduced-motion: reduce`, the zoom and grow transforms apply at
+  once in place of the 300 ms transition.
+- **Progress Bar's fill moves at once under reduced motion.** With
+  `prefers-reduced-motion: reduce`, the fill takes its new width without the
+  400 ms transition.
+- **Image Lightbox's tile holds still under reduced motion.** With
+  `prefers-reduced-motion: reduce`, the hovered tile scales without its
+  250 ms transition, as the lightbox's own open and close animations already
+  did.
+- **Dialog holds focus while it is open.** Outside the inline preview,
+  opening the dialog moves focus to its confirm, cancel or close button,
+  else its first focusable element, else the panel. Tab and Shift+Tab cycle
+  inside the panel, and closing returns focus to the element that held it
+  before. Image Lightbox's Tab handling now shares the same helper.
+
+## 0.97.0 — Custom colors
+
+### Added
+
+- **Every color picker offers custom colors.** A **Custom** row after Danger
+  lists the open theme's own colors, `--color-custom-1`, `--color-custom-2`
+  and so on, each holding one OKLCH value for light and dark. The row's
+  plus swatch starts a new color from the slot's current color and opens
+  the OKLCH editor; confirm assigns it to the slot in one undo step, and
+  cancel removes it. A slot picks an existing custom color as it picks a
+  palette step, opacity included. The pencil on a custom swatch edits it in
+  place, and the edit moves every slot that names it. The Tokens view gains a
+  **Custom Colours** section that lists, edits and removes them. Removing a
+  color that a component property, gradient stop or wash names first asks
+  for a replacement, preselects the nearest token, and rewrites each
+  reference with its opacity intact, all in one undo step.
+- **Themes carry an optional `customColors` field.**
+  `ColorsAndType.customColors` sits beside `gradients` and holds
+  `{ variable, color }` entries. The field is additive: a theme without it
+  loads with no custom colors, `THEME_SCHEMA_VERSION` stays 5, and no
+  migration runs. Save, export and import keep the list, and Adopt writes
+  each custom color into `tokens.generated.css` with the theme's other
+  variables. `set-colors` and `save-theme` carry the field through
+  unchanged. `tokens.css` and the shipped themes declare no custom color, so
+  `check-page` reports `unknown-token` for page CSS that names
+  `var(--color-custom-1)`; reach a custom color through a component property.
+
+## 0.96.1 — Vitest 5 peer range
+
+### Fixed
+
+- **Installs alongside Vitest 5.** The optional `vitest` peer range now reads
+  `^4.0 || ^5.0`. With `^4.0` alone, npm stopped any install that re-resolved
+  the tree with `ERESOLVE` once Vitest 5 sat anywhere in it, including as an
+  uninstalled optional peer of Vite's devtools. The `testing` contract helpers
+  pass the full suite on Vitest 5.
+
 ## 0.96.0 — Lightbox zoom readout in natural pixels
 
 ### Changed

package/README.md

@@ -326,8 +326,8 @@ npx @motion-proto/live-tokens <command>
 | `components [id] [--json]` | List every component the project has, shipped and its own, with the props each takes; with an id, its props, variants, tokens, and defaults. |
 | `tokens [--scale <name>] [--json]` | List every design token the project's `tokens.css` declares, by scale, with its value. |
 | `report [--json]` | The project as facts: pending migrations, tokens each component reads, which page renders which component, and both checkers' findings by rule. Always exits 0. |
-| `check-component [id]` | Validate a component's runtime, editor, and registration against the authoring contract; with no id, every component authored under `src/system/components`. |
-| `check-page [paths...]` | Validate pages against the create-page contract: catalogue components and their props, theme tokens over literals, route wiring. |
+| `check-component [id] [--tests] [--update-aria] [--a11y] [--open-theme]` | Validate a component's runtime, editor, and registration against the authoring contract; with no id, every component authored under `src/system/components`. `--tests` also runs the contract suites, the accessibility scans among them; `--update-aria` records each scanned component's accessibility tree anew after a deliberate markup change; `--a11y` runs the accessibility scans and keyboard cases alone; `--open-theme` tests the theme the editor has open, as saved. |
+| `check-page [paths...] [--tests]` | Validate pages against the create-page contract: catalogue components and their props, theme tokens over literals, route wiring. `--tests` also opens each page in the app and checks its rendered paint, contrast, layout, and accessibility. |
 | `set-colors <base-colors.json> [--dry-run]` | Build the theme's whole color identity from 10 OKLCH base colors, enforce AA contrast on the derived text tokens, and write the result to the unsaved colors-and-type buffer. |
 | `set-type <pairing.json> [--dry-run] [--no-verify]` | Bind Google Fonts families to the theme's font stacks, verified against the API. |
 | `set-geometry <ops.json> [--dry-run]` | Move radius, padding, gap, and border-width aliases along their token scales. |

package/bin/check-component.mjs

@@ -33,6 +33,7 @@ import {
   extractGlobalRootBlocks,
   loadVocabulary,
 } from './lib/tokenVocabulary.mjs';
+import * as a11y from './rules/a11y.mjs';
 import * as componentStructure from './rules/componentStructure.mjs';
 import * as importsAndRoutes from './rules/importsAndRoutes.mjs';
 import * as testRuns from './rules/testRuns.mjs';
@@ -83,6 +84,12 @@ export const COMPONENT_RULES = assembleRules(
     'contract-listed',
     'contract-sketch',
     'contract-missing',
+    'a11y-component',
+    'a11y-review',
+    'a11y-focus-visible',
+    'a11y-keyboard',
+    'a11y-text-spacing',
+    'a11y-reduced-motion',
     'tests-not-installed',
     'tests-setup',
     'tests-incomplete',
@@ -91,6 +98,7 @@ export const COMPONENT_RULES = assembleRules(
   tokenRules.componentRules,
   importsAndRoutes.componentRules,
   testRuns.componentRules,
+  a11y.componentRules,
 );
 
 function capitalize(id) {

package/bin/check-page.mjs

@@ -16,6 +16,7 @@ import { assembleRules, isExcluded, lineOf } from './lib/findings.mjs';
 import { codeRegion, inlineStyleRegions, styleRegions } from './lib/pageSource.mjs';
 import { loadVocabulary, walk } from './lib/tokenVocabulary.mjs';
 import { resolveTokensCssPath } from './migrate.mjs';
+import * as a11y from './rules/a11y.mjs';
 import * as componentUse from './rules/componentUse.mjs';
 import * as importsAndRoutes from './rules/importsAndRoutes.mjs';
 import * as testRuns from './rules/testRuns.mjs';
@@ -49,6 +50,10 @@ export const PAGE_RULES = assembleRules(
     'page-contrast',
     'page-grid',
     'page-overflow',
+    'a11y-page',
+    'a11y-review',
+    'a11y-text-spacing',
+    'a11y-reduced-motion',
     'tests-not-installed',
     'tests-setup',
     'tests-incomplete',
@@ -57,6 +62,7 @@ export const PAGE_RULES = assembleRules(
   importsAndRoutes.pageRules,
   tokenRules.pageRules,
   testRuns.pageRules,
+  a11y.pageRules,
 );
 
 // Directories that hold the system, not pages built on it.

package/bin/cli.mjs

@@ -80,7 +80,7 @@ Commands:
                               renders which component, and both checkers'
                               findings by rule under the project's severities
                               and under --strict. Always exits 0
-  check-component [id] [--tests]
+  check-component [id] [--tests] [--update-aria] [--a11y] [--open-theme]
                               Validate <id>'s runtime, editor, and registration
                               against the live-tokens-create-component contract.
                               --tests also runs the registry contract under
@@ -88,7 +88,16 @@ Commands:
                               Playwright, reporting coverage by rule. Needs
                               @playwright/test, vitest, and happy-dom; a
                               missing one is a tests-not-installed finding
-                              naming the install command
+                              naming the install command. --update-aria
+                              records each component's accessibility tree
+                              anew, after a deliberate markup change.
+                              --a11y runs the accessibility checks alone: the
+                              accessibility suite and the keyboard cases,
+                              with no static checks or fixes, reporting only
+                              a11y-* and tests-* findings. --open-theme tests
+                              the theme the editor has loaded, as saved; the
+                              buffer stays out of the run. Both need --tests.
+                              --json names the tested theme under "theme"
   check-page [paths...] [--tests]
                               Validate pages against the live-tokens-create-page
                               contract: catalogue components only, and every CSS
@@ -222,13 +231,13 @@ if (command === 'create') {
   }
 }
 
-function reportChecks(label, findings, checked, rules, opts, { coverage, hardFailure, exclude, fix } = {}) {
+function reportChecks(label, findings, checked, rules, opts, { coverage, hardFailure, exclude, fix, theme } = {}) {
   const checksConfig = readChecksConfig(process.cwd());
   const resolved = applySeverity(findings, rules, opts, checksConfig, { exclude });
   const resolvedCoverage = coverage ? applyCoverageSeverity(coverage, rules, opts, checksConfig) : coverage;
-  console.log(
+  writeOut(
     opts.json
-      ? toJson(resolved, { label, checked, coverage: resolvedCoverage, fix })
+      ? toJson(resolved, { label, checked, coverage: resolvedCoverage, fix, theme })
       : [fix ? formatFixes(fix) : '', formatFindings(resolved, { label, checked })].filter(Boolean).join('\n'),
   );
   // Decision 2: a missing tool or a setup failure under --tests is an error
@@ -319,7 +328,23 @@ if (command === 'report') {
 
 if (command === 'check-component') {
   const opts = parseCheckFlags(rest);
+  if ((opts.a11y || opts.openTheme) && !opts.tests) fail('--a11y and --open-theme run with --tests.');
   const ids = opts.rest.length > 0 ? [opts.rest[0]] : discoverComponents();
+  if (opts.a11y) {
+    const { hasHardFailure, runContractTests } = await import('./contractRunner.mjs');
+    const outcome = await runContractTests(opts.rest[0], {
+      root: process.cwd(),
+      updateAria: opts.updateAria,
+      a11y: true,
+      openTheme: opts.openTheme,
+    });
+    const label = `check-component${ids.length === 1 ? ` ${ids[0]}` : ''} --tests --a11y`;
+    reportChecks(label, outcome.findings, Math.max(ids.length, 1), COMPONENT_RULES, opts, {
+      coverage: outcome.coverage,
+      hardFailure: hasHardFailure(outcome.findings),
+      theme: outcome.theme,
+    });
+  }
   if (ids.length === 0 && !opts.tests) {
     console.log('✓ check-component: no component authored under src/system/components yet.');
     process.exit(0);
@@ -342,12 +367,17 @@ if (command === 'check-component') {
     reportChecks(label, [...migration.findings, ...results.flatMap(([, r]) => r.findings)], ids.length, COMPONENT_RULES, opts, { fix });
   }
   const { hasHardFailure, runContractTests } = await import('./contractRunner.mjs');
-  const testOutcome = await runContractTests(opts.rest[0], { root: process.cwd() });
+  const testOutcome = await runContractTests(opts.rest[0], {
+    root: process.cwd(),
+    updateAria: opts.updateAria,
+    openTheme: opts.openTheme,
+  });
   const findings = dedupeAliasFindings([...migration.findings, ...results.flatMap(([, r]) => r.findings), ...testOutcome.findings]);
   reportChecks(label, findings, Math.max(ids.length, 1), COMPONENT_RULES, opts, {
     fix,
     coverage: testOutcome.coverage,
     hardFailure: hasHardFailure(testOutcome.findings),
+    theme: testOutcome.theme,
   });
 }