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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.