An open source design system that's fully customizable and agent ready
TypeScript
spec(a11y): APG adoption follows the role a component already plays; CollapsibleGroup adopts Accordion's required parts (#7458)
Cindy Zhang5a184b79423d
diff --git a/docs/specs/AST-020/spec.md b/docs/specs/AST-020/spec.mdindex 8754036052..112109d7fb 100644--- a/docs/specs/AST-020/spec.md+++ b/docs/specs/AST-020/spec.md@@ -24,7 +24,7 @@ affects_consumer_docs: []{"scope": "global","triggers": {- "accessibility": ["FR1", "FR2", "FR6"]+ "accessibility": ["FR1", "FR2", "FR6", "FR15"]}}```@@ -80,6 +80,15 @@ review. It does not claim that one automated pass proves complete accessibility.pattern-specific role, state, relationship, keyboard, and focus requirements.A component part may bind to more than one pattern. A whole component MUST NOT beforced into one pattern when its parts have distinct roles.+- **FR15 — Adoption follows the role a component already plays.** Where a+ component part already plays an APG pattern's role, Astryx adopts that pattern's+ required parts for it: the role, the accessible name, the state and relationship+ properties, and activation by Tab plus Enter or Space. The pattern's optional+ keyboard extras — arrow-key movement between parts, Home and End — are adopted+ only where the component already acts as one composite control; a set of+ independently focusable controls does not gain them. The owning component record+ names the parts it adopts, any required part it does not adopt with the reason,+ and any extra it adopts beyond this rule as a named exception.### Expectation contract@@ -212,13 +221,14 @@ or CI gate. Those changes follow in implementation work governed by this record.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| --------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |-| FR1–FR3 | Source and ownership review against WCAG 2.2, APG, and current Astryx records | component-owned A/AA criterion; page-owned criterion; one component with multiple parts | A draft WCAG 3.0 statement gates CI, an APG example is treated as universal WCAG, or one component is forced into one pattern |-| FR4–FR9 | Contract schema and runner self-tests | required/advisory; unit/DOM/tree/axe/browser/manual/AT; toggle round trip; component-specific callback | A check lacks a source or layer, passes from an unsupported harness, depends on private markup, or one-way behavior hides a reverse-path failure |-| FR10–FR12 | Completed checklist, positive/negative fixture suite, and independent review | simple control; composite widget; overlay; page-owned criterion | A dimension disappears silently, a mutation still passes, or review finds an unrecorded contract-encodable requirement |-| FR13–FR14 | Pull-request template check plus id migration tests | new pattern; narrowed expectation; file-only refactor | Reviewers cannot understand the test from the PR, or an id change orphans bindings and gaps |-| Platform | Real-browser and AST-009 evidence-boundary checks | focus navigation; accessibility tree; forced colors; announcement timing | jsdom or a tree snapshot is credited with pixels, browser behavior, or spoken output it cannot observe |+| Contract | Verification | Representative states | Mutation or failure expectation |+| --------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | Source and ownership review against WCAG 2.2, APG, and current Astryx records | component-owned A/AA criterion; page-owned criterion; one component with multiple parts | A draft WCAG 3.0 statement gates CI, an APG example is treated as universal WCAG, or one component is forced into one pattern |+| FR4–FR9 | Contract schema and runner self-tests | required/advisory; unit/DOM/tree/axe/browser/manual/AT; toggle round trip; component-specific callback | A check lacks a source or layer, passes from an unsupported harness, depends on private markup, or one-way behavior hides a reverse-path failure |+| FR10–FR12 | Completed checklist, positive/negative fixture suite, and independent review | simple control; composite widget; overlay; page-owned criterion | A dimension disappears silently, a mutation still passes, or review finds an unrecorded contract-encodable requirement |+| FR15 | Adoption review against the component's current role claims | a disclosure set adopting required parts only; a composite control adopting arrow keys; a named exception | A required part is skipped without the owning record's reason, or arrow keys are added to independently focusable controls without a named exception |+| FR13–FR14 | Pull-request template check plus id migration tests | new pattern; narrowed expectation; file-only refactor | Reviewers cannot understand the test from the PR, or an id change orphans bindings and gaps |+| Platform | Real-browser and AST-009 evidence-boundary checks | focus navigation; accessibility tree; forced colors; announcement timing | jsdom or a tree snapshot is credited with pixels, browser behavior, or spoken output it cannot observe |### Completion criteria@@ -273,6 +283,22 @@ reviewable by accessibility specialists and maintainers.Rejected: code-only review or a generic accessibility checklist with no exactmapping to executable expectations.+### DEC-4 — Adopt what the component already is++**Reference:** `spec:AST-020/DEC-4`+**Decider:** `cixzhang`, `2026-10-13`++A pattern's required parts belong to any component part that already plays the+pattern's role, because a user who meets that role expects its name, state, and+activation. Its optional keyboard extras belong only to one composite control,+because arrow keys and Home/End move within one widget; independent controls keep+the page Tab order. A component that already ships an extra records it as a named+exception rather than losing it.++Rejected: adopting every part of a pattern wherever its role appears (arrow keys on+independent controls); adopting nothing until a component matches an APG example in+full.+## Open questionsNone.diff --git a/packages/core/src/Collapsible/CollapsibleGroup.spec.md b/packages/core/src/Collapsible/CollapsibleGroup.spec.mdindex f2f8cd5f37..bf3f8525bb 100644--- a/packages/core/src/Collapsible/CollapsibleGroup.spec.md+++ b/packages/core/src/Collapsible/CollapsibleGroup.spec.md@@ -133,6 +133,7 @@ Consumer migration instructions belong in consumer docs and release notes.- **AR1 — Child semantics remain primary.** Group coordination MUST preserve each Collapsible button's accessible name, `aria-expanded`, `aria-controls`, controlled region, and keyboard activation.- **AR2 — Presentation adds no competing interaction.** The divider wrapper MUST NOT add a role, focus target, accessible name, or keyboard behavior.- **AR3 — Direction stays with Collapsible.** Group chevron defaults MUST preserve `component:Collapsible/AR1–AR3`, including the inward leading cue under LTR and RTL.+- **AR4 — The group adopts the APG Accordion pattern's required parts** (`spec:AST-020/FR15`): each direct item's header is a `button` whose accessible name is the item's title, with `aria-expanded` reflecting its panel, `aria-controls` naming the panel it reveals, and `aria-disabled` when it cannot be toggled; every enabled header sits in the page Tab order and Enter or Space toggles its panel, in `single` mode collapsing the sibling that was open; a disabled header carries `aria-disabled`, drops out of the Tab order, and cannot be toggled. Not adopted: a heading element around each header (this record requires none; the caller's document structure supplies headings), the optional `region` role on panels, and arrow-key or Home/End movement between headers — the group is a set of independent disclosures, not one composite control.## Design relationships@@ -171,17 +172,25 @@ The Group container is CollapsibleGroup's conditional aggregate wrapper. The oth## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ---------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |-| FR1–FR4, ORD1 | `CollapsibleGroup.test.tsx`; `useCollapsible.test.tsx` | single/multiple; controlled/uncontrolled; valued/unvalued | A sibling stays open in single mode, closes in multiple mode, controlled state mutates internally, or an unvalued item loses local state. | `audit:CollapsibleGroup/behavior` |-| FR5–FR6, ORD2–ORD3 | `CollapsibleGroup.test.tsx`; `Collapsible.test.tsx`; `themingTargets.test.ts` | plain/divided; each density; group/item/nested position | Wrapper/target reachability changes, defaults stop reaching direct items, or presentation leaks into nested content. | `audit:CollapsibleGroup/theming` |-| AR1–AR3 | DOM and Chromium accessibility suites; component-owned Storybook fixture; RTL audit | open/closed; single/multiple; leading/trailing; LTR/RTL | Disclosure semantics diverge from state, the wrapper becomes interactive, or leading direction stops mirroring. | `audit:CollapsibleGroup/accessibility` |-| PR1–PR2, FR7 | source review plus context and interaction tests | unchanged and changed state/presentation inputs | An Effect/resource appears, unchanged payload broadcasts a new identity, or changed group behavior fails to reach consumers. | `audit:CollapsibleGroup/code-health` |-| Consumer documentation | CLI component projection, docs checks, and `CollapsibleGroup.stories.tsx` | every public concept and representative composition | A released prop/default is undiscoverable or the owned browser route loses representative state coverage. | `audit:CollapsibleGroup/docs` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |+| FR1–FR4, ORD1 | `CollapsibleGroup.test.tsx`; `useCollapsible.test.tsx` | single/multiple; controlled/uncontrolled; valued/unvalued | A sibling stays open in single mode, closes in multiple mode, controlled state mutates internally, or an unvalued item loses local state. | `audit:CollapsibleGroup/behavior` |+| FR5–FR6, ORD2–ORD3 | `CollapsibleGroup.test.tsx`; `Collapsible.test.tsx`; `themingTargets.test.ts` | plain/divided; each density; group/item/nested position | Wrapper/target reachability changes, defaults stop reaching direct items, or presentation leaks into nested content. | `audit:CollapsibleGroup/theming` |+| AR4 | `Collapsible.test.tsx` (disabled trigger: `aria-disabled`, out of the Tab order, no toggle); `CollapsibleGroup.test.tsx` (single/multiple coordination, `aria-expanded`, Enter activation); `Collapsible.a11y.test.tsx` and `Collapsible.a11y.chromium.spec.ts` (disclosure semantics, Space, Tab reachability for a lone item); grouped Tab order, Space in a group, and no arrow-key movement under the Accordion contract (`internal/a11y-spec`, pending) | single/multiple; open/closed; a disabled item, open or closed; Tab order; Enter/Space round trip | A header loses its button role, name, `aria-expanded`, or `aria-controls`; Enter or Space stops toggling; arrow keys move focus between headers | `audit:CollapsibleGroup/accessibility` |+| AR1–AR3 | DOM and Chromium accessibility suites; component-owned Storybook fixture; RTL audit | open/closed; single/multiple; leading/trailing; LTR/RTL | Disclosure semantics diverge from state, the wrapper becomes interactive, or leading direction stops mirroring. | `audit:CollapsibleGroup/accessibility` |+| PR1–PR2, FR7 | source review plus context and interaction tests | unchanged and changed state/presentation inputs | An Effect/resource appears, unchanged payload broadcasts a new identity, or changed group behavior fails to reach consumers. | `audit:CollapsibleGroup/code-health` |+| Consumer documentation | CLI component projection, docs checks, and `CollapsibleGroup.stories.tsx` | every public concept and representative composition | A released prop/default is undiscoverable or the owned browser route loses representative state coverage. | `audit:CollapsibleGroup/docs` |## Decision log-None. This audit records shipped behavior and delegates chevron representation to the current Collapsible contract; it makes no new product decision.+### DEC-1 — Adopt Accordion's required parts; keep the headers independent++**Reference:** `component:CollapsibleGroup/DEC-1`+**Decider:** `cixzhang`, `2026-10-13`++The group's headers already play the accordion header's role, so they carry its name, state, relationship, and Enter/Space activation (AR4). They stay in the page Tab order without arrow-key or Home/End movement because the group coordinates independent disclosures rather than acting as one composite control; a heading wrapper is left to the caller's document structure.++Rejected: arrow-key movement between headers; a required heading element around each header.## Open questions