Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): CheckboxList records its shipped contract as current (#8765)

Cindy Zhangd4de65a77adf
diff --git a/docs/families/input-fields.md b/docs/families/input-fields.md
index 08c0edccd4..59f7bcd791 100644
--- a/docs/families/input-fields.md
+++ b/docs/families/input-fields.md
@@ -372,7 +372,6 @@ DEC-6 does not require unrelated components to add a new floor.
| ComplexSelector | control box | control box | trigger button | `control*` |
| Typeahead | Field | Field | combobox input | `container*` |
| Tokenizer | Field | Field | combobox input | `container*` |
- | CheckboxList | Field | Field | `role="group"` element | `container*` |
| RadioList | Field | not forwarded; `ref` on Field | `role="radiogroup"` element | `container*` |
| Slider | Field | not forwarded; `ref` on the track | slider control | `container*` |
diff --git a/packages/core/src/CheckboxList/CheckboxList.spec.md b/packages/core/src/CheckboxList/CheckboxList.spec.md
index 0920595da9..c13d9a7041 100644
--- a/packages/core/src/CheckboxList/CheckboxList.spec.md
+++ b/packages/core/src/CheckboxList/CheckboxList.spec.md
@@ -1,16 +1,28 @@
---
schema_version: 3
-template_version: 6
+template_version: 7
kind: component
id: component:CheckboxList
-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,
@@ -18,11 +30,11 @@ verified_by:
packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx,
packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts,
packages/core/src/theme/themingTargets.test.ts,
- apps/storybook/stories/CheckboxList.stories.tsx,
+ packages/core/src/CheckboxList/CheckboxList.fr10.test.tsx,
scripts/check-knowledge.mjs,
]
modules: []
-families: []
+families: [family:input-fields]
design_specs: []
architecture:
[
@@ -32,24 +44,24 @@ 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]
---
# CheckboxList component contract
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `CheckboxList` is a labeled `role="group"` of `CheckboxListItem` rows. A `value` array selects controlled collection mode (`onChange`, `changeAction`); without it, its items are standalone. The group owns naming, description, disabled, disabled-reason, read-only, pending values, and status. Each option's behavior is `component:CheckboxListItem`. |
-| Behavior | The group names and describes its options, tracks every value whose `changeAction` is pending so each saving option stays busy while the others stay interactive, and applies disabled, read-only, and status to every option. |
-| End-user impact | People can identify the group, operate every option by pointer, touch, and keyboard, learn why a group is unavailable, and see which options are still saving. |
-| Builder impact | Builders choose collection mode by passing `value`, and then supply stable item `value`s. Invalid-status and group pass-through-target meaning remain owner decisions here; per-option owner decisions are recorded in `component:CheckboxListItem`. |
-| Compatibility/readiness | Released API, defaults, DOM ownership, and targets are unchanged. This draft records shipped behavior, including the concurrent-pending fix from the CheckboxList audit (#6777). |
-| Review checks | Reject a pending value that loses its busy state or re-toggle guard when another option is toggled, dropped group naming or description ids, a toggle while the group is disabled or read-only, or new target or state API introduced without an owner decision. Per-option checks are in `component:CheckboxListItem`. |
-| Governing rules | `architecture:public-component-api/INV1–INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:interaction-modality/INV1–INV5`; `architecture:component-test-sufficiency/INV1–INV7`; `architecture:knowledge-contracts/INV2`; `spec:AST-021/FR8–FR10`; `spec:AST-038/FR7`; WCAG 2.2 1.3.1, 2.1.1, 4.1.2. |
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `CheckboxList` is a labeled `role="group"` of `CheckboxListItem` rows. A `value` array selects controlled collection mode (`onChange`, `changeAction`); without it, its items are standalone. The group owns naming, description, disabled, disabled-reason, read-only, pending values, and status. Each option's behavior is `component:CheckboxListItem`. |
+| Behavior | The group names and describes its options, tracks every value whose `changeAction` is pending so each saving option stays busy while the others stay interactive, and applies disabled, read-only, and status to every option. |
+| End-user impact | People can identify the group, operate every option by pointer, touch, and keyboard, learn why a group is unavailable, and see which options are still saving. |
+| Builder impact | Builders choose collection mode by passing `value`, and then supply stable item `value`s. Invalid-status meaning stays an open question here (OQ3); per-option open questions are in `component:CheckboxListItem`. |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. An error status exposes no invalid state; listed under Current-state impact. |
+| Review checks | Reject a pending value that loses its busy state or re-toggle guard when another option is toggled, dropped group naming or description ids, a toggle while the group is disabled or read-only, or new target or state API introduced without an owner decision. Per-option checks are in `component:CheckboxListItem`. |
+| Governing rules | `architecture:public-component-api/INV1–INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:interaction-modality/INV1–INV5`; `architecture:component-test-sufficiency/INV1–INV7`; `architecture:knowledge-contracts/INV2`; `spec:AST-021/FR8–FR10`; `spec:AST-038/FR7`; `spec:AST-085/FR1, FR7`; `family:input-fields/FR10`; 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,9 +72,8 @@ touch, keyboard, and assistive technology.
## Compatibility and migration
- Released default preserved: `yes`
-- Compatibility class: observational record, including the CheckboxList audit's
- concurrent-pending fix; public types, defaults, DOM ownership, targets, and
- focus order are unchanged
+- Compatibility class: records shipped behavior; no public prop, default,
+ export, or DOM change
- Controlled/uncontrolled behavior: collection mode is controlled by `value`;
standalone items follow `component:CheckboxListItem`; no uncontrolled mode
exists
@@ -74,8 +85,9 @@ Consumer migration instructions belong in consumer docs and release notes.
**Owns**
-- The labeled checkbox group, its `checkbox-list` target, and the group's
- description, status, and disabled-reason relationships.
+- The labeled checkbox group, its `checkbox-list` target, the group's
+ description, status, and disabled-reason relationships, and where its
+ base, `container*`, and `control*` props land.
- Collection state shared with CheckboxListItem: checked membership, change
ordering, optimistic pending values, and group-level availability.
- The composed option anatomy and its target dispositions (Theming anatomy
@@ -90,8 +102,8 @@ Consumer migration instructions belong in consumer docs and release notes.
- List and option-row presentation — owned by `component:List`; its
`list-item` target reaches only the row root.
- The checkbox control, its indicator, focus ring, and pressed overlay — owned
- by `component:CheckboxInput` and `component:CheckboxIndicator`.
-- Group-label and validation-message presentation — owned by `component:Field`
+ by `component:CheckboxInput` and CheckboxIndicator.
+- Group-label and validation-message presentation — owned by Field under `family:input-fields` (shared owner section)
and `component:FieldStatus`.
- Loading-indicator presentation — owned by `component:Spinner`; tooltip
behavior — owned by `useTooltip`.
@@ -99,17 +111,17 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ---------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------- | ---------------------- | -------------------------------------- | ------------------------------------------------------------ |
-| group naming | `label`, `isLabelHidden`, `description` | Names and describes the `role="group"`; a hidden label still names it. | All states. | label required; visible | caller and Field | stable | rejected by the public type |
-| collection value | `value` array present or absent | Present: the group owns checked membership and change handling for its items. Absent: its items are standalone. | All states. | absent | caller and component | stable | an item without `value` in collection mode throws (item FR4) |
-| change path | `onChange`, `changeAction`, both, neither | Reports the next value array; `changeAction` runs after `onChange` in a transition with an optimistic value. | Collection mode. | neither | caller and component | shipped; handlerless meaning unsettled | no handler means no component-owned mutation |
-| availability | enabled, `isDisabled`, `isDisabled` with `disabledMessage` | Blocks toggling on every item; a reason keeps the items focusable through `aria-disabled` and shows a group tooltip. | Reason applies only with `isDisabled`. | enabled | component | stable | a reason without `isDisabled` renders nothing |
-| read-only | `isReadOnly` | Makes every item read-only. | Group-wide. | false | component | stable | boolean only |
-| pending values | the values whose `changeAction` is pending | Each pending value's item renders busy; toggling another item does not clear it; concurrent values settle together. | Collection mode with `changeAction`. | none | component | stable | transition state only |
-| status | `warning`, `error`, `success`, optional message | A message renders a detached FieldStatus after the list and describes the group. | All states. | none | caller and FieldStatus | shipped; invalid semantics unsettled | a status without a message renders nothing |
-| row layout | `density` compact/balanced/spacious; `hasDividers`; `width` | Density reaches the List and its rows; dividers separate rows; width sizes the label, list, and status together. | All states. | balanced; none; intrinsic | component and List | stable | rejected by the public types |
-| pass-through | CheckboxList rest, `ref`, `className`, `style`, `xstyle` | Reach the field root. | All states. | none | component | shipped; ARIA target unsettled | component-owned attributes win |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------- | ---------------------- | -------------------------------------- | ------------------------------------------------------------ |
+| group naming | `label`, `isLabelHidden`, `description` | Names and describes the `role="group"`; a hidden label still names it. | All states. | label required; visible | caller and Field | stable | rejected by the public type |
+| collection value | `value` array present or absent | Present: the group owns checked membership and change handling for its items. Absent: its items are standalone. | All states. | absent | caller and component | stable | an item without `value` in collection mode throws (item FR4) |
+| change path | `onChange`, `changeAction`, both, neither | Reports the next value array; `changeAction` runs after `onChange` in a transition with an optimistic value. | Collection mode. | neither | caller and component | shipped; handlerless meaning unsettled | no handler means no component-owned mutation |
+| availability | enabled, `isDisabled`, `isDisabled` with `disabledMessage` | Blocks toggling on every item, which stays focusable through `aria-disabled`; a reason adds a group tooltip. | Reason applies only with `isDisabled`. | enabled | component | stable | a reason without `isDisabled` renders nothing |
+| read-only | `isReadOnly` | Makes every item read-only. | Group-wide. | false | component | stable | boolean only |
+| pending values | the values whose `changeAction` is pending | Each pending value's item renders busy; toggling another item does not clear it; concurrent values settle together. | Collection mode with `changeAction`. | none | component | stable | transition state only |
+| status | `warning`, `error`, `success`, optional message | A message renders a detached FieldStatus after the list and describes the group. | All states. | none | caller and FieldStatus | shipped; invalid semantics unsettled | a status without a message renders nothing |
+| row layout | `density` compact/balanced/spacious; `hasDividers`; `width` | Density reaches the List and its rows; dividers separate rows; width sizes the label, list, and status together. | All states. | balanced; none; intrinsic | component and List | stable | rejected by the public types |
+| pass-through | CheckboxList rest, `ref`, `container*`, `control*` | Base props and `ref` reach the `role="group"`; `container*` the Field box; `control*` the group element. | All states. | none | component | stable | root `xstyle`, `className`, `style` are not accepted |
Item props (`label`, `aria-label`, `description`, `endContent`, `isChecked`,
`onCheck`, item `isDisabled`, `isLoading`, and item pass-through) are concepts
@@ -117,28 +129,21 @@ of `component:CheckboxListItem`.
## 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 render MUST place CheckboxListItem children inside a List within a `role="group"` named by the group label through `aria-labelledby`; its `aria-describedby` MUST list the description, status message, and disabled-reason tooltip that are present, in that order. | shipped source; focused tests; WCAG 1.3.1 and 4.1.2 | verify |
-| FR2 | The CheckboxList root MUST carry the current `checkbox-list` target. | shipped source and public docs | settled |
-| FR4 | A status message MUST render through a detached FieldStatus after the list. | shipped source, focused tests, and Chromium receipts | verify |
-| FR6 | With a `value` array, the group MUST provide membership to its items, call `onChange` with the next array an item proposes (`component:CheckboxListItem` FR4), and then run `changeAction` with the same array in a transition with an optimistic value. | shipped source and focused tests | verify |
-| FR7 | The group MUST track every value whose `changeAction` is pending and expose it to its items, each of which renders busy (`component:CheckboxListItem` FR7); toggling another item MUST NOT clear an earlier pending value. Concurrent pending values settle together, after which every busy state clears. | shipped public `changeAction` promise; focused regression test; Chromium receipts | verify |
-| FR9 | Group `isDisabled` MUST natively disable every checkbox unless `disabledMessage` is set; with a reason, checkboxes MUST stay focusable through `aria-disabled`, show the reason tooltip on group hover and focus, and refuse toggling. | shipped source, focused tests, and shared checkbox binding | verify |
-| FR10 | Group `isReadOnly` MUST make every item in the group read-only (`component:CheckboxListItem` FR8 and FR10). | shipped source; shared checkbox binding; `spec:AST-011` read-only vocabulary | verify |
-| FR13 | `density` MUST reach the List and its rows (the checkbox size follows `component:CheckboxListItem` FR11); `hasDividers` MUST separate rows without a divider after the last row; `width` MUST size the label, list, and status together. | shipped source, docs, and Chromium receipts | verify |
-| GAP3 | An error `status` exposes no programmatic invalid state on the group or its checkboxes, and a status without a message renders nothing. | shipped source; `spec:AST-002/FR15` | owner decision |
-| GAP4 | Consumer ARIA pass-throughs on CheckboxList reach the field root rather than the named `role="group"`. | shipped source; `architecture:public-component-api/INV5` | owner decision |
-
-Per-option requirements and gaps that earlier drafts listed here have one owner
-(`architecture:knowledge-contracts/INV2`): former FR3 is
-`component:CheckboxListItem` FR1; FR5 is its FR2, FR3, and content concept (the
-target dispositions stay in the theming anatomy below); FR8 is its FR5; FR11 is
-its FR1, FR9, and FR10; FR12 is its FR2 and FR3; and GAP1, GAP2, GAP5, and GAP6
-keep their numbers there.
+| ID | Invariant | Basis |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| FR1 | The render MUST place CheckboxListItem children inside a List within a `role="group"` named by the group label through `aria-labelledby`; its `aria-describedby` MUST list any caller description, then the description, status message, and disabled-reason tooltip that are present, in that order. | shipped source; focused tests; WCAG 1.3.1 and 4.1.2 |
+| FR2 | The CheckboxList root MUST carry the current `checkbox-list` target. | shipped source and public docs |
+| FR4 | A status message MUST render through a detached FieldStatus after the list. | shipped source, focused tests, and the Chromium accessibility suite |
+| FR6 | With a `value` array, the group MUST provide membership to its items, call `onChange` with the next array an item proposes (`component:CheckboxListItem` FR4), and then run `changeAction` with the same array in a transition with an optimistic value. | shipped source and focused tests |
+| FR7 | The group MUST track every value whose `changeAction` is pending and expose it to its items, each of which renders busy (`component:CheckboxListItem` FR7); toggling another item MUST NOT clear an earlier pending value. Concurrent pending values settle together, after which every busy state clears. | shipped public `changeAction` promise; focused regression test; the Chromium accessibility suite |
+| FR9 | Group `isDisabled` MUST make every checkbox focusable-disabled through `aria-disabled` (`component:CheckboxInput` FR4) and refuse toggling. With `disabledMessage`, the reason tooltip opens on group hover and keyboard focus, and the reason MUST describe each focusable checkbox (`spec:AST-085` FR5, FR7). Implementation gap: the reason describes only the `role="group"`, so a focused checkbox is not described by it. | `spec:AST-085` FR1, FR7; shipped source, focused tests, and shared checkbox binding |
+| FR10 | Group `isReadOnly` MUST make every item in the group read-only (`component:CheckboxListItem` FR8 and FR10). | shipped source; shared checkbox binding; `spec:AST-011` read-only vocabulary |
+| FR13 | `density` MUST reach the List and its rows (the checkbox size follows `component:CheckboxListItem` FR11); `hasDividers` MUST separate rows without a divider after the last row; `width` MUST size the label, list, and status together. | shipped source, docs, and the Chromium accessibility suite |
+| FR14 | An error `status` with a message renders it (FR4). Implementation gap: an error exposes no programmatic invalid state on the group or its checkboxes, and a status without a message renders nothing; their meaning is OQ3. | shipped source; `spec:AST-002/FR15` |
+| FR15 | Base props, including ARIA and `ref`, MUST reach the `role="group"`; a caller `aria-labelledby` joins the group label and a caller `aria-describedby` comes first. `container*` MUST reach the Field box where one renders (in a `horizontal-labels` FormLayout none renders, and `container*` has no effect and warns), and `control*` the group element; root `xstyle`, `className`, and `style` are not accepted. | `family:input-fields` FR10; `CheckboxList.fr10.test.tsx` |
+
+Per-option requirements are owned by `component:CheckboxListItem`
+(`architecture:knowledge-contracts/INV2`).
### Allowed variation
@@ -167,8 +172,9 @@ Option variation is `component:CheckboxListItem` AV1–AV3.
- **ORD2 — Toggle.** An item's proposed next array (`component:CheckboxListItem`
ORD2) → `onChange` → `changeAction` in a transition that adds the toggled value
to the pending set.
-- **ORD3 — Availability.** Group disabled wins; a group reason changes
- focusability, not operability; group read-only applies to mutation only.
+- **ORD3 — Availability.** Group disabled wins and keeps every checkbox
+ focusable; a group reason adds the tooltip, not operability; group read-only
+ applies to mutation only.
### Performance and resources
@@ -256,7 +262,7 @@ untargeted spans, so neither delegates to Text nor inherits the row-root
`list-item` target; future exposure remains unsettled. Rich label content and end
content are caller-provided, and end content intentionally stays outside
CheckboxList's public theming ownership. The `Option row` delegation reaches the
-row surface, but not a checked-row state (`component:CheckboxListItem` GAP2).
+row surface, but not a checked-row state (`component:CheckboxListItem` FR15).
## Family and system relationships
@@ -282,34 +288,42 @@ row surface, but not a checked-row state (`component:CheckboxListItem` GAP2).
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, AR1 | `CheckboxList.test.tsx` group naming, description, status, and disabled-reason assertions | Named group; description plus status; disabled reason | Dropping the label, description, status, or tooltip id from the group fails the accessible name or description assertions. | `audit:CheckboxList/a11y` |
-| FR4, FR6, FR7 | `CheckboxList.test.tsx` collection, status, and pending suites; Chromium `pending-*` receipts | add, remove; status; one pending value; two pending values; settled | A wrong array, a missing status, clearing an earlier pending value, allowing its re-toggle, or leaving busy after settlement fails. | `audit:CheckboxList/behavior` |
-| FR9, FR10, AR4 | `CheckboxList.test.tsx` disabled and read-only suites; shared checkbox bindings | Group disabled; disabled with reason; group read-only | A focusability, state, or reason expectation fails, or a toggle succeeds while the group is disabled or read-only. | `audit:CheckboxList/a11y` |
-| FR13 | Chromium density, divider, long-content, and RTL receipts | compact, balanced, spacious; dividers; 320px long content; RTL | A density, divider, width, overflow, or direction sensor fails. | `audit:CheckboxList/responsive` |
-| Local target source | `themingTargets.test.ts` | `checkbox-list` | Source/docs target drift fails the repository target guard. | `audit:CheckboxList/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local target | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:CheckboxList/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1, AR1 | `CheckboxList.test.tsx` group-role, group-description, and disabledMessage cases | Named group; description plus status; disabled reason | A missing group name, or a description and status out of order, fails. Evidence gap: no test asserts the caller description first or the disabled reason last. | `audit:CheckboxList/accessibility` |
+| FR2, FR15 | `CheckboxList.test.tsx` ref and container case; `CheckboxList.fr10.test.tsx` | Standalone; `horizontal-labels` FormLayout | A ref off the group, `container*` off the Field box, or a base prop off the group fails. | `audit:CheckboxList/api` |
+| FR4, FR14 | `CheckboxList.test.tsx` error-status case | Error with message | A missing status message fails. Evidence gap: no test asserts the absent invalid state or the empty render without a message. | `audit:CheckboxList/accessibility` |
+| FR6, FR7 | `CheckboxList.test.tsx` add, remove, and pending cases; `CheckboxList.a11y.chromium.spec.ts` `pending-single`, `pending-concurrent`, and `pending-settled` cases | Add; remove; one and two pending values; settled | A wrong array, a cleared earlier pending value, or a busy state that outlives settlement fails. | `audit:CheckboxList/behavior` |
+| FR9, FR10, AR4 | `CheckboxList.test.tsx` group-disabled, disabledMessage, and read-only cases; shared checkbox bindings | Group disabled; with reason; read-only item | A lost tab stop, a toggle while disabled, or a read-only toggle fails. Evidence gap: no test asserts that a focused checkbox is not described by the reason. | `audit:CheckboxList/accessibility` |
+| FR13 | `CheckboxList.test.tsx` density cases; `CheckboxList.a11y.chromium.spec.ts` density, divider, 320-pixel, and RTL cases | Compact, balanced, spacious; dividers; narrow; RTL | A density, divider, overflow, or direction sensor fails. Evidence gap: no test asserts `width` sizing the label, list, and status together. | `audit:CheckboxList/layout` |
+| ORD1–ORD3, PR1 | ORD1 and ORD2 are covered by the FR6 and FR7 rows, ORD3 by the FR9 and FR10 rows. Evidence gap: no test asserts the absence of observers or global listeners | — | — | `audit:CheckboxList/behavior` |
+| Local target source | `themingTargets.test.ts`; `CheckboxList.test.tsx` ref and container case | `checkbox-list` | A rendered class absent from the documented targets, or a missing `astryx-checkbox-list` on the Field root, fails. | `audit:CheckboxList/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local target | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails validation. | `audit:CheckboxList/theming` |
Per-option verification is owned by `component:CheckboxListItem`'s
verification map. No current repository check resolves `delegatesTo`
-owner/target pairs; the pairs in this draft were verified manually, so semantic
-delegation drift remains a validation gap.
+owner and target pairs; the pairs above match the current Field, List,
+CheckboxInput, Spinner, and FieldStatus targets.
+
+## Current-state impact
+
+- **Group reason (FR9).** A group `disabledMessage` describes only the
+ `role="group"`, so a focused disabled checkbox is not described by it,
+ against `spec:AST-085` FR5 and FR7.
+- **Error status (FR14).** An error `status` sets no invalid state on the group
+ or its checkboxes, and a status without a message renders nothing; the
+ meaning is OQ3.
## Decision log
-None. This draft records shipped behavior; it introduces no new API, default,
-target, or subjective visual decision.
+No component-local decision. CheckboxList applies `spec:AST-021`,
+`spec:AST-085`, and `family:input-fields` FR10.
## Open questions
- **OQ3 — Should an error status expose invalid state, and what should a status
without a message render?** (`human-api`)
-- **OQ4 — Which element owns consumer ARIA pass-throughs on CheckboxList?**
- (`human-api`) They currently reach the field root rather than the group.
-
-Former OQ1, OQ2, OQ5, and OQ6 are per-option questions and keep their numbers in
-`component:CheckboxListItem`.
+ Per-option questions live in `component:CheckboxListItem`.
## Content boundary
diff --git a/packages/core/src/CheckboxList/CheckboxListItem.spec.md b/packages/core/src/CheckboxList/CheckboxListItem.spec.md
index e7ced972a0..78bea1a960 100644
--- a/packages/core/src/CheckboxList/CheckboxListItem.spec.md
+++ b/packages/core/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`)