An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-009): real-AT evidence never gates merge or release (#7915)
Cindy Zhang7370328f6c9c
diff --git a/docs/specs/AST-001/spec.md b/docs/specs/AST-001/spec.mdindex 29682267bc..0dde98690a 100644--- a/docs/specs/AST-001/spec.md+++ b/docs/specs/AST-001/spec.md@@ -74,8 +74,9 @@ actionable-looking selector.- Unsupported behavior: input `isLoading` MUST NOT be used as a fallbackoption-source signal.- Browser evidence: the loading, read-only, and completed-empty states require- real-browser keyboard, accessibility-tree, and screen-reader verification;- DOM assertions alone are not sufficient.+ real-browser keyboard and accessibility-tree verification; DOM assertions alone+ are not sufficient. Screen-reader observation is recommended follow-up under+ `spec:AST-009`, not a merge or release requirement.## Current-state impact@@ -103,12 +104,12 @@ actionable-looking selector.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| ------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |-| FR1, FR2 | Selector and MultiSelector interaction tests | populated options with input `isLoading`; searched and unsearched; pointer and keyboard | A provided option disappears, becomes unreachable, or cannot be selected because the field value is busy |-| FR3, FR5, FR6 | State-transition and activation tests | zero options while initial pending; pending to completed empty; zero options without pending | The control offers a nonexistent choice, claims completed empty while pending, or keeps presenting loading after completion |-| FR7 | Real-browser keyboard, accessibility-tree, and screen-reader matrix | initial pending, completed empty/read-only, populated while input `isLoading`, existing selected value | Visible and announced states disagree, focus is lost, name/value disappears, or a transition is silent or announced repeatedly |-| Public API | Type-level and consumer-example tests after OQ1 is resolved | omitted/default state, explicit initial pending, dynamic completion | Zero options or input `isLoading` silently substitutes for the explicit source state |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |+| FR1, FR2 | Selector and MultiSelector interaction tests | populated options with input `isLoading`; searched and unsearched; pointer and keyboard | A provided option disappears, becomes unreachable, or cannot be selected because the field value is busy |+| FR3, FR5, FR6 | State-transition and activation tests | zero options while initial pending; pending to completed empty; zero options without pending | The control offers a nonexistent choice, claims completed empty while pending, or keeps presenting loading after completion |+| FR7 | Real-browser keyboard and accessibility-tree tests; screen-reader follow-up recommended | initial pending, completed empty/read-only, populated while input `isLoading`, existing selected value | Visible and announced states disagree, focus is lost, name/value disappears, or a transition is silent or announced repeatedly |+| Public API | Type-level and consumer-example tests after OQ1 is resolved | omitted/default state, explicit initial pending, dynamic completion | Zero options or input `isLoading` silently substitutes for the explicit source state |## Decision logdiff --git a/docs/specs/AST-009/spec.md b/docs/specs/AST-009/spec.mdindex ec2cdbf503..908c243d6e 100644--- a/docs/specs/AST-009/spec.md+++ b/docs/specs/AST-009/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-08-31+approved_at: 2026-10-22phase: acceptedowners: [cixzhang, imdreamrunner]affects_architecture: []@@ -32,6 +32,7 @@ affects_consumer_docs: []"FR5","FR6","FR7",+ "FR8","FR9","FR10","FR11",@@ -39,7 +40,9 @@ affects_consumer_docs: []"FR13","FR14","FR15",- "FR16"+ "FR16",+ "FR17",+ "FR19"]}}@@ -47,45 +50,53 @@ affects_consumer_docs: []## Intent-People who depend on assistive technology should get the AT-specific focus and announcement outcome Astryx claims, not only plausible test-DOM markup. Astryx uses real AT/browser checks when that outcome depends on how AT exposes or announces focus, AT-specific focus order, announcement behavior, virtual-cursor entry, or a known AT/browser divergence.+People who depend on assistive technology should get the focus and announcement+outcome Astryx claims, not only plausible test-DOM markup. Astryx proves each+claim with the strongest evidence it can produce: unit, DOM, accessibility-tree,+axe, and real-browser checks. Real assistive-technology (AT) observation adds+proof of what is actually spoken or navigated. It is recommended follow-up when an+outcome depends on AT behavior.-These checks are targeted, not universal. Semantic changes may merge to `main` with the strongest other evidence that proves their claims. A stable release waits only when this spec requires named real AT/browser evidence and that evidence is pending, failed, or expired.+No requirement in Astryx gates merge or release on evidence that cannot be+produced. Missing real-AT observation never blocks merge to `main` or a stable+release.## Non-goalsThis spec does not:-- require every accessibility change to run every assistive technology or every browser;+- require every accessibility change to run any assistive technology or every browser;+- gate merge or release on real-AT observation;- treat real AT as a substitute for unit, DOM, accessibility-tree, axe, or browser tests that prove different claims more precisely;- define consumer accessibility requirements or claim conformance with an entire accessibility standard from one tool or matrix;- require a stable announcement transcript when an AT intentionally changes harmless wording but keeps the required information and order;-- implement release automation, contribution forms, labels, bots, fixtures, or test infrastructure in this specification pull request; or+- implement release automation, contribution forms, labels, bots, fixtures, or test infrastructure; or- copy this policy into contributor or release guidance before those separately owned records exist.### Authority boundary-AST-009 supersedes the public [Accessibility Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist) only for real-AT trigger classification, evidence boundaries, durable receipts, exceptions, revalidation, and stable-release blocks. The checklist remains the consumer and contributor bar for component accessibility requirements.+AST-009 supersedes the public [Accessibility Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist) only for real-AT follow-up classification, evidence boundaries, the merge and release evidence bar, and durable receipts. The checklist remains the consumer and contributor bar for component accessibility requirements.AST-009 does not own focus-ring appearance, interaction-modality behavior, visual or contrast methodology, browser support, component theming, or overlay behavior. Those stay with [interaction modality](../../architecture/interaction-modality.md), [browser support](../AST-013/spec.md), [component theming](../../architecture/component-theming-surface.md), [theme tokens](../../architecture/theme-tokens.md), [layer runtime](../../architecture/layer-runtime.md), [overlay dismissal](../../families/overlay-dismissal.md), and the owning component records.## Requirements-### Verification triggers+### When real-AT follow-up is recommended-| ID | Rule |-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1 | The gate follows the claimed user outcome. Real AT/browser evidence is required only when the intended outcome depends on AT-specific behavior: how AT exposes or announces focus, AT-specific focus order, spoken/braille output, browse or virtual-cursor behavior, mode changes, or a known AT/browser divergence. A semantic code change or focus-only browser behavior is not the trigger; the trigger is an AT-dependent claim that cannot be proved below the real-AT layer. |-| FR2 | Focus changes trigger only for AT-specific outcomes. Real AT/browser verification is required when the claim depends on how AT exposes, announces, or orders programmatic, initial, restored, composite, or after-dismissal focus. Focus destination, order, return, keyboard operation, focus-ring styling, a refactor preserving the same browser focus target, or a static `tabIndex` correction does not trigger by itself. The owning component and [interaction-modality record](../../architecture/interaction-modality.md) define those browser and visual behaviors. |-| FR3 | Role, name, and description changes trigger when announcement or mode is the outcome. A computed role, accessible name, or description may be proved by accessibility-tree evidence when the claim ends at browser exposure. Real AT/browser verification is additionally required when the change relies on that semantic being announced during entry or a state transition, changing interaction/browse mode, or resolving a known AT/browser divergence. |-| FR4 | Announcement content and timing trigger directly. A live region, status message, alert, validation announcement, loading/completion transition, or other spoken/braille update requires real AT/browser evidence when success depends on what is announced, its order, when it occurs, whether it repeats, or whether it is skipped. |-| FR5 | Virtual-cursor entry triggers directly. Opening, navigation, or focus behavior requires real AT/browser evidence when success depends on where screen-reader browse or virtual cursor enters, whether content is discoverable from that entry point, or whether the user can move between browse and interaction modes. Ordinary keyboard Tab order with no browse-mode claim does not trigger this requirement. |-| FR6 | Known divergence keeps the gate active. A changed pattern with a recorded AT/browser divergence requires checks for every named side of that divergence until an owner records that the divergence no longer applies. A passing result from one side does not stand in for another known to differ. |-| FR7 | Untriggered changes use proportionate evidence. Static semantics, keyboard behavior, color/contrast, target size, source order, and similar accessibility changes use the least expensive evidence layer that directly proves the claim. They do not acquire a real-AT gate merely because they are accessibility work. |-| FR8 | Classification is explicit. The change record states which trigger applies, or states why none applies and names the evidence layer that proves the intended outcome. Silence is not a classification. |+| ID | Rule |+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | The recommendation follows the claimed user outcome. Real AT/browser follow-up is recommended only when the intended outcome depends on AT-specific behavior: how AT exposes or announces focus, AT-specific focus order, spoken/braille output, browse or virtual-cursor behavior, mode changes, or a known AT/browser divergence. A semantic code change or focus-only browser behavior is not the trigger. The recommendation never makes real-AT evidence a merge or release requirement (FR17). |+| FR2 | Focus changes warrant follow-up only for AT-specific outcomes. Real-AT follow-up is recommended when the claim depends on how AT exposes, announces, or orders programmatic, initial, restored, composite, or after-dismissal focus. Focus destination, order, return, keyboard operation, focus-ring styling, a refactor preserving the same browser focus target, or a static `tabIndex` correction does not warrant it by itself. The owning component and [interaction-modality record](../../architecture/interaction-modality.md) define those browser and visual behaviors. |+| FR3 | Role, name, and description are proved at the accessibility tree. A computed role, accessible name, or description is proved by accessibility-tree evidence. Real-AT follow-up is additionally recommended when the change relies on that semantic being announced during entry or a state transition, changing interaction/browse mode, or resolving a known AT/browser divergence. |+| FR4 | Announcements are proved by their routing. A live region, status message, alert, validation announcement, or loading/completion transition is proved by DOM and accessibility-tree evidence of which element or channel carries it, its text, its urgency, and how many updates each occasion produces. Real-AT follow-up is recommended when success depends on what is spoken, its order, when it occurs, whether it repeats, or whether it is skipped. |+| FR5 | Virtual-cursor entry warrants follow-up. Real-AT follow-up is recommended when success depends on where screen-reader browse or virtual cursor enters, whether content is discoverable from that entry point, or whether the user can move between browse and interaction modes. Ordinary keyboard Tab order with no browse-mode claim does not warrant it. |+| FR6 | Known divergence widens follow-up. When a changed pattern has a recorded AT/browser divergence, follow-up covers every named side of it until an owner records that the divergence no longer applies. A passing result from one side does not stand in for another known to differ. |+| FR7 | Other changes use proportionate evidence. Static semantics, keyboard behavior, color/contrast, target size, source order, and similar accessibility changes use the least expensive evidence layer that directly proves the claim. They do not acquire a real-AT follow-up merely because they are accessibility work. |+| FR8 | AT-dependent claims are named. A change whose intended outcome depends on AT behavior says so in its record and names the lower-layer evidence that proves what can be proved. It needs no matrix, scenario, or release record to merge. |### What each evidence layer proves-This table bounds claims only when classifying real-AT triggers under AST-009. It does not replace evidence required by current component, family, browser-support, visual, theming, or audit records.+This table bounds what each layer may claim. It does not replace evidence required by current component, family, browser-support, visual, theming, or audit records.Each layer is bounded. Passing one layer MUST NOT be described as proving a claim assigned to a later layer.@@ -100,13 +111,13 @@ Each layer is bounded. Passing one layer MUST NOT be described as proving a clai| ID | Rule || ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR9 | Evidence composes by claim. A triggered change normally keeps its lower-layer evidence and adds real AT/browser checks only for claims those checks can prove. Real AT observation MUST NOT replace deterministic regression coverage for behavior the lower layers own. |+| FR9 | Evidence composes by claim. A change keeps its lower-layer evidence. Real-AT observation, when it runs, adds only the claims it can prove and MUST NOT replace deterministic regression coverage for behavior the lower layers own. || FR10 | The tested state is the claimed state. Evidence exercises the transition or state that carries the user outcome, such as opening the surface, moving focus, producing the status update, dismissing and restoring focus, or entering with the virtual cursor. A static baseline that merely contains the component is insufficient. || FR11 | Real means the shipping pairing. A real-AT check runs the named assistive technology against the named shipping browser on its supported operating system. A virtual machine, remote machine, or simulator is acceptable only when it runs that actual pairing and preserves the input/mode under test. A DOM emulator, accessibility snapshot, synthetic speech stub, or browser engine standing in for a branded browser is not real-AT evidence. |### Representative matrix-The matrix is selected from the outcome and supported platform, not copied in full onto every change.+When real-AT follow-up runs, its pairings are selected from the outcome and supported platform, not copied in full onto every change.| Representative pairing | Use when the outcome includes || ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |@@ -116,148 +127,105 @@ The matrix is selected from the outcome and supported platform, not copied in fu| VoiceOver + Safari on iOS | Touch-driven iOS behavior, mobile Safari, rotor/browse navigation, or iOS-specific divergence. || TalkBack + Chrome on Android | Touch-driven Android behavior, Android virtual navigation, or Android-specific divergence. |-| ID | Rule |-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| FR12 | Desktop-neutral AT-specific focus exposure/order or announcement claims use two independent stacks: at least NVDA + Chrome on Windows and VoiceOver + Safari on macOS. A platform-specific claim uses its matching pairing only unless FR14 expands it. |-| FR13 | Mobile claims use a matching mobile stack. A mobile or touch/virtual-cursor outcome uses at least one matching mobile pairing. Both iOS and Android are required only when the claim covers both and platform-specific code, behavior, or recorded evidence gives reason to expect different outcomes. |-| FR14 | Divergence expands rather than replaces. Every side named in a known divergence is included even when that adds a pairing beyond FR12 or FR13. |-| FR15 | Versions and modes are part of the matrix. The receipt names OS, AT, browser, input mode, and material settings or verbosity that affect the result. “Screen reader checked” or a browser name without its AT is not a matrix. |-| FR16 | Representative does not mean exhaustive. Passing the selected matrix supports only the recorded outcome and pairings. It does not claim every AT, browser, verbosity setting, locale, or input method behaves identically. |--### Stable-release lifecycle--| ID | Rule |-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR17 | Merge and stable release are separate gates. When intended user impact depends on AT-specific focus exposure/order, announcement or virtual-cursor behavior, or a known AT/browser divergence under FR2–FR6, the implementation may merge to `main` once the otherwise-required evidence from the owning records passes, its real-AT matrix and scenario are named, and a durable release-block record exists. Preview and prerelease builds may carry the pending change. The first stable release containing it MUST NOT publish while the block is pending, failed, or expired. |-| FR18 | The block follows the shipped change. It identifies the source pull request and commit, the first affected stable release or release line when known, each required matrix row, and each row state: `pending`, `pass`, `fail`, `excepted`, or `invalidated`. |-| FR19 | Only passes or a current exception clear the block. Every required row must have a passing receipt bound to an applicable build, or be covered by an unexpired owner-recorded exception. Missing, failed, and invalidated rows continue to block the stable release. |-| FR20 | Failures remain findings. A failed observation records the user impact and linked fix. The affected row is retested against the fixed build. Unrelated passing rows remain usable unless the fix could affect them. Editing an expected result to match an undesirable observation does not turn failure into pass. |-| FR21 | Receipts remain valid until invalidated. A passing receipt may be reused for later stable releases while the tested semantic, focus, announcement, virtual-cursor, or divergence-sensitive path and relevant support claim remain unchanged. Revalidation is required after a material change to that path or fixture, a fix for the observed behavior, a newly recorded divergence that affects the matrix, or an explicit receipt/exception expiry. Unrelated commits do not invalidate evidence. |-| FR22 | Revalidation decisions are recorded. When a later build differs from the tested commit, the release record either links the material revalidation receipt or records why the difference cannot affect the tested path. The latter is applicability review, not a new AT pass. |--### Exceptions and expiry--| ID | Rule |-| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR23 | Exceptions are explicit owner decisions. Only a listed owner of this spec may authorize release without a required pass. Absence of equipment, schedule pressure, a green axe run, or prior behavior does not imply an exception. |-| FR24 | Exceptions are narrow and finite. An exception names the exact change, stable release or release line, omitted or failed matrix rows, accepted user risk, compensating evidence or mitigation, owner, decision date, and an expiry date or release boundary. A release-scoped exception authorizes only that named release; it does not become a standing waiver. |-| FR25 | Expiry restores the block. At the earliest recorded expiry, invalidating behavior change, newly applicable divergence, or end of the named release scope, the row returns to `pending` or `invalidated`. A later stable release needs a pass or a new owner decision with current risk information. |-| FR26 | Exceptions do not rewrite evidence. An excepted row remains visibly excepted rather than pass. The follow-up check or fix remains linked until it produces a passing receipt or the affected behavior is removed. |+| ID | Rule |+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR12 | Desktop-neutral follow-up uses two independent stacks: NVDA + Chrome on Windows and VoiceOver + Safari on macOS. A platform-specific claim uses its matching pairing only unless FR14 expands it. |+| FR13 | Mobile follow-up uses a matching mobile stack. A mobile or touch/virtual-cursor outcome uses at least one matching mobile pairing, and both iOS and Android only when the claim covers both and there is reason to expect different outcomes. |+| FR14 | Divergence expands rather than replaces. Every side named in a known divergence is included even when that adds a pairing beyond FR12 or FR13. |+| FR15 | Versions and modes are part of the result. A receipt names OS, AT, browser, input mode, and material settings or verbosity that affect the result. “Screen reader checked” or a browser name without its AT is not a matrix. |+| FR16 | Representative does not mean exhaustive. Passing the selected pairings supports only the recorded outcome and pairings. It does not claim every AT, browser, verbosity setting, locale, or input method behaves identically. |++### Merge, release, and follow-up++| ID | Rule |+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR17 | Merge and release need only producible evidence. A change merges to `main` and ships in a stable release once the unit, DOM, accessibility-tree, axe, and real-browser evidence its owning records require passes. Pending, missing, or not-yet-run real-AT observation MUST NOT block merge or stable release, and no record may make it a gate. |+| FR18 | Follow-up is tracked, not held. A recommended real-AT follow-up MAY be tracked in a public issue naming the claim, scenario, and pairings. The issue holds no pull request or release. |+| FR19 | Lower layers set the bar where real AT is unavailable. An announcement claim is met at merge by FR4 evidence. Focus-exposure, mode, and virtual-cursor claims are met by the accessibility-tree and real-browser evidence that observes the nearest producible state. That evidence MUST NOT be described as proving speech, timing, or cursor placement. |+| FR20 | Failures remain findings. A failed real-AT observation is a defect: it records the user impact and links a fix, and is handled like any other defect. Editing an expected result to match an undesirable observation does not turn failure into pass. |+| FR21 | Receipts remain valid until invalidated. A passing receipt stays usable while the tested semantic, focus, announcement, virtual-cursor, or divergence-sensitive path and relevant support claim remain unchanged. A material change to that path, a fix for the observed behavior, or a newly recorded divergence makes it stale. Unrelated commits do not. |+| FR22 | Stale receipts are labelled. When a later change makes a receipt stale, the tracking record says so and the follow-up returns to recommended. This is information, not a gate. |### Durable receipts and evidence storage-| ID | Rule |-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR27 | The textual receipt is durable and public. The canonical receipt lives in the merged pull request, a linked public tracking issue, or a repository-owned record. It MUST remain readable without access to expiring CI artifacts, private systems, or an unversioned local file. |-| FR28 | Every receipt is reproducible. It records the source pull request and commit or tested build identifier; stable story, fixture, route, or exact reproduction steps; trigger and contract claim under test; expected focus destination, semantics, announcement, timing, or virtual-cursor outcome; OS, AT, browser, and relevant settings/versions; input sequence and starting state; observed result, including announcement transcript or focus/cursor destination when applicable; `pass` or `fail`, tester, and date; and linked defect, follow-up, exception, and attachments when applicable. |-| FR29 | Text carries the decision-critical facts. Screenshots, recordings, speech logs, and CI artifacts may supplement the receipt. They MUST NOT be the only place that records the matrix, expected outcome, observation, result, or exception. Evidence must contain no private user data or internal-only links. |-| FR30 | Reusable scenarios live with the code. When a scenario will be used for release revalidation or represents a component contract, its stable story or fixture is checked into the repository. A one-off external test page is not the sole reproduction path. |-| FR31 | Guidance projects this spec. Future contributor accessibility guidance must link to this spec for trigger classification, evidence bounds, and receipt requirements. Future release guidance must link to this spec for block, exception, expiry, and revalidation rules. Those guides may explain the current workflow but MUST NOT duplicate or redefine this policy. |+| ID | Rule |+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR27 | The textual receipt is durable and public. When a real-AT check runs, its canonical receipt lives in the merged pull request, a linked public tracking issue, or a repository-owned record. It MUST remain readable without access to expiring CI artifacts, private systems, or an unversioned local file. |+| FR28 | Every receipt is reproducible. It records the source pull request and commit or tested build identifier; stable story, fixture, route, or exact reproduction steps; the claim under test; expected focus destination, semantics, announcement, timing, or virtual-cursor outcome; OS, AT, browser, and relevant settings/versions; input sequence and starting state; observed result, including announcement transcript or focus/cursor destination when applicable; `pass` or `fail`, tester, and date; and linked defect or follow-up when applicable. |+| FR29 | Text carries the decision-critical facts. Screenshots, recordings, speech logs, and CI artifacts may supplement the receipt. They MUST NOT be the only place that records the pairings, expected outcome, observation, or result. Evidence must contain no private user data or internal-only links. |+| FR30 | Reusable scenarios live with the code. When a scenario will be reused or represents a component contract, its stable story or fixture is checked into the repository. A one-off external test page is not the sole reproduction path. |+| FR31 | Guidance projects this spec. Future contributor accessibility guidance links to this spec for follow-up classification, evidence bounds, and receipt requirements. Future release guidance links to this spec for the merge and release evidence bar. Those guides may explain the current workflow but MUST NOT duplicate or redefine this policy. |### Platform support-- Supported feature/engine floor: [AST-013](../AST-013/spec.md) and the affected component or package own browser support. This matrix selects AT/browser evidence rows within that support claim.-- Unsupported behavior: no passing claim is made for an untested unsupported pairing; a known supported-pairing divergence follows FR6 and FR14.-- Browser evidence: Playwright or another real-browser runner may prove browser behavior and accessibility-tree exposure. It does not satisfy the real-AT rows unless the actual named assistive technology is operating against the named browser.+- Supported feature/engine floor: [AST-013](../AST-013/spec.md) and the affected component or package own browser support. Follow-up pairings are selected within that support claim.+- Unsupported behavior: no passing claim is made for an untested pairing; a known supported-pairing divergence follows FR6 and FR14.+- Browser evidence: Playwright or another real-browser runner proves browser behavior and accessibility-tree exposure. It is real-AT evidence only when the actual named assistive technology is operating against the named browser.## Current-state impact-### Initial release block — pull request #5373--| Field | Value |-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| Source change | Pull request [#5373](https://github.com/facebook/astryx/pull/5373), merged as `1917581938200c3e56527bf4cda6d5de78b492a5`, changed read-only Popover initial focus so the labeled dialog container receives focus when no content control is available. |-| Affected release | The first stable release containing that commit. Current candidate: draft release [PR #5789](https://github.com/facebook/astryx/pull/5789) for v0.5.3. If another release becomes first, update this row before clearing the block. |-| Trigger | FR2 and FR3. The intended result depends on the focused role and name being announced on entry. |-| Desktop scenario | Open the `Read-only dialog focus` story, confirm the dialog name and role are announced at the focused container, then confirm the first Tab enters the dialog's control cycle rather than moving to unrelated content. |-| Touch/iOS scenario | On a physical iOS device with VoiceOver and Safari, open the same story by touch. Confirm the labeled dialog is announced at entry and touch or swipe navigation remains within the opened task before reaching unrelated page content. |--Its merge-time unit, DOM, axe, and browser evidence from the owning records can support merging the semantic change. Because the intended outcome depends on what is announced at that focus destination, the first stable release waits for the receipts below or an explicit current exception. Existing axe and browser checks remain required where they prove assigned claims; neither clears an AT-triggered release block by itself.--| Required pairing | State |-| --------------------------- | --------- |-| NVDA + Chrome on Windows | `pending` |-| VoiceOver + Safari on macOS | `pending` |-| VoiceOver + Safari on iOS | `pending` |--All three rows block that stable release until they have passing durable receipts or are covered by a current owner-recorded exception. The iOS row covers #5373's touch path; iOS Simulator layout evidence does not prove VoiceOver or physical-device touch behavior.--The [Popover contract](../../../packages/core/src/Popover/Popover.spec.md), [layer runtime](../../architecture/layer-runtime.md), and [overlay dismissal](../../families/overlay-dismissal.md) continue to own focus, runtime, and dismissal behavior. AST-009 owns only the real-AT evidence and stable-release block for the claimed outcome.--### Pending release block — pull request #6950--| Field | Value |-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Source change | Pull request [#6950](https://github.com/facebook/astryx/pull/6950) changes CommandPalette's empty-result live-region content and query-state announcement timing. Bind the final receipt to the landed commit after merge. |-| Affected release | The first stable release containing the landed pull request. |-| Trigger | FR4. The intended result depends on what the live region announces, when a populated result set narrows to nothing, and whether the update repeats or is skipped. |-| Scenario | Open the checked-in `CommandPalette / Audit Matrix` story. **Narrow to empty:** within the panel labeled `Grouped command palette`, focus its `Search commands` input, which lists four results. Type `s`, then `x`, one key at a time. After `s` the results narrow to Settings and Save and no empty-result message is announced. After `x` nothing matches: confirm `No results` is announced once, after the results are replaced by the message. Type `z`: the query still matches nothing and `No results` is announced once more, because each settled empty query announces once. Clear the query and confirm the four results return with no empty-result announcement. **Rendered message:** within the panel labeled `Empty command palette`, focus its `Search commands` input and paste `missing` as one edit. Confirm the rendered `No matching commands. Create a command` message is announced once, without substituting the built-in default. Clear the query and paste `missing` again; it is announced once more. |--| Required pairing | State |-| --------------------------- | --------- |-| NVDA + Chrome on Windows | `pending` |-| VoiceOver + Safari on macOS | `pending` |--Both rows block the first affected stable release until each has a passing durable receipt or a current owner-recorded exception. DOM, axe, accessibility-tree, and browser evidence continue to prove their assigned claims but do not clear this announcement gate.--This accepted spec creates no runtime or process implementation.--**Current enforcement status: missing.** No automated fail-closed check currently reads this block before publication. Implementing that check is non-blocking stack work for this documentation slice. Until it lands, this record states the required hold but does not itself prevent publication.--No current contributing record owns assistive-technology verification or the release hold. When those records are authored, they must link back to `spec:AST-009` rather than copying its policy; only then should their current identifiers be added to `affects_contributing`.+- Earlier recorded stable-release holds for read-only Popover initial focus and+ CommandPalette empty-result announcements are recommended follow-ups. Their+ checked-in scenarios (`Read-only dialog focus`; `CommandPalette / Audit+Matrix`) and pairings stay valid for a real-AT run and hold no release.+- `spec:AST-086` status-announcement fixes merge on FR4 evidence (FR17, FR19).+- `spec:AST-001`, `spec:AST-020`, `spec:AST-021`, `spec:AST-056`, `spec:AST-086`,+ `component:FieldStatus`, `module:Table/useTableRowStatus`, and+ `module:Table/useTableColumnResize` describe real-AT observation as+ recommended follow-up, not a merge or release requirement.+- No contributing record owns assistive-technology verification. When one is+ authored, it links back to `spec:AST-009` rather than copying its policy.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| --------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |-| FR1–FR8 | Classification review against the change's claimed user outcome. | static semantic fix; browser-only focus change; AT-announced autofocus; live update; virtual-cursor entry; known divergence | AT-dependent outcome ships without a gate, or unrelated accessibility fix is forced through a universal AT matrix. |-| FR9–FR11 | Evidence-map review plus focused tests/observations. | unit state; DOM attributes; computed tree; axe state; browser focus; spoken/braille result | Lower layer is credited with speech, timing, cursor, or interoperability it cannot observe. |-| FR12–FR16 | Named matrix in the durable release-block record. | desktop-neutral; platform-specific; mobile; known divergent stacks | Generic “screen reader checked” result substitutes for the required independent or divergent pairing. |-| FR17–FR22 | Release-record review against source commit and candidate build. | merged pending change; passing rows; failed row and fix; later unrelated build | Stable release publishes with a pending/failed/invalid row, or unrelated commits force needless retesting. |-| FR23–FR26 | Owner and expiry review. | release-scoped exception; dated exception; expired or invalidated exception | Waiver is inferred, recorded as pass, loses its user-risk statement, or silently becomes permanent. |-| FR27–FR31 | Receipt completeness and link-durability review. | PR receipt; linked issue; reusable checked-in fixture; supplementary recording | Critical evidence exists only in an expired/private artifact, cannot be reproduced, or guidance forks this policy. |+| Contract | Verification | Representative states | Mutation or failure expectation |+| --------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR8 | Classification review against the change's claimed user outcome. | static semantic fix; browser-only focus change; AT-announced autofocus; live update; virtual-cursor entry; known divergence | An AT-dependent claim ships without its lower-layer proof, or an unrelated accessibility fix is sent to real-AT follow-up. |+| FR9–FR11 | Evidence-map review plus focused tests/observations. | unit state; DOM attributes; computed tree; axe state; browser focus; spoken/braille result | A lower layer is credited with speech, timing, cursor, or interoperability it cannot observe. |+| FR12–FR16 | Pairings named in a real-AT receipt. | desktop-neutral; platform-specific; mobile; known divergent stacks | A generic “screen reader checked” result substitutes for the required independent or divergent pairing. |+| FR17–FR22 | Merge and release review. | announcement fix with FR4 evidence; pending follow-up issue; failed real-AT observation; stale receipt | A pull request or release waits on real-AT evidence, or lower-layer proof is described as proving speech. |+| FR27–FR31 | Receipt completeness and link-durability review. | PR receipt; linked issue; reusable checked-in fixture; supplementary recording | Critical evidence exists only in an expired/private artifact, cannot be reproduced, or guidance forks this policy. |### Completion criteria-For an affected stable release, this accepted policy is satisfied only when:+A change meets this policy when:-- every included change has explicit trigger classification under FR8;-- each claim has evidence from the layer that can observe it under FR9–FR11;-- every triggered real-AT row clears through a complete applicable passing receipt under FR19 and FR28, or a current owner-recorded exception under FR23–FR26;-- pending, failed, invalidated, and expired rows still block release under FR17–FR22 and FR25; and-- canonical receipts and any exceptions remain durably linked from the change or release record under FR27–FR29.+- an AT-dependent claim is named under FR8;+- each claim has evidence from the producible layer that can observe it under FR4, FR9–FR11, and FR19;+- no merge or release waited on real-AT observation under FR17; and+- any real-AT receipt that exists is durable and reproducible under FR27–FR29.## Decision log-### DEC-1 — Real AT verification is outcome-triggered, not category-wide+### DEC-1 — Real-AT follow-up is outcome-triggered, not category-wide**Reference:** `spec:AST-009/DEC-1` · **Decider:** `cixzhang`, `2026-08-31`-**Decision:** FR1–FR8 require real AT/browser verification for AT-specific focus exposure/order, announcement behavior, virtual-cursor entry, or known divergence. Focus destination, keyboard behavior, focus appearance, and other accessibility changes use the evidence and authority that directly own their claim.-**User-impact rationale:** This proves AT-dependent outcomes without making unrelated changes run costly shallow checks. **Rejected:** requiring every accessibility change to run every AT.+**Decision:** FR1–FR8 recommend real AT/browser follow-up for AT-specific focus exposure/order, announcement behavior, virtual-cursor entry, or known divergence. Focus destination, keyboard behavior, focus appearance, and other accessibility changes use the evidence and authority that directly own their claim.+**User-impact rationale:** AT-dependent outcomes get targeted attention without making unrelated changes run costly shallow checks. **Rejected:** running every AT on every accessibility change.### DEC-2 — Evidence layers keep distinct proof boundaries**Reference:** `spec:AST-009/DEC-2` · **Decider:** `cixzhang`, `2026-08-31`**Decision:** Unit, DOM, accessibility-tree, axe, browser, and real-AT evidence each prove a different boundary. Changes compose needed layers instead of treating one tool as general accessibility proof.-**User-impact rationale:** People must get the heard or navigated result, not only plausible markup or a green automated check. **Rejected:** accepting a green axe run, plausible ARIA, or an accessibility snapshot as proof of what a person hears or where their virtual cursor enters.+**User-impact rationale:** People must get the heard or navigated result, not only plausible markup or a green automated check. **Rejected:** describing a green axe run, plausible ARIA, or an accessibility snapshot as proof of what a person hears or where their virtual cursor enters.### DEC-3 — The real-AT matrix is representative and claim-specific**Reference:** `spec:AST-009/DEC-3` · **Decider:** `cixzhang`, `2026-08-31`-**Decision:** Desktop-neutral AT-specific focus exposure/order and announcement claims use NVDA + Chrome on Windows and VoiceOver + Safari on macOS. Mobile, platform-specific, and known-divergent claims select or expand that matrix according to the affected outcome. Passing results make no universal compatibility claim.-**User-impact rationale:** The matrix covers the claim without implying untested AT, browser, verbosity, locale, or input behavior. **Rejected:** one fixed exhaustive matrix for every change, or one convenient pairing standing in for a stack already known to behave differently.+**Decision:** Desktop-neutral follow-up uses NVDA + Chrome on Windows and VoiceOver + Safari on macOS. Mobile, platform-specific, and known-divergent claims select or expand that matrix according to the affected outcome. Passing results make no universal compatibility claim.+**User-impact rationale:** The pairings cover the claim without implying untested AT, browser, verbosity, locale, or input behavior. **Rejected:** one fixed exhaustive matrix for every change, or one convenient pairing standing in for a stack already known to behave differently.-### DEC-4 — Pending AT evidence blocks stable release, not merge to main+### DEC-4 — Real-AT evidence never gates merge or release-**Reference:** `spec:AST-009/DEC-4` · **Decider:** `cixzhang`, `2026-08-31`-**Decision:** Under FR2–FR6, implementation may merge after the otherwise-required evidence from the owning records, plus a durable named follow-up. The first stable release remains blocked until the named real AT/browser matrix passes or a spec owner records a narrow, expiring exception.-**User-impact rationale:** Integration can proceed while stable users are protected from unverified AT-dependent outcomes. **Rejected:** holding every such change out of `main`, or releasing it stably on an unowned promise to test later.+**Reference:** `spec:AST-009/DEC-4` · **Decider:** `cixzhang`, `2026-10-22`+**Decision:** Merge and stable release require only evidence Astryx can produce. DOM, accessibility-tree, axe, and real-browser evidence set the bar; real-AT observation is recommended follow-up (FR17–FR19).+**User-impact rationale:** A requirement no contributor can meet stalls the fixes that remove known accessibility defects, which keeps those defects in front of users longer. **Rejected:** holding stable releases until named real-AT receipts pass.-### DEC-5 — Evidence and exceptions remain durable at the change boundary+### DEC-5 — Real-AT receipts stay durable at the change boundary**Reference:** `spec:AST-009/DEC-5` · **Decider:** `cixzhang`, `2026-08-31`-**Decision:** The change or linked release record carries reproducible textual receipts, applicable build identity, results, and finite exceptions. Expiring artifacts may supplement but cannot own the facts that clear the release block.-**User-impact rationale:** Future contributors and maintainers can audit why a release was allowed. **Rejected:** private notes, local files, or transient CI artifacts as the only release evidence.+**Decision:** When a real-AT check runs, the change or linked tracking record carries a reproducible textual receipt with build identity and result. Expiring artifacts may supplement it but cannot own its facts.+**User-impact rationale:** Future contributors and maintainers can audit what was observed and on which build. **Rejected:** private notes, local files, or transient CI artifacts as the only record.## Open questionsdiff --git a/docs/specs/AST-020/spec.md b/docs/specs/AST-020/spec.mdindex 112109d7fb..0e13238241 100644--- a/docs/specs/AST-020/spec.md+++ b/docs/specs/AST-020/spec.md@@ -108,7 +108,7 @@ review. It does not claim that one automated pass proves complete accessibility.manual, or real-AT checks. A lower layer MUST NOT claim a result only a higherlayer observes. Announcement wording or timing, virtual-cursor entry, and knownAT/browser divergence follow [AST-009](../AST-009/spec.md); an accessibility-tree- snapshot does not satisfy that real-AT contract.+ snapshot does not prove spoken output.- **FR7 — Contracts assert outcomes, not Astryx internals.** A reusable expectationMUST query and act through public semantics and observable behavior. It MUST NOTdepend on Astryx class names, private DOM wrappers, implementation callbacks, ordiff --git a/docs/specs/AST-021/spec.md b/docs/specs/AST-021/spec.mdindex 0c130cee5e..2ed6d4c2ad 100644--- a/docs/specs/AST-021/spec.md+++ b/docs/specs/AST-021/spec.md@@ -152,7 +152,7 @@ implementation-specific regression coverage.explicitly unrun; jsdom success does not clear it.- Browser evidence: component changes that can affect browser-owned pattern behaviorrun the relevant real-browser binding. Real-AT outcomes follow- [AST-009](../AST-009/spec.md) and keep their durable receipts and release boundary.+ [AST-009](../AST-009/spec.md) as recommended follow-up with durable receipts.## Current-state impactdiff --git a/docs/specs/AST-056-search-prop-shape/spec.md b/docs/specs/AST-056-search-prop-shape/spec.mdindex 5cb12dd932..ad0acb10ef 100644--- a/docs/specs/AST-056-search-prop-shape/spec.md+++ b/docs/specs/AST-056-search-prop-shape/spec.md@@ -265,9 +265,9 @@ copying.current API until the rule is settled for it.- Browser evidence: DOM live-region assertions prove the rendered content source,but they do not prove what assistive technology announces or when. Any adopter- that changes announcement content or timing follows `spec:AST-009`: name the- applicable real-AT matrix and keep the first affected stable release blocked- until the required durable receipts pass or a current exception applies.+ that changes announcement content or timing proves its routing, text, and+ occasion count at the DOM and accessibility-tree layers; real-AT observation is+ recommended follow-up under `spec:AST-009`.## Migration and compatibilitydiff --git a/docs/specs/AST-086-status-announcements/spec.md b/docs/specs/AST-086-status-announcements/spec.mdindex a8a5cfa318..76de830555 100644--- a/docs/specs/AST-086-status-announcements/spec.md+++ b/docs/specs/AST-086-status-announcements/spec.md@@ -109,8 +109,8 @@ announcement channel.state through a persistent region inside that modal (FR3, FR8). Otherdelivery inside native modals is outside this record.- Browser evidence: DOM and accessibility-tree checks prove routing (FR1–FR5,- FR7–FR10). Spoken timing, order, and repetition (FR6 on real AT) require- `spec:AST-009` FR4 evidence.+ FR7–FR10). Spoken timing, order, and repetition on real AT are+ recommended `spec:AST-009` follow-up, not a merge or release requirement.## Current-state impact@@ -173,7 +173,7 @@ announcement channel.| FR8 | Shared test: no live role inside a busy owner; channel spy on the owner | Busy TextInput, Selector, Switch thumb, ChatMessageList loader, busy CommandPalette (region inside its dialog) | A composed indicator with a live role or its own announcement, or a busy owner that announces nothing, fails || FR9 | `useAnnounce` tests | First use, many components, region removed, server render | A second region pair, or stale text after the clear delay, fails || FR10 | Accessibility-tree check with a Dialog open | Info and error toast shown over an open Dialog | A toast that reaches only the body-level channel, or no exposed live container, fails |-| FR6 (AT) | `spec:AST-009` real-AT receipt | Toast, busy Switch, chat notice | Missing, repeated, or out-of-order speech fails |+| FR6 (AT) | Recommended `spec:AST-009` real-AT follow-up | Toast, busy Switch, chat notice | Missing, repeated, or out-of-order speech fails |## Decision logdiff --git a/packages/core/src/FieldStatus/FieldStatus.spec.md b/packages/core/src/FieldStatus/FieldStatus.spec.mdindex 1d701cadbc..afba3e860f 100644--- a/packages/core/src/FieldStatus/FieldStatus.spec.md+++ b/packages/core/src/FieldStatus/FieldStatus.spec.md@@ -130,9 +130,9 @@ intentional decision.region, including on first mount and when message or type changes, withoutmoving focus. Inside a mounted live container, `spec:AST-086` FR4 applies.- **AR5 — Assistive-technology output.** Claims about whether, when, or how the- message is spoken or presented in braille MUST be verified through the real-AT- evidence process in `spec:AST-009`; DOM and accessibility-tree checks prove- only programmatic exposure and routing.+ message is spoken or presented in braille are recommended real-AT follow-up+ under `spec:AST-009`, not a merge or release requirement; DOM and+ accessibility-tree checks prove programmatic exposure and routing.- **AR2 — Visible description.** The rendered message box MUST remain availableto assistive technology for `aria-describedby` association and MUST NOT becomeits own newly mounted live region.@@ -182,7 +182,7 @@ change either presentation.| FR5, FR6 | `FieldStatus.test.tsx` forwarding and update suites | Initial render and rerender | Breaking the released root or update behavior fails compatibility assertions. | `audit:FieldStatus/behavior` || AR1 | `StatusMessage.a11y.test.tsx` and `StatusMessage.a11y.chromium.spec.ts` | Error, warning, and success; post-mount message replacement | Removing the persistent channel, changing its role/urgency, or dropping a post-mount update fails the shared status-message contract. | `audit:FieldStatus/accessibility` || AR1 | `FieldStatus.test.tsx` channel-routing suite | First non-empty mount; same-instance message and type changes | Breaking FieldStatus's first-use hook call or severity rerouting fails component-specific assertions. | `audit:FieldStatus/accessibility` |-| AR5 | Pending/unverified real-AT evidence governed by `spec:AST-009` | First mount; message replacement; type/urgency change | Spoken and braille output remain unverified until a durable named AT/browser receipt exists. | `audit:FieldStatus/accessibility` |+| AR5 | Recommended real-AT follow-up under `spec:AST-009` | First mount; message replacement; type/urgency change | Spoken and braille output stay unverified until a real-AT receipt exists; this does not block merge or release. | `audit:FieldStatus/accessibility` || AR2 | `FieldStatus.test.tsx` | Attached/detached visible message and empty message | The visible description becomes a second live region or is hidden from assistive technology. | `audit:FieldStatus/accessibility` || Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current targets | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation. | `audit:FieldStatus/theming` |diff --git a/packages/core/src/Table/plugins/columnResize/useTableColumnResize.spec.md b/packages/core/src/Table/plugins/columnResize/useTableColumnResize.spec.mdindex 98f804ca0f..95b467b750 100644--- a/packages/core/src/Table/plugins/columnResize/useTableColumnResize.spec.md+++ b/packages/core/src/Table/plugins/columnResize/useTableColumnResize.spec.md@@ -227,17 +227,17 @@ without a target of its own.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation |-| ------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1, FR6 | `useTableColumnResize.test.tsx` boundary-presence cases plus hover-capability and coarse-primary cases | Resizable, opted-out, and generated columns; hover-capable, coarse-primary with keyboard, and coarse-only inputs | A boundary appears on a non-resizable column, disappears from a resizable one, the hover reveal fires where no pointer can hover, or the control is absent where an input can operate it. |-| FR2 | Browser measurement of scroll-region vertical overflow with the plugin enabled | Short and tall tables, wrapped and single-line headers, dense and default | The indicator ends below the last row or the scroll region gains vertical scroll that the same table lacks without resize. |-| FR3-FR5, FR9, ORD1 | New focused tests for resting, header-hovered, pointer-on-boundary, focused, and dragging states | Rest, header hover, hover plus pointer on one boundary, keyboard focus with no pointer in the row, drag | A resting header draws boundaries, header hover misses a boundary, the pointed/focused boundary fails to outrank the hint, or focus alone draws a neighbor. |-| FR10, ORD0 | Scroll-gate test driving the scroll region with a stationary pointer over the header | Pointer resting over a header while the region scrolls and after it settles | Boundaries reveal mid-scroll, an existing hint survives the scroll, or disclosure fails to resume once scrolling stops. |-| FR7 | Snapshot or assertion that header hover changes no other header or row treatment | Header hover over a sortable and a selectable header | Header hover changes background, label, cursor, width, or another control's state. |-| FR8, AR1-AR3, AR6 | Existing keyboard and ARIA suites, a coarse-primary keyboard case, plus assistive-technology spot check | Tab to boundary, arrow resize, screen-reader navigation of the header, coarse-primary device with a keyboard | The boundary leaves tab order on any input that can operate it, loses its name or values, or the hint reaches the accessibility tree. |-| PR1, PR2 | Render-count assertion around header pointer enter/leave and during a scroll; listener and observer inspection | Pointer enters and leaves the header repeatedly; the region scrolls under a resting pointer | Disclosure rerenders the Table, the scroll gate sets React state, more than one scroll listener or any timer is added, or the extent measurement observes what it resizes. |-| Plugin composition | Test mounting the resize and sticky-columns plugins together in both insertion orders | Pinned start column with resize enabled, before and after a drag | A pinned column loses `position: sticky` in either order, or the composition depends on caller insertion order. |-| Record shape | `scripts/check-knowledge.mjs` | Colocated module record, canonical id and filename, parent backlink | A missing, misnamed, mis-parented, or unlinked record passes validation. |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, FR6 | `useTableColumnResize.test.tsx` boundary-presence cases plus hover-capability and coarse-primary cases | Resizable, opted-out, and generated columns; hover-capable, coarse-primary with keyboard, and coarse-only inputs | A boundary appears on a non-resizable column, disappears from a resizable one, the hover reveal fires where no pointer can hover, or the control is absent where an input can operate it. |+| FR2 | Browser measurement of scroll-region vertical overflow with the plugin enabled | Short and tall tables, wrapped and single-line headers, dense and default | The indicator ends below the last row or the scroll region gains vertical scroll that the same table lacks without resize. |+| FR3-FR5, FR9, ORD1 | New focused tests for resting, header-hovered, pointer-on-boundary, focused, and dragging states | Rest, header hover, hover plus pointer on one boundary, keyboard focus with no pointer in the row, drag | A resting header draws boundaries, header hover misses a boundary, the pointed/focused boundary fails to outrank the hint, or focus alone draws a neighbor. |+| FR10, ORD0 | Scroll-gate test driving the scroll region with a stationary pointer over the header | Pointer resting over a header while the region scrolls and after it settles | Boundaries reveal mid-scroll, an existing hint survives the scroll, or disclosure fails to resume once scrolling stops. |+| FR7 | Snapshot or assertion that header hover changes no other header or row treatment | Header hover over a sortable and a selectable header | Header hover changes background, label, cursor, width, or another control's state. |+| FR8, AR1-AR3, AR6 | Existing keyboard and ARIA suites and a coarse-primary keyboard case; an assistive-technology spot check is recommended follow-up | Tab to boundary, arrow resize, screen-reader navigation of the header, coarse-primary device with a keyboard | The boundary leaves tab order on any input that can operate it, loses its name or values, or the hint reaches the accessibility tree. |+| PR1, PR2 | Render-count assertion around header pointer enter/leave and during a scroll; listener and observer inspection | Pointer enters and leaves the header repeatedly; the region scrolls under a resting pointer | Disclosure rerenders the Table, the scroll gate sets React state, more than one scroll listener or any timer is added, or the extent measurement observes what it resizes. |+| Plugin composition | Test mounting the resize and sticky-columns plugins together in both insertion orders | Pinned start column with resize enabled, before and after a drag | A pinned column loses `position: sticky` in either order, or the composition depends on caller insertion order. |+| Record shape | `scripts/check-knowledge.mjs` | Colocated module record, canonical id and filename, parent backlink | A missing, misnamed, mis-parented, or unlinked record passes validation. |Browser, render-count, and assistive-technology evidence are pending. Passing thisspecification pull request proves record integrity only.diff --git a/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.spec.md b/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.spec.mdindex 8600530a7d..ac20a40781 100644--- a/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.spec.md+++ b/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.spec.md@@ -214,8 +214,9 @@ add semantic/custom cases to representative Table render and no-op update budget- **AR5 — Supplemental tooltip.** Tooltip may repeat `label` as pointer help, butthe indicator's accessible name MUST remain sufficient without opening it. Thecurrent indicator is not focusable, so tooltip presence is not keyboard evidence.-- **AR6 — Row context.** Assistive-technology verification MUST confirm the named- status is encountered in its row context without duplicate announcements.+- **AR6 — Row context.** The named status is exposed in its row context without a+ duplicate name, proved at the accessibility tree. Assistive-technology+ observation of the announcement is recommended follow-up under `spec:AST-009`.## Design relationships@@ -259,7 +260,7 @@ own AST-002 review and synchronized consumer anatomy.| FR3, FR4, FR6 | Add public-subpath compile fixtures for the unchanged interface, declaration merging and extension, semantic interface, callback union, missing labels, unknown statuses, and forbidden mixtures. | Stable custom annotations/extensions; all semantic statuses. | `TableRowStatus` changes or stops merging, semantic usage is inaccessible, or supported status mixes with custom fields. || FR3-FR5 | Extend row-status runtime tests with semantic-looking custom colors, raw/palette dots, explicit custom icons, all semantic statuses, and active-theme substitution. | Custom dot, custom icon, and three semantic outcomes. | Custom color selects an implicit glyph, semantic status bypasses shared resolution, or variant becomes caller/theme input. || FR7, ORD2-ORD4, PR4 | Runtime tests under development and production modes with repeated mixed objects, rows, and renders. | `status + color`, `status + icon`, and all three fields. | Custom input overrides supported status, forbidden fields affect output, production warns, or development warns more than once per loaded module instance. |-| AR1-AR6 | Existing role/name tests plus browser axe, forced-colors, tooltip modality, and VoiceOver table-navigation evidence. | Semantic glyphs, custom icon, custom dot, `null`, light/dark, and every shipped theme. | Header or indicator loses its name, nested glyph is announced twice, glyph distinctions disappear, tooltip becomes sole meaning, or row context duplicates status. |+| AR1-AR6 | Existing role/name tests plus browser axe, forced-colors, tooltip modality, and accessibility-tree row-context evidence; VoiceOver table navigation is recommended follow-up. | Semantic glyphs, custom icon, custom dot, `null`, light/dark, and every shipped theme. | Header or indicator loses its name, nested glyph is announced twice, glyph distinctions disappear, tooltip becomes sole meaning, or row context duplicates status. || PR1-PR3 | Extend `Table.perf.test.tsx` with semantic/custom initial render and no-op update cases. | Stable rerender, mixed rows, and theme substitution. | Resolution adds measurement/resources, creates a parallel registry, or exceeds existing representative Table budgets. || Structural ownership | `scripts/check-knowledge.mjs`. | Colocated module, canonical filename/id, and parent backlink. | A missing, duplicate, orphaned, mis-parented, misnamed, or undiscovered record passes validation. || Public hygiene and scope | Prettier, `check:knowledge`, checker tests, `check:repo`, changed-file scan, and public-content scan. | Parent backlink plus one module specification; no Changeset. | Runtime/docs files, private context, invalid record shape, or unrelated changes enter this contract proposal. |