Skip to content

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.md
index 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 a
supported escape exists. A default that changes a functional or semantic contract is
judged 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 is
nonbreaking when the old released call, import, option, identifier, or input
continues 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 that
behavior and the correction breaks the consumer, FR32–FR35 classify it as an
incompatible 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 not
make 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, and
package 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 routes
follow
FR45. An internal label, low adoption, or lack of a source-level API change does
not 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 supported
workflow, 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 behavior
violated, a latest-stable reproducer, and the migration. Without pre-existing
authority, 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 breaking
correction merges on its `[breaking]` Changeset. When `main` declares a patch, the
patch 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 newer
owner plan, FR50 preserves it and no duplicate bump is required. The plan remains
malleable 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 questions
None.