@motion-proto/live-tokens 0.98.2 → 0.99.0

package/src/editor/core/a11y/a11yReport.ts

@@ -1,6 +1,15 @@
-import { derived, writable, type Readable } from 'svelte/store';
+import { derived, get, writable, type Readable } from 'svelte/store';
 import { API_BASE } from '../storage/apiBase';
-import type { A11yContrastFailure, A11yFinding, A11yFinishedReport, A11yReport } from './a11yReportTypes';
+import { openThemeSlug } from '../store/editorConfigStore';
+import type {
+  A11yContrastFailure,
+  A11yFailedReport,
+  A11yFinding,
+  A11yFinishedReport,
+  A11yReport,
+  A11yReportState,
+  A11yRunningReport,
+} from './a11yReportTypes';
 
 /** One component's share of the last finished run, sorted by its fix (decision 6). */
 export interface ComponentA11yIssues {
@@ -10,44 +19,73 @@ export interface ComponentA11yIssues {
   property: A11yFinding[];
   /** Fix in the component's code: every other `a11y-*` finding but `a11y-review`. */
   code: A11yFinding[];
-  /** Check by eye. */
+  /** Check by eye, unmarked. */
   review: A11yFinding[];
+  /** Check by eye, marked as looking right. They count as no issue. */
+  confirmed: A11yFinding[];
+  /** Contrast failures of the run that pass as the editor now measures them. They count as no issue. */
+  fixed: A11yFixedContrast[];
+}
+
+export interface A11yFixedContrast {
+  failure: A11yContrastFailure;
+  /** The ratio the editor measures now. */
+  ratio: number;
 }
 
 /** Engine rules whose failure a property's value fixes. */
 export const PROPERTY_FIX_RULES: ReadonlySet<string> = new Set(['focus-indicator-contrast', 'control-boundary-contrast']);
 
-const latest = writable<A11yReport | null>(null);
-const lastFinished = writable<A11yFinishedReport | null>(null);
+const running = writable<A11yRunningReport | null>(null);
+const failed = writable<A11yFailedReport | null>(null);
+const reports = writable<Record<string, A11yFinishedReport>>({});
+const fixedRatios = writable<ReadonlyMap<A11yContrastFailure, number>>(new Map());
 let heard = false;
 
-/** The dev server's latest word: a run going, finished or failed. */
-export const a11yReport: Readable<A11yReport | null> = { subscribe: latest.subscribe };
+/** The dev server's latest word for the open theme: a run going (for any theme, since one runs at a time), a failed run, or the theme's last finished report. */
+export const a11yReport: Readable<A11yReport | null> = derived(
+  [running, failed, reports, openThemeSlug],
+  ([$running, $failed, $reports, $open]) => $running ?? ($failed?.theme === $open ? $failed : null) ?? $reports[$open] ?? null,
+);
 
-/** The last run that finished, which the markers follow while a new run goes (decision 7). */
-export const a11yFinishedReport: Readable<A11yFinishedReport | null> = { subscribe: lastFinished.subscribe };
+/** The open theme's last finished run, which the markers follow while a new run goes (decision 7). */
+export const a11yFinishedReport: Readable<A11yFinishedReport | null> = derived(
+  [reports, openThemeSlug],
+  ([$reports, $open]) => $reports[$open] ?? null,
+);
+
+/** Sets the run's contrast failures that pass now, with the ratio each measures. `contrastFixes` measures them. */
+export function setFixedContrast(ratios: ReadonlyMap<A11yContrastFailure, number>): void {
+  fixedRatios.set(ratios);
+}
 
-export const a11yIssues: Readable<Record<string, ComponentA11yIssues>> = derived(lastFinished, ($report) => {
+export const a11yIssues: Readable<Record<string, ComponentA11yIssues>> = derived([a11yFinishedReport, fixedRatios], ([$report, $fixed]) => {
   const out: Record<string, ComponentA11yIssues> = {};
   if (!$report) return out;
-  const entry = (id: string) => (out[id] ??= { contrast: [], property: [], code: [], review: [] });
-  for (const failure of $report.contrast) entry(failure.component).contrast.push(failure);
+  const confirmed = new Set($report.confirmed);
+  const entry = (id: string) => (out[id] ??= { contrast: [], property: [], code: [], review: [], confirmed: [], fixed: [] });
+  for (const failure of $report.contrast) {
+    const ratio = $fixed.get(failure);
+    if (ratio === undefined) entry(failure.component).contrast.push(failure);
+    else entry(failure.component).fixed.push({ failure, ratio });
+  }
   for (const finding of $report.findings) {
     if (!finding.component || !finding.rule.startsWith('a11y-')) continue;
     const issues = entry(finding.component);
     const group = finding.rule === 'a11y-review'
-      ? issues.review
+      ? (confirmed.has(finding.message) ? issues.confirmed : issues.review)
       : PROPERTY_FIX_RULES.has(finding.details?.engineRule ?? '') ? issues.property : issues.code;
     group.push(finding);
   }
   return out;
 });
 
-/** The run's findings under each component property they trace to (decision 7). The editor's contrast failures stay out. */
-export const a11yPropertyFindings: Readable<Map<string, A11yFinding[]>> = derived(lastFinished, ($report) => {
+/** The run's findings under each component property they trace to (decision 7). The editor's contrast failures and the results marked as looking right stay out. */
+export const a11yPropertyFindings: Readable<Map<string, A11yFinding[]>> = derived(a11yFinishedReport, ($report) => {
   const out = new Map<string, A11yFinding[]>();
+  const confirmed = new Set($report?.confirmed);
   for (const finding of $report?.findings ?? []) {
-    if (!finding.component || !finding.rule.startsWith('a11y-')) continue;
+    if (!finding.component || !finding.rule.startsWith('a11y-') || confirmed.has(finding.message)) continue;
     for (const variable of finding.details?.variables ?? []) {
       const list = out.get(variable);
       if (list) list.push(finding);
@@ -59,16 +97,23 @@ export const a11yPropertyFindings: Readable<Map<string, A11yFinding[]>> = derive
 
 export function receiveA11yReport(report: A11yReport): void {
   heard = true;
-  latest.set(report);
-  if (report.state === 'finished') lastFinished.set(report);
+  if (report.state === 'running') {
+    running.set(report);
+    failed.set(null);
+    return;
+  }
+  running.set(null);
+  if (report.state === 'failed') failed.set(report);
+  else reports.update(($reports) => ({ ...$reports, [report.theme]: report }));
 }
 
 export async function init(): Promise<void> {
   const res = await fetch(`${API_BASE}/a11y/report`);
   if (!res.ok) return;
-  const { report } = (await res.json()) as { report: A11yReport | null };
+  const state = (await res.json()) as A11yReportState;
   // An event that landed while the read was in flight is the newer word.
-  if (report && !heard) receiveA11yReport(report);
+  reports.update(($reports) => ({ ...state.reports, ...$reports }));
+  if (!heard) running.set(state.running);
 }
 
 /**
@@ -94,8 +139,26 @@ export async function startA11yRun(contrast: A11yContrastFailure[]): Promise<A11
   return report;
 }
 
+/** Marks results to check by eye in the open theme's last report as looking right, or clears the mark. */
+export async function confirmReview(findings: A11yFinding[], confirmed: boolean): Promise<void> {
+  const theme = get(a11yFinishedReport)?.theme;
+  if (!theme) return;
+  const res = await fetch(`${API_BASE}/a11y/confirmed`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ theme, messages: findings.map((f) => f.message), confirmed }),
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as { error?: string };
+    throw new Error(body.error || 'The mark did not save');
+  }
+  receiveA11yReport((await res.json()) as A11yReport);
+}
+
 export function __resetForTests(): void {
   heard = false;
-  latest.set(null);
-  lastFinished.set(null);
+  running.set(null);
+  failed.set(null);
+  reports.set({});
+  fixedRatios.set(new Map());
 }

package/src/editor/core/a11y/a11yReportTypes.ts

@@ -43,6 +43,8 @@ export interface A11yFinding {
 
 interface A11yReportBase {
   startedAt: string;
+  /** The theme the run tests, the one open when it started. */
+  theme: string;
   contrast: A11yContrastFailure[];
 }
 
@@ -54,12 +56,12 @@ export interface A11yRunningReport extends A11yReportBase {
 export interface A11yFinishedReport extends A11yReportBase {
   state: 'finished';
   finishedAt: string;
-  /** Absent when the run stopped before it copied the data tree, as a missing tool stops it. */
-  theme?: string;
   findings: A11yFinding[];
+  /** The messages of the results to check by eye that someone marked as looking right. A new run keeps each one it finds again. */
+  confirmed?: string[];
 }
 
-/** The CLI crashed or printed no report. */
+/** The CLI crashed or printed no report. The theme's last finished report stands. */
 export interface A11yFailedReport extends A11yReportBase {
   state: 'failed';
   finishedAt: string;
@@ -67,3 +69,9 @@ export interface A11yFailedReport extends A11yReportBase {
 }
 
 export type A11yReport = A11yRunningReport | A11yFinishedReport | A11yFailedReport;
+
+/** `GET /a11y/report`: the run going, if any, and each theme's last finished report by theme name. */
+export interface A11yReportState {
+  running: A11yRunningReport | null;
+  reports: Record<string, A11yFinishedReport>;
+}

package/src/editor/core/a11y/contrastFixes.ts

@@ -0,0 +1,41 @@
+import { get } from 'svelte/store';
+import { getContrastPairs } from '../components/contrastPairRegistry';
+import { measurePair, type ContrastPair, type Resolver } from '../palettes/contrastPairs';
+import { createDomResolver } from '../palettes/resolveColor';
+import { editorState } from '../store/editorStore';
+import { THEME_APPLIED_EVENT } from '../themes/themeDocumentSync';
+import { a11yFinishedReport, setFixedContrast } from './a11yReport';
+import type { A11yContrastFailure } from './a11yReportTypes';
+
+function samePair(pair: ContrastPair, failure: A11yContrastFailure): boolean {
+  return pair.role === failure.role
+    && pair.context === failure.context
+    && pair.backdrop.join('\n') === failure.backdrop.join('\n');
+}
+
+/** Each failure whose pair passes now, with the ratio it measures. */
+export function measureFixes(failures: A11yContrastFailure[], resolver: Resolver): Map<A11yContrastFailure, number> {
+  const out = new Map<A11yContrastFailure, number>();
+  for (const failure of failures) {
+    const pair = getContrastPairs(failure.component, failure.variable).find((p) => samePair(p, failure));
+    if (!pair) continue;
+    const measure = measurePair(pair, resolver);
+    if (measure.passes) out.set(failure, measure.ratio);
+  }
+  return out;
+}
+
+/** Re-measures the last run's contrast failures whenever the editor's state or the open theme changes. */
+export function init(): void {
+  let frame = 0;
+  // Measuring reads the DOM, so it waits a frame for the renderer's CSS variables.
+  const schedule = () => {
+    cancelAnimationFrame(frame);
+    frame = requestAnimationFrame(() => {
+      setFixedContrast(measureFixes(get(a11yFinishedReport)?.contrast ?? [], createDomResolver()));
+    });
+  };
+  a11yFinishedReport.subscribe(schedule);
+  editorState.subscribe(schedule);
+  document.addEventListener(THEME_APPLIED_EVENT, schedule);
+}

package/src/editor/core/palettes/contrastPairs.ts

@@ -68,7 +68,10 @@ export function measurePair(pair: ContrastPair, resolver: Resolver): PairMeasure
       pair.fontWeight ? resolver.fontWeight(pair.fontWeight) : NORMAL_WEIGHT,
     );
   const floor = floorFor(pair.role, large);
-  return { pair, ratio, floor, large, passes: pair.inactive === true || ratio >= floor };
+  // A non-text part painted fully transparent, such as an unselected tab's
+  // underline, draws nothing for SC 1.4.11 to measure.
+  const absent = pair.role === 'non-text' && fronts.every((front) => front[3] === 0);
+  return { pair, ratio, floor, large, passes: pair.inactive === true || absent || ratio >= floor };
 }
 
 /** An inactive pair applies no floor, so it ranks only when every pair is inactive. */

package/src/editor/docs/content/accessibility.md

@@ -83,12 +83,19 @@ sibling, such as a slider thumb's cap, counts. The indicator is the outline
 when focus changes one, else the first outer box shadow, else a border side.
 
 The backdrop is every box behind the ring's outer edge, composited in order
-over white. A ring below 3:1 against it reports under `a11y-component` with
+over white. The walk stops at the preview's edge and ends on `--page-bg`, so a
+part that fills its preview edge to edge is measured against the page. A ring below 3:1 against it reports under `a11y-component` with
 engine rule `focus-indicator-contrast`, such as "Focus outline on span.cap
 2.14:1 against the backdrop, needs 3:1". Ratios floor to two places, because
 WCAG does not round. Chromium's own `outline-style: auto` ring passes: it pairs
 a dark band with a light one. An element with no indicator at all is
-SIA-R65's finding and adds none here.
+SIA-R65's finding and adds none here. Alfa reads only the element, its
+descendants, and its ancestors, so a ring this check finds on a sibling settles
+SIA-R65's "can't tell" for that element.
+
+A state view that forces the focused look with a class, such as Input's
+focused state, would leave focus nothing to change. Both focus checks lift
+that class while they measure, then put it back.
 
 ## Control boundary contrast
 
@@ -236,10 +243,19 @@ three and a half minutes. With edits pending, it shows "Save the changes you
 want to have checked." and starts nothing. Save the theme first, so the run
 and the editor read the same values.
 
-Every finding counts, results to check by eye included. An overview opens
-the report. It shows the total, the count in each repair group below, and a
-table of every component with a finding: its count per group and a bar of
-its share. A component's name in the table scrolls to its section.
+Each theme keeps its own report. Opening another theme shows that theme's
+last run, or none if it has never run. The dev server keeps each report in
+`_a11y-reports/` in the data directory, and deleting a theme deletes its
+report. A failed run leaves the theme's last report in place.
+
+The total counts the findings a fix clears. A result to check by eye counts
+apart, because only a person can settle it. An overview opens the report. It
+shows the total, the count in each repair group below, and a table of every
+component with a finding and its count per group. The "Check by eye" figure
+scrolls to the By eye list. The table
+lists first the components with the most findings a property fixes, then those
+with the most a code change fixes. A component's name in the table scrolls to
+its section.
 
 Each component's section heads its count with **Open component**, which opens
 the component's page at its accessibility panel. The section sorts its rows
@@ -251,7 +267,8 @@ by repair:
 - **Fix in the component's code** holds every other finding: axe failures,
   focus styles that SIA-R65 finds unchanged, failed keyboard cases, text that
   clips under the spacing override, and motion that ignores reduced motion.
-- **Check by eye** holds the `a11y-review` results.
+- **Check by eye** holds the `a11y-review` results, each led by an eye. The
+  By eye list gathers them for the whole report.
 
 Findings that share an engine rule, a help text, and their traced properties
 merge into one row. The row names its element, or its element count, and the
@@ -265,15 +282,33 @@ check by eye is grey. The row's links sit beside its text:
   "Rule" for an axe or Alfa rule, "Success criterion" with its number for a
   WCAG criterion, "Technique" for a WCAG technique, and "Pattern" for a
   WAI-ARIA pattern.
+- A result to check by eye has **Looks right** at the row's right edge.
+  Press it once you have judged the element and found it passes. The row's
+  eye turns to a check, its text dims, and it stops counting and stops
+  marking the editor. Press it again to clear the mark. The mark belongs to
+  the open theme's report, and each later run of that theme keeps it while
+  the run finds the same result.
 
 A property's label leads with the words from its variable name that the
 editor's label leaves out, so `--input-focused-border` reads "Focused border
 color" where the editor's row reads "Border color". The contrast rows read
 the same labels.
 
-The overview and the per-component counts include the results to check by
-eye. A component's section ends in a "N results to check by eye" button that
-opens one closed list of those results, merged per component. axe's contrast
+The overview's "Check by eye" column counts the results no one has marked.
+A component whose results all look right leaves the table, the sections, and
+the view's sidebar. A component section lists only issues and fixes, so the
+view's sidebar lists the components with one of those.
+
+The **By eye** list closes the view and holds every result to check by eye,
+merged per component. The results to check come first, under a tally such
+as "2 to check, 18 look right" and a bar that fills as you mark them. Pressing
+**Looks right** moves focus to the result that takes the row's place, so
+Enter or Space walks the list. **Mark all as looking right** marks every
+result still to check in one step. The marked results follow in **Looks
+right**, a group that starts closed and shows their count. Open it to
+revisit them, each with its button pressed, or to clear a mark. A component's
+section with results still to check ends in a link such as "2 results to
+check by eye" that scrolls to the list. axe's contrast
 violations stay out of the report, because the contrast checker measures the
 same pairs.
 
@@ -289,18 +324,25 @@ the `default` theme. Both work from the command line too.
 
 ## Marks in the editor
 
-The last finished run marks the rest of the editor:
+The last finished run marks the rest of the editor. A result marked as
+looking right is acknowledged and marks nothing: no sidebar mark, no panel,
+and no property mark. The By eye list keeps it to revisit.
 
-- The component list leads the name of each component with any finding
-  with a warning triangle. A condensed list shows the triangle on the
+- The component list leads the name of each component with a finding with a
+  warning triangle, or with a grey eye when its only results are unmarked
+  results to check by eye. A condensed list shows the mark on the
   component's icon.
 - That component's page opens with a panel under its title that lists its
-  findings in all three groups, check by eye included.
+  findings in all three groups, check by eye included, and leaves out the
+  results marked as looking right. The panel heads with
+  the triangle and the issue count, or with the eye and the count to check by
+  eye when no issue remains.
 - Each "→" in the panel opens the tab holding the property and highlights
   its row.
 - Each property row a finding traces to carries a mark beside its label: a
-  warning triangle in the highlight colour, or a grey "?" when every finding on the row is a
-  result to check by eye. On a colour or size row the mark sits between the
+  warning triangle in the highlight colour, or a grey eye when every finding
+  on the row is a result to check by eye. A result marked as looking right
+  adds no mark. On a colour or size row the mark sits between the
   label and the value. On a toggle row it follows the label.
 
 Click a row's mark to open its findings: the count, then each merged row
@@ -308,10 +350,17 @@ with its element, its views, its help page, and the properties it traces to. The
 editor's own contrast failures add no row mark, because the contrast readout
 on the colour row already shows them.
 
-The marks and the panel keep the run's time and change when the next run
-finishes. The contrast readout on each colour row stays live and measures
+The marks and the panel keep the run's time and change when the open
+theme's next run finishes. The contrast readout on each colour row stays live and measures
 every edit as you make it.
 
+The editor also re-measures each contrast failure of the run as you edit.
+Once one passes, its row in the panel and in the Accessibility view turns
+green and shows the run's ratio beside the ratio now, such as
+"Fill color 2.66:1 → 5.31:1". A fixed row counts as no issue, so a component
+whose only issues are fixed loses its triangle in the component list. The
+run's other findings change only when the next run finishes.
+
 ## Installing the engines
 
 The engines ship as optional peer dependencies. A project made with `create`

package/src/editor/docs/content/editing-tokens.md

@@ -125,6 +125,10 @@ it. Each edit and each theme load updates it, and the rows keep their places.
   header and the body text on the page, so its popover lists two pairs.
 - **Disabled states.** WCAG exempts disabled controls, so a disabled state's
   ratio shows in a dimmer grey, whatever its value.
+- **Transparent marks.** A mark painted fully transparent, such as an
+  unselected tab's underline, draws nothing, so it meets its floor at any
+  ratio. Transparent text still needs its floor. A decorative line, such as
+  a section divider's hairline, shows no readout.
 - **Page background.** Every stack ends on the page background, `--page-bg`.
   A translucent layer blends into the layers beneath it, and the readout
   measures the blend. A gradient layer counts its worst stop.

package/src/editor/docs/content.generated.ts

@@ -3,9 +3,9 @@
 
 export const docContent: Record<string, string> = {
   "01-overview": "# Overview\n\nLiveTokens is a design system for building Svelte microsites quickly. You\nstyle your site by editing tokens and components in a live editor. When it looks right, you save the theme and ship it.\n\n## How it works\n\n- The editor runs in your dev server, on top of your real pages. You style in\n  context, not in a separate sandbox.\n- Every change updates a CSS variable, so the page repaints instantly. No\n  reload, no build step.\n- Saving writes a small JSON file into your project. Shipping bakes your chosen\n  theme into a plain CSS file that the build bundles.\n- The editor is dev-only. Production ships plain CSS variables and the\n  components you used, nothing else.\n\n## What you can edit\n\n- **Tokens**: the design-system primitives, colour palettes, type, spacing,\n  radius, shadow, and gradients, that apply across your whole site.\n- **Components**: the package ships about 25 editable components (Button,\n  IconButton, Card, Dialog, Table, and more). You style components by changing\n  the tokens assigned to each property.\n\n## Where to go next\n\n- **[Getting started](getting-started.md)**: scaffold a project and make your\n  first edit.\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Sketch mode](sketch-mode.md)**: redraw the page by hand.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own components\n  editable.\n",
-  "accessibility": "# Accessibility\n\n`check-component --tests` and `check-page --tests` test the shipped\ncomponents, your own components, and your pages against WCAG 2 A and AA. Every\naccessibility finding reports at `warn`: the run prints it and leaves the exit\nstatus to the other rules. `--strict` turns each one into an error that fails\nthe run, as it does every other warning.\n\n```bash\nnpx live-tokens check-component statcard --tests\nnpx live-tokens check-page src/pages/Home.svelte --tests --strict\n```\n\n## Suites and checks\n\n**Components.** The component suite opens every variant and state the\ncomponent's contract names and scans the preview:\n\n- **axe-core** checks names, roles, ARIA, contrast, target size, and\n  structure.\n- **Siteimprove Alfa**, rule SIA-R65, checks that each focusable element\n  looks different when it takes focus.\n- **Focus indicator contrast** measures each focus ring against the backdrop\n  around it, at 3:1 under WCAG 2.2 SC 1.4.11.\n- **Control boundary contrast** measures each part the contract lists in\n  `boundaries` against the backdrop behind it, at 3:1 under WCAG 2.2\n  SC 1.4.11.\n- **Text spacing** applies the WCAG 2.2 SC 1.4.12 override inside the\n  component and reports text that clips under it.\n- **Reduced motion** reports motion longer than 200 ms that still runs under\n  `prefers-reduced-motion: reduce`.\n- **Playwright** reads each view's accessibility tree and compares it with\n  the tree recorded for that view.\n- **Keyboard cases** in the contract press Enter, Space, the arrow keys, and\n  Escape, and read what each key did.\n\nA project's run scans the open theme. The library's own test run also repeats\naxe's contrast rule, and both contrast checks, under each of the eight preset\nthemes.\n\n**Pages.** `check-page --tests` runs three tests on each page at each\nviewport:\n\n- `page-a11y` runs axe over the page, leaving out the router's chrome and\n  every component the component suite scans. axe's contrast rule stays off here, because\n  `page-contrast` already reports text contrast at `error`.\n- `page-text-spacing` applies the WCAG 2.2 SC 1.4.12 text spacing override\n  (line height 1.5, paragraph spacing 2em, letter spacing 0.12em, word\n  spacing 0.16em) and reports content that overflows under it.\n- `page-reduced-motion` loads the page under `prefers-reduced-motion: reduce`\n  and reports animations that keep running.\n\n## Rules\n\n| Rule | Checker | Reports |\n|------|---------|---------|\n| `a11y-component` | `check-component` | An axe failure inside a component's preview, a focus ring or control boundary below 3:1, or a changed accessibility tree. |\n| `a11y-focus-visible` | `check-component` | An element that looks the same focused as at rest (SIA-R65). |\n| `a11y-keyboard` | `check-component` | A keyboard case whose key failed to activate, move, or close. |\n| `a11y-page` | `check-page` | An axe failure in the page's own markup. |\n| `a11y-text-spacing` | `check-component`, `check-page` | Content that overflows under the text spacing override. |\n| `a11y-reduced-motion` | `check-component`, `check-page` | Motion that still runs under reduced motion. |\n| `a11y-review` | both | A check the engine could not decide, for you to judge by eye. |\n\nEach finding's message names the engine's own rule, the element, the view it\nfailed in, and a help page that states the requirement and its repair. The\nrules take the same severity settings as every other rule. `--off=a11y-review`\nsilences one for a single run, `--error=a11y-page` raises one, and\n`live-tokens.config.json` records either for good:\n\n```json\n{ \"checks\": { \"rules\": { \"a11y-review\": \"off\", \"a11y-page\": \"error\" } } }\n```\n\nA scan that crashes reports `tests-setup`.\n\n## Focus indicator contrast\n\nThe suite forces `:focus` and `:focus-visible` on each focusable element in\neach view and looks for the style focus changes. It searches the element, its\ndescendants, and its siblings with their descendants, so a ring painted on a\nsibling, such as a slider thumb's cap, counts. The indicator is the outline\nwhen focus changes one, else the first outer box shadow, else a border side.\n\nThe backdrop is every box behind the ring's outer edge, composited in order\nover white. A ring below 3:1 against it reports under `a11y-component` with\nengine rule `focus-indicator-contrast`, such as \"Focus outline on span.cap\n2.14:1 against the backdrop, needs 3:1\". Ratios floor to two places, because\nWCAG does not round. Chromium's own `outline-style: auto` ring passes: it pairs\na dark band with a light one. An element with no indicator at all is\nSIA-R65's finding and adds none here.\n\n## Control boundary contrast\n\nA control whose edge shows where to click or what it holds needs that edge\nat 3:1 against the backdrop behind it. So does a selected or current item\nwhose surface or edge alone shows that state. The contract lists these parts\nin `boundaries`. Each part passes when its border, on any side, or its\noutline, 1px or wider, or its surface reaches 3:1. A failure names both ratios, such as \"Track border\n1.45:1 and surface 1.3:1 against the backdrop, needs 3:1\", and reports under\n`a11y-component` with engine rule `control-boundary-contrast`. A part whose\nform controls are all disabled is skipped, because SC 1.4.11 exempts inactive\ncontrols.\n\nThe shipped controls that draw their own edge declare it: Input's field,\nRadioButton's circle, Slider's and Toggle's track and thumb, and\nSegmentedControl's bar. The selected states that show by surface and edge\nalone declare their part too: TabBar's selected tab, SegmentedControl's\nselected option, and SideNavigation's selected title, section, item and\nfooter. Each measures against the bar or panel behind it, the surface the\nunselected items show. MenuSelect's selected option carries a check mark, so\nit declares none.\n\n## Text spacing and motion per component\n\nThe text spacing check measures every element of the component that holds\ntext: its root part, its portaled parts, and their descendants. It applies\nthe override inside the preview alone and reports each element the override\npushes more than 1px past its box, on an axis it does not scroll. An element\nalready cut at rest adds nothing. The help names the measure: \"Under the text\nspacing override, `<span>` holds 24px of content in 18px of height, and its\noverflow-y is hidden\".\n\nThe reduced motion check reads the declared animations and transitions of\nthe same elements and their `::before` and `::after`, along with every\nscript animation running on them. Motion that lasts past 200 ms, its delay\nincluded, is recorded. The check then emulates\n`prefers-reduced-motion: reduce` in the same view and reports each motion\nstill that long, such as \"A transition of left lasts 500 ms under\nprefers-reduced-motion: reduce\". A view with no long motion costs no second\nread. The help page is WCAG technique C39, which serves WCAG 2.2 SC 2.3.3\nAnimation from Interactions.\n\n## Property tracing\n\nA finding that a property can fix names that property. The suite reads the\nCSS rules that match the failing element through the Chrome DevTools\nprotocol, keeps the declarations the finding depends on, such as the outline\nand border of a focus ring or the height and padding of a clipped label, and\nfollows each `var()` to the component's semantic properties and intrinsics.\nA component's private custom properties lead through to the property behind\nthem. Theme and editor variables drop out.\n\n`--json` output carries the result in each finding's `details.variables`,\nsorted, and leaves the field out when the trace finds nothing. An excerpt:\n\n```json\n{\n  \"rule\": \"a11y-component\",\n  \"component\": \"slider\",\n  \"details\": {\n    \"engineRule\": \"focus-indicator-contrast\",\n    \"target\": \"span.cap\",\n    \"variables\": [\"--slider-range-thumb-border\", \"--slider-range-thumb-border-width\"]\n  }\n}\n```\n\naxe's contrast and target size rules, SIA-R65, both contrast checks, text\nspacing, and reduced motion trace. The ARIA rules, the keyboard cases, and\nthe accessibility tree mark the component alone.\n\n## Review findings\n\n`a11y-review` collects the checks an engine left undecided. axe reads contrast\nfrom the colour behind the text, so it returns no verdict for text over a\ngradient, an image, or a backdrop, or under a pseudo-element that covers it.\nThe focus indicator and control boundary checks do the same for a ring or an\nedge over a gradient or an image. Judge each element by eye against the help\npage the finding names.\n\nTwo sources account for most of them. Button's shimmer pseudo-element and its\ntinted hover surfaces leave every Button view undecided, so a Button run lists\nmany `a11y-review` warnings. A theme that paints gradient surfaces does the\nsame for every component that sits on one.\n\n## Accessibility trees\n\nThe package records each shipped component's accessibility tree, one block\nper view, in `src/testing/contracts/__aria__/<id>.yml`. A run that reads a\ndifferent tree reports `a11y-component` with engine rule `aria-snapshot` and\nthe lines that changed.\n\nInside the live-tokens repository, after a deliberate markup change,\n`--update-aria` records the tree anew, and `LIVE_TOKENS_UPDATE_ARIA=1 npm run\ntest:e2e:contract` rewrites every file:\n\n```bash\nnode bin/cli.mjs check-component button --tests --update-aria\n```\n\nIn a project the trees sit under `node_modules`, where the suite reads them\nand never writes. A project's own components therefore have no recorded tree\nyet.\n\n## Keyboard cases\n\nA component contract declares its keyboard cases among its interaction\ncases, each marked `rule: 'a11y-keyboard'`: Enter or Space activates, an\narrow key moves where the component's WAI-ARIA pattern moves, and Escape\ncloses an overlay. A failed keyboard case reports `a11y-keyboard` at `warn`.\nA case without the mark fails as `contract-interaction`, an error. The\n`live-tokens-create-component` skill writes these cases for a new component,\nand its `references/contract-tests.md` describes their shape.\n\nAn editor that adds placeholder content to its preview, such as a demo label\nor a hover target, marks it `data-preview-demo`, and the scans skip it.\n\n## Boundaries in the contract\n\n`boundaries` is an optional contract field,\n`{ part: string; label: string; when?: string }[]`, for the parts that draw a\ncontrol's visible edge or show its selected state. `part` is a key of the\ncontract's `parts`, and `label` names the part in a finding. `when` is a\nselector the part must also match to be measured, for a part that carries its\nselected state as a class in some views only.\n\n```ts\nboundaries: [\n  { part: 'track', label: 'Track' },\n  { part: 'thumb', label: 'Thumb' },\n],\n```\n\nList a part whose border or surface is the only thing that shows the control\nis there, a thumb whose position shows the value, or a selected item whose\nsurface or edge is the only thing that shows it is selected. Leave out a part whose\ntext or icon already shows it. A contract without the field runs no boundary\ncheck.\n\n## Accessibility view\n\nThe editor's Accessibility view runs the component checks from the browser.\n**Run test** checks every component in the open theme as saved, in about\nthree and a half minutes. With edits pending, it shows \"Save the changes you\nwant to have checked.\" and starts nothing. Save the theme first, so the run\nand the editor read the same values.\n\nEvery finding counts, results to check by eye included. An overview opens\nthe report. It shows the total, the count in each repair group below, and a\ntable of every component with a finding: its count per group and a bar of\nits share. A component's name in the table scrolls to its section.\n\nEach component's section heads its count with **Open component**, which opens\nthe component's page at its accessibility panel. The section sorts its rows\nby repair:\n\n- **Fix with a property** holds each colour pair below its WCAG floor, as the\n  editor's contrast checker measures it, such as \"Brand text color 3.87:1,\n  needs 4.5:1\", and every focus ring and control boundary below 3:1.\n- **Fix in the component's code** holds every other finding: axe failures,\n  focus styles that SIA-R65 finds unchanged, failed keyboard cases, text that\n  clips under the spacing override, and motion that ignores reduced motion.\n- **Check by eye** holds the `a11y-review` results.\n\nFindings that share an engine rule, a help text, and their traced properties\nmerge into one row. The row names its element, or its element count, and the\nviews it failed in, up to four. An issue's text is amber, and a result to\ncheck by eye is grey. The row's links sit beside its text:\n\n- Each property the row traces to links with a \"→\" to its row on the\n  component's page, which scrolls to the row and highlights it. A row that\n  traces to no property links to the component's page instead.\n- The link on the right opens the page the finding cites and names its kind:\n  \"Rule\" for an axe or Alfa rule, \"Success criterion\" with its number for a\n  WCAG criterion, \"Technique\" for a WCAG technique, and \"Pattern\" for a\n  WAI-ARIA pattern.\n\nA property's label leads with the words from its variable name that the\neditor's label leaves out, so `--input-focused-border` reads \"Focused border\ncolor\" where the editor's row reads \"Border color\". The contrast rows read\nthe same labels.\n\nThe overview and the per-component counts include the results to check by\neye. A component's section ends in a \"N results to check by eye\" button that\nopens one closed list of those results, merged per component. axe's contrast\nviolations stay out of the report, because the contrast checker measures the\nsame pairs.\n\nWhen Playwright, axe, or Alfa is missing, the report names its install\ncommand and Run test stays disabled. Install the package and press **Check\nagain**. The view runs its tests through the dev server, so it exists under\nthe dev server alone, with the rest of the editor.\n\nThe view runs `check-component --tests --a11y --no-fix --json --open-theme`.\n`--a11y` runs the accessibility suite and the keyboard cases alone, and\n`--open-theme` tests the theme the editor has open. A run without it tests\nthe `default` theme. Both work from the command line too.\n\n## Marks in the editor\n\nThe last finished run marks the rest of the editor:\n\n- The component list leads the name of each component with any finding\n  with a warning triangle. A condensed list shows the triangle on the\n  component's icon.\n- That component's page opens with a panel under its title that lists its\n  findings in all three groups, check by eye included.\n- Each \"→\" in the panel opens the tab holding the property and highlights\n  its row.\n- Each property row a finding traces to carries a mark beside its label: a\n  warning triangle in the highlight colour, or a grey \"?\" when every finding on the row is a\n  result to check by eye. On a colour or size row the mark sits between the\n  label and the value. On a toggle row it follows the label.\n\nClick a row's mark to open its findings: the count, then each merged row\nwith its element, its views, its help page, and the properties it traces to. The\neditor's own contrast failures add no row mark, because the contrast readout\non the colour row already shows them.\n\nThe marks and the panel keep the run's time and change when the next run\nfinishes. The contrast readout on each colour row stays live and measures\nevery edit as you make it.\n\n## Installing the engines\n\nThe engines ship as optional peer dependencies. A project made with `create`\nhas them. Any other project installs them beside `@playwright/test`:\n\n```bash\nnpm install -D axe-core @axe-core/playwright \\\n  @siteimprove/alfa-act@^0.119.0 @siteimprove/alfa-device@^0.119.0 \\\n  @siteimprove/alfa-dom@^0.119.0 @siteimprove/alfa-http@^0.119.0 \\\n  @siteimprove/alfa-rules@^0.119.0 @siteimprove/alfa-url@^0.119.0 \\\n  @siteimprove/alfa-web@^0.119.0\n```\n\nThe Alfa packages share one minor version. axe-core needs 4.11.1 or later to\nread OKLCH colours, which every shipped theme uses. A test whose engine is\nmissing reports as inapplicable, and its coverage names the package. A\nmissing engine leaves the exit status to the other rules, under `--strict`\ntoo.\n\n## Limits\n\n- The page's text spacing test measures widths, so it reports horizontal\n  overflow alone. The component check measures both axes.\n- The page's reduced motion test reports animations still running 200 ms\n  after the page loads. A short entrance animation finishes first and goes\n  unseen.\n- The component's reduced motion check reads the preference within each\n  view. A script that reads it only when the component mounts goes unseen.\n- The page scan leaves contrast to `page-contrast` and focus visibility to\n  the component suite.\n- SIA-R65 reads the focused element, its descendants, and its ancestors, so\n  it reports a focus ring painted on a sibling as missing. The focus\n  indicator check measures that ring; confirm it by eye.\n- A view that forces the focused look at rest, such as Input's focused\n  state, leaves real focus nothing to change, so SIA-R65 reports it there.\n  The same element passes in the views that leave it at rest.\n- A finding traces to the component's own semantic properties and\n  intrinsics. A ring or colour that a theme token paints directly, such as\n  SegmentedControl's `--border-neutral-strong` focus ring, traces to\n  nothing. A finding on a component nested\n  inside another, such as a Button inside a Dialog, marks the host and names\n  none of the nested component's properties.\n- A literal value in the component's code, such as a transition's duration,\n  has no property to name. The finding traces to whatever property governs\n  the same declaration, or to none.\n- A project's own components get no recorded accessibility tree.\n- Automated checks find part of what WCAG asks. Reading order, the meaning of\n  labels and alt text, and screen reader behaviour still need a person.\n",
+  "accessibility": "# Accessibility\n\n`check-component --tests` and `check-page --tests` test the shipped\ncomponents, your own components, and your pages against WCAG 2 A and AA. Every\naccessibility finding reports at `warn`: the run prints it and leaves the exit\nstatus to the other rules. `--strict` turns each one into an error that fails\nthe run, as it does every other warning.\n\n```bash\nnpx live-tokens check-component statcard --tests\nnpx live-tokens check-page src/pages/Home.svelte --tests --strict\n```\n\n## Suites and checks\n\n**Components.** The component suite opens every variant and state the\ncomponent's contract names and scans the preview:\n\n- **axe-core** checks names, roles, ARIA, contrast, target size, and\n  structure.\n- **Siteimprove Alfa**, rule SIA-R65, checks that each focusable element\n  looks different when it takes focus.\n- **Focus indicator contrast** measures each focus ring against the backdrop\n  around it, at 3:1 under WCAG 2.2 SC 1.4.11.\n- **Control boundary contrast** measures each part the contract lists in\n  `boundaries` against the backdrop behind it, at 3:1 under WCAG 2.2\n  SC 1.4.11.\n- **Text spacing** applies the WCAG 2.2 SC 1.4.12 override inside the\n  component and reports text that clips under it.\n- **Reduced motion** reports motion longer than 200 ms that still runs under\n  `prefers-reduced-motion: reduce`.\n- **Playwright** reads each view's accessibility tree and compares it with\n  the tree recorded for that view.\n- **Keyboard cases** in the contract press Enter, Space, the arrow keys, and\n  Escape, and read what each key did.\n\nA project's run scans the open theme. The library's own test run also repeats\naxe's contrast rule, and both contrast checks, under each of the eight preset\nthemes.\n\n**Pages.** `check-page --tests` runs three tests on each page at each\nviewport:\n\n- `page-a11y` runs axe over the page, leaving out the router's chrome and\n  every component the component suite scans. axe's contrast rule stays off here, because\n  `page-contrast` already reports text contrast at `error`.\n- `page-text-spacing` applies the WCAG 2.2 SC 1.4.12 text spacing override\n  (line height 1.5, paragraph spacing 2em, letter spacing 0.12em, word\n  spacing 0.16em) and reports content that overflows under it.\n- `page-reduced-motion` loads the page under `prefers-reduced-motion: reduce`\n  and reports animations that keep running.\n\n## Rules\n\n| Rule | Checker | Reports |\n|------|---------|---------|\n| `a11y-component` | `check-component` | An axe failure inside a component's preview, a focus ring or control boundary below 3:1, or a changed accessibility tree. |\n| `a11y-focus-visible` | `check-component` | An element that looks the same focused as at rest (SIA-R65). |\n| `a11y-keyboard` | `check-component` | A keyboard case whose key failed to activate, move, or close. |\n| `a11y-page` | `check-page` | An axe failure in the page's own markup. |\n| `a11y-text-spacing` | `check-component`, `check-page` | Content that overflows under the text spacing override. |\n| `a11y-reduced-motion` | `check-component`, `check-page` | Motion that still runs under reduced motion. |\n| `a11y-review` | both | A check the engine could not decide, for you to judge by eye. |\n\nEach finding's message names the engine's own rule, the element, the view it\nfailed in, and a help page that states the requirement and its repair. The\nrules take the same severity settings as every other rule. `--off=a11y-review`\nsilences one for a single run, `--error=a11y-page` raises one, and\n`live-tokens.config.json` records either for good:\n\n```json\n{ \"checks\": { \"rules\": { \"a11y-review\": \"off\", \"a11y-page\": \"error\" } } }\n```\n\nA scan that crashes reports `tests-setup`.\n\n## Focus indicator contrast\n\nThe suite forces `:focus` and `:focus-visible` on each focusable element in\neach view and looks for the style focus changes. It searches the element, its\ndescendants, and its siblings with their descendants, so a ring painted on a\nsibling, such as a slider thumb's cap, counts. The indicator is the outline\nwhen focus changes one, else the first outer box shadow, else a border side.\n\nThe backdrop is every box behind the ring's outer edge, composited in order\nover white. The walk stops at the preview's edge and ends on `--page-bg`, so a\npart that fills its preview edge to edge is measured against the page. A ring below 3:1 against it reports under `a11y-component` with\nengine rule `focus-indicator-contrast`, such as \"Focus outline on span.cap\n2.14:1 against the backdrop, needs 3:1\". Ratios floor to two places, because\nWCAG does not round. Chromium's own `outline-style: auto` ring passes: it pairs\na dark band with a light one. An element with no indicator at all is\nSIA-R65's finding and adds none here. Alfa reads only the element, its\ndescendants, and its ancestors, so a ring this check finds on a sibling settles\nSIA-R65's \"can't tell\" for that element.\n\nA state view that forces the focused look with a class, such as Input's\nfocused state, would leave focus nothing to change. Both focus checks lift\nthat class while they measure, then put it back.\n\n## Control boundary contrast\n\nA control whose edge shows where to click or what it holds needs that edge\nat 3:1 against the backdrop behind it. So does a selected or current item\nwhose surface or edge alone shows that state. The contract lists these parts\nin `boundaries`. Each part passes when its border, on any side, or its\noutline, 1px or wider, or its surface reaches 3:1. A failure names both ratios, such as \"Track border\n1.45:1 and surface 1.3:1 against the backdrop, needs 3:1\", and reports under\n`a11y-component` with engine rule `control-boundary-contrast`. A part whose\nform controls are all disabled is skipped, because SC 1.4.11 exempts inactive\ncontrols.\n\nThe shipped controls that draw their own edge declare it: Input's field,\nRadioButton's circle, Slider's and Toggle's track and thumb, and\nSegmentedControl's bar. The selected states that show by surface and edge\nalone declare their part too: TabBar's selected tab, SegmentedControl's\nselected option, and SideNavigation's selected title, section, item and\nfooter. Each measures against the bar or panel behind it, the surface the\nunselected items show. MenuSelect's selected option carries a check mark, so\nit declares none.\n\n## Text spacing and motion per component\n\nThe text spacing check measures every element of the component that holds\ntext: its root part, its portaled parts, and their descendants. It applies\nthe override inside the preview alone and reports each element the override\npushes more than 1px past its box, on an axis it does not scroll. An element\nalready cut at rest adds nothing. The help names the measure: \"Under the text\nspacing override, `<span>` holds 24px of content in 18px of height, and its\noverflow-y is hidden\".\n\nThe reduced motion check reads the declared animations and transitions of\nthe same elements and their `::before` and `::after`, along with every\nscript animation running on them. Motion that lasts past 200 ms, its delay\nincluded, is recorded. The check then emulates\n`prefers-reduced-motion: reduce` in the same view and reports each motion\nstill that long, such as \"A transition of left lasts 500 ms under\nprefers-reduced-motion: reduce\". A view with no long motion costs no second\nread. The help page is WCAG technique C39, which serves WCAG 2.2 SC 2.3.3\nAnimation from Interactions.\n\n## Property tracing\n\nA finding that a property can fix names that property. The suite reads the\nCSS rules that match the failing element through the Chrome DevTools\nprotocol, keeps the declarations the finding depends on, such as the outline\nand border of a focus ring or the height and padding of a clipped label, and\nfollows each `var()` to the component's semantic properties and intrinsics.\nA component's private custom properties lead through to the property behind\nthem. Theme and editor variables drop out.\n\n`--json` output carries the result in each finding's `details.variables`,\nsorted, and leaves the field out when the trace finds nothing. An excerpt:\n\n```json\n{\n  \"rule\": \"a11y-component\",\n  \"component\": \"slider\",\n  \"details\": {\n    \"engineRule\": \"focus-indicator-contrast\",\n    \"target\": \"span.cap\",\n    \"variables\": [\"--slider-range-thumb-border\", \"--slider-range-thumb-border-width\"]\n  }\n}\n```\n\naxe's contrast and target size rules, SIA-R65, both contrast checks, text\nspacing, and reduced motion trace. The ARIA rules, the keyboard cases, and\nthe accessibility tree mark the component alone.\n\n## Review findings\n\n`a11y-review` collects the checks an engine left undecided. axe reads contrast\nfrom the colour behind the text, so it returns no verdict for text over a\ngradient, an image, or a backdrop, or under a pseudo-element that covers it.\nThe focus indicator and control boundary checks do the same for a ring or an\nedge over a gradient or an image. Judge each element by eye against the help\npage the finding names.\n\nTwo sources account for most of them. Button's shimmer pseudo-element and its\ntinted hover surfaces leave every Button view undecided, so a Button run lists\nmany `a11y-review` warnings. A theme that paints gradient surfaces does the\nsame for every component that sits on one.\n\n## Accessibility trees\n\nThe package records each shipped component's accessibility tree, one block\nper view, in `src/testing/contracts/__aria__/<id>.yml`. A run that reads a\ndifferent tree reports `a11y-component` with engine rule `aria-snapshot` and\nthe lines that changed.\n\nInside the live-tokens repository, after a deliberate markup change,\n`--update-aria` records the tree anew, and `LIVE_TOKENS_UPDATE_ARIA=1 npm run\ntest:e2e:contract` rewrites every file:\n\n```bash\nnode bin/cli.mjs check-component button --tests --update-aria\n```\n\nIn a project the trees sit under `node_modules`, where the suite reads them\nand never writes. A project's own components therefore have no recorded tree\nyet.\n\n## Keyboard cases\n\nA component contract declares its keyboard cases among its interaction\ncases, each marked `rule: 'a11y-keyboard'`: Enter or Space activates, an\narrow key moves where the component's WAI-ARIA pattern moves, and Escape\ncloses an overlay. A failed keyboard case reports `a11y-keyboard` at `warn`.\nA case without the mark fails as `contract-interaction`, an error. The\n`live-tokens-create-component` skill writes these cases for a new component,\nand its `references/contract-tests.md` describes their shape.\n\nAn editor that adds placeholder content to its preview, such as a demo label\nor a hover target, marks it `data-preview-demo`, and the scans skip it.\n\n## Boundaries in the contract\n\n`boundaries` is an optional contract field,\n`{ part: string; label: string; when?: string }[]`, for the parts that draw a\ncontrol's visible edge or show its selected state. `part` is a key of the\ncontract's `parts`, and `label` names the part in a finding. `when` is a\nselector the part must also match to be measured, for a part that carries its\nselected state as a class in some views only.\n\n```ts\nboundaries: [\n  { part: 'track', label: 'Track' },\n  { part: 'thumb', label: 'Thumb' },\n],\n```\n\nList a part whose border or surface is the only thing that shows the control\nis there, a thumb whose position shows the value, or a selected item whose\nsurface or edge is the only thing that shows it is selected. Leave out a part whose\ntext or icon already shows it. A contract without the field runs no boundary\ncheck.\n\n## Accessibility view\n\nThe editor's Accessibility view runs the component checks from the browser.\n**Run test** checks every component in the open theme as saved, in about\nthree and a half minutes. With edits pending, it shows \"Save the changes you\nwant to have checked.\" and starts nothing. Save the theme first, so the run\nand the editor read the same values.\n\nEach theme keeps its own report. Opening another theme shows that theme's\nlast run, or none if it has never run. The dev server keeps each report in\n`_a11y-reports/` in the data directory, and deleting a theme deletes its\nreport. A failed run leaves the theme's last report in place.\n\nThe total counts the findings a fix clears. A result to check by eye counts\napart, because only a person can settle it. An overview opens the report. It\nshows the total, the count in each repair group below, and a table of every\ncomponent with a finding and its count per group. The \"Check by eye\" figure\nscrolls to the By eye list. The table\nlists first the components with the most findings a property fixes, then those\nwith the most a code change fixes. A component's name in the table scrolls to\nits section.\n\nEach component's section heads its count with **Open component**, which opens\nthe component's page at its accessibility panel. The section sorts its rows\nby repair:\n\n- **Fix with a property** holds each colour pair below its WCAG floor, as the\n  editor's contrast checker measures it, such as \"Brand text color 3.87:1,\n  needs 4.5:1\", and every focus ring and control boundary below 3:1.\n- **Fix in the component's code** holds every other finding: axe failures,\n  focus styles that SIA-R65 finds unchanged, failed keyboard cases, text that\n  clips under the spacing override, and motion that ignores reduced motion.\n- **Check by eye** holds the `a11y-review` results, each led by an eye. The\n  By eye list gathers them for the whole report.\n\nFindings that share an engine rule, a help text, and their traced properties\nmerge into one row. The row names its element, or its element count, and the\nviews it failed in, up to four. An issue's text is amber, and a result to\ncheck by eye is grey. The row's links sit beside its text:\n\n- Each property the row traces to links with a \"→\" to its row on the\n  component's page, which scrolls to the row and highlights it. A row that\n  traces to no property links to the component's page instead.\n- The link on the right opens the page the finding cites and names its kind:\n  \"Rule\" for an axe or Alfa rule, \"Success criterion\" with its number for a\n  WCAG criterion, \"Technique\" for a WCAG technique, and \"Pattern\" for a\n  WAI-ARIA pattern.\n- A result to check by eye has **Looks right** at the row's right edge.\n  Press it once you have judged the element and found it passes. The row's\n  eye turns to a check, its text dims, and it stops counting and stops\n  marking the editor. Press it again to clear the mark. The mark belongs to\n  the open theme's report, and each later run of that theme keeps it while\n  the run finds the same result.\n\nA property's label leads with the words from its variable name that the\neditor's label leaves out, so `--input-focused-border` reads \"Focused border\ncolor\" where the editor's row reads \"Border color\". The contrast rows read\nthe same labels.\n\nThe overview's \"Check by eye\" column counts the results no one has marked.\nA component whose results all look right leaves the table, the sections, and\nthe view's sidebar. A component section lists only issues and fixes, so the\nview's sidebar lists the components with one of those.\n\nThe **By eye** list closes the view and holds every result to check by eye,\nmerged per component. The results to check come first, under a tally such\nas \"2 to check, 18 look right\" and a bar that fills as you mark them. Pressing\n**Looks right** moves focus to the result that takes the row's place, so\nEnter or Space walks the list. **Mark all as looking right** marks every\nresult still to check in one step. The marked results follow in **Looks\nright**, a group that starts closed and shows their count. Open it to\nrevisit them, each with its button pressed, or to clear a mark. A component's\nsection with results still to check ends in a link such as \"2 results to\ncheck by eye\" that scrolls to the list. axe's contrast\nviolations stay out of the report, because the contrast checker measures the\nsame pairs.\n\nWhen Playwright, axe, or Alfa is missing, the report names its install\ncommand and Run test stays disabled. Install the package and press **Check\nagain**. The view runs its tests through the dev server, so it exists under\nthe dev server alone, with the rest of the editor.\n\nThe view runs `check-component --tests --a11y --no-fix --json --open-theme`.\n`--a11y` runs the accessibility suite and the keyboard cases alone, and\n`--open-theme` tests the theme the editor has open. A run without it tests\nthe `default` theme. Both work from the command line too.\n\n## Marks in the editor\n\nThe last finished run marks the rest of the editor. A result marked as\nlooking right is acknowledged and marks nothing: no sidebar mark, no panel,\nand no property mark. The By eye list keeps it to revisit.\n\n- The component list leads the name of each component with a finding with a\n  warning triangle, or with a grey eye when its only results are unmarked\n  results to check by eye. A condensed list shows the mark on the\n  component's icon.\n- That component's page opens with a panel under its title that lists its\n  findings in all three groups, check by eye included, and leaves out the\n  results marked as looking right. The panel heads with\n  the triangle and the issue count, or with the eye and the count to check by\n  eye when no issue remains.\n- Each \"→\" in the panel opens the tab holding the property and highlights\n  its row.\n- Each property row a finding traces to carries a mark beside its label: a\n  warning triangle in the highlight colour, or a grey eye when every finding\n  on the row is a result to check by eye. A result marked as looking right\n  adds no mark. On a colour or size row the mark sits between the\n  label and the value. On a toggle row it follows the label.\n\nClick a row's mark to open its findings: the count, then each merged row\nwith its element, its views, its help page, and the properties it traces to. The\neditor's own contrast failures add no row mark, because the contrast readout\non the colour row already shows them.\n\nThe marks and the panel keep the run's time and change when the open\ntheme's next run finishes. The contrast readout on each colour row stays live and measures\nevery edit as you make it.\n\nThe editor also re-measures each contrast failure of the run as you edit.\nOnce one passes, its row in the panel and in the Accessibility view turns\ngreen and shows the run's ratio beside the ratio now, such as\n\"Fill color 2.66:1 → 5.31:1\". A fixed row counts as no issue, so a component\nwhose only issues are fixed loses its triangle in the component list. The\nrun's other findings change only when the next run finishes.\n\n## Installing the engines\n\nThe engines ship as optional peer dependencies. A project made with `create`\nhas them. Any other project installs them beside `@playwright/test`:\n\n```bash\nnpm install -D axe-core @axe-core/playwright \\\n  @siteimprove/alfa-act@^0.119.0 @siteimprove/alfa-device@^0.119.0 \\\n  @siteimprove/alfa-dom@^0.119.0 @siteimprove/alfa-http@^0.119.0 \\\n  @siteimprove/alfa-rules@^0.119.0 @siteimprove/alfa-url@^0.119.0 \\\n  @siteimprove/alfa-web@^0.119.0\n```\n\nThe Alfa packages share one minor version. axe-core needs 4.11.1 or later to\nread OKLCH colours, which every shipped theme uses. A test whose engine is\nmissing reports as inapplicable, and its coverage names the package. A\nmissing engine leaves the exit status to the other rules, under `--strict`\ntoo.\n\n## Limits\n\n- The page's text spacing test measures widths, so it reports horizontal\n  overflow alone. The component check measures both axes.\n- The page's reduced motion test reports animations still running 200 ms\n  after the page loads. A short entrance animation finishes first and goes\n  unseen.\n- The component's reduced motion check reads the preference within each\n  view. A script that reads it only when the component mounts goes unseen.\n- The page scan leaves contrast to `page-contrast` and focus visibility to\n  the component suite.\n- SIA-R65 reads the focused element, its descendants, and its ancestors, so\n  it reports a focus ring painted on a sibling as missing. The focus\n  indicator check measures that ring; confirm it by eye.\n- A view that forces the focused look at rest, such as Input's focused\n  state, leaves real focus nothing to change, so SIA-R65 reports it there.\n  The same element passes in the views that leave it at rest.\n- A finding traces to the component's own semantic properties and\n  intrinsics. A ring or colour that a theme token paints directly, such as\n  SegmentedControl's `--border-neutral-strong` focus ring, traces to\n  nothing. A finding on a component nested\n  inside another, such as a Button inside a Dialog, marks the host and names\n  none of the nested component's properties.\n- A literal value in the component's code, such as a transition's duration,\n  has no property to name. The finding traces to whatever property governs\n  the same declaration, or to none.\n- A project's own components get no recorded accessibility tree.\n- Automated checks find part of what WCAG asks. Reading order, the meaning of\n  labels and alt text, and screen reader behaviour still need a person.\n",
   "creating-components": "# Creating components\n\nThe package ships about 25 editable components. When you need one it doesn't\nhave, you can make your own Svelte component editable, so anyone using the\neditor can re-point its colours, type, and spacing without touching code.\n\nThe simplest way is to ask Claude. The package bundles a Claude Code skill that\nknows the conventions, writes the files, and checks the result for you.\n\n## Install the skills\n\n```bash\nnpx @motion-proto/live-tokens setup-claude\n```\n\nThis copies the bundled skills into your project's `.claude/skills/`. Once\nthey're there, Claude Code picks them up automatically.\n\n## Browse the skill atlas\n\nThe package also ships a Skill Atlas component: a diagram of the reasoning\nbehind each bundled skill, with its `SKILL.md` and reference files alongside\nso you can see exactly which lines drive which step. Import it from\n`@motion-proto/live-tokens/skill-atlas` and mount it on a route of your own:\n\n```js\n'/skills': {\n  lazy: () => import('@motion-proto/live-tokens/skill-atlas'),\n},\n```\n\n## Ask for a component\n\nDescribe what you want in plain English. Phrases like these trigger the skill:\n\n- \"Add a Toggle component to live-tokens\"\n- \"Make this Svelte component editable in the live-tokens editor\"\n- \"Create a Stat component with a value and a label\"\n\nClaude asks any clarifying questions it needs (which variants, which states,\nwhich parts), then writes the component, registers it with the editor, and runs\nits verification checklist. When it finishes, open `/live-tokens/components` to see your new\ncomponent in the editor and confirm everything works.\n\n## What you get\n\n- A runtime component whose editable properties default to your theme tokens.\n- An editor entry that appears under **Custom** in the `/live-tokens/components` view.\n- A catalogue entry in the runtime file that says what the component is for and\n  what to use instead. `npx live-tokens components` prints it, and the skills\n  read it when they choose a component for a page.\n- The naming and wiring handled for you, so the component fits the system.\n\nAdvanced authors who want to write a component by hand can read the naming and\nstate-model conventions shipped in the package\n(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).\n",
-  "editing-tokens": "# Editing tokens\n\nA tour of the editor. The page behind it repaints on every change; saving\nwrites a theme file you can reload later.\n\nThe editor has five views:\n\n- **Tokens**: the design-system primitives (colour, type, spacing, and so on).\n  They apply everywhere your site uses them.\n- **Color Wheel**: the harmony wheel, the palette curves, and the story your colours\n  tell across a page.\n- **Components**: per-component editors. Re-Assign what tokens a component uses\n  without changing the underlying system.\n- **Sketchstyle**: an effect layer that redraws the page by hand. See\n  [Sketch mode](sketch-mode.md).\n- **Accessibility**: Run test checks every component in the open theme as\n  saved and lists each issue it finds by component.\n\nThis page covers **Tokens**. For components, see\n[Creating components](creating-components.md).\n\n## Palettes\n\nMost colour work happens here. Each palette (Brand, Accent, Neutral, Canvas,\nSuccess, Warning, Info, Danger, and a few more) has:\n\n- **Base colour.** Pick a hex; the palette derives an 11-step ramp (100 to 950)\n  from it.\n- **Curves.** Three curves shape the ramp, in stack order: Hue, Saturation,\n  Lightness. Drag the handles to bias it warmer or cooler, more or less\n  saturated, darker or lighter. Hue drifts the ramp's temperature without\n  moving contrast, because OKLCH hue rotation is close to lightness-preserving.\n  It holds ±45 degrees; a bigger shift belongs on the base colour or the\n  harmony axis.\n- **Overrides.** Lock a single step to a hand-picked hex when the curve doesn't\n  land where you want.\n\nEditing a palette base ripples through every colour that depends on it, in real\ntime. Colours use OKLCH, so the ramp stays perceptually even across hues\nwithout muddy mid-tones.\n\n## Custom colours\n\nA custom colour is one colour of your own, for a slot no palette step fits.\nThe open theme holds it as a token named by number: `--color-custom-1`,\n`--color-custom-2`, and so on.\n\n- **Adding.** Every colour picker has a **Custom** row after Danger. Open it\n  and click the plus swatch. The new colour starts from the slot's current colour and\n  opens in the OKLCH editor, and the slot previews it as you drag. The check\n  assigns it to the slot; the cross discards it and restores the slot.\n- **Reusing.** Pick a custom colour from the same row as you pick a palette\n  step, opacity included. Every slot that names it follows its value.\n- **Editing.** Click the pencil on a custom swatch in the picker, or\n  click **Edit** in the **Custom Colours** section of the Tokens view. The edit\n  repaints every slot that names the colour.\n- **Removing.** The bin on a custom swatch in the picker, or **Remove** in\n  the Tokens view, deletes a colour nothing names. When a component property,\n  gradient stop, or wash names it, the editor first asks for a replacement and\n  preselects the nearest colour. **Replace and remove** points each of those\n  at the replacement, keeps each one's opacity, and deletes the custom colour.\n\nEach add, edit, and remove is one undo step. A custom colour holds one value in\nlight and dark mode. Saving writes the theme's custom colours into its file,\nand loading another theme brings in that theme's set. Reach a custom colour\nthrough a component property: `live-tokens check-page` reports `unknown-token`\nfor page CSS that writes `var(--color-custom-1)`, since the name exists only in\nthe theme.\n\n## Type\n\n- **Fonts.** Add sources from Google Fonts, Adobe (Typekit), a CSS URL, or an\n  inline `@font-face`. The font loads in the page as soon as you add it.\n- **Stacks.** Named font cascades you reference by token, such as a display\n  stack and a body stack.\n- **Sizes and weights.** A t-shirt scale (xs, sm, md, lg, xl, 2xl…) for size and\n  a numeric scale (100 to 900) for weight.\n\n## Spacing, radius, shadow\n\nNumeric scales with a slider per step.\n\n- **Spacing**: the padding, gap, and margin scale.\n- **Radius**: none through full.\n- **Shadow**: colour, offset, blur, spread, and opacity per step, with stacked\n  shadows supported.\n\nChange a step and every element using it repaints.\n\n## Washes and gradients\n\n- **Scrims** are translucent layers that dim what sits behind them, like the\n  one a dialog draws over the page. Set a colour and opacity per stop.\n- **Tints** are the opposite operation: they shade the surface they sit on\n  rather than dimming what is behind it, which is what a hover needs.\n- **Gradients** are reusable gradient tokens with a stop list and direction, for\n  hero panels and accent backgrounds.\n\n## Columns\n\nPages lay out on the column grid. The column count and the max width hold at\nevery width. Desktop, Tablet, and Phone each set a gutter and an outer margin,\nand the grid takes the tablet values at 767px and narrower and the phone values\nat 480px and narrower. The columns button in the editor bar draws the grid over\nthe page, and a page on the grid reflows as you edit.\n\n## Contrast readout\n\nIn the **Components** view, every colour row that paints text, an icon, or\nanother foreground mark shows its WCAG contrast ratio beside the colour's name.\nThe readout measures the colour against the layers the component paints behind\nit. Each edit and each theme load updates it, and the rows keep their places.\n\n- **Value.** The ratio shows on every foreground row, in grey while it meets\n  its floor. It truncates to two decimals, so 4.499 reads `4.49:1`, below the\n  4.5:1 floor. Text needs 4.5:1, or 3:1 at 24px or 18.66px bold. An icon or\n  another mark needs 3:1.\n- **Amber mark.** A ratio below its floor turns amber and gains an exclamation\n  mark.\n- **Popover.** Click the ratio to open it. For each pair the colour forms, it\n  names the WCAG rule and its floor, the measured ratio, and the layers behind\n  the colour, top first, with a link to the success criterion. A colour over\n  several backgrounds forms one pair per background, and the row shows the pair\n  closest to failing. Notification's body colour paints the dismiss icon on the\n  header and the body text on the page, so its popover lists two pairs.\n- **Disabled states.** WCAG exempts disabled controls, so a disabled state's\n  ratio shows in a dimmer grey, whatever its value.\n- **Page background.** Every stack ends on the page background, `--page-bg`.\n  A translucent layer blends into the layers beneath it, and the readout\n  measures the blend. A gradient layer counts its worst stop.\n\n## Saving\n\nThe editor saves to your browser continuously, so work survives a reload\nmid-edit. Writing a file is a separate step: the **Theme** panel at the foot of\nthe sidebar has **Save**, **Save As**, and **Load**, and each theme is one JSON\nfile under `src/live-tokens/data/themes/`.\n\nThe header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`). You can keep\nmany themes side by side; one is open at a time, and only **Adopt** publishes\none. See [Themes](themes-workflow.md) for the full lifecycle.\n",
+  "editing-tokens": "# Editing tokens\n\nA tour of the editor. The page behind it repaints on every change; saving\nwrites a theme file you can reload later.\n\nThe editor has five views:\n\n- **Tokens**: the design-system primitives (colour, type, spacing, and so on).\n  They apply everywhere your site uses them.\n- **Color Wheel**: the harmony wheel, the palette curves, and the story your colours\n  tell across a page.\n- **Components**: per-component editors. Re-Assign what tokens a component uses\n  without changing the underlying system.\n- **Sketchstyle**: an effect layer that redraws the page by hand. See\n  [Sketch mode](sketch-mode.md).\n- **Accessibility**: Run test checks every component in the open theme as\n  saved and lists each issue it finds by component.\n\nThis page covers **Tokens**. For components, see\n[Creating components](creating-components.md).\n\n## Palettes\n\nMost colour work happens here. Each palette (Brand, Accent, Neutral, Canvas,\nSuccess, Warning, Info, Danger, and a few more) has:\n\n- **Base colour.** Pick a hex; the palette derives an 11-step ramp (100 to 950)\n  from it.\n- **Curves.** Three curves shape the ramp, in stack order: Hue, Saturation,\n  Lightness. Drag the handles to bias it warmer or cooler, more or less\n  saturated, darker or lighter. Hue drifts the ramp's temperature without\n  moving contrast, because OKLCH hue rotation is close to lightness-preserving.\n  It holds ±45 degrees; a bigger shift belongs on the base colour or the\n  harmony axis.\n- **Overrides.** Lock a single step to a hand-picked hex when the curve doesn't\n  land where you want.\n\nEditing a palette base ripples through every colour that depends on it, in real\ntime. Colours use OKLCH, so the ramp stays perceptually even across hues\nwithout muddy mid-tones.\n\n## Custom colours\n\nA custom colour is one colour of your own, for a slot no palette step fits.\nThe open theme holds it as a token named by number: `--color-custom-1`,\n`--color-custom-2`, and so on.\n\n- **Adding.** Every colour picker has a **Custom** row after Danger. Open it\n  and click the plus swatch. The new colour starts from the slot's current colour and\n  opens in the OKLCH editor, and the slot previews it as you drag. The check\n  assigns it to the slot; the cross discards it and restores the slot.\n- **Reusing.** Pick a custom colour from the same row as you pick a palette\n  step, opacity included. Every slot that names it follows its value.\n- **Editing.** Click the pencil on a custom swatch in the picker, or\n  click **Edit** in the **Custom Colours** section of the Tokens view. The edit\n  repaints every slot that names the colour.\n- **Removing.** The bin on a custom swatch in the picker, or **Remove** in\n  the Tokens view, deletes a colour nothing names. When a component property,\n  gradient stop, or wash names it, the editor first asks for a replacement and\n  preselects the nearest colour. **Replace and remove** points each of those\n  at the replacement, keeps each one's opacity, and deletes the custom colour.\n\nEach add, edit, and remove is one undo step. A custom colour holds one value in\nlight and dark mode. Saving writes the theme's custom colours into its file,\nand loading another theme brings in that theme's set. Reach a custom colour\nthrough a component property: `live-tokens check-page` reports `unknown-token`\nfor page CSS that writes `var(--color-custom-1)`, since the name exists only in\nthe theme.\n\n## Type\n\n- **Fonts.** Add sources from Google Fonts, Adobe (Typekit), a CSS URL, or an\n  inline `@font-face`. The font loads in the page as soon as you add it.\n- **Stacks.** Named font cascades you reference by token, such as a display\n  stack and a body stack.\n- **Sizes and weights.** A t-shirt scale (xs, sm, md, lg, xl, 2xl…) for size and\n  a numeric scale (100 to 900) for weight.\n\n## Spacing, radius, shadow\n\nNumeric scales with a slider per step.\n\n- **Spacing**: the padding, gap, and margin scale.\n- **Radius**: none through full.\n- **Shadow**: colour, offset, blur, spread, and opacity per step, with stacked\n  shadows supported.\n\nChange a step and every element using it repaints.\n\n## Washes and gradients\n\n- **Scrims** are translucent layers that dim what sits behind them, like the\n  one a dialog draws over the page. Set a colour and opacity per stop.\n- **Tints** are the opposite operation: they shade the surface they sit on\n  rather than dimming what is behind it, which is what a hover needs.\n- **Gradients** are reusable gradient tokens with a stop list and direction, for\n  hero panels and accent backgrounds.\n\n## Columns\n\nPages lay out on the column grid. The column count and the max width hold at\nevery width. Desktop, Tablet, and Phone each set a gutter and an outer margin,\nand the grid takes the tablet values at 767px and narrower and the phone values\nat 480px and narrower. The columns button in the editor bar draws the grid over\nthe page, and a page on the grid reflows as you edit.\n\n## Contrast readout\n\nIn the **Components** view, every colour row that paints text, an icon, or\nanother foreground mark shows its WCAG contrast ratio beside the colour's name.\nThe readout measures the colour against the layers the component paints behind\nit. Each edit and each theme load updates it, and the rows keep their places.\n\n- **Value.** The ratio shows on every foreground row, in grey while it meets\n  its floor. It truncates to two decimals, so 4.499 reads `4.49:1`, below the\n  4.5:1 floor. Text needs 4.5:1, or 3:1 at 24px or 18.66px bold. An icon or\n  another mark needs 3:1.\n- **Amber mark.** A ratio below its floor turns amber and gains an exclamation\n  mark.\n- **Popover.** Click the ratio to open it. For each pair the colour forms, it\n  names the WCAG rule and its floor, the measured ratio, and the layers behind\n  the colour, top first, with a link to the success criterion. A colour over\n  several backgrounds forms one pair per background, and the row shows the pair\n  closest to failing. Notification's body colour paints the dismiss icon on the\n  header and the body text on the page, so its popover lists two pairs.\n- **Disabled states.** WCAG exempts disabled controls, so a disabled state's\n  ratio shows in a dimmer grey, whatever its value.\n- **Transparent marks.** A mark painted fully transparent, such as an\n  unselected tab's underline, draws nothing, so it meets its floor at any\n  ratio. Transparent text still needs its floor. A decorative line, such as\n  a section divider's hairline, shows no readout.\n- **Page background.** Every stack ends on the page background, `--page-bg`.\n  A translucent layer blends into the layers beneath it, and the readout\n  measures the blend. A gradient layer counts its worst stop.\n\n## Saving\n\nThe editor saves to your browser continuously, so work survives a reload\nmid-edit. Writing a file is a separate step: the **Theme** panel at the foot of\nthe sidebar has **Save**, **Save As**, and **Load**, and each theme is one JSON\nfile under `src/live-tokens/data/themes/`.\n\nThe header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`). You can keep\nmany themes side by side; one is open at a time, and only **Adopt** publishes\none. See [Themes](themes-workflow.md) for the full lifecycle.\n",
   "getting-started": "# Getting started\n\nScaffold a live token site in a moments. You need Node 20 or later, a\npackage manager (npm, pnpm, or yarn), and a browser. Open claude code in your repo and start building.\n\n## Scaffold a new app\n\n```bash\nnpm create @motion-proto/live-tokens@latest my-app\ncd my-app\nnpm install\nnpm run dev\n```\n\nOpen the URL Vite prints (usually `http://localhost:5173`). You get a\none-page Svelte + Vite app that depends on the published package, with the\neditor wired up and the full component set ready to import.\n\n`npx @motion-proto/live-tokens create my-app` runs the same scaffold without\nthe initialiser package.\n\n### What the scaffold gives you\n\nEvery editable file lives under `src/` and is committed, so `npm install` and\nversion upgrades never touch your styles. The package code stays in\n`node_modules`.\n\n| Path | What it is |\n|------|------------|\n| `src/pages/Home.svelte` | The starter page. Replace it with your own content. |\n| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds dev-only routes under a reserved `/live-tokens/*` namespace: `/live-tokens/editor`, `/live-tokens/components`, and `/live-tokens/docs`. |\n| `src/system/styles/tokens.css` | Your base token vocabulary, hand-authored. |\n| `src/styles/site.css` | Themed page typography, yours to edit. |\n\n## Your first edit\n\n1. Run `npm run dev` and open the home page.\n2. Click **Open Token Editor**, or visit `/live-tokens/editor`. The editor opens beside\n   the page.\n3. Open **Palettes**, pick **Brand**, and change the base hex. The page\n   repaints as you type.\n4. In the **Theme** panel at the foot of the sidebar, choose **Save As**. Your\n   theme appears as JSON under `src/live-tokens/data/themes/`.\n5. Reload. The editor reopens on your theme, so the page returns as you left\n   it.\n\n## What you just changed\n\nEvery edit sets a CSS custom property on `:root`. Your components read those\nproperties through `var(--...)`. There is no token build step and no\npreprocessor rewriting your code: the page renders against plain CSS variables\nthe editor swaps live.\n\nTo ship, click **Adopt** in the Theme panel. That saves the open theme and bakes\nit into `src/live-tokens/data/tokens.generated.css`, which your build bundles\nalongside `tokens.css`. Adopt is the only action that changes what your site\nships, so try any theme you like first. The editor itself never reaches\nproduction.\n\nAlready have a Svelte 5 + Vite app? The\n[README](https://github.com/motionproto/live-tokens#readme) covers installing\ninto an existing project.\n\n## Where to go next\n\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own component\n  editable.\n",
   "light-and-dark": "# Light and dark\n\nSome things on a page cannot be written as a token. A wordmark drawn in white\ndisappears on a pale theme. Ink that multiplies onto paper vanishes on a dark\none. A photograph behind a headline is dark no matter what the palette says.\n\nEach of those needs the same fact first: which way does the surface behind this\nthing lean? One attribute carries it.\n\n## The attribute\n\n`data-backdrop` is either `light` or `dark`, and it does two things at once: it\nselects, so a rule can key on it, and it sets `color-scheme`, so every\n`light-dark()` under it resolves the half that reads.\n\n```css\n.title {\n  color: light-dark(var(--color-black), var(--color-white));\n}\n```\n\nThat line is right on both sides of the theme, and it is right inside a dark\nsection on a pale page, because the nearest `color-scheme` wins.\n\n## Stating it\n\nPut it in the markup when the surface knows its own tone — a hero over a\nphotograph, a plate that stays pale in every theme:\n\n```svelte\n<div class=\"hero-panel\" data-backdrop=\"dark\">\n```\n\nA stated tone beats any measurement, and it inherits, so everything inside the\npanel resolves against it.\n\n## Measuring it\n\nWhere the tone is a property of the theme rather than of the markup, let it be\nmeasured:\n\n```svelte\n<script>\n  import { backdrop } from '@motion-proto/live-tokens/backdrop';\n</script>\n\n<section use:backdrop>\n```\n\nThe action reads whatever actually paints behind the element — the nearest\nancestor with an opaque fill, averaged across its gradient stops, falling back\nto the theme's `--page-bg` — and stamps the answer. It re-reads when the theme\nchanges, which the editor does by rewriting custom properties with no reload,\nso the stamp follows a live edit.\n\nThe page itself is stamped for you: the build bakes the production theme's\npolarity into `tokens.generated.css`, so the first paint is already right, and\n`syncDocumentBackdrop()` keeps `<html>` current as themes switch.\n\n```ts\nimport { syncDocumentBackdrop } from '@motion-proto/live-tokens/backdrop';\n\nsyncDocumentBackdrop();\n```\n\n## Reading it from JavaScript\n\nAnything that paints outside CSS — a canvas, a WebGL uniform, an `<img>` that\ncomes in two versions — asks the same question through the same module:\n\n```ts\nimport { isLightBackdrop, watchBackdrop, cssColorToHex } from '@motion-proto/live-tokens/backdrop';\n\nconst stop = watchBackdrop(logoEl, {\n  stamp: false,\n  onChange: (polarity) => (src = polarity === 'light' ? darkMark : lightMark),\n});\n```\n\n`isLightBackdrop(el)` answers once. `watchBackdrop` keeps answering and returns\na stop function. `cssColorToHex` resolves any CSS colour — including the\n`oklch()` a token holds — to a hex a non-CSS consumer can take.\n\n## What it does not do\n\nPolarity is a property of a surface, not of a component, so nothing is stamped\nfor you below `<html>`: a section that needs an answer either states one or asks\nfor one. And a measurement reads the paint at the moment it runs — an element\nthat scrolls from a pale section onto a dark one keeps the answer it was given.\nState the tone on each section instead.\n",
   "production-css": "# Production CSS\n\nIn dev, every design token sits on `:root` as a CSS variable, because the\neditor can rewrite any of them while the page runs. A production build runs no\neditor, so most of those values never change. `vite build` rewrites the CSS it\nemits to match: a token stays a variable only where its value can change at\nruntime, and every other `var()` gives way to the value it reads.\n\nThe dev server keeps every variable. Your source files keep every token too:\nthe build rewrites only the files it emits, so `tokens.css`,\n`tokens.generated.css` and your components still name each token, and the\ntoken names stay the API you write against.\n\n## The build step\n\n`themeFileApi` runs the step at the end of every `vite build`, after Vite has\nbundled and minified the CSS. It reads every stylesheet and script in the\nbundle, including lazy chunks, and then:\n\n- **removes** each custom property that no rule reads, directly or through\n  another property;\n- **substitutes** each `var()` that reads a static property with the text of\n  that property's value, so `calc()` and `color-mix()` still resolve on the\n  element that uses them;\n- **declares** each remaining property once on `:root`, with the value that\n  wins the cascade, so DevTools lists it once.\n\nThe build prints one line with the result:\n\n```\nlive-tokens: the production CSS declares 76 of 848 custom properties and is 61.3 kB smaller.\n```\n\nA file's hashed name follows its content. Each stylesheet the build rewrites\ntakes a new hash, and so does each script that loads it, so a cache that keeps\nhashed files forever serves each release its own files. A file name pattern\nwithout `[hash]` keeps every name.\n\n## The dynamic rule\n\nA property stays a variable when its value can change while the page runs, or\nwhen the build cannot prove it never does. A property that changes and loses\nits variable breaks a page, and an extra variable costs a few bytes, so a case\nthat could fall either way stays a variable. A property is **dynamic** when any\nof these hold:\n\n- A rule declares it under a selector besides a root selector such as `:root`\n  or `:root:root`, or inside `@media`, `@supports` or `@container`. The size\n  tokens and the column gutter and margin in the three responsive `@media`\n  blocks of `tokens.css` stay variables this way.\n- Its name appears in a script or HTML page the build emits. That covers\n  `style:--name` directives, `setProperty`, `getPropertyValue` and inline\n  `style` attributes. Card sets `--card-hover-border-enabled` through a\n  `style:` directive, so the token stays a variable.\n- Its name appears in an at-rule's prelude, such as a `style()` container\n  query.\n- An `@property` rule registers it.\n- The `keep` option lists it.\n- Its value reads a dynamic property.\n- Its winning value is a CSS-wide keyword such as `initial`, or it reads\n  itself through a loop of `var()` references.\n- Two stylesheets give it different `:root` values.\n- Its value reads a name that no stylesheet declares and no script or `keep`\n  entry names.\n- Only a lazily loaded stylesheet declares it, and another stylesheet reads\n  it.\n\nEvery other property is **static**: one value on `:root` for the life of the\npage.\n\n## Computed names\n\nThe build finds a name in a script only when the script spells it out. A\nscript that assembles a name while the page runs, such as\n`` `--color-${family}-500` ``, hides it. The build then substitutes or removes\nthat token, so a read returns an empty string and a write changes nothing. List\neach such name under `keep`:\n\n```ts\nthemeFileApi({\n  tokensCssPath: 'src/system/styles/tokens.css',\n  productionCss: { keep: ['--color-brand-500', '--color-accent-500'] },\n}),\n```\n\n`keep` takes exact names. The same goes for a stylesheet outside the bundle,\nsuch as one in `public/`: the build never reads it, so list each token it\nreads under `keep`.\n\n## Options\n\n`productionCss` on `themeFileApi` sets the step:\n\n- **Default.** The build removes, substitutes and declares, as above.\n- **`productionCss: { keep: [...] }`.** Each listed name stays a variable.\n- **`productionCss: { substitute: false }`.** The build removes properties no\n  rule reads and keeps every other `var()`, so DevTools shows token names while\n  you debug. It still declares each property once on `:root`.\n- **`productionCss: false`.** The build keeps every variable, as dev does.\n\n`keep` and `substitute` combine in one object. When a page renders differently\nin production, build it with `productionCss: false`. A difference that goes\naway points at a token the rule missed, and `keep` fixes it.\n\n## Limits\n\n- **Values a property rejects.** In dev, `width: var(--color-brand-500)` passes\n  the parser, and when the color reaches `width` the browser treats the\n  declaration as `unset`. After substitution, `width` holds a color, the parser\n  drops the declaration, and an earlier `width` rule applies. Keep each token's\n  value valid for every property that reads it.\n- **Fixed stylesheet names.** The build renames each stylesheet it rewrites\n  through the hash in the build's `assetFileNames` pattern. A plugin that emits\n  a stylesheet under a fixed `fileName` breaks that pattern, and the build\n  stops with `live-tokens: <file> does not follow the output pattern\n  \"<pattern>\"`. Set `productionCss: false` for that build.\n",

package/src/editor/pages/ComponentEditorPage.svelte

@@ -112,7 +112,8 @@
   const allComponentNavItems = getComponentRegistryEntries().map(({ id, label, icon, origin }) => ({ id, label, icon, origin }));
   const systemNavItems = allComponentNavItems.filter((i) => i.origin === 'system');
   const customNavItems = allComponentNavItems.filter((i) => i.origin === 'custom');
-  let a11yMarked = $derived(new Set(componentsWithIssues($a11yIssues).map((row) => row.component)));
+  /** Each marked component, true when its only results are to check by eye. */
+  let a11yMarked = $derived(new Map(componentsWithIssues($a11yIssues).map((row) => [row.component, row.count === 0])));
 </script>
 
 <!--
@@ -171,7 +172,7 @@
             <span class="dirty-dot" aria-label="Unsaved changes" title="Unsaved changes"></span>
           {/if}
           {#if a11yMarked.has(item.id)}
-            <A11yRailMark />
+            <A11yRailMark review={a11yMarked.get(item.id)} />
           {/if}
         </button>
       {/each}
@@ -194,7 +195,7 @@
               <span class="dirty-dot" aria-label="Unsaved changes" title="Unsaved changes"></span>
             {/if}
             {#if a11yMarked.has(item.id)}
-              <A11yRailMark />
+              <A11yRailMark review={a11yMarked.get(item.id)} />
             {/if}
           </button>
         {/each}