@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/src/CheckboxList/CheckboxListItem.spec.md

@@ -1,23 +1,34 @@
 ---
 schema_version: 3
-template_version: 6
+template_version: 7
 kind: component
 id: component:CheckboxListItem
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-28
 owners: [cixzhang]
 review_triggers:
-  [public-api, behavior, interaction, theming, accessibility, visual]
+  [
+    public-api,
+    behavior,
+    layout,
+    interaction,
+    motion,
+    theming,
+    styling,
+    accessibility,
+    visual,
+    react-runtime,
+    compatibility,
+  ]
 verified_by:
   [
     packages/core/src/CheckboxList/CheckboxList.test.tsx,
     packages/core/src/CheckboxList/__tests__/CheckboxList.a11y.chromium.spec.ts,
     packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx,
     packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts,
-    apps/storybook/stories/CheckboxList.stories.tsx,
     apps/storybook/rtl-audit/targets.json,
     scripts/check-knowledge.mjs,
   ]
@@ -32,7 +43,7 @@ architecture:
     architecture:interaction-modality,
   ]
 contributing: []
-system_specs: [spec:AST-011, spec:AST-021, spec:AST-038]
+system_specs: [spec:AST-011, spec:AST-021, spec:AST-038, spec:AST-085]
 ---
 
 # CheckboxListItem component contract
@@ -44,12 +55,12 @@ system_specs: [spec:AST-011, spec:AST-021, spec:AST-038]
 | Public contract         | One option row: a native checkbox named by `label` or `aria-label`, described by `description`, with optional `endContent`, rendered through ListItem. Inside a CheckboxList with a `value` array (collection mode), checked state comes from membership and `value` is required. Inside List, or inside a CheckboxList without `value` (standalone mode), the item reads `isChecked` and calls `onCheck`. |
 | Behavior                | The checkbox is the option's only tab stop. Row-surface clicks delegate to it when the item is editable and sits in a CheckboxList or has `onCheck`, or when it has `onClick`; an item `onClick` fires once per direct, keyboard, or row-surface click. Disabled, read-only, and busy states refuse toggling.                                                                                              |
 | End-user impact         | People can operate each option by pointer, touch, and keyboard, hear its name, description, and checked, mixed, disabled, read-only, or busy state, and see a spinner while it saves.                                                                                                                                                                                                                      |
-| Builder impact          | Where the item sits, and whether its parent list has `value`, selects the mode; `value` is required only in collection mode. Handlerless meaning, checked-row theming and pointer feedback, consumer DOM-prop targets, and focus-ring ownership remain owner decisions. Read-only click propagation to ancestors is an unscored authority gap routed to the shared clickable-container hook.               |
-| Compatibility/readiness | Released API, defaults, DOM ownership, and targets are unchanged. This draft records shipped behavior only.                                                                                                                                                                                                                                                                                                |
+| Builder impact          | Where the item sits, and whether its parent list has `value`, selects the mode; `value` is required only in collection mode. Handlerless meaning, checked-row theming and pointer feedback, consumer DOM-prop targets, read-only click propagation, and focus-ring ownership stay open questions (OQ1–OQ6).                                                                                                |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Handlerless items, checked-row state reflection, and the double focus indicator are listed under Current-state impact.                                                                                                                                                                                                                           |
 | Review checks           | Reject a second tab stop, a toggle while disabled, read-only, or busy, `isChecked` overriding a parent `value` array, an `onClick` that fires more than once per click, a dropped description relationship, or a new target, state, or event-routing API introduced without an owner decision.                                                                                                             |
-| Governing rules         | `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:interaction-modality/INV1–INV5`; `architecture:component-test-sufficiency/INV1–INV7`; `spec:AST-021/FR8–FR10`; `spec:AST-011`; `spec:AST-038/FR7`; WCAG 2.2 1.3.1, 2.1.1, 4.1.2.                                                                                                          |
+| Governing rules         | `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:interaction-modality/INV1–INV5`; `architecture:component-test-sufficiency/INV1–INV7`; `spec:AST-021/FR8–FR10`; `spec:AST-085/FR1, FR7`; `spec:AST-011`; `spec:AST-038/FR7`; WCAG 2.2 1.3.1, 2.1.1, 4.1.2.                                                                                 |
 
-This table is a review projection; the body below becomes authoritative only after owner approval.
+This table is a review projection; the body below is authoritative.
 
 ## Intent
 
@@ -60,7 +71,8 @@ read-only, and busy state, inside a CheckboxList or a plain List.
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: observational record; no runtime change
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
 - Controlled/uncontrolled behavior: controlled only — by the parent list's
   `value` in collection mode, by `isChecked` in standalone mode
 - Migration decision: none
@@ -92,7 +104,7 @@ Consumer migration instructions belong in consumer docs and release notes.
   truncation — owned by `component:List` and Item.
 - The checkbox control, its indicator, focus ring, pressed overlay, and busy,
   disabled, and read-only semantics — owned by `component:CheckboxInput` and
-  `component:CheckboxIndicator`.
+  CheckboxIndicator.
 - Loading-indicator presentation — owned by `component:Spinner`; delegation
   mechanics — owned by the shared clickable-container hook.
 - New targets, reflected states, or event-routing API.
@@ -105,7 +117,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | mode          | collection (parent has `value`); standalone in CheckboxList without `value`; standalone in List | Collection reads membership and reports through the parent; standalone reads `isChecked` and calls `onCheck`.                         | Chosen by placement; `isChecked` and `onCheck` are ignored in collection mode. | standalone     | component            | stable                                 | a collection item without `value` throws     |
 | checked state | unchecked, checked, mixed (standalone only)                                                     | Native checkbox state; mixed uses the native `indeterminate` property and proposes `true`.                                            | All modes.                                                                     | unchecked      | caller               | stable                                 | rejected by the public type                  |
 | change path   | parent `onChange`/`changeAction` (collection); `onCheck` (standalone); none                     | Proposes the next value array or boolean.                                                                                             | Enabled, editable, non-busy items.                                             | none           | caller and component | shipped; handlerless meaning unsettled | no handler means no component-owned mutation |
-| availability  | enabled; item `isDisabled`; group disabled; group disabled with reason                          | Blocks toggling and the checked-row fill; a group reason keeps the checkbox focusable through `aria-disabled`.                        | Item and group.                                                                | enabled        | component            | stable                                 | boolean only                                 |
+| availability  | enabled; item `isDisabled`; group disabled; group disabled with reason                          | Blocks toggling and the checked-row fill; the checkbox stays focusable through `aria-disabled`.                                       | Item and group.                                                                | enabled        | component            | stable                                 | boolean only                                 |
 | read-only     | from the group's `isReadOnly`                                                                   | Keeps the value visible, focusable, and full-opacity while refusing toggles.                                                          | Inside CheckboxList only.                                                      | false          | component            | stable                                 | boolean only                                 |
 | busy          | `isLoading`; pending parent `changeAction` for the item's `value`                               | Spinner in the checkbox, busy row and checkbox, toggling refused.                                                                     | Per item.                                                                      | idle           | component            | stable                                 | boolean/transition state only                |
 | content       | `description`, `endContent`                                                                     | Description describes the checkbox; end content stays caller-owned and outside the name.                                              | All states.                                                                    | none           | caller               | stable                                 | typed values only                            |
@@ -114,30 +126,27 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision. A `current` contract contains no unresolved rows.
-
-| ID   | Candidate invariant                                                                                                                                                                                                                                                                                                                                                         | Basis                                                                                                  | Draft review state                               |
-| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
-| FR1  | The row MUST render one native CheckboxInput as ListItem start content; that checkbox MUST be the option's only focusable control, and the row itself MUST NOT be focusable.                                                                                                                                                                                                | shipped source; focused tests; WCAG 2.1.1 and 4.1.2                                                    | verify                                           |
-| FR2  | A string `label` MUST name the checkbox; a node `label` MUST name it from the visible label element through `aria-labelledby`; `aria-label` MUST replace the derived name on the checkbox and never reach the row.                                                                                                                                                          | shipped source and focused tests                                                                       | verify                                           |
-| FR3  | A renderable `description` MUST describe the checkbox through `aria-describedby`; an absent or empty description MUST add none.                                                                                                                                                                                                                                             | shipped source and focused tests; WCAG 1.3.1                                                           | verify                                           |
-| FR4  | Inside a CheckboxList with a `value` array, the item MUST read checked state from membership, throw without `value`, and propose the array with its `value` added or removed through the parent's change path; `isChecked` and `onCheck` MUST be ignored.                                                                                                                   | shipped source and focused tests                                                                       | verify                                           |
-| FR5  | Inside List, or inside a CheckboxList without `value`, the item MUST read `isChecked` and call `onCheck` with the next boolean; a mixed item MUST propose `true`, and `value` MAY be omitted.                                                                                                                                                                               | shipped source and focused tests                                                                       | verify                                           |
-| FR6  | Item `isDisabled` or a disabled group MUST disable the checkbox, refuse toggling, and omit the checked-row fill; a group reason keeps the checkbox focusable through `aria-disabled` (`component:CheckboxList` FR9).                                                                                                                                                        | shipped source, focused tests, and shared checkbox binding                                             | verify                                           |
-| FR7  | Item `isLoading`, or a pending parent `changeAction` for the item's `value`, MUST render Spinner inside the checkbox, mark the row and the checkbox busy, and refuse toggling.                                                                                                                                                                                              | shipped source, focused tests, and Chromium receipts                                                   | verify                                           |
-| FR8  | A read-only group MUST make the checkbox read-only, focusable, and full-opacity, refuse every toggle, and omit the checked-row fill; the row delegates clicks only when the item has `onClick`.                                                                                                                                                                             | shipped source, focused tests, and shared checkbox binding; `spec:AST-011`                             | verify                                           |
-| FR9  | On an enabled, editable item inside a CheckboxList or with `onCheck`, a row-surface click outside interactive descendants MUST be delegated to the checkbox; links and buttons in the label, description, or end content MUST keep their own behavior.                                                                                                                      | shipped source and focused tests                                                                       | verify                                           |
-| FR10 | An item `onClick` MUST fire once for each direct, keyboard, or row-surface click, including on read-only items.                                                                                                                                                                                                                                                             | shipped source and focused tests; `architecture:public-component-api/INV5`                             | verify                                           |
-| FR11 | `compact` density MUST render the `sm` checkbox; other densities MUST render `md`.                                                                                                                                                                                                                                                                                          | shipped source and focused test                                                                        | verify                                           |
-| FR12 | An enabled, editable, checked row MUST paint the `--color-accent-muted` fill, and consumer `xstyle` MUST compose after it.                                                                                                                                                                                                                                                  | shipped source and Chromium receipts                                                                   | verify                                           |
-| FR13 | `ref`, `className`, `style`, `xstyle`, data attributes, ARIA other than `aria-label`, and events other than `onClick` MUST reach the row `<li>`.                                                                                                                                                                                                                            | shipped source and focused tests                                                                       | verify                                           |
-| GAP1 | A standalone item with `isChecked` and no `onCheck` is inert but exposed as an editable checkbox; inside a CheckboxList without `value`, its row also delegates clicks and shows pointer feedback.                                                                                                                                                                          | exact `spec:AST-021` known failure `list-item-handlerless-read-only`; WCAG 4.1.2                       | owner decision                                   |
-| GAP2 | The item paints the checked-row fill itself, but no selection state is reflected on the row's `list-item`/`item` targets, so a theme cannot restyle checked rows apart from unchecked rows.                                                                                                                                                                                 | `architecture:component-theming-surface/INV6`                                                          | owner decision                                   |
-| GAP3 | Consumer DOM inputs split between two elements: data attributes and ARIA reach the row, while `onClick` runs on the checkbox and is typed for the row, so `event.currentTarget` is the checkbox and does not carry the row's data attributes.                                                                                                                               | `architecture:public-component-api/INV5`; `INV9` for any retype or move                                | owner decision                                   |
-| GAP4 | On a read-only item with `onClick`, the item stops the click's propagation, so React ancestors never receive those clicks, while they do for enabled items. The stop exists because the shared clickable-container hook would re-delegate a click that came from an `aria-readonly` delegate target back to it. The item's own `onClick` still fires once per click (FR10). | No current authority owns ancestor propagation; shared clickable-container hook behavior (advisory)    | authority gap (unscored); shared-module advisory |
-| GAP5 | On an enabled, editable, checked row, the checked-row fill replaces the row's hover and pressed overlays, so pointer hover and hold give no row feedback.                                                                                                                                                                                                                   | Chromium receipts; `design:user-states` leaves hover and selection treatment outside its current claim | authority gap (unscored); owner decision         |
-| GAP6 | One keyboard focus move paints two indicators: Item's row focus-within outline and CheckboxInput's indicator ring.                                                                                                                                                                                                                                                          | Chromium receipts; `architecture:interaction-modality/INV3`                                            | owner decision                                   |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                    | Basis                                                                                                                 |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| FR1  | The row MUST render one native CheckboxInput as ListItem start content; that checkbox MUST be the option's only focusable control, and the row itself MUST NOT be focusable.                                                                                                                                                                                 | shipped source; focused tests; WCAG 2.1.1 and 4.1.2                                                                   |
+| FR2  | A string `label` MUST name the checkbox; a node `label` MUST name it from the visible label element through `aria-labelledby`; `aria-label` MUST replace the derived name on the checkbox and never reach the row.                                                                                                                                           | shipped source and focused tests                                                                                      |
+| FR3  | A renderable `description` MUST describe the checkbox through `aria-describedby`; an absent or empty description MUST add none.                                                                                                                                                                                                                              | shipped source and focused tests; WCAG 1.3.1                                                                          |
+| FR4  | Inside a CheckboxList with a `value` array, the item MUST read checked state from membership, throw without `value`, and propose the array with its `value` added or removed through the parent's change path; `isChecked` and `onCheck` MUST be ignored.                                                                                                    | shipped source and focused tests                                                                                      |
+| FR5  | Inside List, or inside a CheckboxList without `value`, the item MUST read `isChecked` and call `onCheck` with the next boolean; a mixed item MUST propose `true`, and `value` MAY be omitted. The mixed-state gap `component:CheckboxInput` FR1 records applies when the mixed value is kept.                                                                | shipped source and focused tests                                                                                      |
+| FR6  | Item `isDisabled` or a disabled group MUST make the checkbox focusable-disabled through `aria-disabled` (`component:CheckboxInput` FR4), refuse toggling, and omit the checked-row fill; a group reason adds the group tooltip (`component:CheckboxList` FR9).                                                                                               | shipped source, focused tests, and shared checkbox binding                                                            |
+| FR7  | Item `isLoading`, or a pending parent `changeAction` for the item's `value`, MUST render Spinner inside the checkbox, mark the row and the checkbox busy, and refuse toggling.                                                                                                                                                                               | shipped source, focused tests, and the Chromium accessibility suite                                                   |
+| FR8  | A read-only group MUST make the checkbox read-only, focusable, and full-opacity, refuse every toggle, and omit the checked-row fill; the row delegates clicks only when the item has `onClick`.                                                                                                                                                              | shipped source, focused tests, and shared checkbox binding; `spec:AST-011`                                            |
+| FR9  | On an enabled, editable item inside a CheckboxList or with `onCheck`, a row-surface click outside interactive descendants MUST be delegated to the checkbox; links and buttons in the label, description, or end content MUST keep their own behavior.                                                                                                       | shipped source and focused tests                                                                                      |
+| FR10 | An item `onClick` MUST fire once for each direct, keyboard, or row-surface click, including on read-only items.                                                                                                                                                                                                                                              | shipped source and focused tests; `architecture:public-component-api/INV5`                                            |
+| FR11 | `compact` density MUST render the `sm` checkbox; other densities MUST render `md`.                                                                                                                                                                                                                                                                           | shipped source and focused test                                                                                       |
+| FR12 | An enabled, editable, checked row MUST paint the `--color-accent-muted` fill, and consumer `xstyle` MUST compose after it.                                                                                                                                                                                                                                   | shipped source and the Chromium accessibility suite                                                                   |
+| FR13 | `ref`, `className`, `style`, `xstyle`, data attributes, ARIA other than `aria-label`, and events other than `onClick` MUST reach the row `<li>`.                                                                                                                                                                                                             | shipped source and focused tests                                                                                      |
+| FR14 | A standalone item with `isChecked` and no `onCheck` changes nothing on activation. Implementation gap: it declares no read-only state, so the checkbox is exposed as editable (WCAG 2.2 4.1.2); inside a CheckboxList without `value`, its row also delegates clicks and shows pointer feedback. Its meaning is OQ1.                                         | exact `spec:AST-021` known failure `list-item-handlerless-read-only`; WCAG 4.1.2                                      |
+| FR15 | The item paints the checked-row fill itself and reflects no selection state on the row's `list-item` or `item` targets, so a theme cannot restyle checked rows apart from unchecked rows (OQ2). Selection state MUST be reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: no selection state is reflected. | `architecture:component-theming-surface/INV6`                                                                         |
+| FR16 | Shipped behavior, not a requirement until its open question is ruled: consumer DOM inputs split between two elements: data attributes and ARIA reach the row, while `onClick` runs on the checkbox and is typed for the row, so `event.currentTarget` is the checkbox and does not carry the row's data attributes (OQ3).                                    | `architecture:public-component-api/INV5`; `INV9` for any retype or move                                               |
+| FR17 | Shipped behavior, not a requirement until its open question is ruled: on a read-only item with `onClick`, the item stops the click's propagation, so React ancestors never receive those clicks, while they do for enabled items (OQ4). The item's own `onClick` still fires once per click (FR10).                                                          | Current source; shared clickable-container hook behavior                                                              |
+| FR18 | Shipped behavior, not a requirement until its open question is ruled: on an enabled, editable, checked row, the checked-row fill replaces the row's hover and pressed overlays, so pointer hover and hold give no row feedback (OQ5).                                                                                                                        | the Chromium accessibility suite; `design:user-states` leaves hover and selection treatment outside its current claim |
+| FR19 | One keyboard focus move paints two indicators: Item's row focus-within outline and CheckboxInput's indicator ring (OQ6). One focus move MUST have one owning indicator (`architecture:interaction-modality` INV3). Implementation gap: both indicators paint.                                                                                                | the Chromium accessibility suite; `architecture:interaction-modality/INV3`                                            |
 
 ### Allowed variation
 
@@ -159,7 +168,7 @@ intentional decision. A `current` contract contains no unresolved rows.
 | Busy option                       | Spinner, busy row and checkbox, toggling refused                            | Loading source (prop or pending save) |
 | Read-only option                  | Visible, focusable, full-opacity, immutable; `onClick` fires once per click | Whether the item has `onClick`        |
 | Disabled option                   | Inoperable; no checked-row fill                                             | Item or group source; group reason    |
-| Handlerless standalone option     | Inert; read-only, unavailable, or invalid-usage meaning is unsettled        | No policy is introduced by this draft |
+| Handlerless standalone option     | Inert; declares no read-only state (FR14, OQ1)                              | —                                     |
 
 ### Transformation and precedence order
 
@@ -195,7 +204,7 @@ durable constraints and their verification target.
 - **AR4 — Busy perception.** A busy option MUST expose busy state in the
   accessibility tree and visibly through Spinner.
 - **AR5 — Focus visibility.** Keyboard focus on the checkbox MUST stay visible;
-  which element owns the single indicator is open (GAP6).
+  two indicators paint today (FR19, OQ6).
 
 ## Design relationships
 
@@ -204,12 +213,12 @@ durable constraints and their verification target.
 | Option row         | Full-width row with start checkbox, label and description, and end content. | List and Item                                              | Supporting      | FR1, FR9, FR13     |
 | Checkbox           | Presents the option's selection indicator.                                  | CheckboxInput owner and `design:user-states` for its press | Prominent       | FR1, FR6–FR8, FR11 |
 | Label, description | Name and describe the checkbox.                                             | Item                                                       | Primary content | FR2, FR3           |
-| Checked-row fill   | Supplements the checkbox state on enabled, editable checked rows.           | unsettled (GAP2, GAP5)                                     | Supporting      | FR12               |
+| Checked-row fill   | Supplements the checkbox state on enabled, editable checked rows.           | unsettled (FR15, FR18)                                     | Supporting      | FR12               |
 | Spinner            | Replaces the mark while the option is busy.                                 | Spinner                                                    | Supporting      | FR7                |
 
-This draft adds no `anatomy-theming:v1` block. The composed option anatomy and
-its target dispositions are recorded in `component:CheckboxList`'s theming
-anatomy, and CheckboxListItem owns no target of its own.
+This record carries no anatomy-theming map. The composed option anatomy and its
+target dispositions are recorded in `component:CheckboxList`'s theming anatomy,
+and CheckboxListItem owns no target of its own.
 
 ## Family and system relationships
 
@@ -233,22 +242,39 @@ anatomy, and CheckboxListItem owns no target of its own.
 
 ## Verification map
 
-| Contract           | Verification                                                                                                          | Representative states                                                                         | Mutation or failure expectation                                                                        | Audit section                            |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
-| FR1, FR9, AR2, AR3 | `CheckboxList.test.tsx` single-tab-stop, delegation, and interactive-content suites                                   | Collection option; row-surface click; link in a rich label; interactive end content           | A second tab stop, lost delegation, or a toggle from an interactive descendant fails the assertions.   | `audit:CheckboxListItem/behavior`        |
-| FR2, FR3, AR1      | `CheckboxList.test.tsx` accessible-name and description suites; shared checkbox bindings                              | String and rich label; `aria-label` override; string and node description; absent description | A wrong name or description, or `aria-label` on the row, fails the assertions.                         | `audit:CheckboxListItem/a11y`            |
-| FR4, FR5           | `CheckboxList.test.tsx` collection, standalone, and select-all suites                                                 | add, remove, missing `value`, mixed, select-all, `isChecked` with a parent `value` array      | A wrong array or boolean, a missing error, or `isChecked` overriding the parent fails the assertions.  | `audit:CheckboxListItem/behavior`        |
-| FR6–FR8, AR4       | `CheckboxList.test.tsx` disabled, loading, pending, and read-only suites; shared checkbox bindings; Chromium receipts | Item and group disabled; reason; loading; pending; read-only with and without `onClick`       | A toggle while disabled, read-only, or busy, a lost busy state, or a read-only toggle fails the tests. | `audit:CheckboxListItem/a11y`            |
-| FR10               | `CheckboxList.test.tsx` item `onClick` and read-only click tests                                                      | Enabled and read-only; direct, keyboard, and row-surface clicks                               | An `onClick` that fires zero or several times per click fails the assertions.                          | `audit:CheckboxListItem/behavior`        |
-| FR11               | `CheckboxList.test.tsx` density test                                                                                  | compact and balanced                                                                          | A wrong checkbox size fails the assertion.                                                             | `audit:CheckboxListItem/behavior`        |
-| FR12               | Chromium checked, hover, and pressed receipts                                                                         | light and dark                                                                                | A missing or misplaced fill fails the receipts' row-paint check.                                       | `audit:CheckboxListItem/design-rendered` |
-| FR13               | `CheckboxList.test.tsx` pass-through, data-testid, and ARIA tests                                                     | row ref, class, style, data, ARIA                                                             | A dropped or misrouted input fails the assertions.                                                     | `audit:CheckboxListItem/api`             |
-| Direction          | curated RTL D2 target `core-checkboxlist--rich-descriptions`                                                          | LTR and RTL                                                                                   | The checkbox and end content fail to swap inline order.                                                | `audit:CheckboxListItem/i18n-rtl`        |
+| Contract           | Verification                                                                                                                                                                   | Representative states                                                                | Mutation or failure expectation                                                                                                                 | Audit section                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| FR1, FR9, AR2, AR3 | `CheckboxList.test.tsx` single-tab-stop, row-click, link-in-label, and interactive end-content cases                                                                           | Collection option; row-surface click; link in a rich label; interactive end content  | A second tab stop, lost delegation, or a toggle from an interactive descendant fails.                                                           | `audit:CheckboxListItem/interaction`   |
+| FR2, FR3, AR1      | `CheckboxList.test.tsx` accessible-name and description cases; shared checkbox bindings                                                                                        | String and rich label; `aria-label`; string and node description; absent description | A wrong name or description, or `aria-label` on the row, fails.                                                                                 | `audit:CheckboxListItem/accessibility` |
+| FR4, FR5           | `CheckboxList.test.tsx` collection, standalone, and select-all cases                                                                                                           | Add, remove, missing `value`, mixed, select-all, `isChecked` with a parent array     | A wrong array or boolean, a missing error, or `isChecked` overriding membership fails.                                                          | `audit:CheckboxListItem/behavior`      |
+| FR6–FR8, AR4       | `CheckboxList.test.tsx` disabled, loading, pending, and read-only cases; `CheckboxList.a11y.chromium.spec.ts` `disabled-*`, `loading-item`, `pending-*`, and `read-only` cases | Item and group disabled; reason; loading; pending; read-only                         | A toggle while disabled, read-only, or busy, or a lost busy state, fails.                                                                       | `audit:CheckboxListItem/accessibility` |
+| FR10, FR17         | `CheckboxList.test.tsx` item `onClick` and read-only click cases                                                                                                               | Enabled and read-only; direct, keyboard, and row-surface clicks                      | An `onClick` that fires zero or several times per click fails. Evidence gap: no test asserts the stopped propagation on read-only items (FR17). | `audit:CheckboxListItem/behavior`      |
+| FR11               | `CheckboxList.test.tsx` density case                                                                                                                                           | Compact and balanced                                                                 | A wrong checkbox size fails.                                                                                                                    | `audit:CheckboxListItem/layout`        |
+| FR12, FR18         | `CheckboxList.a11y.chromium.spec.ts` `checked`, `hover-*`, and `pressed-*` cases                                                                                               | Light and dark; unchecked and checked                                                | A missing or misplaced fill fails the row-paint check. Evidence gap: no assertion that `xstyle` composes after the fill.                        | `audit:CheckboxListItem/visual`        |
+| FR13, FR16         | `CheckboxList.test.tsx` ref and styling, data-testid, and ARIA cases                                                                                                           | Row ref, class, style, data, ARIA                                                    | A dropped or misrouted input fails. Evidence gap: no test asserts `event.currentTarget` for `onClick` (FR16).                                   | `audit:CheckboxListItem/api`           |
+| FR14               | `Checkbox.a11y.test.tsx` known failure `list-item-handlerless-read-only`; `CheckboxList.a11y.chromium.spec.ts` `handlerless` case                                              | Standalone with `isChecked` and no `onCheck`                                         | The recorded known failure stops matching when its gap closes.                                                                                  | `audit:CheckboxListItem/accessibility` |
+| FR15, FR19, AR5    | `CheckboxList.a11y.chromium.spec.ts` `focus-visible` and `forced-colors-focus` cases                                                                                           | Keyboard focus; forced colors                                                        | A lost focus indicator fails. Evidence gap: no test asserts the absent selection state (FR15) or counts focus indicators (FR19).                | `audit:CheckboxListItem/visual`        |
+| Direction          | RTL audit target `core-checkboxlist--rich-descriptions` (`apps/storybook/rtl-audit/targets.json`); `CheckboxList.a11y.chromium.spec.ts` `rtl` case                             | LTR and RTL                                                                          | The checkbox and end content fail to swap inline order.                                                                                         | `audit:CheckboxListItem/layout`        |
+| ORD1–ORD4, PR1     | Covered by the FR4–FR10 and FR13 rows. Evidence gap: no test asserts the absence of observers, timers, or global listeners                                                     | —                                                                                    | —                                                                                                                                               | `audit:CheckboxListItem/behavior`      |
+
+## Current-state impact
+
+- **Handlerless item (FR14).** A standalone item with `isChecked` and no
+  `onCheck` is exposed as an editable checkbox though activation changes
+  nothing (WCAG 2.2 4.1.2). The shared checkbox suite records this as a known
+  failure; the meaning is OQ1.
+- **Mixed state after activation (FR5).** A standalone mixed item whose value
+  stays mixed loses its native mixed state on activation, as
+  `component:CheckboxInput` records.
+- **Checked-row state (FR15).** No selection state is reflected on the row
+  targets, against `architecture:component-theming-surface` INV6.
+- **Two focus indicators (FR19).** Keyboard focus paints both the row outline
+  and the checkbox ring, against `architecture:interaction-modality` INV3.
 
 ## Decision log
 
-None. This draft records shipped behavior; it introduces no new API, default,
-target, or subjective visual decision.
+No component-local decision. CheckboxListItem applies `spec:AST-021` and
+`spec:AST-085`.
 
 ## Open questions
 
@@ -260,9 +286,9 @@ target, or subjective visual decision.
 - **OQ3 — Which element owns consumer DOM inputs?** (`human-api`) Data and ARIA
   reach the row while `onClick` runs on the checkbox under a row-typed handler.
 - **OQ4 — Should read-only item clicks propagate?** (`human-api`) No current
-  authority owns ancestor propagation, so this is an unscored authority gap.
-  Removing the stop needs the shared clickable-container hook to stop
-  re-delegating clicks that already came from its delegate target.
+  authority owns ancestor propagation. The stop exists because the shared
+  clickable-container hook would otherwise re-delegate a click that came from
+  its `aria-readonly` delegate target back to it.
 - **OQ5 — What hover and pressed feedback should a checked row show?**
   (`human-design`) The checked-row fill currently replaces both overlays.
 - **OQ6 — Which element paints the option's focus ring?** (`human-design`)

package/src/CheckboxList/__tests__/CheckboxList.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y audit CheckboxList, CheckboxListItem
 
 /**
  * @file CheckboxList.a11y.chromium.spec.ts

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -38,8 +38,7 @@ export const docs = {
     container: true,
     targets: [{className: 'astryx-clickable-card', visualProps: ['variant']}],
     vars: [
-      {name: '--_press-overlay', description: 'Fill of the ::after interaction overlay: transparent at rest, the hover overlay token on hover (hover-capable pointers), the pressed overlay token while pressed (`:active` on a mouse; `data-astryx-press="on"` written by the touch press controller under a finger) and the hover token for the release fade. Set on the card element by its own interaction arms.', default: 'transparent', private: true},
-      {name: '--_press-overlay-transition', description: 'Duration of the overlay\'s background-color transition: the fast duration token, except 0s while a believed touch press paints so it lands on the first frame.', default: 'var(--duration-fast)', private: true},
+      {name: '--_press-overlay', description: 'Colour of the ::after interaction overlay for the hover and mouse states: transparent at rest, the hover overlay token on hover (hover-capable pointers), the pressed overlay token while a mouse holds `:active`. A press the touch press controller paints (`data-astryx-press`) is the overlay\'s image instead, at the press\'s strength, and the colour yields to it. Set on the card element by its own interaction arms.', default: 'transparent', private: true},
     ],
   },
   playground: {

package/src/ClickableCard/ClickableCard.test.tsx

@@ -4,7 +4,12 @@ import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {ClickableCard} from './ClickableCard';
-import {hasReleaseFade, readsPressStrength} from '../__tests__/pressState';
+import {
+  afterPaintsPress,
+  hasReleaseFade,
+  pressArmsShadowedByDefault,
+  readsPressStrength,
+} from '../__tests__/pressState';
 
 describe('ClickableCard', () => {
   it('renders children', () => {
@@ -257,11 +262,17 @@ describe('ClickableCard pressed state (touch)', () => {
       throw new Error('the card carries no pressable marker');
     }
     // The controller writes the card; the card owns the strength and its
-    // release, and `--_press-overlay` (what the `::after` paints) is the
-    // pressed token at that strength on both touch arms.
+    // release, and its `::after` paints the pressed token at that strength
+    // as its image on both arms, its hover and mouse colour yielding.
     expect(hasReleaseFade(card)).toBe(true);
     expect(readsPressStrength(card, '[data-astryx-press="on"]')).toBe(true);
     expect(readsPressStrength(card)).toBe(true);
+    expect(afterPaintsPress(card, '[data-astryx-press="on"]')).toBe(true);
+    expect(afterPaintsPress(card)).toBe(true);
+    // No press arm sits on a custom property the card also declares without
+    // it: in a layered stylesheet that declaration wins and the press never
+    // paints.
+    expect(pressArmsShadowedByDefault(card)).toEqual([]);
   });
 
   it('carries none of it when disabled', () => {

package/src/ClickableCard/ClickableCard.tsx

@@ -60,7 +60,11 @@ import {disabledInteractionProps} from '../utils/disabledInteraction';
 // element the controller writes to (`pressedAlpha`) at the press's strength,
 // 1 while on and 1 → 0 over the release, and inherited resolved by the
 // `::after` that paints it. See interactionOverlay.stylex.ts.
-const pressedOverlayColor = 'var(--_press-paint)';
+const pressedOverlayImage = 'var(--_press-paint-image)';
+/** Written by the press controller while it paints a press. */
+const PRESSED_ON = '[data-astryx-press="on"]';
+/** Written by the press controller for the press's release. */
+const PRESSED_FADING = '[data-astryx-press="fading"]';
 
 const styles = stylex.create({
   interactive: {
@@ -74,16 +78,18 @@ const styles = stylex.create({
   },
   // Hover and pressed overlay. Hover is guarded by @media (hover: hover) so
   // touch devices don't show a stuck hover state; the press has two arms,
-  // `:active` for a mouse and `data-astryx-press` for a finger.
+  // `:active` for a mouse and `data-astryx-press` for the press controller.
   overlay: {
-    // The `::after` layer paints whatever `--_press-overlay` says, and the
-    // interaction arms set that variable on the element itself. Setting the
-    // pseudo-element's colour from compound keys (`:active::after`) would
-    // leave the touch arms unable to outrank the mouse arm: a pseudo-element
-    // key carries the highest generated priority, and the `data-astryx-press`
-    // attribute the touch press model writes must win over `:active`, which
-    // still matches under a finger (see interactionOverlay.stylex.ts). Same
-    // enabled guard as the shared overlay utility.
+    // The `::after` layer paints the hover and mouse states as its colour,
+    // `--_press-overlay`, which their arms set on the element itself (same
+    // enabled guard as the shared overlay utility). The press the controller
+    // paints (a finger's, and on a touch-first device a mouse's or a key's)
+    // is the same layer's image, keyed on the `data-astryx-press` attribute
+    // the controller writes. Every arm of that press is a plain property of
+    // the `::after`, which outranks the layer's own defaults in a layered
+    // stylesheet and a flat one alike. A custom property's attribute arm
+    // does not: a layered build emits the property's default outside the
+    // priority layers its attribute arms land in, and the default wins.
     '--_press-overlay': {
       default: 'transparent',
       ':where(:not(:disabled,[aria-disabled="true"]))': {
@@ -98,32 +104,42 @@ const styles = stylex.create({
             colorVars['--color-overlay-hover'],
           ':active': colorVars['--color-overlay-pressed'],
         },
-        // The touch arms paint through the press's strength, which the
-        // card's `pressedAlpha` arms own: 1 on the first frame of a believed
-        // press, then 1 → 0 over the release. The `::after` inherits the
-        // resolved colour and repaints with it on every frame of the fade.
-        '[data-astryx-press="on"]': pressedOverlayColor,
-        '[data-astryx-press="fading"]': pressedOverlayColor,
       },
     },
-    // A believed touch press paints on the first frame, and the release is the
-    // strength's own animation, so neither may pass through the layer's colour
-    // transition (it would fade the onset in, and drag behind the release).
-    // The mouse states keep the fast fade.
-    '--_press-overlay-transition': {
-      default: durationVars['--duration-fast'],
-      '[data-astryx-press="on"]': '0s',
-      '[data-astryx-press="fading"]': '0s',
-    },
     '::after': {
       content: '""',
       position: 'absolute',
       inset: 0,
       pointerEvents: 'none',
-      transitionProperty: 'background-color',
-      transitionDuration: 'var(--_press-overlay-transition)',
+      // A press the controller paints shows on its first frame and fades on
+      // its strength's own animation, so the colour it replaces drops out at
+      // once rather than crossfading: no transition while it paints. The
+      // mouse states keep the fast fade.
+      transitionProperty: {
+        default: 'background-color',
+        [PRESSED_ON]: 'none',
+        [PRESSED_FADING]: 'none',
+      },
+      transitionDuration: durationVars['--duration-fast'],
       transitionTimingFunction: easeVars['--ease-standard'],
-      backgroundColor: 'var(--_press-overlay)',
+      // While the controller paints, the colour yields to the image: a
+      // touchscreen beside a fine pointer still matches `:active` under a
+      // finger, and the press would otherwise paint twice.
+      backgroundColor: {
+        default: 'var(--_press-overlay)',
+        [PRESSED_ON]: 'transparent',
+        [PRESSED_FADING]: 'transparent',
+      },
+      // The press at its strength, which the card's `pressedAlpha` arms own:
+      // 1 on the first frame of a believed press, then 1 → 0 over the
+      // release. The `::after` inherits the resolved paint and repaints with
+      // it on every frame of the fade. Read only inside this element's own
+      // arms, so a pressed ancestor's strength never paints here.
+      backgroundImage: {
+        default: null,
+        [PRESSED_ON]: pressedOverlayImage,
+        [PRESSED_FADING]: pressedOverlayImage,
+      },
     },
   },
   // Borderless variants (everything except `default`): drop the transparent