@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/src/Citation/Citation.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 6
+template_version: 7
 kind: component
 id: component:Citation
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, theming, accessibility, visual]
 verified_by:
@@ -16,6 +16,9 @@ verified_by:
     packages/core/src/utils/safeUrl.test.ts,
     apps/storybook/stories/Citation.stories.tsx,
     apps/storybook/rtl-audit/verified-not-applicable.json,
+    packages/core/src/theme/themingTargets.test.ts,
+    .github/visual-baseline/manifest.json,
+    scripts/check-knowledge.mjs,
   ]
 modules: []
 families: [family:navigation-destinations]
@@ -35,17 +38,17 @@ system_specs: [spec:AST-005]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                 |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | `Citation` is exported from `@astryxdesign/core/Citation`; `source` and `number` are required, and `variant` defaults to `label`.                                                                                                                                                                                        |
-| Behavior                | An accepted source URL renders a native anchor in a new tab. A missing or rejected URL renders the same citation content in an inert span. Label and number variants preserve that navigation decision.                                                                                                                  |
-| End-user impact         | Readers receive a consistent citation label or numbered reference without a blocked destination becoming navigation or a decorative source icon being announced twice.                                                                                                                                                   |
-| Builder impact          | Builders may supply source text, a destination, an image or node icon, neutral DOM props, a root ref, and composed styling without replacing Citation’s navigation or accessibility ownership.                                                                                                                           |
-| Compatibility/readiness | The released defaults, export, theme target, URL behavior, and visual presentation remain unchanged. The inert span now uses a noninteractive naming role so its existing translated label reaches assistive technology.                                                                                                 |
-| Review checks           | Reject a blocked URL that becomes navigation, an accepted URL that loses native anchor affordances, an interactive or reference role on an inert citation, a missing inert accessible name, an announced decorative icon, dropped supported passthrough or ref behavior, or a new public theme target without authority. |
-| Governing rules         | `family:navigation-destinations/FR1,FR3–FR5,FR7–FR8`; `architecture:public-component-api/INV1,INV5,INV6,INV8,INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`.                                                                                 |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `Citation` is exported from `@astryxdesign/core/Citation`; `source` and `number` are required, and `variant` defaults to `label`.                                                                                                                                                                                                                               |
+| Behavior                | An accepted source URL renders a native anchor in a new tab. A missing or rejected URL renders the same citation content in an inert span. Label and number variants preserve that navigation decision.                                                                                                                                                         |
+| End-user impact         | Readers receive a consistent citation label or numbered reference without a blocked destination becoming navigation or a decorative source icon being announced twice.                                                                                                                                                                                          |
+| Builder impact          | A builder's explicit `role` or `aria-label` is meant to reach the root; today the component's role and translated name replace them (FR5 gap).                                                                                                                                                                                                                  |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.                                                                                                                                                                                                                         |
+| Review checks           | Reject a blocked URL that becomes navigation, an accepted URL that loses native anchor affordances, an interactive or reference role that Citation adds to an inert citation, a missing inert accessible name when the caller supplies none, an announced decorative icon, dropped passthrough or ref behavior, or a new public theme target without authority. |
+| Governing rules         | `family:navigation-destinations/FR1,FR3–FR5,FR7–FR8`; `architecture:public-component-api/INV1,INV5,INV6,INV8,INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`.                                                                                                                        |
 
-This table is a review projection; the body below is authoritative only after owner approval.
+This table is a review projection; the body below is authoritative.
 
 ## Intent
 
@@ -53,13 +56,22 @@ Present an inline reference to a source as a readable label or compact number wh
 
 ## Compatibility and migration
 
-- Released default preserved: yes
-- Compatibility class: restorative accessibility semantics plus observational documentation; no public-type, visual, layout, styling, or theme-target change
-- Controlled/uncontrolled behavior: not applicable; Citation owns no state
-- Migration decision: none; the existing package export and source shape remain unchanged
+- Released default preserved: `yes` — `variant="label"`.
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  target, or styling output changes.
+- Controlled/uncontrolled behavior: not applicable; Citation owns no state.
+- Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **Caller `role` and `aria-label` replaced (FR5).** Caller props spread
+  before the component's `role` and `aria-label`, so a caller's explicit
+  values never reach the root, where `architecture:public-component-api` INV5
+  lets a caller's explicit input reach the element. The root-contract test
+  pins the replacement today.
+
 ## Ownership boundary
 
 **Owns**
@@ -85,15 +97,15 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                 | Basis                                                                                     | Draft review state |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------ |
-| FR1 | An accepted `source.url` MUST render a native anchor with the unchanged destination, `target="_blank"`, `rel="noopener noreferrer"`, `role="doc-noteref"`, and the current title and translated accessible name.                                                                                                                                                    | shipped source and tests; `family:navigation-destinations/FR1,FR3–FR5`                    | verify             |
-| FR2 | A missing or rejected destination MUST render the selected citation presentation in a noninteractive span with no navigation or reference role. The span MUST use a supported naming role so its translated label reaches assistive technology. Rejection MUST NOT derive navigation attributes from `source.url`, invent disabled semantics, or hide the citation. | shipped source and tests; `family:navigation-destinations/FR4,FR7`; WAI-ARIA naming rules | verify             |
-| FR3 | The label variant MUST present the source title, optional decorative source icon, and truncation behavior; the number variant MUST present the supplied number as the compact visible reference.                                                                                                                                                                    | shipped source, docs, tests, and stories                                                  | verify             |
-| FR4 | Node icons MUST take precedence over `src`; otherwise `src` MUST take precedence over a legacy string `icon`. Every icon path remains decorative inside an `aria-hidden` wrapper.                                                                                                                                                                                   | shipped compatibility behavior and tests                                                  | verify             |
-| FR5 | Both root branches MUST preserve supported DOM props, `className`, `style`, `xstyle`, `data-*` attributes, and the declared `HTMLElement` ref while keeping the component-owned role and accessible name authoritative.                                                                                                                                             | `architecture:public-component-api/INV5,INV6,INV8`; regression tests                      | verify             |
-| FR6 | Citation MUST keep one public `citation` target on the painted root and MUST NOT expose an internal icon or text target without an approved theming-contract change.                                                                                                                                                                                                | shipped docs/source; `architecture:component-theming-surface/INV3–INV6`                   | verify             |
-| FR7 | Component-owned accessible text MUST remain routed through `useTranslator`; visible source text and numeric content remain caller-supplied data.                                                                                                                                                                                                                    | shipped source and i18n infrastructure                                                    | verify             |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Basis                                                                                     |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| FR1 | An accepted `source.url` renders a native anchor with the unchanged destination, `target="_blank"`, `rel="noopener noreferrer"`, `role="doc-noteref"` unless a caller supplies an explicit `role`, and the translated accessible name unless a caller supplies an explicit `aria-label` (FR5); its `title` is the source title, or the number when there is none.                                                                                                     | shipped source and tests; `family:navigation-destinations/FR1,FR3–FR5`                    |
+| FR2 | A missing or rejected destination renders the selected citation presentation in a noninteractive span; Citation adds no navigation or reference role to it. Unless a caller supplies an explicit `role`, the span uses a supported naming role, so its translated label, or a caller's `aria-label`, reaches assistive technology (FR5). Rejection derives no navigation attributes from `source.url`, invents no disabled semantics, and does not hide the citation. | shipped source and tests; `family:navigation-destinations/FR4,FR7`; WAI-ARIA naming rules |
+| FR3 | The label variant presents the source title, an optional decorative source icon, and truncation; the number variant presents the supplied number as the compact visible reference.                                                                                                                                                                                                                                                                                    | shipped source, docs, tests, and stories                                                  |
+| FR4 | A node icon takes precedence over `src`, and `src` over a legacy string `icon`. Every icon path remains decorative inside an `aria-hidden` wrapper.                                                                                                                                                                                                                                                                                                                   | shipped compatibility behavior and tests                                                  |
+| FR5 | Both root branches preserve supported DOM props, `className`, `style`, `xstyle`, `data-*` attributes, and the declared `HTMLElement` ref, and a caller's explicit `role` or `aria-label` reaches the root (`architecture:public-component-api` INV5). Implementation gap: the component's role and translated name replace a caller's values (Current-state impact).                                                                                                  | `architecture:public-component-api/INV5,INV6,INV8`; regression tests                      |
+| FR6 | Citation keeps one public `citation` target on the painted root, reflecting `variant`, and exposes no internal icon or text target without an approved theming-contract change.                                                                                                                                                                                                                                                                                       | shipped docs/source; `architecture:component-theming-surface/INV3–INV6`                   |
+| FR7 | Component-owned accessible text comes from the translation catalog; visible source text and numeric content remain caller-supplied data.                                                                                                                                                                                                                                                                                                                              | shipped source and i18n infrastructure                                                    |
 
 ### Allowed variation
 
@@ -103,18 +115,18 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Representative states
 
-| State                   | Required invariant                                                                                                       | Allowed variation                     |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
-| linked label            | Native anchor, source title, optional decorative icon, translated accessible name.                                       | Source content and root theme paint.  |
-| linked number           | Native anchor, numeric visible reference, translated accessible name.                                                    | Number and root theme paint.          |
-| missing or rejected URL | Inert span with the same selected presentation, a supported naming role, and no navigation/reference role or attributes. | Source content and root theme paint.  |
-| node or image icon      | Icon remains decorative and appears only in the label variant.                                                           | Caller-owned artwork or source image. |
+| State                   | Required invariant                                                                                                                                            | Allowed variation                     |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| linked label            | Native anchor, source title, optional decorative icon, translated accessible name absent a caller `aria-label`.                                               | Source content and root theme paint.  |
+| linked number           | Native anchor, numeric visible reference, translated accessible name absent a caller `aria-label`.                                                            | Number and root theme paint.          |
+| missing or rejected URL | Inert span with the same selected presentation; absent a caller `role`, a supported naming role; Citation adds no navigation or reference role or attributes. | Source content and root theme paint.  |
+| node or image icon      | Icon remains decorative and appears only in the label variant.                                                                                                | Caller-owned artwork or source image. |
 
 ### Transformation and precedence order
 
 - **ORD1 — Destination.** `source.url` → shared safe-URL decision → native anchor or inert span.
 - **ORD2 — Icon.** Non-string `source.icon` → `source.src` → legacy string `source.icon` → no icon.
-- **ORD3 — Root props.** Caller passthrough → component-owned role, name, test id, and navigation attributes → theme and style composition.
+- **ORD3 — Root props.** Caller passthrough → component-owned test id and navigation attributes, and the component's role and name unless the caller supplies its own (FR5; today the component's replace the caller's, the FR5 gap) → theme and style composition.
 
 ### Performance and resources
 
@@ -123,8 +135,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Accessibility contract
 
-- **AR1 — Linked reference.** An accepted destination exposes one native link with `doc-noteref` and the translated `Citation {number}: {title}` accessible name.
-- **AR2 — Inert reference.** Missing or rejected destinations expose no interactive or navigation role or attributes. The inert span uses `role="group"` so its translated citation label remains an accessible name, including when the visible number has no source text.
+- **AR1 — Linked reference.** An accepted destination exposes one native link with `doc-noteref` absent a caller `role`, and the translated `Citation {number}: {title}` accessible name absent a caller `aria-label` (FR5).
+- **AR2 — Inert reference.** For a missing or rejected destination, Citation adds no interactive or navigation role or attributes; a caller's explicit `role` reaches the span (FR5). Absent a caller `role` (FR5), the inert span uses `role="group"` so its translated citation label remains an accessible name, including when the visible number has no source text.
 - **AR3 — Decorative source mark.** Source image and node icon paint remains hidden from the accessibility tree so it does not duplicate the citation name.
 - **AR4 — Focus ownership.** The native anchor remains the semantic focus owner. Citation adds no focus owner to the inert span.
 
@@ -136,7 +148,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | Source icon      | Presents optional caller-supplied source identity without accessibility semantics. | observed shipped representation                 | decorative               | FR3–FR4, AR3       |
 | Label or number  | Presents the source title or compact index.                                        | observed shipped representation                 | primary citation content | FR3, FR7           |
 
-Citation exposes only the documented `citation` root target. Internal icon and text parts currently have no public target; this observational draft neither adds nor promises one.
+Citation exposes only the documented `citation` root target. Internal icon and text parts have no public target.
 
 ## Family and system relationships
 
@@ -149,15 +161,16 @@ Citation exposes only the documented `citation` root target. Internal icon and t
 
 ## Verification map
 
-| Contract         | Verification                                                                | Representative states                                                        | Mutation or failure expectation                                                                                                                       | Audit section               |
-| ---------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
-| FR1–FR2, AR1–AR2 | `Citation.test.tsx` destination suites and `safeUrl.test.ts` matrix         | accepted, missing, blocked schemes, normalized blocked text                  | A blocked URL creates navigation, an accepted URL loses its destination or native affordances, or an inert reference loses its supported naming role. | `audit:Citation/navigation` |
-| FR3–FR4, AR3     | `Citation.test.tsx` variant and icon suites                                 | label, number, no icon, node icon, `src`, legacy string icon                 | The wrong visible variant renders, icon precedence changes, or decorative source paint reaches the accessibility tree.                                | `audit:Citation/behavior`   |
-| FR5              | `Citation.test.tsx` root-contract suite and strict type/lint validation     | anchor and span roots with ref, DOM props, class, inline style, and `xstyle` | Either root drops supported passthrough or ref behavior, or caller-supplied role/name overrides component ownership.                                  | `audit:Citation/api`        |
-| FR6              | Public docs, source review, and theming-target inventories                  | linked and inert roots; both variants                                        | The root target disappears, moves off the painter, or an undocumented internal target becomes public.                                                 | `audit:Citation/theming`    |
-| FR7              | Existing i18n build and Citation accessible-name assertions                 | linked label and number                                                      | Component-authored accessible text bypasses translation or loses source/number context.                                                               | `audit:Citation/i18n`       |
-| RTL N/A          | `verified-not-applicable.json` source-hashed record                         | label and number stories; linked/inert source paths; icon/no-icon            | A direction-sensitive glyph, physical inline placement, ordering, scrolling, overlay, or horizontal keyboard behavior appears without RTL evidence.   | `audit:Citation/rtl`        |
-| All              | `Citation.stories.tsx`, component tests, typecheck, lint, and exact-head CI | all documented variants and representative source states                     | A required state becomes unreachable or gains a build, accessibility, visual, or test regression.                                                     | `audit:Citation/testing`    |
+| Contract         | Verification                                                            | Representative states                                                        | Mutation or failure expectation                                                                                                                                                                                                   | Audit section               |
+| ---------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| FR1–FR2, AR1–AR2 | `Citation.test.tsx` destination suites and `safeUrl.test.ts` matrix     | accepted, missing, blocked schemes, normalized blocked text                  | A blocked URL creates navigation, an accepted URL loses its destination or native affordances, or an inert reference loses its supported naming role when the caller supplies no `role`.                                          | `audit:Citation/navigation` |
+| FR3–FR4, AR3     | `Citation.test.tsx` variant and icon suites                             | label, number, no icon, node icon, `src`, legacy string icon                 | The wrong visible variant renders, icon precedence changes, or decorative source paint reaches the accessibility tree. Gap: no test covers the label's truncation. Gap: no test covers `src` winning over a legacy string `icon`. | `audit:Citation/behavior`   |
+| FR5              | `Citation.test.tsx` root-contract suite and strict type/lint validation | anchor and span roots with ref, DOM props, class, inline style, and `xstyle` | Either root drops supported passthrough or ref behavior. Gap: the root-contract test asserts that the component's role and name replace a caller's `role` and `aria-label`, which pins the FR5 gap.                               | `audit:Citation/api`        |
+| FR6              | `Citation.test.tsx` class-name tests; `themingTargets.test.ts`          | linked and inert roots; both variants                                        | The root target disappearing from the class-name tests fails. `themingTargets.test.ts` catches only a renamed or undocumented target. Gap: no test asserts the `variant` reflection on the target.                                | `audit:Citation/theming`    |
+| FR7              | `Citation.test.tsx` accessible-name assertions                          | linked label and number                                                      | A name that loses the source or number context fails. Gap: no test runs a non-English catalog, so text that bypasses translation passes.                                                                                          | `audit:Citation/i18n`       |
+| RTL N/A          | `verified-not-applicable.json` source-hashed record                     | label and number stories; linked/inert source paths; icon/no-icon            | A direction-sensitive glyph, physical inline placement, ordering, scrolling, overlay, or horizontal keyboard behavior appears without RTL evidence.                                                                               | `audit:Citation/rtl`        |
+| All              | `Citation.stories.tsx`; stable visual baseline `core-citation--label`   | Documented variants and source states                                        | A changed label citation comes back changed for review.                                                                                                                                                                           | `audit:Citation/testing`    |
+| AR4, PR1, PR2    | Source review                                                           | Linked and inert roots; image icon                                           | Gap: no automated check fails if Citation adds a focus owner to the inert span, state, an effect, or a listener, or emits more than one source image.                                                                             | `audit:Citation/behavior`   |
 
 ## Decision log
 
@@ -172,7 +185,7 @@ Reconsider this mechanism if a supported platform primitive can name inert inlin
 
 ## Open questions
 
-None. This observational draft does not decide a general resource URL policy or add a component-local theming surface.
+None.
 
 ## Content boundary
 

package/src/ClickableCard/ClickableCard.tsx

@@ -29,7 +29,13 @@
  * For toggle selection, use SelectableCard.
  */
 
-import {type ReactNode, type MouseEvent, useRef, type Ref} from 'react';
+import {
+  type ReactNode,
+  type MouseEvent,
+  useCallback,
+  useRef,
+  type Ref,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {
@@ -327,6 +333,41 @@ export function ClickableCard({
   const pressable = usePressFeedback();
   const containerRef = useRef<HTMLDivElement | null>(null);
   const interactiveRef = useRef<HTMLElement | null>(null);
+  const restoreFocusRef = useRef(false);
+  // The isDisabled value of the link that just detached: a link card that
+  // flips it replaces its hidden link (router component and plain anchor),
+  // and only that replacement takes focus back.
+  const detachedDisabledRef = useRef<boolean | null>(null);
+
+  // A focused link remounts when isDisabled changes: the replacement takes
+  // focus back, without scrolling, if focus fell to the page. Any other
+  // detach and attach (a hidden Activity or Suspense boundary revealed
+  // again) leaves focus where the person put it.
+  const setInteractiveRef = useCallback(
+    (node: HTMLElement | null) => {
+      if (node == null) {
+        const previous = interactiveRef.current;
+        restoreFocusRef.current =
+          previous != null && previous === previous.ownerDocument.activeElement;
+        detachedDisabledRef.current = isDisabled;
+        interactiveRef.current = null;
+        return;
+      }
+      interactiveRef.current = node;
+      const isFlip =
+        detachedDisabledRef.current != null &&
+        detachedDisabledRef.current !== isDisabled;
+      const active = node.ownerDocument.activeElement;
+      const hasFallen = active == null || active === node.ownerDocument.body;
+      if (restoreFocusRef.current && isFlip && hasFallen) {
+        node.focus({preventScroll: true});
+      }
+      restoreFocusRef.current = false;
+      detachedDisabledRef.current = null;
+    },
+    [isDisabled],
+  );
+
   const LinkComponent = useLinkComponent();
 
   const {onClick, onMouseUp} = useClickableContainer({
@@ -347,6 +388,9 @@ export function ClickableCard({
 
   const isLink = href != null;
 
+  // Disabled links have no href, so bypass the router and render an anchor.
+  const LinkRoot = isDisabled ? 'a' : LinkComponent;
+
   // Only the `default` variant has a visible border. Card draws a transparent
   // 1px border on every other variant purely to avoid layout jitter; we drop
   // it here so the hover overlay covers the full box with no untinted ring.
@@ -385,8 +429,8 @@ export function ClickableCard({
       onMouseUp={!isDisabled ? handleMouseUp : undefined}
       {...props}>
       {isLink ? (
-        <LinkComponent
-          ref={interactiveRef as React.Ref<HTMLAnchorElement>}
+        <LinkRoot
+          ref={setInteractiveRef}
           href={isDisabled ? undefined : href}
           target={isDisabled ? undefined : target}
           role={isDisabled ? 'link' : undefined}
@@ -399,7 +443,7 @@ export function ClickableCard({
         />
       ) : (
         <button
-          ref={interactiveRef as React.Ref<HTMLButtonElement>}
+          ref={setInteractiveRef}
           type="button"
           aria-label={label}
           aria-disabled={isDisabled || undefined}

package/src/Collapsible/Collapsible.spec.md

@@ -69,6 +69,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 - caller-provided chevron, cue, icon, or render-function escape hatches;
 - TreeList, Table, or another component's disclosure indicator;
 - generic icon resolution or artwork customization;
+- sibling open-value coordination, group state, and the divided group wrapper
+  — owned by `component:CollapsibleGroup`;
 - a shared responsive or directional API; or
 - new content-reveal motion behavior. Existing behavior outside this decision stays
   unchanged until its own current authority changes it.

package/src/Collapsible/CollapsibleGroup.spec.md

@@ -3,11 +3,11 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:CollapsibleGroup
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang, imdreamrunner]
 review_triggers: [public-api, behavior, layout, accessibility, theming]
 verified_by:
@@ -17,6 +17,8 @@ verified_by:
     packages/core/src/Collapsible/__tests__/Collapsible.a11y.test.tsx,
     packages/core/src/Collapsible/__tests__/Collapsible.a11y.chromium.spec.ts,
     packages/core/src/Collapsible/__tests__/CollapsibleGroup.a11y.chromium.spec.ts,
+    packages/core/src/Collapsible/__tests__/CollapsibleGroup.a11y.test.tsx,
+    packages/core/src/Collapsible/__tests__/CollapsibleGroupAccordion.a11y.chromium.spec.ts,
     packages/core/src/theme/themingTargets.test.ts,
     apps/storybook/stories/CollapsibleGroup.stories.tsx,
   ]
@@ -31,7 +33,7 @@ architecture:
     architecture:component-test-sufficiency,
   ]
 contributing: [contributing:api-conventions]
-system_specs: [spec:AST-029]
+system_specs: [spec:AST-029, spec:AST-085]
 ---
 
 # CollapsibleGroup component contract
@@ -44,11 +46,11 @@ system_specs: [spec:AST-029]
 | Behavior                | Direct children with a `value` read group state; opening an item replaces or extends the open-value set according to mode. The group renders no wrapper unless divider chrome is enabled.                                       |
 | End-user impact         | People can reveal one section or several sections without disclosure state drifting between sibling rows; divided groups keep one coherent visual and directional treatment.                                                    |
 | Builder impact          | Builders choose state ownership and selection mode, give participating items stable values, and may opt into divided-row presentation.                                                                                          |
-| Compatibility/readiness | Released DOM output, props, defaults, targets, and migration promises are unchanged. An unchanged controlled string preserves the coordination broadcast identity instead of rerendering every consumer.                        |
+| Compatibility/readiness | Records shipped behavior; no public change. Three implementation gaps, listed under Current-state impact.                                                                                                                       |
 | Review checks           | Reject lost single/multiple coordination, controlled state that mutates internally, uncontrolled state that stops updating, presentation leakage into nested disclosures, or a wrapper appearing when dividers are absent.      |
 | Governing rules         | `component:Collapsible/FR7–FR9,DEC-2`; `architecture:public-component-api/INV1,INV5–INV9`; `architecture:react-component-runtime/INV1,INV8–INV9`; `architecture:component-theming-surface/INV3–INV7`.                           |
 
-This table is a review projection; the body below is authoritative only after owner approval.
+This table is a review projection; the body below is authoritative.
 
 ## Intent
 
@@ -57,12 +59,29 @@ Coordinate a set of disclosure items so their open state follows one group owner
 ## Compatibility and migration
 
 - Released default preserved: yes
-- Compatibility class: compatible runtime efficiency correction; no DOM output, public type, default, target, export, or migration change
+- Compatibility class: records shipped behavior; no public change
 - Controlled/uncontrolled behavior: unchanged
 - Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **A disabled header leaves the Tab order.** A disabled direct item's header
+  carries `aria-disabled` but drops out of the Tab order, so a keyboard user
+  cannot reach it to learn why it is unavailable. `spec:AST-085` FR1 keeps a
+  disabled control focusable; the header is owned by `component:Collapsible`.
+- **Equal values can rebuild the coordination context.** An equal new
+  controlled array, or a new `onChange` such as an inline handler, rebuilds the
+  coordination context on every parent render, so memoized direct items
+  re-render. `architecture:react-component-runtime` INV9 keeps an unchanged
+  payload from broadcasting a new identity (FR7).
+- **The accordion binding runs adopted rows as advisory.** The binding runs
+  the header-to-header Tab step, single-mode sibling collapse, and no
+  arrow-key movement as advisory rows, so
+  a regression there does not fail the binding lane. `spec:AST-020` FR9 makes
+  an adopted expectation required once this record adopts it (AR4).
+
 ## Ownership boundary
 
 **Owns**
@@ -90,15 +109,15 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                   | Basis                                                                                             | Draft review state |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------ |
-| FR1 | In `single` mode, toggling a closed direct item MUST replace the open-value set with that item, and toggling the open item MUST clear the set.                                                        | shipped source, consumer docs, and focused interaction tests                                      | verify             |
-| FR2 | In `multiple` mode, toggling a direct item MUST add or remove only that value while preserving the state of other values.                                                                             | shipped source, consumer docs, and focused interaction tests                                      | verify             |
-| FR3 | Supplying `value` MUST keep state caller-owned and report requested changes through `onChange`; omitting it MUST keep state internal after initialization from `defaultValue`.                        | `architecture:react-component-runtime/INV1,INV8`; shipped controlled and uncontrolled tests       | verify             |
-| FR4 | A direct `Collapsible` with a `value` MUST use group coordination; an item without a value MUST retain standalone ownership.                                                                          | shipped hook behavior and focused group/standalone tests                                          | verify             |
-| FR5 | With `hasDividers=false`, the group MUST add no DOM wrapper. With dividers enabled it MUST render one wrapper that receives documented root props and the `collapsible-group` target.                 | `architecture:public-component-api/INV5–INV8`; `architecture:component-theming-surface/INV3–INV7` | verify             |
-| FR6 | Density, divider, and chevron defaults MUST reach direct items without leaking through a direct item's revealed content into nested independent disclosures.                                          | `component:Collapsible/FR7–FR8,DEC-2`; focused nesting tests                                      | settled            |
-| FR7 | Presentation context identity MUST remain stable while divider, density, and chevron inputs are unchanged; coordination identity MUST change only when the open-value behavior it broadcasts changes. | `architecture:react-component-runtime/INV9`; memoized source and interaction tests                | verify             |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                                                                             |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| FR1 | In `single` mode, toggling a closed direct item MUST replace the open-value set with that item, and toggling the open item MUST clear the set.                                                                                                                                                                                                                                                                            | shipped source, consumer docs, and focused interaction tests                                      |
+| FR2 | In `multiple` mode, toggling a direct item MUST add or remove only that value while preserving the state of other values.                                                                                                                                                                                                                                                                                                 | shipped source, consumer docs, and focused interaction tests                                      |
+| FR3 | Supplying `value` MUST keep state caller-owned and report requested changes through `onChange`; omitting it MUST keep state internal after initialization from `defaultValue`.                                                                                                                                                                                                                                            | `architecture:react-component-runtime/INV1,INV8`; shipped controlled and uncontrolled tests       |
+| FR4 | A direct `Collapsible` with a `value` MUST use group coordination; an item without a value MUST retain standalone ownership.                                                                                                                                                                                                                                                                                              | shipped hook behavior and focused group/standalone tests                                          |
+| FR5 | With `hasDividers=false`, the group MUST add no DOM wrapper. With dividers enabled it MUST render one wrapper that receives documented root props and the `collapsible-group` target.                                                                                                                                                                                                                                     | `architecture:public-component-api/INV5–INV8`; `architecture:component-theming-surface/INV3–INV7` |
+| FR6 | Density, divider, and chevron defaults MUST reach direct items without leaking through a direct item's revealed content into nested independent disclosures.                                                                                                                                                                                                                                                              | `component:Collapsible/FR7–FR8,DEC-2`; focused nesting tests                                      |
+| FR7 | Presentation context identity MUST remain stable while divider, density, and chevron inputs are unchanged; coordination identity MUST stay stable across a rerender with an unchanged controlled string, the same controlled array reference, or unchanged internal state, with the same `type` and `onChange`. Implementation gap: an equal new controlled array or a new `onChange` rebuilds it (Current-state impact). | `architecture:react-component-runtime/INV9`; memoized source and interaction tests                |
 
 ### Allowed variation
 
@@ -126,14 +145,14 @@ Consumer migration instructions belong in consumer docs and release notes.
 ### Performance and resources
 
 - **PR1 — Render-owned coordination.** The group derives output from props, state, and context and owns no Effect, listener, observer, timer, request, subscription, or imperative browser resource.
-- **PR2 — Stable broadcasts.** Memoized context values prevent unchanged semantic payloads from broadcasting new identities to direct consumers.
+- **PR2 — Stable broadcasts.** Memoized context values keep the identities FR7 names stable for direct consumers.
 
 ## Accessibility contract
 
 - **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.
+- **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` and cannot be toggled, apart from the Tab-order gap (Current-state impact). 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
 
@@ -142,7 +161,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | Group container  | Optional divider chrome visually associates sibling disclosures as a set. | observed shipped representation | aggregate container | FR5–FR6, AR2       |
 | Direct item      | Density and chevron defaults remain consistent across sibling rows.       | `component:Collapsible/FR7–FR8` | disclosure row      | FR6, AR3           |
 
-No current design record prescribes exact CollapsibleGroup pixels. This observational draft records the shipped divided and plain relationships without deciding new visual direction.
+No current design record prescribes exact CollapsibleGroup pixels. This record covers the shipped divided and plain relationships without deciding new visual direction.
 
 ### Theming anatomy
 
@@ -160,7 +179,7 @@ No current design record prescribes exact CollapsibleGroup pixels. This observat
 }
 ```
 
-The Group container is CollapsibleGroup's conditional aggregate wrapper. The other anatomy rows remain owned by `component:Collapsible`; they are repeated in this observational subcomponent map only because the released consumer anatomy and target inventory are shared. Trigger, content, chevron, open state, disabled state, density padding, and per-item dividers remain with Collapsible's contract.
+The Group container is CollapsibleGroup's conditional aggregate wrapper. The other anatomy rows remain owned by `component:Collapsible`; they are repeated in this subcomponent map only because the released consumer anatomy and target inventory are shared. Trigger, content, chevron, open state, disabled state, density padding, and per-item dividers remain with Collapsible's contract.
 
 ## Family and system relationships
 
@@ -172,14 +191,23 @@ 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`       |
-| 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`          |
+| 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` and no toggle; its out-of-Tab-order assertion pins the gap, pending conformance); `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); `CollapsibleGroup.a11y.test.tsx` and `CollapsibleGroupAccordion.a11y.chromium.spec.ts` (Space on grouped headers; the header-to-header Tab step, single-mode sibling collapse, and no arrow-key movement run as advisory rows) | 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`          |
+
+Read from source, with no focused test yet:
+
+- AR4: no Home/End movement between headers.
+- FR7: presentation context identity staying stable while divider, density,
+  and chevron inputs are unchanged, and coordination identity across the same
+  array reference, unchanged internal state, and an equal new array; only the
+  controlled-string case is tested.
+- PR1: the group owning no Effect or browser resource.
 
 ## Decision log
 
@@ -194,7 +222,7 @@ Rejected: arrow-key movement between headers; a required heading element around
 
 ## Open questions
 
-None. This observational draft does not broaden the released coordination modes or decide new presentation.
+None. This record does not broaden the released coordination modes or decide new presentation.
 
 ## Content boundary
 

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -37,10 +37,7 @@ import {useDialogContext} from '../Dialog/DialogContext';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
-import {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
@@ -223,13 +220,13 @@ export function CommandPaletteInput({
   // Text-entry controls match :focus-visible after pointer focus in Chromium.
   // Keep the shared selector, but narrow its ring to focus acquired through
   // keyboard navigation so a click or pointer-opened palette stays unringed.
-  useInteractionModalityTracking();
+  const {ref: modalityRef, readModality} = useInteractionModalityTracking();
   const handleFocus = useCallback(
     (event: React.FocusEvent<HTMLInputElement>) => {
-      setIsKeyboardFocus(getInteractionModality() === 'keyboard');
+      setIsKeyboardFocus(readModality() === 'keyboard');
       onFocus?.(event);
     },
-    [onFocus],
+    [onFocus, readModality],
   );
   const handleBlur = useCallback(
     (event: React.FocusEvent<HTMLInputElement>) => {
@@ -312,7 +309,7 @@ export function CommandPaletteInput({
       </span>
       <input
         {...props}
-        ref={useMergedRefs(ref, inputRef)}
+        ref={useMergedRefs(ref, inputRef, modalityRef)}
         {...(isKeyboardFocus
           ? focusOutlineProps.focusVisible(styles.input)
           : focusOutlineProps.suppressed(styles.input))}