An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-017): accessibility behavior fixes are not breaking (#7523)
Cindy Zhangafd7e557732e
diff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.mdindex 6025d873ef..9943ec2c3a 100644--- a/docs/specs/AST-017/spec.md+++ b/docs/specs/AST-017/spec.md@@ -48,6 +48,7 @@ affects_consumer_docs: [release-process, templates]"DEC-14","DEC-17","DEC-18",+ "DEC-20","FR3","FR4","FR5",@@ -94,6 +95,7 @@ affects_consumer_docs: [release-process, templates]"FR49","FR50","FR51",+ "FR53","DEC-15","DEC-16"]@@ -163,7 +165,9 @@ one removal merged ahead of the decision to allow it.Its Changeset names the old and new appearance and how to keep the old look when asupported escape exists. A default that changes a functional or semantic contract isjudged under FR1 instead. Its Changeset names the old and new default and the prop or- option that restores the old default, which is the migration.+ option that restores the old default, which is the migration. A change to documented+ interaction or accessibility behavior made for accessibility conformance is+ classified under FR53.- **FR4 — Preserved old usage is nonbreaking.** A rename or replacement isnonbreaking when the old released call, import, option, identifier, or inputcontinues to work with equivalent meaning through a compatibility alias or@@ -176,7 +180,8 @@ one removal merged ahead of the decision to allow it.released faulty behavior must change. When a supported consumer relies on thatbehavior and the correction breaks the consumer, FR32–FR35 classify it as anincompatible fix even though the implementation violated authority. A proposal- that intentionally replaces the documented contract is not a fix.+ that intentionally replaces the documented contract is not a fix, except an+ accessibility behavior fix under FR53.- **FR6 — Risk does not override compatibility.** Low adoption, low likelihood,engineering approval, or confidence that affected callers are uncommon does notmake an incompatible released contract nonbreaking. Conversely, implementation@@ -392,8 +397,8 @@ one removal merged ahead of the decision to allow it.documented markup or selectors, accessibility semantics, persistence, CLI,configuration, schemas, build tooling, contractual documentation operations, andpackage files MUST be additive, implementation-equivalent, a nonbreaking default- change under FR3, or a victim-free contract restoration under FR5; a breaking change- lands only in a declared minor (FR31). Documentation catalog names and routes+ change under FR3, a victim-free contract restoration under FR5, or an accessibility+ behavior fix under FR53; a breaking change lands only in a declared minor (FR31). Documentation catalog names and routesfollowFR45. An internal label, low adoption, or lack of a source-level API change doesnot weaken this rule.@@ -490,11 +495,15 @@ one removal merged ahead of the decision to allow it.the correction breaks code, interaction, persisted data, output, or a supportedworkflow, the correction is `[breaking]` and follows FR31 for the declared tier,stating the corrected contract and the migration. A visible correction with no valid- released victim remains `[fix]` under FR5.+ released victim remains `[fix]` under FR5. An accessibility behavior fix is not a+ breaking correction: FR53 classifies it.- **FR33 — A correction's authority and victim are named.** The `[breaking]`Changeset or its pull request names the pre-existing authority the released behaviorviolated, a latest-stable reproducer, and the migration. Without pre-existingauthority, the proposal is a new contract decision for the direct owner, not a fix.+ For an accessibility behavior fix, the authority is the conformance target FR53+ names, and the owner records any behavior decision the fix needs in the component's+ record.- **FR34 — A correction follows the same tier rule.** In a declared minor a breakingcorrection merges on its `[breaking]` Changeset. When `main` declares a patch, thepatch ships the corrected opt-in or adapter beside the old behavior (FR28) and the@@ -651,6 +660,22 @@ one removal merged ahead of the decision to allow it.until the declaration is strictly above stable. If main already carries a newerowner plan, FR50 preserves it and no duplicate bump is required. The plan remainsmalleable under FR46 until the next cut.+- **FR53 — Accessibility behavior fixes are not breaking.** A change whose purpose is+ to make a released component conform to its accessibility target — a WCAG 2.2 Level+ A or AA success criterion, the required parts of an APG pattern the component adopts+ under `spec:AST-020/FR15`, or a current accessibility requirement in its record — is+ `[fix]` and patch-eligible, even when it replaces documented interaction or+ accessibility behavior: roles, accessible names, states and properties, focus+ movement, and keyboard behavior. No deprecation precedes it and no coexistence path+ is required. An accessibility behavior fix requires no app-layer code change:+ existing public props, types, exports, tokens and documented usage keep working+ unchanged. It may add optional public surface (for example a new optional prop),+ which is not breaking and is admitted under the existing rules for public additions;+ it never removes, renames, or narrows existing surface. It ships as a patch `[fix]`,+ with a release-note line when documented behavior changes; its Changeset names the+ old and new behavior and the accessibility target it serves. A change that would+ require apps to edit code must be redesigned so the component absorbs it, or it is+ classified under FR1.### Platform support@@ -758,29 +783,30 @@ lands, maintainers apply its requirement in review and release approval.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, narrowed type, changed interaction default; unreleased and private surface; visual-only spacing, typography, layout styling, or default appearance | A change is labeled from diff size or possibility alone, a functional contract loss is hidden as visual-only, or a pixel-only change is tagged `[breaking]` even though callers need no source or configuration change |-| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |-| FR7–FR8 | `pnpm check:changesets` (tag, bump, contributors, declared tier) plus FR8 migration review of `[breaking]` text | existing `[fix]`, `[feat]`, `[breaking]`, and `[experimental]` tags paired with compatible, deprecation, planned-removal, or incompatible-fix metadata | A new lifecycle replaces an established tag, tag/metadata/bump diverge, an incompatible correction uses bare `[fix]`, or migration is unusable |-| FR9–FR13 | CLI contract tests, response-schema/type snapshots, text projections, generated consumer docs, and template catalog/output tests | slug rename, metadata edit, source rebuild, optional field addition, command or schema change | Catalog data is frozen as API, a command/schema incompatibility is mislabeled as catalog-only, or a response field lacks a complete projection |-| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |-| FR14 | Help/manifest snapshots, public API and consumer docs, and focused contract tests | command, option, API/config, private rollout/test hook | Supported behavior is hidden, an environment variable changes behavior, or automation lacks a documented API |-| FR15 | Full manifest-derived command matrix, supported-consumer evidence, and scope-specific contract tests | global invariant, scoped command group, single command, programmatic API | A global control is a no-op for any command, has different meanings, or replaces a narrower owning surface |-| FR16–FR18 | Boundary inventory, hostile side-effect probes, response snapshots, and concurrent API tests | known and new extension, partial result, text/JSON/API parity, independent concurrent calls | A route bypasses the guarantee, omitted work looks complete, or one invocation changes another |-| FR19–FR20 | Proposal evidence with a regression fixture for the detection failure, plus composition and provenance tests | convention covers the case, detection fails, app plus two integrations, refusal, failing contribution, repeated load | A key ships without a reproduced detection failure, a contribution displaces the app or applies twice, a part of the effective value has no inspectable source, or a failure silently weakens protection |-| FR21–FR24 | Published-surface comparison, declaration/doc metadata checks, import-boundary checks, and Changeset classification review | experimental prop object, experimental subpath, patch evolution, promotion, unpublished adjacent field, stable warning behavior, integration theme | A prose-only marker excludes a stable API, adjacency falsely publishes a new field, an experimental export leaks through a stable path, a patch changes stable behavior, or a promoted API remains unprotected |-| FR25–FR27 | Stable-surface inventory and experimental-boundary matrix | package/API, CSS/token, CLI/config, persistence, build tooling, docs, whole Lab component | An unmarked experiment changes stable defaults or a stable surface bypasses compatibility review |-| FR28–FR31 | Declared-tier check: on a minor, the `[breaking]` Changeset describes the change (old usage, replacement, migration); on a patch, a breaking Changeset is refused and the deprecation ships instead; declaration/doc/build/CLI warning projections; old/new fixtures; dry-run/idempotence/migration tests; maintained-source and latest-stable upgrade evidence | whole component, prop/value, theme field/helper/token/target/source, CLI command, CLI option; old-only, new-only, both, static/dynamic/uncertain migration, text/JSON, development/production | A warning has no usable modernization route, production runtime changes for deprecation, maintained guidance teaches the old surface, a migration guesses, old behavior degrades early, cadence invents a wait, or one cleanup id covers multiple incompatible deltas |-| FR32–FR35 | Latest-stable victim fixture, pre-existing authority named in the Changeset or pull request, owner review, declared-tier check, and emergency attestation | victim-free `[fix]`, `[fix]` plus incompatible-fix metadata, coexistence, cleanup transition, critical-harm emergency | A released victim uses bare `[fix]`, a new Changeset tag replaces metadata, a correction record disagrees with its public-surface state, or urgency bypasses migration |-| FR36–FR40 | Owner-declared target, locked final-patch receipt, three-way delta classification against the merged `[breaking]` Changesets, and separated release notes | ordinary cadence, immediate pair, cleanup, release metadata, pre/post-lock compatible fix | Cadence becomes eligibility, the final patch is recut for bookkeeping, a feature or incompatible fix enters the incidental-fix lane, or release notes merge cleanup with fixes |-| FR41–FR44 | Schema validation, PR declaration, semantic stable/base/head comparisons, exact-main gate, and immutable publish/rollback receipt | duplicate ids, missing evidence, route/schema removal, old-client metadata, partial publish, safe rollback | A label passes without semantics, a delta maps zero or multiple times, fixed-group membership drifts, or a release rebuilds under one identity |-| FR45 | Docs route inventory, repository-reference checks, and Changeset review | catalog entry rename, former-route miss, stable command and JSON schema | Catalog routing is frozen as API, or a rename silently changes the contractual command or response schema |-| FR46–FR47 | Declared-tier Changeset admission, canary publication ordering, and release-versioning fixtures | owner increase/decrease, above/equal/below stable, split group, `[breaking]` on patch and minor plans | Pending Changesets derive the plan, `[breaking]` passes on a patch or fails on a minor, equality publishes a canary, or a lower/split declaration publishes instead of failing |-| FR48 | Category and classification admission under each declared tier | patch release with `[breaking]`, patch release with a deprecation, minor release with `[breaking]` | Incompatible work passes in a patch release, or a deprecation is refused in one |-| FR49 | Malformed and inconsistent declaration fixtures | disagreeing group versions, canary identifier, release version unlike the cut manifest, already-released version, skipped version, no stable tag | An untrustworthy or mismatched declaration is released |-| FR50 | Three-way squash merge-back fixtures bound to the immutable tag, branch head, and plan digest | exact branch outputs, frozen deletion, branch-only marker exclusion, post-cut Changeset/manifest edit, newer main declaration, merge conflict, regenerated output | Merge-back differs from release bytes, lands lifecycle files, consumes post-cut work, overwrites a newer main declaration or unrelated field, or chooses a version |-| FR51 | Separate next-plan manifest/pin/lockfile/compatibility-asset fixtures plus canary routing assertions | default patch successor, explicitly named minor, pre-advanced main plan, unrelated main work during equality | Equality publishes a canary, the default skips a patch, pending Changesets choose a minor, exact pins or compatibility assets split, or merge-back requires a duplicate bump for an existing newer plan |+| Contract | Verification | Representative states | Mutation or failure expectation |+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, narrowed type, changed interaction default; unreleased and private surface; visual-only spacing, typography, layout styling, or default appearance | A change is labeled from diff size or possibility alone, a functional contract loss is hidden as visual-only, or a pixel-only change is tagged `[breaking]` even though callers need no source or configuration change |+| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |+| FR7–FR8 | `pnpm check:changesets` (tag, bump, contributors, declared tier) plus FR8 migration review of `[breaking]` text | existing `[fix]`, `[feat]`, `[breaking]`, and `[experimental]` tags paired with compatible, deprecation, planned-removal, or incompatible-fix metadata | A new lifecycle replaces an established tag, tag/metadata/bump diverge, an incompatible correction uses bare `[fix]`, or migration is unusable |+| FR9–FR13 | CLI contract tests, response-schema/type snapshots, text projections, generated consumer docs, and template catalog/output tests | slug rename, metadata edit, source rebuild, optional field addition, command or schema change | Catalog data is frozen as API, a command/schema incompatibility is mislabeled as catalog-only, or a response field lacks a complete projection |+| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |+| FR14 | Help/manifest snapshots, public API and consumer docs, and focused contract tests | command, option, API/config, private rollout/test hook | Supported behavior is hidden, an environment variable changes behavior, or automation lacks a documented API |+| FR15 | Full manifest-derived command matrix, supported-consumer evidence, and scope-specific contract tests | global invariant, scoped command group, single command, programmatic API | A global control is a no-op for any command, has different meanings, or replaces a narrower owning surface |+| FR16–FR18 | Boundary inventory, hostile side-effect probes, response snapshots, and concurrent API tests | known and new extension, partial result, text/JSON/API parity, independent concurrent calls | A route bypasses the guarantee, omitted work looks complete, or one invocation changes another |+| FR19–FR20 | Proposal evidence with a regression fixture for the detection failure, plus composition and provenance tests | convention covers the case, detection fails, app plus two integrations, refusal, failing contribution, repeated load | A key ships without a reproduced detection failure, a contribution displaces the app or applies twice, a part of the effective value has no inspectable source, or a failure silently weakens protection |+| FR21–FR24 | Published-surface comparison, declaration/doc metadata checks, import-boundary checks, and Changeset classification review | experimental prop object, experimental subpath, patch evolution, promotion, unpublished adjacent field, stable warning behavior, integration theme | A prose-only marker excludes a stable API, adjacency falsely publishes a new field, an experimental export leaks through a stable path, a patch changes stable behavior, or a promoted API remains unprotected |+| FR25–FR27 | Stable-surface inventory and experimental-boundary matrix | package/API, CSS/token, CLI/config, persistence, build tooling, docs, whole Lab component | An unmarked experiment changes stable defaults or a stable surface bypasses compatibility review |+| FR28–FR31 | Declared-tier check: on a minor, the `[breaking]` Changeset describes the change (old usage, replacement, migration); on a patch, a breaking Changeset is refused and the deprecation ships instead; declaration/doc/build/CLI warning projections; old/new fixtures; dry-run/idempotence/migration tests; maintained-source and latest-stable upgrade evidence | whole component, prop/value, theme field/helper/token/target/source, CLI command, CLI option; old-only, new-only, both, static/dynamic/uncertain migration, text/JSON, development/production | A warning has no usable modernization route, production runtime changes for deprecation, maintained guidance teaches the old surface, a migration guesses, old behavior degrades early, cadence invents a wait, or one cleanup id covers multiple incompatible deltas |+| FR32–FR35 | Latest-stable victim fixture, pre-existing authority named in the Changeset or pull request, owner review, declared-tier check, and emergency attestation | victim-free `[fix]`, `[fix]` plus incompatible-fix metadata, coexistence, cleanup transition, critical-harm emergency | A released victim uses bare `[fix]`, a new Changeset tag replaces metadata, a correction record disagrees with its public-surface state, or urgency bypasses migration |+| FR36–FR40 | Owner-declared target, locked final-patch receipt, three-way delta classification against the merged `[breaking]` Changesets, and separated release notes | ordinary cadence, immediate pair, cleanup, release metadata, pre/post-lock compatible fix | Cadence becomes eligibility, the final patch is recut for bookkeeping, a feature or incompatible fix enters the incidental-fix lane, or release notes merge cleanup with fixes |+| FR41–FR44 | Schema validation, PR declaration, semantic stable/base/head comparisons, exact-main gate, and immutable publish/rollback receipt | duplicate ids, missing evidence, route/schema removal, old-client metadata, partial publish, safe rollback | A label passes without semantics, a delta maps zero or multiple times, fixed-group membership drifts, or a release rebuilds under one identity |+| FR45 | Docs route inventory, repository-reference checks, and Changeset review | catalog entry rename, former-route miss, stable command and JSON schema | Catalog routing is frozen as API, or a rename silently changes the contractual command or response schema |+| FR46–FR47 | Declared-tier Changeset admission, canary publication ordering, and release-versioning fixtures | owner increase/decrease, above/equal/below stable, split group, `[breaking]` on patch and minor plans | Pending Changesets derive the plan, `[breaking]` passes on a patch or fails on a minor, equality publishes a canary, or a lower/split declaration publishes instead of failing |+| FR48 | Category and classification admission under each declared tier | patch release with `[breaking]`, patch release with a deprecation, minor release with `[breaking]` | Incompatible work passes in a patch release, or a deprecation is refused in one |+| FR49 | Malformed and inconsistent declaration fixtures | disagreeing group versions, canary identifier, release version unlike the cut manifest, already-released version, skipped version, no stable tag | An untrustworthy or mismatched declaration is released |+| FR50 | Three-way squash merge-back fixtures bound to the immutable tag, branch head, and plan digest | exact branch outputs, frozen deletion, branch-only marker exclusion, post-cut Changeset/manifest edit, newer main declaration, merge conflict, regenerated output | Merge-back differs from release bytes, lands lifecycle files, consumes post-cut work, overwrites a newer main declaration or unrelated field, or chooses a version |+| FR51 | Separate next-plan manifest/pin/lockfile/compatibility-asset fixtures plus canary routing assertions | default patch successor, explicitly named minor, pre-advanced main plan, unrelated main work during equality | Equality publishes a canary, the default skips a patch, pending Changesets choose a minor, exact pins or compatibility assets split, or merge-back requires a duplicate bump for an existing newer plan |+| FR53 | Changeset classification review against the governing component record's accessibility evidence | a fix that replaces documented keyboard or focus behavior to meet an adopted APG pattern's required parts; a fix that changes a role, state, or accessible name to meet WCAG 2.2 A/AA; a fix that adds an optional prop | An accessibility fix is held for a minor, given a coexistence path, or classified `[breaking]`; or a change that needs an app-layer code edit, or that removes, renames, or narrows public surface, ships as an accessibility `[fix]` |## Decision log@@ -1143,6 +1169,22 @@ before merging, which duplicated the Changeset and made bookkeeping the blocker;per-record transition requirement and waiver, which the patch rule already expresses;and dropping the manifest, which would lose the minor's migration inventory.+### DEC-20 — Accessibility behavior fixes are not breaking++**Reference:** `spec:AST-017/DEC-20`+**Decider:** `cixzhang`, `2026-10-14`++Every user of a component that misses its accessibility target is harmed until the+fix ships, and the people harmed most are the ones least able to work around it.+Holding such a fix for a planned minor, or shipping it behind an opt-in beside the+inaccessible behavior, keeps that harm in place to protect callers who depended on+behavior that excluded someone. So a change made for accessibility conformance is a+`[fix]` in the patch line even when it replaces documented roles, names, states, focus+or keyboard behavior. The boundary is the public surface: the fix needs no app-layer code change, may add optional surface, and never removes, renames, or narrows existing surface; a change that would make apps edit code is redesigned so the component absorbs it, or classified as any other change.++Rejected: classifying accessibility corrections as breaking whenever a released+caller observes the old behavior, which delays every conformance fix to a minor.+## Open questionsNone.