@ecoma-io/loom 0.4.0 → 0.6.0

package/dist/packages/core/src/a11y-contract.d.ts

@@ -0,0 +1,417 @@
+/**
+ * The role-aware accessibility evidence contract: what a component OWES, not
+ * what the library asserts.
+ *
+ * `a11y-scope.ts` partitions the 70 WCAG-tagged rules into the tiers that can
+ * judge them. That partition is library-wide — it says nothing about any one
+ * component, and a purely visual span ends up with exactly the evidence
+ * obligation of a focusable, labelled control. This file is the per-component
+ * half: a closed role vocabulary, the evidence tiers a role must answer, and
+ * the matrix binding each role to the requirements its claim has to satisfy.
+ *
+ * Three readers, one source:
+ *
+ * - `tools/check-a11y-evidence.ts` and `tools/check-interaction-evidence.ts`,
+ *   the gates for the two axes, read this file AS DATA — parsed, never
+ *   imported. The tooling layer's boundary row (layer-tooling) forbids
+ *   importing the library it checks, and a checker that executed its subject
+ *   could not report on a tree that will not load. Each parse is fail-closed:
+ *   a contract a gate cannot read is a lint failure, not an empty verdict.
+ * - `packages/loom/src/a11y.ts` re-exports the role vocabulary and the type,
+ *   so a consumer or a docs page reads the same law the gate enforces. The
+ *   interaction vocabulary is not re-exported from the public surface yet —
+ *   its readers today are the gate, the pin test and the docs build, and an
+ *   export nobody consumes is a public promise with no reader.
+ * - `packages/core/tests/a11y-contract.test.ts` pins the law's internal
+ *   consistency on both axes: no matrix row for a role or class outside its
+ *   vocabulary, no requirement id without a definition, no requirement in an
+ *   unknown tier.
+ *
+ * The component's own declaration lives beside it, in
+ * `packages/<tier>/<name>/a11y.json` — one sidecar per component, the sixth
+ * artifact `tools/check-a11y-evidence.ts` asserts. THE CLAIM IS DECLARED, NOT
+ * DERIVED: Reka injects ARIA roles at runtime, so no reader can derive a
+ * component's role from its source with confidence. The sidecar declares it,
+ * cites the rendered evidence for the claim (`basis`), declares the evidence
+ * files that exist today, and records an `exceptions` entry — requirement id
+ * plus reason — for every matrix requirement nothing answers yet. The gate
+ * counts and names those exceptions instead of failing the repository, so the
+ * contract lands truthfully and the exception list shrinks as evidence grows.
+ *
+ * The sidecar now carries a SECOND axis beside the role claim: the
+ * interaction class. Phase 3D reserved room here for exactly this — the same
+ * sidecar, a second axis, not a second file — which is why `role` was held
+ * orthogonal to evidence and exceptions rather than folded into them. The
+ * interaction half is defined at the bottom of this file, and
+ * `tools/check-interaction-evidence.ts` is its validator.
+ *
+ * Every collection below is a flat `as const` array of records — the shape the
+ * gates' parsers and the pin test all rely on. Keep new fields string- or
+ * array-valued and entry objects brace-free.
+ */
+/**
+ * The three evidence tiers, using `a11y-scope.ts`'s own vocabulary for the
+ * same three runtimes: the browserless jsdom demo sweep, the component
+ * harness's browser specs, and the root sweep over the built site.
+ */
+export declare const A11Y_EVIDENCE_TIERS: readonly ["browserless", "harness", "sweep"];
+/**
+ * The closed ARIA role vocabulary a component may claim. Every member is a
+ * real ARIA role — the one whose AT contract the component's own markup
+ * asserts, native or injected: a native `<button>`, Reka's `role="dialog"`
+ * content, an explicit `role="list"` wrapper. Composite widgets claim the
+ * container role (tabs → tablist, select → combobox, tree-view → tree); the
+ * `basis` field of each sidecar names the parts that make the claim true.
+ */
+export declare const ARIA_ROLES: readonly ["alert", "alertdialog", "button", "checkbox", "combobox", "dialog", "grid", "group", "img", "link", "list", "menu", "menubar", "meter", "navigation", "progressbar", "radiogroup", "region", "searchbox", "separator", "slider", "spinbutton", "status", "switch", "tablist", "table", "textbox", "toolbar", "tooltip", "tree"];
+/**
+ * The two non-role members. `none` — the component asserts no ARIA role of
+ * its own: its semantics are native landmarks, flow content or slotted
+ * children. `visual-only` — presentational by design, removed from the
+ * accessibility tree or carrying nothing a reader should hear; its only
+ * obligation is to not assert broken ARIA while hiding.
+ */
+export declare const NON_ROLE_MEMBERS: readonly ["none", "visual-only"];
+/** The role vocabulary the sidecar's `role` field is held to. */
+export declare const A11Y_ROLES: readonly ["alert", "alertdialog", "button", "checkbox", "combobox", "dialog", "grid", "group", "img", "link", "list", "menu", "menubar", "meter", "navigation", "progressbar", "radiogroup", "region", "searchbox", "separator", "slider", "spinbutton", "status", "switch", "tablist", "table", "textbox", "toolbar", "tooltip", "tree", "none", "visual-only"];
+/**
+ * The evidence requirements — one row per family of WCAG-tagged rules, named
+ * for the obligation rather than the implementation so the matrix reads as
+ * law. `tier` is where the claim must be ANSWERED; `answers` names the axe
+ * rules of `a11y-scope.ts` the family covers, or the bespoke suite where axe
+ * ships no rule for the criterion (2.4.11 has none, which is why
+ * `e2e/focus-not-obscured.e2e.ts` exists at all).
+ *
+ * The families deliberately do not cover the whole partition — 27 of the 68
+ * runtime-tier rules are named by no family, and the absence is recorded
+ * rather than hidden, the way TAGGED_BUT_DISABLED_RULES records its own two:
+ *
+ * - host-document facts a consumer's page answers, not a component:
+ *   `aria-hidden-body`, `bypass`, `document-title`, `html-has-lang`,
+ *   `html-lang-valid`, `html-xml-lang-mismatch`, `meta-refresh`,
+ *   `meta-viewport`, `valid-lang`;
+ * - elements no Loom component ships: `blink`, `frame-focusable-content`,
+ *   `frame-title`, `frame-title-unique`, `input-button-name`, `marquee`,
+ *   `no-autoplay-audio`, `object-alt`, `server-side-image-map`,
+ *   `summary-name`, `video-caption`;
+ * - attributes whose truth belongs to the host, not the component:
+ *   `aria-braille-equivalent` (no Loom component emits a braille equivalent
+ *   today) and `autocomplete-valid` (the token is forwarded unchanged by
+ *   combobox, editable, tags-input, text-field and command — the rule judges
+ *   whether the host chose the right token for its field, which no component
+ *   can answer for);
+ * - consumer styling, not component markup: `avoid-inline-spacing`;
+ * - conservative-partial table geometry, run by the sweep site-wide but owed
+ *   by no role's row per-component: `table-fake-caption`, `td-has-header`,
+ *   `td-headers-attr`, `th-has-data-cells`.
+ *
+ * The sweep runs all 68 site-wide regardless, so an uncovered rule is still
+ * exercised on every page — what no role owes is per-component accountability.
+ * The coverage set is pinned by packages/core/tests/a11y-contract.test.ts: a
+ * rule that moves into or out of a family must edit that pin and this list
+ * together.
+ */
+export declare const A11Y_EVIDENCE_REQUIREMENTS: readonly [{
+    readonly id: "semantic-aria";
+    readonly tier: "browserless";
+    readonly answers: readonly ["aria-roles", "aria-required-attr", "aria-valid-attr", "aria-valid-attr-value", "aria-allowed-attr", "aria-conditional-attr", "aria-prohibited-attr", "aria-deprecated-role", "aria-roledescription", "aria-required-children", "aria-required-parent", "duplicate-id-aria", "nested-interactive"];
+}, {
+    readonly id: "name";
+    readonly tier: "browserless";
+    readonly answers: readonly ["button-name", "link-name", "label", "form-field-multiple-labels", "aria-input-field-name", "aria-command-name", "aria-toggle-field-name", "aria-meter-name", "aria-progressbar-name", "aria-tab-name", "aria-tooltip-name", "select-name", "image-alt", "svg-img-alt", "role-img-alt", "input-image-alt", "area-alt"];
+}, {
+    readonly id: "structure";
+    readonly tier: "browserless";
+    readonly answers: readonly ["list", "listitem", "definition-list", "dlitem"];
+}, {
+    readonly id: "keyboard";
+    readonly tier: "harness";
+    readonly answers: readonly ["aria-hidden-focus", "scrollable-region-focusable"];
+}, {
+    readonly id: "contrast";
+    readonly tier: "sweep";
+    readonly answers: readonly ["color-contrast", "link-in-text-block", "p-as-heading", "label-content-name-mismatch"];
+}, {
+    readonly id: "target-size";
+    readonly tier: "sweep";
+    readonly answers: readonly ["target-size"];
+}, {
+    readonly id: "focus-not-obscured";
+    readonly tier: "sweep";
+    readonly answers: readonly ["e2e/focus-not-obscured.e2e.ts (WCAG 2.4.11 — axe-core ships no rule for it)"];
+}];
+/**
+ * The matrix: the role's row is the claim it must satisfy. Shared shapes are
+ * spelled out once per role rather than DRYed into inheritance — the matrix is
+ * law, and a law a reader cannot read whole is a law a reader cannot argue
+ * with. `semantic-aria` is the universal floor: every role owes it, including
+ * visual-only, because an aria-hidden skeleton asserting a broken role is
+ * still a defect.
+ */
+export declare const A11Y_EVIDENCE_MATRIX: readonly [{
+    readonly role: "visual-only";
+    readonly requirements: readonly ["semantic-aria"];
+}, {
+    readonly role: "none";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast"];
+}, {
+    readonly role: "img";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast"];
+}, {
+    readonly role: "separator";
+    readonly requirements: readonly ["semantic-aria", "contrast"];
+}, {
+    readonly role: "alert";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast"];
+}, {
+    readonly role: "status";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast"];
+}, {
+    readonly role: "meter";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast"];
+}, {
+    readonly role: "progressbar";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast"];
+}, {
+    readonly role: "tooltip";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast"];
+}, {
+    readonly role: "list";
+    readonly requirements: readonly ["semantic-aria", "name", "structure", "contrast"];
+}, {
+    readonly role: "tree";
+    readonly requirements: readonly ["semantic-aria", "name", "structure", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "table";
+    readonly requirements: readonly ["semantic-aria", "name", "structure", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "grid";
+    readonly requirements: readonly ["semantic-aria", "name", "structure", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "region";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "navigation";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "button";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "link";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "checkbox";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "switch";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "radiogroup";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "slider";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "spinbutton";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "textbox";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "combobox";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "searchbox";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "menu";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "menubar";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "toolbar";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "tablist";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "dialog";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "alertdialog";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}, {
+    readonly role: "group";
+    readonly requirements: readonly ["semantic-aria", "name", "contrast", "keyboard", "target-size", "focus-not-obscured"];
+}];
+/** A member of the closed role vocabulary. */
+export type A11yRole = (typeof A11Y_ROLES)[number];
+/** A pure ARIA role, as distinct from the non-role members. */
+export type AriaRole = (typeof ARIA_ROLES)[number];
+/** One evidence runtime: browserless jsdom, component harness, or the root sweep. */
+export type A11yEvidenceTier = (typeof A11Y_EVIDENCE_TIERS)[number];
+/** A requirement the matrix can demand. */
+export type A11yRequirementId = (typeof A11Y_EVIDENCE_REQUIREMENTS)[number]["id"];
+/**
+ * One declared piece of evidence. A plain string is a repository-root-relative
+ * path the gate verifies exists; an object is the same path plus the `because`
+ * a tier the role's row does not demand must carry.
+ */
+export type A11yEvidenceEntry = string | {
+    path: string;
+    because?: string;
+};
+/**
+ * The sidecar — the declared claim `packages/<tier>/<name>/a11y.json` must
+ * satisfy. `basis` is the reviewer's handle on the role claim: the rendered
+ * element or injected role that makes it true. `evidence` is keyed by tier,
+ * because the tiers are what the sweep, harness and jsdom run over — a
+ * requirement is answered by its tier's evidence, not by a per-rule file
+ * list. `exceptions` carries the matrix requirements nothing answers yet,
+ * each with the reason it is missing.
+ */
+export interface A11yContract {
+    /** The claimed role, from {@link A11Y_ROLES}. */
+    role: A11yRole;
+    /** The rendered fact the role claim rests on — what a reviewer checks. */
+    basis: string;
+    /** Evidence that exists today, by tier. Paths are repository-root-relative. */
+    evidence: Partial<Record<A11yEvidenceTier, readonly A11yEvidenceEntry[]>>;
+    /** Matrix requirements this component does not answer yet, each with its reason. */
+    exceptions?: readonly {
+        requirement: A11yRequirementId;
+        because: string;
+    }[];
+}
+/**
+ * The closed interaction-class vocabulary — the second axis of the same
+ * sidecar, kept in this file so the two claims cannot drift apart. Each word
+ * names the interaction contract the component OWNS, which is a smaller thing
+ * than the interaction it makes possible: a layout slots buttons into itself,
+ * but it owns none of their contract.
+ *
+ * - `interactive` — ONE operable target of the component's own: activate,
+ *   adjust, type into. A button, a checkbox, a text field, a link.
+ * - `composite` — SEVERAL operable parts the component manages as one: the
+ *   traversal among them, the focus routing, the open/close state. A
+ *   combobox, a tablist, a menu, a dialog, a tree.
+ * - `container` — operates nothing itself; its own contract is the surface it
+ *   puts around operable content. Keyboard passage through it must not trap,
+ *   and its own scroll, collapse or resize behaviour must answer the keyboard
+ *   too. A card, a scroll area, an app shell, a fieldset.
+ * - `visual-only` — presents and wraps; nothing in it operates, takes focus
+ *   or reports an interactive state of its own, by design. A skeleton, a
+ *   badge, a meter, a flex wrapper.
+ *
+ * Two revealed surfaces that look like twins land in different classes on
+ * purpose: a hover-card is `container` and a tooltip is `visual-only`. The
+ * hover-card keeps a real, focusable, dismissible surface around content a
+ * reader operates into; the tooltip is an announcement with nothing inside
+ * it to operate. A component that could sit in either row takes the class
+ * that demands more — the conservative direction costs a duty, the lenient
+ * one forgives one.
+ *
+ * The class is declared, not derived, for the reason the role claim is: the
+ * class is a fact about the contract the component's source owns, and no
+ * reader can reconstruct it with confidence. Each sidecar's interaction claim
+ * carries a `basis` naming the fact that puts the component in its class —
+ * the reviewer's handle, the same one the role claim keeps.
+ */
+export declare const INTERACTION_CLASSES: readonly ["interactive", "composite", "container", "visual-only"];
+/**
+ * The two runtimes that can witness an interaction duty. Same tiers, same
+ * vocabulary, as {@link A11Y_EVIDENCE_TIERS} — a keypress is a browser fact
+ * and a rendered state is a jsdom fact, exactly as the role axis has it. The
+ * sweep tier is absent on purpose: no duty below is a page-geometry fact, so
+ * a sweep citation would be evidence by adjacency, which is the fabricated
+ * kind.
+ */
+export declare const INTERACTION_EVIDENCE_TIERS: readonly ["browserless", "harness"];
+/**
+ * The interaction duties — one row per family of interaction obligations,
+ * named for the obligation rather than the implementation. `tier` is where
+ * the duty must be ANSWERED; `answers` is prose rather than a rule list,
+ * because no axe rule judges an interaction contract — these duties are what
+ * the component's own specs exist to witness.
+ *
+ * Three duties, and no reduced-motion row — a deliberate absence, recorded
+ * rather than hidden. Animation is a per-component fact none of the four
+ * class words carries, and the root reduced-motion suite reaches four pages
+ * today (dialog, drawer, toast, skeleton), so a class row demanding it would
+ * be a duty nothing in the vocabulary could answer honestly. A per-component
+ * motion duty — a declared `animates` fact answered through that suite's
+ * growing population — is the tranche work this axis opens; it lands as a row
+ * edit plus suite growth in one PR, the way every other row change must.
+ */
+export declare const INTERACTION_REQUIREMENTS: readonly [{
+    readonly id: "keyboard-operate";
+    readonly tier: "harness";
+    readonly answers: readonly ["the component's keyboard contract — its own keys, or keyboard passage through its surface — witnessed as gestures in a browser by its own harness spec (WCAG 2.1.1)"];
+}, {
+    readonly id: "state-report";
+    readonly tier: "browserless";
+    readonly answers: readonly ["the states a component renders — disabled, readonly, busy, expanded, selected — reaching the DOM where the unit tier can pin them (WCAG 4.1.2)"];
+}, {
+    readonly id: "keyboard-inert";
+    readonly tier: "browserless";
+    readonly answers: readonly ["the absence of an interaction surface: nothing in a visual-only component takes focus or a key (WCAG 2.1.1 vacuously, 2.4.3 actually) — a pin of absence, worthless asserted in prose"];
+}];
+/**
+ * The interaction matrix: the class's row is the claim it must satisfy, the
+ * role matrix's discipline on the second axis. `keyboard-inert` is
+ * visual-only's whole row because "nothing operates here" is itself a
+ * contract — the one an aria-hidden placeholder that steals a tab stop breaks
+ * — and an absence nobody pins is an absence nobody would notice breaking.
+ */
+export declare const INTERACTION_MATRIX: readonly [{
+    readonly class: "interactive";
+    readonly requirements: readonly ["keyboard-operate", "state-report"];
+}, {
+    readonly class: "composite";
+    readonly requirements: readonly ["keyboard-operate", "state-report"];
+}, {
+    readonly class: "container";
+    readonly requirements: readonly ["keyboard-operate"];
+}, {
+    readonly class: "visual-only";
+    readonly requirements: readonly ["keyboard-inert"];
+}];
+/** A member of the closed interaction-class vocabulary. */
+export type InteractionClass = (typeof INTERACTION_CLASSES)[number];
+/** A runtime that can witness an interaction duty. */
+export type InteractionEvidenceTier = (typeof INTERACTION_EVIDENCE_TIERS)[number];
+/** A duty the interaction matrix can demand. */
+export type InteractionRequirementId = (typeof INTERACTION_REQUIREMENTS)[number]["id"];
+/**
+ * One declared piece of interaction evidence. A plain string is a
+ * repository-root-relative path the gate verifies exists; an object is the
+ * same path plus the `because` that narrows what the file witnesses — and a
+ * qualified entry answers no duty.
+ */
+export type InteractionEvidenceEntry = string | {
+    path: string;
+    because?: string;
+};
+/**
+ * The `interaction` claim `packages/<tier>/<name>/a11y.json` carries beside
+ * its `role` claim — the second axis in the same sidecar, not a second file,
+ * the reservation at the top of this file kept. Same doctrine as the role
+ * claim: declared, cited where the evidence exists, and excepted with a
+ * reason where it does not, so the contract lands truthfully and shrinks as
+ * the harness-spec tranche lands.
+ */
+export interface InteractionContract {
+    /** The claimed interaction class, from {@link INTERACTION_CLASSES}. */
+    class: InteractionClass;
+    /** The fact the class claim rests on — what a reviewer checks. */
+    basis: string;
+    /** Evidence that exists today, by tier. Paths are repository-root-relative. */
+    evidence: Partial<Record<InteractionEvidenceTier, readonly InteractionEvidenceEntry[]>>;
+    /** Matrix duties this component does not answer yet, each with its reason. */
+    exceptions?: readonly {
+        requirement: InteractionRequirementId;
+        because: string;
+    }[];
+}
+//# sourceMappingURL=a11y-contract.d.ts.map

package/dist/packages/core/src/a11y-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y-contract.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/a11y-contract.ts"],"names":[],"mappings":"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"}

package/dist/packages/core/src/a11y-scope.d.ts

@@ -5,15 +5,83 @@
  * the document is the consumer's to answer, not ours.
  *
  * Single source for every axe run against this package, and there is more
- * than one, in different processes: the documentation site's live
- * accessibility panel and the end-to-end gate that scans the built site. Both
- * import this. The list must never be restated, or the panel a contributor
- * reads and the gate that blocks the merge drift into disagreeing about what
- * counts as a violation.
+ * than one, in different processes: the jsdom demo sweep, the harness gate,
+ * the root gate that scans the built site, and the pin tests that hold the
+ * partition exact. All import this. The list must never be restated, or the
+ * tier a contributor reads and the gate that blocks the merge drift into
+ * disagreeing about what counts as a violation.
  *
  * Exported from the narrow `@ecoma-io/loom/a11y` entry so a tool that only
  * needs this array — a Playwright run, a CI script — can read it without
  * pulling in a single Vue component.
+ *
+ * The array is partitioned into BROWSERLESS_RULES, BROWSER_REQUIRED_RULES, and
+ * TAGGED_BUT_DISABLED_RULES. The split line between the first two is whether a rule's
+ * checks read layout geometry, hit-testing, pseudo-element or computed-color resolution,
+ * cascade-dependent font metrics, canvas, or media state — none of which the jsdom demo
+ * tier provides. TAGGED_BUT_DISABLED holds the WCAG-tagged rules that axe-core 4.12.1
+ * ships with enabled:false; a tag-type runOnly (the old gate: withTags([...WCAG_TAGS]))
+ * excludes them, so they were never part of the tag-selected rule set. A rule-type
+ * runOnly (the gates that consume these lists: withRules([...list])) RUNS any named
+ * rule regardless of enabled status.
+ *
+ * Loom's bar is that a rule mapping to a Level A or AA success criterion stays out of
+ * the runtime tiers only when it is SUPERSEDED (another rule in the tiers already
+ * judges the same criterion) or OUT-OF-REACH (the criterion needs something this
+ * repository cannot supply) — "axe ships it disabled" is not a reason. The partition
+ * below is the result of that review, 2026-08-26: of the 7 disabled rules, 5 were
+ * adopted (aria-roledescription browserless; label-content-name-mismatch, p-as-heading,
+ * table-fake-caption and td-has-header browser-required — the findings on loom's own
+ * markup were fixed in the same change) and 2 remain out, each with its criterion and
+ * its reason written below.
+ *
+ * The runtime tiers hold 68 of the 70 WCAG-tagged rules: BROWSERLESS_RULES (51) ∪
+ * BROWSER_REQUIRED_RULES (17). The union of all three sets equals the full 70, which
+ * is pinned by packages/core/tests/a11y-scope.test.ts.
  */
 export declare const WCAG_TAGS: readonly ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"];
+/**
+ * Rules that can be judged in jsdom — semantic checks that read only the DOM,
+ * attributes, and cascade (no layout geometry, hit-testing, pseudo-elements,
+ * computed colors, canvas, or media state).
+ *
+ * These 51 rules are verified to produce identical verdicts in jsdom 30 and
+ * Chromium on violation fixtures, and to agree on every demo the sweep
+ * covers (it globs the demos directory, so the comment names no count).
+ * Each entry was classified by scanning its check helpers for browser-API
+ * dependencies; the partition is pinned by
+ * packages/core/tests/a11y-scope.test.ts.
+ */
+export declare const BROWSERLESS_RULES: readonly ["area-alt", "aria-allowed-attr", "aria-braille-equivalent", "aria-command-name", "aria-conditional-attr", "aria-deprecated-role", "aria-hidden-body", "aria-input-field-name", "aria-meter-name", "aria-progressbar-name", "aria-prohibited-attr", "aria-required-attr", "aria-required-children", "aria-required-parent", "aria-roledescription", "aria-roles", "aria-tab-name", "aria-toggle-field-name", "aria-tooltip-name", "aria-valid-attr", "aria-valid-attr-value", "autocomplete-valid", "blink", "button-name", "definition-list", "dlitem", "document-title", "duplicate-id-aria", "form-field-multiple-labels", "frame-title", "frame-title-unique", "html-has-lang", "html-lang-valid", "html-xml-lang-mismatch", "image-alt", "input-button-name", "input-image-alt", "label", "link-name", "list", "listitem", "meta-refresh", "meta-viewport", "nested-interactive", "role-img-alt", "select-name", "server-side-image-map", "summary-name", "svg-img-alt", "valid-lang", "video-caption"];
+/**
+ * Rules that require a rendering engine — their checks (or, for the table
+ * rules, their `matches` predicate) read layout geometry, hit-test results,
+ * pseudo-element styles, computed color pipelines, cascade-dependent font
+ * metrics, canvas, or media state (src, currentSrc, plays), which jsdom does
+ * not provide — or which the jsdom demo tier cannot judge because it mounts
+ * demos with no stylesheet loaded.
+ *
+ * These 17 rules are what the browser gates run. The split is:
+ * - 11 rendering-dependent (geometry, hit-testing, computed colors, canvas, media, iframe content)
+ * - 2 conservative-partial (table rules whose `matches` predicate uses border
+ *   geometry; kept in browser until Table semantic markup is pinned)
+ * - 4 adopted 2026-08-26 from TAGGED_BUT_DISABLED (see their own comments)
+ */
+export declare const BROWSER_REQUIRED_RULES: readonly ["aria-hidden-focus", "avoid-inline-spacing", "bypass", "color-contrast", "frame-focusable-content", "link-in-text-block", "marquee", "no-autoplay-audio", "object-alt", "scrollable-region-focusable", "target-size", "td-headers-attr", "th-has-data-cells", "label-content-name-mismatch", "p-as-heading", "table-fake-caption", "td-has-header"];
+/**
+ * WCAG-tagged rules that axe-core 4.12.1 ships with enabled: false and that
+ * stay OUT of the runtime tiers — each with its success criterion and the
+ * OUT-OF-REACH reason, per the review of 2026-08-26. A disabled rule may only
+ * sit here if the criterion needs something this repository cannot supply;
+ * "axe ships it disabled" is not a reason, and neither is a finding on loom's
+ * own markup (that gets fixed and the rule adopted — the other five disabled
+ * rules went exactly that way).
+ *
+ * Naming one of these in a rule-type runOnly would run it anyway (enabled
+ * status does not gate withRules), which is why they live in their own list
+ * rather than being deleted: the union pin in packages/core/tests/
+ * a11y-scope.test.ts keeps the 70-rule partition exact, and a future
+ * component that reaches one of these criteria re-adjudicates here.
+ */
+export declare const TAGGED_BUT_DISABLED_RULES: readonly ["audio-caption", "css-orientation-lock"];
 //# sourceMappingURL=a11y-scope.d.ts.map

package/dist/packages/core/src/a11y-scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"a11y-scope.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/a11y-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,mEAAoE,CAAC"}
+{"version":3,"file":"a11y-scope.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/a11y-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,SAAS,mEAAoE,CAAC;AAE3F;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,u9BAgEpB,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,+VAoCzB,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,oDAsB5B,CAAC"}

package/dist/packages/core/src/index.d.ts

@@ -1,8 +1,14 @@
 export { cn } from "./cn";
 export { optional } from "./props";
 export { useSplitAttrs } from "./attrs";
-export { LIST_STAGGER_CAP, LIST_STAGGER_STEP_MS, listStaggerDelay, smoothScrollBehavior, } from "./motion";
-export { WCAG_TAGS } from "./a11y-scope";
+export { EMPTY_STATE_STAGGER_STEP_MS, LIST_STAGGER_CAP, LIST_STAGGER_STEP_MS, listStaggerDelay, smoothScrollBehavior, staggerDelay, } from "./motion";
+export { WCAG_TAGS, BROWSERLESS_RULES, BROWSER_REQUIRED_RULES } from "./a11y-scope";
+export { A11Y_EVIDENCE_TIERS, A11Y_EVIDENCE_REQUIREMENTS, A11Y_EVIDENCE_MATRIX, ARIA_ROLES, NON_ROLE_MEMBERS, A11Y_ROLES, } from "./a11y-contract";
+export type { A11yContract, A11yRole, AriaRole, A11yEvidenceTier, A11yRequirementId, A11yEvidenceEntry, } from "./a11y-contract";
+export { RESPONSIVE_BEHAVIOURS, RESPONSIVE_EVIDENCE_TIERS, RESPONSIVE_VIEWPORT_BANDS, } from "./responsive-contract";
+export type { ResponsiveBehaviour, ResponsiveEvidenceTier, ResponsiveViewportBand, ResponsiveEvidenceEntry, ResponsiveContract, } from "./responsive-contract";
+export { INTERACTION_CLASSES, INTERACTION_EVIDENCE_TIERS, INTERACTION_REQUIREMENTS, INTERACTION_MATRIX, } from "./a11y-contract";
+export type { InteractionClass, InteractionEvidenceTier, InteractionRequirementId, InteractionEvidenceEntry, InteractionContract, } from "./a11y-contract";
 export { useTheme, themeScript } from "./theme";
 export type { ThemePreference, ResolvedTheme } from "./theme";
 export { applyLoomIconDefaults } from "./icon-defaults";

package/dist/packages/core/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;AAG1B,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;AAG1B,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EACL,2BAA2B,EAC3B,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,GACb,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAKpF,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/packages/core/src/motion.d.ts

@@ -1,14 +1,23 @@
 /**
- * The list-reveal stagger vocabulary — one source for every overlay that
- * reveals rows (DropdownMenu, Menubar, Select) and for the Motion
- * documentation page. Each revealed row is delayed one step after the
- * previous, capped so a long list does not tail off indefinitely.
+ * The stagger vocabularies — one source for every sequence that reveals
+ * element after element. The list family (DropdownMenu, Menubar, Select, the
+ * Motion documentation page) steps quickly and caps, so a long list does not
+ * tail off indefinitely; the empty-state family steps slower because it
+ * stages three fixed regions — icon, title, description, action — rather than
+ * an unbounded row set, and a cap would be dead weight over a sequence that
+ * cannot grow.
  *
- * It lives here rather than in each template because it was written into
- * three of them independently once, which is how the three drifted.
+ * They live here rather than in each template because a stagger was written
+ * into three of them independently once, which is how the three drifted —
+ * and because the token gate holds every other duration to the theme's
+ * vocabulary, so a duration family with one writer each would be exactly the
+ * second home for a visual decision the law exists to prevent.
  */
 export declare const LIST_STAGGER_STEP_MS = 24;
 export declare const LIST_STAGGER_CAP = 5;
+export declare const EMPTY_STATE_STAGGER_STEP_MS = 60;
+/** The inline `animation-delay` for the i-th element of a `step`-staggered sequence. */
+export declare function staggerDelay(i: number, step: number): string;
 /** The inline `animation-delay` for the i-th revealed row. */
 export declare function listStaggerDelay(i: number): string;
 /**

package/dist/packages/core/src/motion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/motion.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,QAAQ,CAOxD"}
+{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/motion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,QAAQ,CAOxD"}