Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): define accessibility spec tests and migration (#5990)

Cindy Zhang1252020cd83a
diff --git a/docs/specs/AST-020/spec.md b/docs/specs/AST-020/spec.md
new file mode 100644
index 0000000000..c4d93176f8
--- /dev/null
+++ b/docs/specs/AST-020/spec.md
@@ -0,0 +1,267 @@
+---
+schema_version: 1
+template_version: 1
+kind: system-spec
+id: spec:AST-020
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-03
+phase: accepted
+owners: [cixzhang]
+affects_architecture: []
+affects_families: []
+affects_contributing: []
+affects_consumer_docs: []
+---
+
+# Accessibility spec-test authoring system spec
+
+## Intent
+
+People using Astryx components should get the keyboard, focus, meaning, and state
+promised by [WCAG 2.2](https://www.w3.org/TR/WCAG22/) and the
+[WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) widget pattern
+Astryx adopts. Reusable accessibility spec tests turn those promises into
+reviewable contracts instead of requiring each component author to reinterpret
+the standards.
+
+A spec test states one user-observable requirement, cites its source, names the
+evidence layer that can prove it, and runs unchanged against every conforming
+binding. The test suite complements axe, browser checks, and assistive-technology
+review. It does not claim that one automated pass proves complete accessibility.
+
+## Non-goals
+
+- Implementing the spec-test package or CI jobs in this specification pull request.
+- Defining how existing component tests migrate; that is owned by
+ [AST-021](../AST-021/spec.md).
+- Publishing the first implementation as a supported package.
+- Reimplementing axe rules or replacing browser, visual, manual, or real-AT
+ verification.
+- Treating WAI-ARIA Authoring Practices as a substitute for WCAG conformance.
+- Using the WCAG 3.0 working draft as a pass/fail baseline before it is ready.
+- Encoding page-owned requirements in an isolated component contract when the
+ component cannot satisfy them.
+
+## Requirements
+
+### Normative basis and scope
+
+- **FR1 — WCAG 2.2 A and AA are the conformance baseline.** Every WCAG
+ conformance expectation MUST cite an applicable WCAG 2.2 Level A or AA success
+ criterion. A pattern expectation MAY instead cite an exact APG requirement when
+ APG supplies the interaction detail. In that case it MUST identify the WCAG 2.2
+ user outcome it supports without inventing a success-criterion mapping. WCAG 3.0
+ principles MAY inform plain-language intent, user needs, and future research, but
+ a WCAG 3.0 draft requirement MUST NOT create or clear a pass/fail check without a
+ later current Astryx record.
+- **FR2 — APG defines an adopted widget pattern, not universal conformance.** When
+ Astryx adopts a WAI-ARIA APG pattern, the pattern contract MUST cite the exact APG
+ roles, states, properties, or keyboard interaction it adopts and the WCAG 2.2
+ outcome those mechanics support. A component MAY use another standards-valid
+ model only when its current component, family, or system contract records that
+ choice; the spec test MUST follow the owning contract rather than forcing an APG
+ example mechanically.
+- **FR3 — Contracts have two layers.** Every pattern review MUST consider both:
+ broad component-owned requirements that apply across patterns, and
+ pattern-specific role, state, relationship, keyboard, and focus requirements.
+ A component part may bind to more than one pattern. A whole component MUST NOT be
+ forced into one pattern when its parts have distinct roles.
+
+### Expectation contract
+
+- **FR4 — Every expectation is traceable.** An expectation MUST have a stable id,
+ a short user outcome, an exact normative source (WCAG 2.2 success criterion, APG
+ requirement, current Astryx contract, or an applicable combination),
+ applicability conditions, an evidence layer, and an enforcement class. The test
+ name and failure output MUST expose the expectation id and source reference so a
+ failure can be understood without opening the runner implementation.
+- **FR5 — Applicability is explicit.** For every checklist dimension, an author
+ MUST either encode an applicable expectation or record why the dimension is not
+ owned by this pattern, binding, or evidence layer. Silence is not an exemption.
+ An exemption MUST name the actual owner or verification method; it MUST NOT be a
+ generic “not applicable” escape hatch.
+- **FR6 — Evidence layers keep distinct proof boundaries.** Expectations are
+ classified as unit, DOM, accessibility-tree, axe, real-browser, visual, lint,
+ manual, or real-AT checks. A lower layer MUST NOT claim a result only a higher
+ layer observes. Announcement wording or timing, virtual-cursor entry, and known
+ AT/browser divergence follow [AST-009](../AST-009/spec.md); an accessibility-tree
+ snapshot does not satisfy that real-AT contract.
+- **FR7 — Contracts assert outcomes, not Astryx internals.** A reusable expectation
+ MUST query and act through public semantics and observable behavior. It MUST NOT
+ depend on Astryx class names, private DOM wrappers, implementation callbacks, or
+ source layout unless an owning current record makes that structure contractual.
+ Component-specific API effects remain in component tests.
+- **FR8 — Interactive expectations prove the complete transition.** Keyboard,
+ pointer, state, and focus expectations MUST exercise the relevant starting state,
+ action, resulting state, and reverse or dismissal path when the pattern supports
+ one. Merely finding a role or proving one direction of a toggle is insufficient.
+- **FR9 — Enforcement is separate from severity and tool coverage.** A directly
+ applicable WCAG 2.2 Level A or AA expectation is `required`. An APG or
+ Astryx-specific expectation is `required` only when a current Astryx record adopts
+ that outcome. `Advisory` expectations report best practice, an unsettled choice,
+ or an outcome not yet adopted as an Astryx contract. `Advisory` expectations
+ report only; `required` expectations gate new or changed behavior at a layer that
+ can objectively verify them. A coverage score, tool capability, or ease of
+ automation MUST NOT promote or demote either class.
+
+### Completeness and review
+
+- **FR10 — Every pattern uses one completeness review.** The review starts with
+ the source map below, then adds applicable WCAG 2.2 component outcomes such as
+ focus not obscured, status messages, target size, contrast, forced colors, and
+ the pattern's APG interactions. Page-owned rows are considered only for fixtures
+ or surfaces that own a page. Every row follows FR5 and FR6 rather than being
+ forced into the reusable runtime contract.
+
+| WCAG 2.2 source | Outcome to consider | Usual ownership |
+| ----------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------- |
+| 1.1.1 Non-text Content | Informative non-text content has an equivalent alternative; decorative content is ignored. | Component or content |
+| 1.3.1 Info and Relationships | Visual structure and relationships are programmatically available. | Component or composition |
+| 1.3.2 Meaningful Sequence | Programmatic reading sequence preserves meaning. | Component or composition |
+| 1.4.1 Use of Color | Color is not the only way to convey information or state. | Component, theme, and caller content |
+| 1.4.3 Contrast (Minimum) | Text and images of text meet the required contrast. | Component and theme |
+| 1.4.11 Non-text Contrast | Controls, states, and meaningful graphics meet non-text contrast. | Component and theme |
+| 2.1.1 Keyboard | Every component-owned function is operable by keyboard. | Component |
+| 2.1.2 No Keyboard Trap | Keyboard focus can leave any component unless the user has a documented exit. | Component or composition |
+| 2.4.2 Page Titled | A page has a descriptive title. | Page only |
+| 2.4.3 Focus Order | Sequential focus preserves meaning and operation. | Component or composition |
+| 2.4.4 Link Purpose (In Context) | A link's purpose is determinable. | Component and caller content |
+| 2.4.6 Headings and Labels | Headings and labels describe their topic or purpose. | Component and caller content |
+| 2.4.7 Focus Visible | Keyboard focus has a visible indicator. | Component and theme |
+| 2.4.11 Focus Not Obscured (Minimum) | Focused content is not entirely hidden by author-created content. | Component or composition |
+| 2.5.8 Target Size (Minimum) | Pointer targets meet the minimum size or an allowed exception. | Component or composition |
+| 3.1.1 Language of Page | The page language is programmatically available. | Page only |
+| 3.2.4 Consistent Identification | Repeated functions are identified consistently. | System, component, and caller content |
+| 3.3.2 Labels or Instructions | Inputs have persistent labels or needed instructions. | Component and caller content |
+| 4.1.2 Name, Role, Value | Name, role, state, value, and changes are programmatically available. | Component |
+| 4.1.3 Status Messages | Status changes are exposed without moving focus. | Component or composition |
+
+- **FR11 — The contract itself has positive and negative proof.** Each expectation
+ MUST pass against a minimally conforming fixture or binding and fail when its
+ required outcome is deliberately removed. Pattern-level tests MUST distinguish a
+ real violation from an unsupported harness operation or fixture error.
+- **FR12 — Completion requires an independent accessibility review.** A pattern is
+ complete only when every checklist dimension is encoded or explicitly assigned
+ elsewhere, all expectations are traceable, representative bindings pass or expose
+ exact known gaps, mutation evidence proves required expectations can fail, and an
+ accessibility subject-matter reviewer finds no unaccounted contract-encodable
+ requirement.
+- **FR13 — The pull request describes the spec test in readable form.** A new or
+ materially changed pattern pull request MUST state who is affected, the adopted
+ pattern and scope, the expectation table with source and evidence layer, explicit
+ exemptions, representative bindings and states, known component gaps, and the
+ mutations or failures that prove the contract. The description is the readable
+ specification of the test; the executable contract remains the checked source of
+ truth.
+- **FR14 — Stable ids survive refactors.** Renaming files, helpers, or harnesses MUST
+ preserve expectation ids. Splitting, combining, narrowing, or changing the user
+ outcome creates an explicit contract change and migration for every binding and
+ known-gap record that refers to the affected ids.
+
+### Platform support
+
+- Supported feature/engine floor: the affected component's current browser-support
+ contract under [AST-013](../AST-013/spec.md).
+- Unsupported behavior: a harness that cannot observe an assigned evidence layer
+ reports that limitation; it does not pass, skip silently, or substitute a lower
+ layer.
+- Browser evidence: browser-class expectations run in a real shipping engine. A
+ DOM emulator cannot prove focus navigation, native top-layer behavior, computed
+ accessibility-tree exposure, contrast, target geometry, or forced-color paint.
+
+## Current-state impact
+
+[Issue #4112](https://github.com/facebook/astryx/issues/4112) established the
+reusable pattern-contract direction. The closed
+[Switch prototype](https://github.com/facebook/astryx/pull/4113) demonstrated one
+contract running through jsdom and Chromium bindings, source-linked expectation ids,
+and exact known failures. It also showed why axe and pattern contracts are
+complementary: axe finds broad markup violations, while the contract verifies the
+state and interaction that make a switch behave as a switch.
+
+The prototype is evidence, not current policy. Its package name, scoring model,
+priority names, and harness shape remain implementation choices unless this or
+another current record adopts them. This spec keeps the proven contract boundary
+while correcting two risks before scale-out: a numeric score must not stand in for
+conformance, and each expectation must name the evidence layer that can actually
+observe its outcome.
+
+The completeness review incorporates recurrent component-owned failures such as
+text alternatives, semantic relationships and order, focus order and visibility,
+descriptive labels and links, consistent identification, persistent instructions,
+and name/role/value/state. It updates that review to WCAG 2.2 and keeps page-owned,
+browser-owned, and real-AT-owned checks outside a component runtime contract when
+that is the honest boundary.
+
+This accepted spec creates no tests, package, CLI documentation, component behavior,
+or CI gate. Those changes follow in implementation work governed by this record.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| --------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| FR1–FR3 | Source and ownership review against WCAG 2.2, APG, and current Astryx records | component-owned A/AA criterion; page-owned criterion; one component with multiple parts | A draft WCAG 3.0 statement gates CI, an APG example is treated as universal WCAG, or one component is forced into one pattern |
+| FR4–FR9 | Contract schema and runner self-tests | required/advisory; unit/DOM/tree/axe/browser/manual/AT; toggle round trip; component-specific callback | A check lacks a source or layer, passes from an unsupported harness, depends on private markup, or one-way behavior hides a reverse-path failure |
+| FR10–FR12 | Completed checklist, positive/negative fixture suite, and independent review | simple control; composite widget; overlay; page-owned criterion | A dimension disappears silently, a mutation still passes, or review finds an unrecorded contract-encodable requirement |
+| FR13–FR14 | Pull-request template check plus id migration tests | new pattern; narrowed expectation; file-only refactor | Reviewers cannot understand the test from the PR, or an id change orphans bindings and gaps |
+| Platform | Real-browser and AST-009 evidence-boundary checks | focus navigation; accessibility tree; forced colors; announcement timing | jsdom or a tree snapshot is credited with pixels, browser behavior, or spoken output it cannot observe |
+
+### Completion criteria
+
+This spec moves from `accepted` to `shipped` only when:
+
+- the reusable contract schema enforces FR4–FR6 and FR9;
+- the authoring guide and pull-request template implement FR10–FR13;
+- contract self-tests include conforming and deliberately violating fixtures under
+ FR11;
+- at least one pattern runs against representative jsdom and browser bindings
+ without relying on Astryx-private structure;
+- unsupported harness capabilities fail honestly rather than passing or skipping;
+- no aggregate coverage score is presented as proof of conformance; and
+- the shipped guide links AST-009 for real-AT claims and AST-021 for migration.
+
+## Decision log
+
+### DEC-1 — Use WCAG 2.2 for conformance and WCAG 3.0 only for forward-looking intent
+
+**Reference:** `spec:AST-020/DEC-1`
+**Decider:** `cixzhang`, `2026-09-03`
+
+WCAG 2.2 Level A and AA provide the current testable baseline. WCAG 3.0 may help
+frame user needs, assistive-technology experience, and future evaluation, but its
+working draft does not decide current pass/fail results.
+
+Rejected: waiting for WCAG 3.0 or treating a draft outcome as a current conformance
+requirement.
+
+### DEC-2 — Author one reusable outcome contract per adopted pattern
+
+**Reference:** `spec:AST-020/DEC-2`
+**Decider:** `cixzhang`, `2026-09-03`
+
+Separate the standards-derived pattern contract from component bindings. This lets
+multiple components share one interpretation while allowing a component's parts to
+bind to different patterns and keeping component-specific API behavior local.
+
+Rejected: copying APG assertions into every component test or forcing all
+accessibility checks into one global scanner.
+
+### DEC-3 — Make the pull request a readable specification of the executable test
+
+**Reference:** `spec:AST-020/DEC-3`
+**Decider:** `cixzhang`, `2026-09-03`
+
+A reviewer must be able to judge the user outcome, standards basis, evidence layer,
+exemptions, bindings, and mutation proof without reverse-engineering runner code.
+The checked contract remains executable truth; the pull request makes that truth
+reviewable by accessibility specialists and maintainers.
+
+Rejected: code-only review or a generic accessibility checklist with no exact
+mapping to executable expectations.
+
+## Open questions
+
+None.
diff --git a/docs/specs/AST-021/spec.md b/docs/specs/AST-021/spec.md
new file mode 100644
index 0000000000..1336d351b5
--- /dev/null
+++ b/docs/specs/AST-021/spec.md
@@ -0,0 +1,260 @@
+---
+schema_version: 1
+template_version: 1
+kind: system-spec
+id: spec:AST-021
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-03
+phase: accepted
+owners: [cixzhang]
+affects_architecture: []
+affects_families: []
+affects_contributing: []
+affects_consumer_docs: []
+---
+
+# Component accessibility-test migration system spec
+
+## Intent
+
+People using existing Astryx components should gain the same standards-traceable
+protection as new components without waiting for a repository-wide rewrite. Astryx
+migrates accessibility assertions progressively into reusable spec-test contracts,
+locks in behavior that already passes, and exposes each existing failure as owned
+work instead of hiding it behind missing or skipped tests.
+
+Migration separates shared pattern behavior from component-specific behavior. A
+component binding says which pattern and states it implements. The reusable contract
+owns the shared WCAG 2.2/APG outcome; the component suite keeps API, composition, and
+implementation-specific regression coverage.
+
+## Non-goals
+
+- Defining how accessibility spec tests are authored; that is owned by
+ [AST-020](../AST-020/spec.md).
+- Fixing every accessibility defect in the same pull request that reveals it.
+- Deleting component-specific tests merely because they mention ARIA or keyboard
+ input.
+- Treating a known failure, skipped expectation, or high coverage percentage as a
+ passing accessibility result.
+- Blocking all existing components on every historical gap before migration can
+ begin.
+- Migrating page-level, visual, or real-AT requirements into a component runtime
+ contract that cannot prove them.
+
+## Requirements
+
+### Migration inventory and unit of work
+
+- **FR1 — Migration depends on the authoring contract.** This spec MUST NOT become
+ `current` before AST-020 is `current`. Every migrated pattern and binding MUST
+ satisfy AST-020's traceability, applicability, evidence-layer, review, and
+ readable-pull-request requirements.
+- **FR2 — Inventory precedes deletion.** Before changing tests for a component, the
+ migration MUST record each interactive part, its adopted pattern or patterns,
+ representative states, existing shared-pattern assertions, component-specific
+ assertions, assigned evidence layers, and known failures. A component with
+ multiple interactive parts MUST map each part separately.
+- **FR3 — Migration pull requests stay bounded.** A pull request SHOULD add or
+ materially revise one reusable pattern contract and its first representative
+ bindings, or migrate one bounded set of bindings to an already-current contract.
+ It MUST NOT combine unrelated patterns, broad component remediation, or visual
+ redesign merely to raise coverage.
+- **FR4 — Representative states are explicit.** Each binding MUST cover every
+ component state that can change the adopted pattern outcome. Depending on the
+ component, that includes default and changed value, controlled and uncontrolled,
+ enabled and disabled, focusable-disabled, required or invalid, open and closed,
+ orientation, direction, loading, error, and relevant composed parts. The inventory
+ records why omitted states cannot change the shared outcome.
+
+### Moving and retaining coverage
+
+- **FR5 — Move only equivalent assertions.** An existing test moves into the shared
+ contract only when its user outcome, applicability, and evidence layer are the
+ same for every binding. Tests for callback payloads, public props, form submission,
+ component-owned composition, styling, or a deliberate component exception remain
+ local even when they also inspect ARIA or keyboard events.
+- **FR6 — Duplicate ownership ends in the migration pull request.** Once a contract
+ and binding prove an existing shared outcome at the same or stronger layer, the
+ exact local assertion MUST be removed or rewritten to cover only the remaining
+ component-specific contract. Temporary duplication requires a named removal
+ blocker; “extra coverage” is not a permanent reason to keep two owners.
+- **FR7 — Existing behavior is preserved unless a separate change authorizes it.**
+ A migration pull request records observed failures but does not silently change
+ component API, interaction, focus, semantics, visuals, or compatibility. A small
+ prerequisite fix may land first or in a separately reviewable commit and pull
+ request under its owning current records.
+
+### Known failures and regression gates
+
+- **FR8 — Every known failure is exact and actionable.** A known-failure record MUST
+ name the expectation id, component binding and state, observed user impact,
+ standards reference, evidence layer, public tracking issue, and reason the
+ migration does not fix it. Wildcards, whole-pattern suppression, and unowned text
+ reasons are prohibited.
+- **FR9 — A known failure changes only its exact gate result.** A binding with a
+ known failure still runs the expectation and reports `known-failure`, never
+ `pass`. Only that exact expected result stops gating the first migration. A
+ different error, another state, a new expectation, or a wider failure MUST fail.
+ When the expectation starts passing, CI MUST report an unexpected pass and
+ require removal of the stale record rather than continuing to count it as debt.
+- **FR10 — Migration locks the baseline without calling debt conformance.** Required
+ expectations that pass gate immediately for that binding. Recorded historical
+ failures remain visibly failing debt but do not prevent the first migration.
+ New components and newly supported states MUST NOT add a required known failure.
+ Adding or widening a known failure after the baseline requires an explicit owner
+ decision and linked defect; it is not a routine test update.
+- **FR11 — Reports show facts, not one quality score.** Coverage output MUST report
+ patterns, bindings, applicable expectations, passes, known failures, unrun layers,
+ and exemptions separately. It MUST NOT collapse those states into one percentage
+ or grade presented as component accessibility or conformance. A pattern with one
+ required failure is not “mostly conformant.”
+
+### Repository integration and review
+
+- **FR12 — Current component records point to the new owner.** When a migrated
+ component has a current component or module record, its `verified_by` metadata and
+ verification map MUST name the binding and keep separate evidence for outcomes the
+ shared contract does not own. Migration does not create a component record solely
+ to satisfy this backlink.
+- **FR13 — New work uses an existing contract first.** Once a pattern contract is
+ current, a new component or newly added component part that adopts that pattern
+ MUST bind to it from its first implementation. Authors MUST NOT create a parallel
+ ad hoc copy of the shared assertions. If the contract is incomplete, extend and
+ review the contract before relying on local tests.
+- **FR14 — The migration pull request is a readable ledger.** Its description MUST
+ name the affected users and pattern, component parts and states bound, assertions
+ moved, local tests retained and why, exact known failures and linked issues,
+ evidence layers run, and mutation or before/after evidence. The description MUST
+ distinguish test migration from component remediation.
+- **FR15 — Progress is ordered by user leverage.** The first binding remains the
+ Switch reference proven by the prototype. Later work prioritizes widely reused
+ interactive patterns, components with known keyboard/focus/semantic failures, and
+ shared primitives whose correction protects multiple components. Repository order
+ or ease of producing a high count MUST NOT override user impact.
+
+### Platform support
+
+- Supported feature/engine floor: each binding follows its component's current
+ support contract and AST-020's assigned evidence layer.
+- Unsupported behavior: an unrun browser, visual, manual, or real-AT layer remains
+ explicitly unrun; jsdom success does not clear it.
+- Browser evidence: component changes that can affect browser-owned pattern behavior
+ run the relevant real-browser binding. Real-AT outcomes follow
+ [AST-009](../AST-009/spec.md) and keep their durable receipts and release boundary.
+
+## Current-state impact
+
+Current component suites mix shared accessibility outcomes with public API,
+implementation, visual, and regression tests. For example, Switch currently tests
+role, accessible name and description, checked and disabled states, activation,
+form participation, loading and error semantics, disabled-reason composition,
+forced-color CSS, callback payloads, and layout details in one file. The shared
+Switch pattern can own only the standards-derived role, name, state, focusability,
+and activation outcomes. Form data, callback payloads, tooltip composition, and
+component styling remain Switch-owned.
+
+[Issue #4112](https://github.com/facebook/astryx/issues/4112) and the closed
+[Switch prototype](https://github.com/facebook/astryx/pull/4113) prove that an
+existing component can bind to one reusable contract in jsdom and Chromium. The
+prototype's `expectedFailures` mechanism is retained only with FR8–FR10's exactness:
+a known failure is visible debt, never a pass or a broad skip.
+
+The accessibility program tracker
+[#4475](https://github.com/facebook/astryx/issues/4475) remains the public place to
+order pattern migrations and component defects. Migration pull requests add newly
+found defects there or to focused public issues. They do not depend on a private
+backlog or private review link.
+
+### Progressive rollout
+
+1. **Reference pattern.** Rebuild the Switch prototype under current AST-020 types,
+ self-tests, evidence boundaries, and reporting. Bind the current Switch states
+ without changing behavior.
+2. **Simple controls.** Migrate other single-control patterns where role, name,
+ state, disabled behavior, and keyboard activation can be isolated cleanly.
+3. **Composite widgets.** Migrate selection, navigation, grid, tree, and menu parts
+ with orientation, direction, roving focus, typeahead, and open/closed states.
+4. **Overlays and async outcomes.** Add browser-owned focus, top-layer, inert, and
+ dismissal checks, while routing announcement and virtual-cursor claims through
+ AST-009.
+
+The tracker may reorder components within these phases by user impact. A later phase
+MUST NOT weaken the evidence boundaries or known-failure rules to increase throughput.
+
+This accepted spec changes no component test, behavior, package, public API, or CI
+gate. Those changes follow in implementation work governed by this record.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| --------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR4 | Migration inventory schema and review | one control; component with trigger and popup; controlled/disabled/error/RTL states | Migration starts without an applicable current contract, treats a whole component as one part, or omits a state that changes semantics |
+| FR5–FR7 | Before/after assertion ownership review and unchanged component suites | shared role/state check; callback payload; form data; style rule; discovered component defect | Shared assertion remains duplicated, component-specific proof is deleted, or migration silently changes behavior |
+| FR8–FR10 | Runner tests for exact known failures, new failures, and unexpected passes | one historical gap; wrong error; second state; fixed expectation | A wildcard masks regression, a stale gap remains, or new work adds debt without decision |
+| FR11 | Coverage-report snapshot and assertions | pass; known failure; exemption; unrun browser layer | One percentage hides a required failure or reports an unrun layer as pass |
+| FR12–FR14 | Knowledge validation, component verification map, and PR-template check | current component record; component with no record; first new adopter | Backlink points to deleted local tests, parallel ad hoc assertions appear, or the PR hides migration/remediation scope |
+| FR15 | Public tracker review | high-use control; known keyboard defect; easy low-impact component | Work is ordered only to maximize migrated counts |
+| Platform | Existing unit/axe/browser checks plus AST-009 classification | jsdom behavior; real focus; tree exposure; spoken announcement | A lower layer clears browser pixels or real-AT output it cannot observe |
+
+### Completion criteria
+
+A pattern migration is complete only when:
+
+- its contract is current under AST-020 and passes its positive and negative
+ self-tests;
+- every affected component part and relevant state has a binding or an explicit
+ ownership reason for exclusion;
+- equivalent shared assertions have one owner and component-specific tests remain;
+- every historical failure has the exact public debt record required by FR8;
+- required passing expectations gate regressions and unexpected passes remove stale
+ debt;
+- reporting separates passes, known failures, exemptions, and unrun layers;
+- current component or module records point to the new binding when those records
+ exist; and
+- the pull request presents the readable migration ledger required by FR14.
+
+The repository migration is complete only when every shipped interactive component
+part is mapped to a current pattern contract or explicitly records why no reusable
+pattern applies, and no duplicate ad hoc test remains for a shared expectation.
+
+## Decision log
+
+### DEC-1 — Migrate progressively with exact known failures
+
+**Reference:** `spec:AST-021/DEC-1`
+**Decider:** `cixzhang`, `2026-09-03`
+
+Apply contracts one pattern and bounded binding set at a time. Preserve historical
+failures as exact, runnable, public debt while immediately gating outcomes that
+already pass. This adds protection now without pretending existing defects are
+conformant or waiting for a repository-wide remediation.
+
+Rejected: all-or-nothing migration, silent skips, and enabling one broad report-only
+suite that cannot stop regressions.
+
+### DEC-2 — Keep one owner for shared tests and preserve historical failures exactly
+
+**Reference:** `spec:AST-021/DEC-2`
+**Decider:** `cixzhang`, `2026-09-03`
+
+Keep test migration separate from component remediation. Move only reusable
+standards-derived outcomes into pattern contracts; retain component-specific API,
+composition, form, styling, and callback tests with the component. Existing defects
+stay as exact runnable `known-failure` results tied to one expectation, binding,
+state, and public issue. They never count as passing, cannot mask a different or
+wider failure, and become unexpected passes when fixed so stale debt is removed.
+
+Report passes, known failures, exemptions, and unrun layers as separate facts rather
+than averaging them into one accessibility score.
+
+Rejected: changing component behavior inside migration work, deleting
+component-owned tests, broad skips, and a percentage that can make a required
+failure look conformant.
+
+## Open questions
+
+None.