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.mdindex 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.mdindex 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: 7kind: componentid: component:CheckboxList-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-28owners: [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 modeexists@@ -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, changeordering, 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`; tooltipbehavior — 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 valueto 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 endcontent are caller-provided, and end content intentionally stays outsideCheckboxList'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`'sverification 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 statuswithout 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 boundarydiff --git a/packages/core/src/CheckboxList/CheckboxListItem.spec.md b/packages/core/src/CheckboxList/CheckboxListItem.spec.mdindex 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: 7kind: componentid: component:CheckboxListItem-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-28owners: [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`; delegationmechanics — 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 theaccessibility 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 ARIAreach 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`)