@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f77aaf2

package/src/SegmentedControl/SegmentedControlItem.spec.md

@@ -1,206 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:SegmentedControlItem
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers:
-  [
-    public-api,
-    behavior,
-    layout,
-    interaction,
-    motion,
-    theming,
-    styling,
-    accessibility,
-    visual,
-    react-runtime,
-    compatibility,
-  ]
-verified_by:
-  [
-    packages/core/src/SegmentedControl/SegmentedControl.test.tsx,
-    packages/core/src/RadioList/__tests__/RadioGroup.a11y.test.tsx,
-    packages/core/src/RadioList/__tests__/RadioGroup.a11y.chromium.spec.ts,
-    packages/core/src/__tests__/PressedState.a11y.chromium.spec.ts,
-  ]
-modules: []
-families: []
-design_specs: [design:user-states]
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-020, spec:AST-085, spec:AST-102]
----
-
-# SegmentedControlItem component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                  |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | None changes. SegmentedControlItem takes `value`, `label`, `isLabelHidden`, `icon`, `isDisabled`, and base props, and must sit inside a SegmentedControl.                                                                                                                                                                                                 |
-| Behavior                | One segment: a `<button role="radio">` with `aria-checked`. A click, or Space or Enter on the focused segment, selects it unless it is selected, disabled, or the caller's `onClick` prevents default.                                                                                                                                                    |
-| End-user impact         | People see the selected segment raised and bold, and pick another with one click. Icon-only segments are still named. A disabled selected segment drops out of the tab order.                                                                                                                                                                             |
-| Builder impact          | None.                                                                                                                                                                                                                                                                                                                                                     |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A disabled selected segment leaves the tab order, a caller `onClick` runs while disabled or cannot veto a press while focused, a caller `className` is replaced, segments hold a fixed height, and a truncated `sm` segment can be under 24 px wide; all are listed under Current-state impact. |
-| Review checks           | Reject a segment without a name, a click that selects a disabled segment, press paint on the selected or a disabled segment, or a lost forced-colors selected state.                                                                                                                                                                                      |
-| Governing rules         | `component:SegmentedControl`; WAI-ARIA radio pattern; `spec:AST-020` FR9, FR15, DEC-5; `spec:AST-085` FR1, FR2; `spec:AST-102` FR4; `design:user-states` DR1–DR3 (pressed overlay, disabled non-response, and selected-segment exception); `architecture:public-component-api` INV5, INV6; WCAG 1.4.11.                                                   |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-SegmentedControlItem is one choice in a SegmentedControl. It owns the
-segment's radio semantics, click selection, naming, label and icon rendering,
-item disabled state, and the segment's paint. Consumer usage lives in
-`SegmentedControlItem.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`; label visible, enabled
-- Compatibility class: records shipped behavior; no public prop, default,
-  export, or DOM change
-- Controlled/uncontrolled behavior: controlled by the parent's `value`
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The segment button, its radio role, checked and disabled state, and name.
-- Click selection and `onClick` composition.
-- Label and icon rendering, truncation, and segment paint per size and state.
-
-**Does not own / non-goals**
-
-- Tab stop, arrow navigation, selection-follows-focus, group disabled state,
-  and the theming anatomy map — owned by `component:SegmentedControl`. The
-  `segmented-control-item` target is declared in SegmentedControl's consumer
-  docs and mapped in its record.
-- Icon artwork — owned by the caller.
-- Use outside SegmentedControl — not supported.
-
-## Public concepts
-
-| Concept  | Closed values or states   | Meaning                                            | Availability by variant/orientation/state | Default  | Owner                            | Stability | Invalid-value behavior              |
-| -------- | ------------------------- | -------------------------------------------------- | ----------------------------------------- | -------- | -------------------------------- | --------- | ----------------------------------- |
-| Value    | string                    | The value this segment selects.                    | Always.                                   | required | `component:SegmentedControlItem` | Stable    | TypeScript rejects a missing value. |
-| Label    | string; visible or hidden | Visible text, or the name of an icon-only segment. | Always.                                   | visible  | `component:SegmentedControlItem` | Stable    | TypeScript rejects a missing label. |
-| Disabled | off, item, group          | Blocks selection.                                  | Always.                                   | off      | `component:SegmentedControlItem` | Stable    | Not applicable.                     |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Basis                                                                        |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| FR1 | Each segment renders one `<button type="button" role="radio">` with `aria-checked` true when its `value` equals the group value, `data-value`, and the `segmented-control-item` target reflecting `data-size`, `data-selected`, and `data-disabled`. A forwarded prop cannot override the role.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | WAI-ARIA radio pattern; current source and tests                             |
-| FR2 | A click, including one from Space or Enter on the focused segment (native button activation; `spec:AST-020` FR15), runs the caller `onClick` first; unless it prevents default, an enabled, unselected segment passes its value to the group's `onChange`. Clicking the selected segment does nothing. The caller's `preventDefault()` MUST veto every press. Implementation gap: a press while focus is already in the group selects through `component:SegmentedControl` FR3 before the click, so the veto does not apply to it.                                                                                                                                                                                                                                                            | `spec:AST-020` FR15; current tests                                           |
-| FR3 | The segment renders its icon (sized to the segment size) followed by its label. With `isLabelHidden`, the label is not rendered and becomes `aria-label`, and the segment does not shrink. A visible label truncates with an ellipsis when the segment is narrower than it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current tests                                                                |
-| FR4 | A segment disabled by its own `isDisabled` or by the group sets `aria-disabled`, refuses selection, shows disabled text color, and shows no hover or press paint. A disabled selected segment MUST keep the Tab stop (`spec:AST-085` FR1); for a value that matches no segment, `component:SegmentedControl` FR2 places the stop. Implementation gap: a disabled selected segment leaves the tab order, except in a group disabled with a reason when it is not itself `isDisabled`, and a caller `onClick` still runs on a disabled segment (`spec:AST-085` FR2).                                                                                                                                                                                                                            | `spec:AST-085` FR1, FR2; current tests                                       |
-| FR5 | The selected segment paints a raised surface with a low shadow and semibold primary text; under forced colors it paints `Highlight` with `HighlightText`. Unselected enabled segments paint the shared hover tint and, under `design:user-states` DR1 and DR2, the pressed overlay; the selected segment keeps its raised surface during a press (DR3).                                                                                                                                                                                                                                                                                                                                                                                                                                       | WCAG 1.4.11; `design:user-states` DR1–DR3; current tests                     |
-| FR6 | Segment height is the element height for the size minus 4 CSS px (24, 28, or 32) as a minimum that grows with a set text size under `spec:AST-102` FR4 (implementation gap: the height is fixed), with corners concentric with the control; `sm` uses supporting text and tighter padding. Keyboard focus paints the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `architecture:interaction-modality` INV1; current source; `spec:AST-102` FR4 |
-| FR7 | The segment owns `role`, `aria-checked`, `aria-disabled`, `aria-label` (set from the label when hidden), `tabIndex`, `type`, `data-value`, and `data-size`, and writes `data-selected`, `data-disabled`, and the press marker `data-astryx-pressable` in their own states; a caller value for an owned attribute is replaced, while a caller `data-selected`, `data-disabled`, or `data-astryx-pressable` passes through on segments outside that state. `ref`, other `data-*`, `style`, other ARIA such as `aria-describedby`, and other base props reach the button; `xstyle` composes last. Caller `className` MUST compose with the component's classes (`architecture:public-component-api` INV5, INV6). Implementation gap: the component's merged class replaces a caller `className`. | `architecture:public-component-api` INV5, INV6; current tests                |
-
-### Allowed variation
-
-- **AV1 — Content.** Label text and icon vary within their types.
-
-### Representative states
-
-| State      | Required invariant                                                  | Allowed variation |
-| ---------- | ------------------------------------------------------------------- | ----------------- |
-| Unselected | `aria-checked="false"`; hover and press overlay.                    | Icon.             |
-| Selected   | `aria-checked="true"`; raised; bold; Highlight under forced colors. | —                 |
-| Icon-only  | Named by `aria-label`; does not shrink.                             | —                 |
-| Disabled   | `aria-disabled`; no paint feedback; no selection.                   | Item or group.    |
-
-### Transformation and precedence order
-
-- **ORD1 — Click.** Caller `onClick`, then selection unless prevented,
-  disabled, or already selected; today a press while focus is in the group
-  selects through focus first (FR2 gap).
-
-### Performance and resources
-
-- **PR1 — Bounded resources.** No state, effect, or listener of its own; press
-  feedback shares the press controller's window and document listeners.
-
-## Accessibility contract
-
-- **AR1 — Radio semantics.** Each segment exposes the radio role, checked
-  state, disabled state, and a name (FR1, FR3).
-- **AR2 — Target size.** The smallest segment is 24 CSS px tall. A labelled
-  `sm` segment that truncates under `component:SegmentedControl` FR5 can shrink
-  below 24 CSS px wide, short of WCAG 2.5.8 (implementation gap).
-- **AR3 — Non-color state.** FR5.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Segment          | Transparent button; raised surface when selected. | Current source           | Prominent      | FR1, FR5, FR6      |
-| Label            | Medium text; semibold when selected; truncates.   | Current source           | Prominent      | FR3, FR5           |
-| Icon             | Caller artwork sized to the segment.              | Current source           | Supporting     | FR3                |
-
-The target mapping for these parts lives in `component:SegmentedControl`'s
-theming anatomy.
-
-## Family and system relationships
-
-- `component:SegmentedControl` supplies the value, size, layout, and group
-  disabled state, and owns keyboard navigation.
-- `spec:AST-085` owns disabled focusability; FR4 records the gap.
-- `design:user-states` owns the pressed treatment.
-
-## Verification map
-
-| Contract | Verification                                                                                                                                                                                                       | Representative states                         | Mutation or failure expectation                                                                                                                                                                                                                                                                                                 | Audit section                              |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
-| FR1      | `SegmentedControl.test.tsx` aria-checked and data-testid cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-option-*` states                           | Selection change; data-testid                 | Stale `aria-checked` fails. Evidence gap: no test passes `role` to a segment; the role-override case covers the radiogroup.                                                                                                                                                                                                     | `audit:SegmentedControlItem/accessibility` |
-| FR2      | `SegmentedControl.test.tsx` click and onClick-composition cases                                                                                                                                                    | Click; selected click; prevented click        | A selected or prevented click that selects fails. Evidence gap: no test covers a press while focus is already in the group.                                                                                                                                                                                                     | `audit:SegmentedControlItem/behavior`      |
-| FR3      | `SegmentedControl.test.tsx` icon, icon-only, and truncation cases                                                                                                                                                  | Icon and label; icon-only; long label         | A missing name, or an icon that truncates, fails.                                                                                                                                                                                                                                                                               | `audit:SegmentedControlItem/anatomy`       |
-| FR4      | `SegmentedControl.test.tsx` disabled cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-option-disabled` and `segmented-option-group-disabled*` states | Item and group disabled                       | A disabled segment that selects fails. Evidence gap: no test asserts the disabled text color, absent hover paint, or the caller `onClick` while disabled. The `segmented-option-group-disabled` state declares a checked, group-disabled segment with `tabReachable: false`, asserting the current FR4 gap pending conformance. | `audit:SegmentedControlItem/accessibility` |
-| FR5      | `SegmentedControl.test.tsx` forced-colors and pressed-state cases; `PressedState.a11y.chromium.spec.ts` segmented-control cases                                                                                    | Selected under forced colors; press; disabled | Lost forced-colors state, or press paint on a disabled segment, fails. Evidence gap: no test asserts the raised selected surface or the hover tint.                                                                                                                                                                             | `audit:SegmentedControlItem/visual`        |
-| FR6, FR7 | Evidence gap: no test of segment heights, text growth, focus outline, `ref`, or `xstyle` order                                                                                                                     | —                                             | —                                                                                                                                                                                                                                                                                                                               | `audit:SegmentedControlItem/layout`        |
-
-## Current-state impact
-
-- **Narrow target (AR2).** A labelled `sm` segment that truncates can shrink
-  below 24 CSS px wide, short of WCAG 2.5.8.
-- **Press veto (FR2).** A caller `onClick` cannot veto a press made while focus
-  is already in the group, which selects before the click.
-- **Caller className (FR7).** A caller `className` on a segment is replaced by
-  the component's class, against `architecture:public-component-api` INV5 and
-  INV6.
-- **Caller onClick while disabled (FR4).** A disabled segment still runs a
-  caller's `onClick`, against `spec:AST-085` FR2.
-- **Fixed height (FR6).** Segments hold a fixed height instead of growing with
-  a set text size, against `spec:AST-102` FR4.
-- **Disabled selected segment (FR4).** A disabled selected segment leaves the
-  tab order, except in a group disabled with a reason when it is not itself
-  `isDisabled`, against `spec:AST-085` FR1.
-
-## Decision log
-
-No component-local decision.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.

package/src/SelectableCard/SelectableCard.spec.md

@@ -1,230 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:SelectableCard
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx,
-    packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts,
-    packages/core/src/__tests__/CardPress.a11y.chromium.spec.ts,
-    .github/visual-baseline/manifest.json,
-    packages/core/src/SelectableCard/SelectableCard.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    apps/storybook/stories/SelectableCard.stories.tsx,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-009, spec:AST-020, spec:AST-085]
----
-
-# SelectableCard component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                    |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | A Card that toggles a controlled `isSelected` through `onChange`, named by a required `label`, with `isDisabled` and Card's `variant`, `elevation`, `padding`, and sizing.                                  |
-| Behavior                | A visually hidden native checkbox carries the role, name, and checked state; the whole surface toggles; selection draws an inset ring without moving layout.                                                |
-| End-user impact         | Screen-reader users hear a named checkbox and its state; pointer users click anywhere on the card; disabled cards stay discoverable by keyboard.                                                            |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                                |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact.                                                                   |
-| Review checks           | Reject a toggle that fires twice for one press, a disabled card that toggles or leaves the tab order, a ring that shifts layout, or a nested control that toggles the card.                                 |
-| Governing rules         | `spec:AST-085/FR1,FR2,FR5,FR6`; `spec:AST-020/FR9`; `architecture:interaction-modality/INV3`; `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV7,INV8`. |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-SelectableCard turns a Card into one checkbox option for multi-select card
-groups; each card is a checkbox, so single-select groups are out of scope. It owns the hidden checkbox semantics, whole-surface
-toggling, and the selection ring; the caller owns the selection state.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  or styling output changes
-- Controlled/uncontrolled behavior: controlled only; `isSelected` and
-  `onChange` are required
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Two focus indicators on nested controls (FR4, AR2).** The card draws its
-  outline whenever any descendant has `:focus-visible`, so focusing a nested
-  control shows the card outline and the control's own, where
-  `architecture:interaction-modality` INV3 allows one indicator per focus move.
-- **Disabled state not reflected on the target (FR5).** The
-  `selectable-card` target carries no disabled state, so a theme cannot style it
-  there, where `architecture:component-theming-surface` INV6 keeps state on the
-  owning target.
-
-## Ownership boundary
-
-**Owns**
-
-- The hidden native checkbox, its name, checked state, and disabled state.
-- Toggling from the card surface, the checkbox, and Enter, and suppressing
-  toggles from nested interactive content.
-- The selection ring, the selected border color, hover and pressed overlays,
-  the delegated focus indicator, and the disabled treatment.
-- The `selectable-card` target and the public `--selectable-card-ring-color`
-  variable.
-
-**Does not own / non-goals**
-
-- Card surface paint, padding, radius, elevation, and sizing — owned by
-  `component:Card`.
-- Group semantics and which options are selected — owned by the product
-  callsite. Single-select groups need a radio pattern, which SelectableCard
-  does not provide.
-- Navigation and one-shot actions — owned by `component:ClickableCard`.
-
-## Public concepts
-
-| Concept   | Closed values or states        | Meaning                                                 | Availability by variant/orientation/state | Default   | Owner                      | Stability | Invalid-value behavior                                                                                               |
-| --------- | ------------------------------ | ------------------------------------------------------- | ----------------------------------------- | --------- | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------- |
-| Selection | selected; unselected           | Controlled checked state, reflected as `data-selected`. | Always                                    | Required  | `component:SelectableCard` | Stable    | —                                                                                                                    |
-| Disabled  | enabled; disabled              | Blocks toggling while keeping the checkbox focusable.   | Always                                    | enabled   | `component:SelectableCard` | Stable    | —                                                                                                                    |
-| Variant   | Card variants; theme additions | Card paint and the matching selection ring color.       | Always                                    | `default` | `component:Card`           | Stable    | A theme-added variant rings in `--selectable-card-ring-color` (default `--color-accent`) and keeps its border color. |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                    |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | SelectableCard renders `component:Card` with the given `variant`, `elevation`, `padding`, and sizing. The root also carries the `selectable-card` target reflecting `variant` and `selected`, and the first child is a visually hidden native `input type="checkbox"` named by `label` with `checked` equal to `isSelected`.                                                                                                                                                                                                                                                                            | Current source and tests |
-| FR2 | While enabled, a click on the card surface, a click or Space on the checkbox, or Enter on the checkbox calls `onChange(!isSelected)` exactly once. A click that belongs to nested interactive content or selected text does not toggle. A caller `onClick` runs after the toggle for a surface click, before it for a click or Space on the checkbox, and not at all for Enter; it also runs for clicks that do not toggle. A caller `onMouseUp` runs after the card's own handling.                                                                                                                    | Current source and tests |
-| FR3 | Selection adds a 2px inset ring through Card's ring variable, so layout does not move, and composes with any elevation shadow. `default`, `transparent`, and `muted` ring in `--color-accent`; each palette variant rings in its `--color-border-<name>`; a theme-added variant rings in `--selectable-card-ring-color`. Selection also colors the border in the ring color where Card draws one, which is only the `default` variant.                                                                                                                                                                  | Current source and tests |
-| FR4 | While enabled, the surface paints the shared hover overlay under a hover-capable pointer and the pressed overlay for mouse and touch presses. Keyboard focus on the hidden checkbox shows one indicator on the card root (`architecture:interaction-modality` INV3). Implementation gap: the root outlines while any descendant has `:focus-visible`, so focusing a nested control draws both the card outline and the control's own (Current-state impact).                                                                                                                                            | Current source and tests |
-| FR5 | `isDisabled` dims the card to half opacity, removes the card's own click and mouseup handling and the caller's `onClick` and `onMouseUp` (other caller event props still reach the root) and the hover and pressed overlays (`spec:AST-085` FR6), and keeps the checkbox focusable with `aria-disabled="true"`; no click, Space, or Enter calls `onChange`. The disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `selectable-card` target reflects `variant` and `selected` but not the disabled state (Current-state impact). | Current source and tests |
-| FR6 | `ref` reaches the Card root. Supported DOM, ARIA, data, and event props reach the root; `xstyle`, `className`, and `style` merge after the component's interactive styles.                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Content.** Caller content, including nested controls, keeps its own
-  semantics and interaction.
-- **AV2 — Theme paint.** A theme may restyle `selectable-card` per `variant` and
-  `selected`, and set the ring color for an added variant.
-
-### Representative states
-
-| State          | Required invariant                                                                                | Allowed variation |
-| -------------- | ------------------------------------------------------------------------------------------------- | ----------------- |
-| Unselected     | Unchecked named checkbox; no ring.                                                                | Variant.          |
-| Selected       | Checked; inset ring in the variant's color, and a matching border on `default`; layout unchanged. | Elevation.        |
-| Keyboard focus | Focus outline on the card root.                                                                   | —                 |
-| Disabled       | Focusable checkbox with `aria-disabled`; no toggle; half opacity.                                 | Selection.        |
-| Nested control | Activating the nested control does not toggle the card.                                           | Control type.     |
-
-### Transformation and precedence order
-
-- **ORD1 — Toggle.** Disabled → nothing runs, caller `onClick` and
-  `onMouseUp` included; nested interactive target or selection → no toggle,
-  caller handlers still run; otherwise one `onChange(!isSelected)`, with a
-  caller `onClick` after it for a surface click, before it for a click or
-  Space on the checkbox, and not at all for Enter.
-- **ORD2 — Ring color.** Built-in variant mapping → `--selectable-card-ring-color`
-  for a theme-added variant.
-
-### Performance and resources
-
-- **PR1 — Shared resources only.** SelectableCard installs the shared press
-  controller on mount and marks its root as a press surface only while
-  enabled; it adds no listener, observer, or timer of its own.
-
-## Accessibility contract
-
-- **AR1 — Native checkbox.** The hidden checkbox supplies the role, name, and
-  checked state; the card root adds no role or tab stop of its own, except
-  that a fixed-height card whose content overflows is a scroll container that
-  browsers may make an unnamed tab stop (`component:Card` AR1).
-- **AR2 — Delegated focus indicator.** Keyboard focus on the hidden checkbox is
-  shown on the visible card root (`architecture:interaction-modality` INV3).
-  Implementation gap: a focused nested control shows a second outline.
-- **AR3 — Focusable disabled.** A disabled card keeps its tab stop, exposes
-  `aria-disabled`, and blocks every toggle path (`spec:AST-085` FR1, FR2, FR5).
-- **AR4 — Persistent selection.** Selection changes the
-  checked state for assistive technology and draws a ring (and, on `default`,
-  a border) that persists under hover and press, which still paint their
-  overlays.
-- **AR5 — Pointer cancellation.** A press that slides off the card before the
-  lift does not toggle it (`spec:AST-020` FR9; WCAG 2.2 2.5.2).
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Container        | Interactive card with an inset ring on selection. | Current source and docs  | Prominent      | FR1, FR3–FR5       |
-| Content          | Caller content inside the card.                   | Current source and docs  | Prominent      | FR2, AV1           |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Container": {"target": "selectable-card"},
-  "Content": {
-    "none": {
-      "reason": "intentional: caller content keeps its own styling and has no component-owned paint target"
-    }
-  }
-}
-```
-
-## Family and system relationships
-
-- `component:Card` supplies paint, padding, and the ring and elevation
-  variables SelectableCard sets.
-- `spec:AST-085` owns focusable disabled controls; AR3 records conformance.
-- `spec:AST-020` FR9 excludes SelectableCard from the slide-off exception;
-  AR5 applies it.
-- `architecture:component-theming-surface` sets the rules the
-  `selectable-card` target follows and requires a safe baseline for the
-  extensible `variant`, which `--selectable-card-ring-color` satisfies.
-
-## Verification map
-
-| Contract            | Verification                                                                                                                         | Representative states                                                            | Mutation or failure expectation                                                                                                                                                                                                                                                              | Audit section                   |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, FR2            | `SelectableCard.test.tsx` surface, checkbox, Enter, and Space tests                                                                  | Unselected, selected                                                             | A missed toggle, a wrong `onChange` value, or a doubled toggle from Space fails. Gap: surface-click tests assert only the value, not the call count, and no test asserts the `selectable-card` target or its reflection, or the order of a caller `onClick` or `onMouseUp`.                  | `audit:SelectableCard/behavior` |
-| FR3                 | `SelectableCard.test.tsx` elevation tests; stable visual baseline `core-selectablecard--single-select`; `SelectableCard.stories.tsx` | Selected with elevation; one selected default card beside unselected ones        | A lost elevation while selected fails; a changed default ring or border comes back changed for review. Gap: palette and theme-added ring colors have no automated check.                                                                                                                     | `audit:SelectableCard/theming`  |
-| FR4                 | `SelectableCard.test.tsx` touch-press test; `CardPress.a11y.chromium.spec.ts` on `core-selectablecard--single-select`                | Rest; desktop hover and mouse press; touch press                                 | A hover that does not paint over rest, a mouse press that does not paint over hover, or a touch press that does not match the desktop press or fade fails. Gap: the focus outline, and the double indicator on nested controls, have no automated check.                                     | `audit:SelectableCard/design`   |
-| FR5, AR3            | `SelectableCard.test.tsx` disabled tests; `Checkbox.a11y.chromium.spec.ts` `card-disabled` state                                     | Disabled click, Enter, Space                                                     | A toggle while disabled, or a disabled card that leaves keyboard reach, fails. Gap: the half opacity, the removed overlays, and the missing disabled reflection on the target have no automated check.                                                                                       | `audit:SelectableCard/a11y`     |
-| FR2 (nested)        | Shared clickable-container hook tests in other components                                                                            | Card with a nested control or selected text                                      | Gap: no SelectableCard test or story covers nested-control or selection suppression.                                                                                                                                                                                                         | `audit:SelectableCard/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                        | Consumer anatomy and current target                                              | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                | `audit:SelectableCard/theming`  |
-| AR1, AR2, AR4       | `SelectableCard.test.tsx` checkbox tests; `Checkbox.a11y.test.tsx` and `Checkbox.a11y.chromium.spec.ts` SelectableCard states        | Unchecked, checked, disabled (`card-unchecked`, `card-checked`, `card-disabled`) | A lost checkbox role or name, a wrong checked state, or a disabled card that is not exposed as unavailable or not reachable fails, including at the accessibility tree. Gap: no test asserts that the root adds no role or tab stop, the root focus outline, or the ring winning over hover. | `audit:SelectableCard/a11y`     |
-| FR6, PR1            | Source review                                                                                                                        | Ref; caller props                                                                | Gap: no test asserts ref or passthrough routing, or fails if SelectableCard adds its own listener or timer.                                                                                                                                                                                  | `audit:SelectableCard/behavior` |
-| AR5                 | `Checkbox.a11y.chromium.spec.ts` aborted-press check on the SelectableCard states                                                    | Press that slides off the card before the lift                                   | A toggle after a slide-off lift fails.                                                                                                                                                                                                                                                       | `audit:SelectableCard/a11y`     |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.