@chromvoid/headless-ui 0.1.0

package/specs/components/button.md

@@ -0,0 +1,115 @@
+# Button Component Contract
+
+## Purpose
+
+`Button` is a headless APG-aligned contract for an interactive element that allows users to trigger an action or event. It handles activation via click and keyboard, focus management, disabled state, and loading gating.
+
+## Component Files
+
+- `src/button/index.ts` - model and public `createButton` API
+- `src/button/button.test.ts` - unit behavior tests
+
+## Public API
+
+- `createButton(options)`
+  - `options`:
+    - `isDisabled?`: boolean signal or value
+    - `isLoading?`: boolean signal or value
+    - `isPressed?`: boolean signal or value (for toggle buttons)
+    - `onPress?`: callback function
+- `state` (signal-backed):
+  - `isDisabled()` - boolean indicating if the button is disabled
+  - `isLoading()` - boolean indicating if the button is loading
+  - `isPressed()` - boolean indicating if the button is in a pressed state (for toggle buttons)
+- `actions`:
+  - `setDisabled(next)` - updates disabled state
+  - `setLoading(next)` - updates loading state
+  - `setPressed(next)` - controlled pressed update
+  - `press()` - manually triggers the button's action
+  - `handleKeyDown(event)` - processes activation keys (`Enter`, `Space`)
+  - `handleKeyUp(event)` - processes `Space` key release
+- `contracts`:
+  - `getButtonProps()` - returns ARIA and event handler props for the button element
+
+## APG and A11y Contract
+
+- role: `button`
+- required attributes:
+  - `aria-disabled`: reflects interaction unavailability (`isDisabled || isLoading`)
+  - `aria-busy`: reflects loading state
+  - `aria-pressed`: reflects `isPressed` state (only for toggle buttons)
+  - `tabindex`: `0` when interactive, `-1` when unavailable (`isDisabled || isLoading`)
+- focus management:
+  - the button is in the page tab sequence when interactive
+- keyboard interaction:
+  - `Enter`: triggers the button action on `keydown`
+  - `Space`: triggers the button action on `keyup`
+
+## Behavior Contract
+
+- **Activation**:
+  - clicking the button triggers the `onPress` callback
+  - pressing `Enter` triggers the `onPress` callback on `keydown`
+  - pressing `Space` triggers the `onPress` callback on `keyup`
+- **Toggle Button**:
+  - if `isPressed` is provided in options, the button acts as a toggle button
+  - activation toggles the `isPressed` state
+- **Unavailable State**:
+  - if `isDisabled` is true, activation actions are ignored
+  - if `isLoading` is true, activation actions are ignored
+  - controlled actions (`setPressed`, `setDisabled`) remain available while loading
+
+## Transitions Table
+
+| Event               | Guard                       | Action              | Next State                                           |
+| ------------------- | --------------------------- | ------------------- | ---------------------------------------------------- |
+| click               | `!isDisabled && !isLoading` | `press()`           | calls `onPress`; if toggle: `isPressed = !isPressed` |
+| click               | `isDisabled \|\| isLoading` | —                   | no change                                            |
+| `keydown Enter`     | `!isDisabled && !isLoading` | `handleKeyDown(e)`  | calls `onPress`; if toggle: `isPressed = !isPressed` |
+| `keydown Enter`     | `isDisabled \|\| isLoading` | —                   | no change                                            |
+| `keyup Space`       | `!isDisabled && !isLoading` | `handleKeyUp(e)`    | calls `onPress`; if toggle: `isPressed = !isPressed` |
+| `keyup Space`       | `isDisabled \|\| isLoading` | —                   | no change                                            |
+| `setDisabled(next)` | —                           | `setDisabled(next)` | `isDisabled = next`                                  |
+| `setLoading(next)`  | —                           | `setLoading(next)`  | `isLoading = next`                                   |
+| `setPressed(next)`  | —                           | `setPressed(next)`  | `isPressed = next`                                   |
+
+## Adapter Expectations
+
+UIKit (`cv-button`) binds to the headless contract as follows:
+
+- **Signals read**: `state.isDisabled()`, `state.isLoading()`, `state.isPressed()` — to reflect host attributes and visual states
+- **Actions called**: `actions.setDisabled(v)`, `actions.setLoading(v)`, `actions.setPressed(v)` — to sync attribute changes into headless state
+- **Contracts spread**: `contracts.getButtonProps()` — spread onto the inner `[part="base"]` element to apply `role`, `aria-disabled`, `aria-busy`, `aria-pressed`, `tabindex`, and keyboard/click handlers
+- **Toggle events**: UIKit dispatches `input` and `change` events by observing `isPressed` changes triggered by user activation (not by controlled `setPressed`)
+
+## Invariants
+
+- `aria-pressed` must only be present if the button is a toggle button
+- `aria-disabled` must be `true` when `isDisabled` or `isLoading` is true
+- `aria-busy` must be `true` when `isLoading` is true
+- `onPress` must not be called when interaction is unavailable
+
+## Minimum Test Matrix
+
+- trigger `onPress` on click
+- trigger `onPress` on `Enter` keydown
+- trigger `onPress` on `Space` keyup
+- verify `aria-disabled` reflects unavailable state (`isDisabled || isLoading`)
+- verify `aria-busy` reflects `isLoading`
+- verify `aria-pressed` reflects `isPressed` for toggle buttons
+- ensure `onPress` is not triggered when unavailable
+- verify `tabindex` behavior for interactive vs unavailable states
+- verify `setPressed` remains available in controlled loading scenario
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Layering**: core -> interactions -> a11y-contracts -> adapters; adapters remain thin mappings.
+- **Independence**: No imports from @project/_, apps/_, or other out-of-package modules.
+- **Verification**: Mandatory adapter integration tests and standalone package test execution.
+
+## Out of Scope (Current)
+
+- menu buttons (handled by `Menu` component)
+- split buttons
+- button groups (layout only)

package/specs/components/callout.md

@@ -0,0 +1,195 @@
+# Callout Component Contract
+
+## Purpose
+
+`Callout` is a headless contract for static supplementary content blocks that highlight important information to the user. Unlike `Alert`, a callout is not a live region — it does not announce dynamically. It uses `role="note"` to convey that the content is parenthetic or ancillary. Callouts optionally support a closable dismiss pattern.
+
+## Component Files
+
+- `src/callout/index.ts` - model and public `createCallout` API
+- `src/callout/callout.test.ts` - unit behavior tests
+
+## Options (`CreateCalloutOptions`)
+
+| Option     | Type             | Default     | Description                                      |
+| ---------- | ---------------- | ----------- | ------------------------------------------------ |
+| `idBase`   | `string`         | `'callout'` | Base id prefix for generated ids                 |
+| `variant`  | `CalloutVariant` | `'info'`    | Visual variant for theming                       |
+| `closable` | `boolean`        | `false`     | Whether the callout can be dismissed by the user |
+| `open`     | `boolean`        | `true`      | Initial visibility state                         |
+
+## Type Definitions
+
+```ts
+type CalloutVariant = 'info' | 'success' | 'warning' | 'danger' | 'neutral'
+```
+
+## Public API
+
+### `createCallout(options?: CreateCalloutOptions): CalloutModel`
+
+### State (signal-backed)
+
+| Signal     | Type                   | Derived? | Description                           |
+| ---------- | ---------------------- | -------- | ------------------------------------- |
+| `variant`  | `Atom<CalloutVariant>` | No       | Current visual variant                |
+| `closable` | `Atom<boolean>`        | No       | Whether the close button is available |
+| `open`     | `Atom<boolean>`        | No       | Whether the callout is visible        |
+
+### Actions
+
+| Action        | Signature                         | Description                                             |
+| ------------- | --------------------------------- | ------------------------------------------------------- |
+| `setVariant`  | `(value: CalloutVariant) => void` | Updates the visual variant                              |
+| `setClosable` | `(value: boolean) => void`        | Toggles whether the callout is closable                 |
+| `close`       | `() => void`                      | Sets `open` to `false`. No-op if `closable` is `false`. |
+| `show`        | `() => void`                      | Sets `open` to `true`                                   |
+
+### Contracts
+
+| Contract                | Return type               | Description                                                     |
+| ----------------------- | ------------------------- | --------------------------------------------------------------- |
+| `getCalloutProps()`     | `CalloutProps`            | Ready-to-spread ARIA attribute map for the callout root element |
+| `getCloseButtonProps()` | `CalloutCloseButtonProps` | Ready-to-spread attribute map for the close button element      |
+
+#### `CalloutProps` Shape
+
+```ts
+{
+  id: string
+  role: 'note'
+  'data-variant': CalloutVariant
+}
+```
+
+The `role` is always `'note'` — a static structural role indicating parenthetic or ancillary content. This is NOT a live region; content is not announced dynamically by assistive technologies.
+
+#### `CalloutCloseButtonProps` Shape
+
+```ts
+{
+  id: string
+  role: 'button'
+  tabindex: '0'
+  'aria-label': 'Dismiss'
+  onClick: () => void
+}
+```
+
+The close button props are only meaningful when `closable` is `true`. UIKit should conditionally render the close button based on the `closable` signal.
+
+## APG and A11y Contract
+
+- **Role**: `role="note"` on the root element — indicates supplementary content
+- **Not a live region**: No `aria-live`, no `aria-atomic`. Content is read inline when encountered, not announced on change.
+- **Close button**: When `closable` is `true`, a button with `aria-label="Dismiss"` is rendered. Standard button keyboard interaction applies (Enter/Space activates).
+- **Non-interactive root**: The callout root itself is not focusable and has no keyboard interactions. Only the close button (when present) is interactive.
+
+## Keyboard Contract
+
+| Key     | Element      | Condition            | Action                                                  |
+| ------- | ------------ | -------------------- | ------------------------------------------------------- |
+| `Enter` | Close button | `closable` is `true` | Activates close (handled by native button or `onClick`) |
+| `Space` | Close button | `closable` is `true` | Activates close (handled by native button or `onClick`) |
+
+No keyboard handling is needed on the callout root itself.
+
+## Behavior Contract
+
+- `variant` is set programmatically; it affects visual theming only, not ARIA semantics.
+- `closable` controls whether the close button is rendered and whether the `close` action has effect.
+- `close` action: sets `open` to `false` only when `closable` is `true`; otherwise it is a no-op.
+- `show` action: sets `open` to `true` unconditionally (allows programmatic re-showing after dismiss).
+- `open` determines visibility; when `false`, UIKit should hide the callout (e.g., via `hidden` attribute or conditional rendering).
+- The callout does not manage focus. Closing does not move focus elsewhere (UIKit may handle focus restoration if needed).
+- No automatic dismissal timer. The callout remains visible until explicitly closed.
+
+## Transitions Table
+
+| Trigger                  | Precondition                         | State Change     | Contract Effect                             |
+| ------------------------ | ------------------------------------ | ---------------- | ------------------------------------------- |
+| `actions.setVariant(v)`  | valid variant                        | `variant` = v    | `getCalloutProps()` updates `data-variant`  |
+| `actions.setVariant(v)`  | invalid variant                      | no change        | no effect                                   |
+| `actions.setClosable(v)` | any                                  | `closable` = v   | UIKit conditionally renders close button    |
+| `actions.close()`        | `closable` = `true`, `open` = `true` | `open` = `false` | UIKit hides callout; emits `cv-close` event |
+| `actions.close()`        | `closable` = `false`                 | no change        | no-op                                       |
+| `actions.close()`        | `open` = `false`                     | no change        | no-op                                       |
+| `actions.show()`         | `open` = `false`                     | `open` = `true`  | UIKit shows callout                         |
+| `actions.show()`         | `open` = `true`                      | no change        | no-op                                       |
+
+## Invariants
+
+1. `role` is always `'note'` on the root element — never changes regardless of variant or state.
+2. No `aria-live` or `aria-atomic` attributes are ever produced. Callout is not a live region.
+3. `variant` must always be one of `'info' | 'success' | 'warning' | 'danger' | 'neutral'`. Invalid values are rejected.
+4. `variant` defaults to `'info'` when not specified or when an invalid value is provided.
+5. `close` action is a no-op when `closable` is `false`.
+6. `getCloseButtonProps()` always returns the button attribute map, but UIKit must only render the button when `closable` is `true`.
+7. Callout must never produce `tabindex` or focus-related attributes on the root element.
+8. `open` defaults to `true` (callout is visible by default).
+
+## Adapter Expectations
+
+This section defines what UIKit (`cv-callout`) binds to from the headless model.
+
+### Signals read by adapter
+
+| Signal             | UIKit usage                                                          |
+| ------------------ | -------------------------------------------------------------------- |
+| `state.variant()`  | Maps to `variant` host attribute and CSS class for color theming     |
+| `state.closable()` | Determines whether the close button is rendered in the template      |
+| `state.open()`     | Controls visibility of the callout; maps to `open` attribute on host |
+
+### Actions called by adapter
+
+| Action                   | UIKit trigger                                                  |
+| ------------------------ | -------------------------------------------------------------- |
+| `actions.setVariant(v)`  | When `variant` attribute/property changes on the host element  |
+| `actions.setClosable(v)` | When `closable` attribute/property changes on the host element |
+| `actions.close()`        | When the close button is clicked; emits `cv-close` event       |
+| `actions.show()`         | When programmatically re-showing the callout                   |
+
+### Contracts spread by adapter
+
+| Contract                | Target element                               | Notes                                                         |
+| ----------------------- | -------------------------------------------- | ------------------------------------------------------------- |
+| `getCalloutProps()`     | Root callout element (`part="base"`)         | Spread as attributes; provides `id`, `role`, `data-variant`   |
+| `getCloseButtonProps()` | Close button element (`part="close-button"`) | Spread as attributes; only rendered when `closable` is `true` |
+
+### Options passed through from UIKit attributes
+
+| UIKit attribute | Headless option | Notes                                  |
+| --------------- | --------------- | -------------------------------------- |
+| `variant`       | `variant`       | String enum, defaults to `'info'`      |
+| `closable`      | `closable`      | Boolean attribute, defaults to `false` |
+| `open`          | `open`          | Boolean attribute, defaults to `true`  |
+
+## Minimum Test Matrix
+
+- default state: `variant='info'`, `closable=false`, `open=true`
+- `getCalloutProps()` returns `role='note'` and `data-variant` matching current variant
+- `getCalloutProps()` never includes `aria-live` or `aria-atomic`
+- `setVariant` updates variant signal; invalid values rejected
+- all five variant values are accepted: `info`, `success`, `warning`, `danger`, `neutral`
+- `close()` sets `open` to `false` when `closable` is `true`
+- `close()` is a no-op when `closable` is `false`
+- `show()` sets `open` to `true`
+- `getCloseButtonProps()` returns `role='button'`, `tabindex='0'`, `aria-label='Dismiss'`
+- clicking close button (calling `onClick` from props) triggers `close` action
+- callout never produces `tabindex` on root element
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Layering**: `core -> interactions -> a11y-contracts -> adapters`; adapters remain thin mappings.
+- **Independence**: No imports from `@project/*`, `apps/*`, or other out-of-package modules.
+- **Verification**: Mandatory adapter integration tests and standalone package test execution.
+
+## Out of Scope (Current)
+
+- Rich content slots (icon, title, description) — handled by UIKit template only
+- Collapsible/expandable content within the callout
+- Auto-dismiss timer (use `Alert` for time-sensitive announcements)
+- Live region behavior (use `Alert` for dynamic announcements)
+- Focus management on close (UIKit concern if needed)
+- Animation/transition on show/hide (UIKit/CSS concern)

package/specs/components/card.md

@@ -0,0 +1,280 @@
+# Card Component Contract
+
+## Purpose
+
+`Card` is a headless contract for a visual container that groups related content into a cohesive unit. It supports an optional expandable variant that follows the disclosure pattern: a trigger area (header) toggles the visibility of body content. When not expandable, the card is a simple non-interactive container with minimal ARIA semantics.
+
+## Component Files
+
+- `src/card/index.ts` - model and public `createCard` API
+- `src/card/card.test.ts` - unit behavior tests
+
+## Options (`CreateCardOptions`)
+
+| Option             | Type                            | Default     | Description                                                                    |
+| ------------------ | ------------------------------- | ----------- | ------------------------------------------------------------------------------ |
+| `idBase`           | `string`                        | `'card'`    | Base id prefix for generated ids                                               |
+| `isExpandable`     | `boolean`                       | `false`     | Whether the card has disclosure (expand/collapse) behavior                     |
+| `isExpanded`       | `boolean`                       | `false`     | Initial expanded state (only meaningful when `isExpandable` is `true`)         |
+| `isDisabled`       | `boolean`                       | `false`     | Whether interaction is blocked (only meaningful when `isExpandable` is `true`) |
+| `onExpandedChange` | `(isExpanded: boolean) => void` | `undefined` | Callback fired when expanded state changes                                     |
+
+## Public API
+
+### `createCard(options?: CreateCardOptions): CardModel`
+
+### State (signal-backed)
+
+| Signal         | Type            | Derived? | Description                                                                |
+| -------------- | --------------- | -------- | -------------------------------------------------------------------------- |
+| `isExpandable` | `Atom<boolean>` | No       | Whether the card has disclosure behavior                                   |
+| `isExpanded`   | `Atom<boolean>` | No       | Whether the card body content is visible (only meaningful when expandable) |
+| `isDisabled`   | `Atom<boolean>` | No       | Whether user interaction is blocked (only meaningful when expandable)      |
+
+### Actions
+
+| Action          | Signature                                                                       | Description                                                                         |
+| --------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `toggle`        | `() => void`                                                                    | Toggles expanded state; no-op when not expandable or disabled                       |
+| `expand`        | `() => void`                                                                    | Sets expanded to `true`; no-op when not expandable, disabled, or already expanded   |
+| `collapse`      | `() => void`                                                                    | Sets expanded to `false`; no-op when not expandable, disabled, or already collapsed |
+| `setDisabled`   | `(value: boolean) => void`                                                      | Updates the disabled state                                                          |
+| `handleClick`   | `() => void`                                                                    | Delegates to `toggle()`; intended for the trigger element                           |
+| `handleKeyDown` | `(event: Pick<KeyboardEvent, 'key'> & { preventDefault?: () => void }) => void` | Processes keyboard input on the trigger (see Keyboard Contract)                     |
+
+### Contracts
+
+| Contract            | Return Type        | Description                                                                              |
+| ------------------- | ------------------ | ---------------------------------------------------------------------------------------- |
+| `getCardProps()`    | `CardProps`        | Ready-to-spread ARIA attribute map for the card root element                             |
+| `getTriggerProps()` | `CardTriggerProps` | Ready-to-spread ARIA and event handler attribute map for the expandable trigger (header) |
+| `getContentProps()` | `CardContentProps` | Ready-to-spread ARIA attribute map for the expandable content region (body)              |
+
+## Contract Prop Shapes
+
+### `getCardProps()`
+
+**When `isExpandable` is `false` (static card):**
+
+```ts
+{
+  // No role, no interactive attributes — plain container
+}
+```
+
+**When `isExpandable` is `true`:**
+
+```ts
+{
+  // No role — the card root is a container; trigger and content carry the ARIA semantics
+}
+```
+
+The card root element does not carry interactive ARIA attributes in either mode. The expandable semantics are carried by the trigger and content sub-elements.
+
+### `getTriggerProps()`
+
+Only meaningful when `isExpandable` is `true`. When `isExpandable` is `false`, returns an empty object.
+
+**When `isExpandable` is `true`:**
+
+```ts
+{
+  id: string                          // '{idBase}-trigger'
+  role: 'button'
+  tabindex: '0' | '-1'               // '-1' when disabled
+  'aria-expanded': 'true' | 'false'  // reflects isExpanded
+  'aria-controls': string             // points to content region id
+  'aria-disabled'?: 'true'           // present only when disabled
+  onClick: () => void                 // calls handleClick
+  onKeyDown: (event) => void          // calls handleKeyDown
+}
+```
+
+### `getContentProps()`
+
+Only meaningful when `isExpandable` is `true`. When `isExpandable` is `false`, returns an empty object.
+
+**When `isExpandable` is `true`:**
+
+```ts
+{
+  id: string                          // '{idBase}-content'
+  role: 'region'
+  'aria-labelledby': string           // points to trigger id
+  hidden: boolean                     // !isExpanded
+}
+```
+
+## APG and A11y Contract
+
+### Static card (not expandable)
+
+- No role on the card root — it is a presentational grouping container
+- No keyboard interaction, no `tabindex`, no focus management
+- Content is always visible
+
+### Expandable card
+
+- Trigger: `role="button"` with `aria-expanded`, `aria-controls`, `tabindex`
+- Content region: `role="region"` with `aria-labelledby`, `hidden`
+- This follows the APG Disclosure (Show/Hide) pattern
+- Focus management:
+  - The trigger is in the page tab sequence (`tabindex: '0'`); removed from tab order when disabled (`tabindex: '-1'`)
+  - Focus remains on the trigger when toggled
+
+## Keyboard Contract
+
+Only applies when `isExpandable` is `true`. All keyboard actions are no-ops when `isDisabled` is `true`.
+
+| Key                        | Action                                                                |
+| -------------------------- | --------------------------------------------------------------------- |
+| `Enter`                    | Toggle the `isExpanded` state; calls `preventDefault`                 |
+| `Space`                    | Toggle the `isExpanded` state; calls `preventDefault`                 |
+| `ArrowDown` / `ArrowRight` | Expand (show content) if currently collapsed; calls `preventDefault`  |
+| `ArrowUp` / `ArrowLeft`    | Collapse (hide content) if currently expanded; calls `preventDefault` |
+
+## Behavior Contract
+
+- **Static Card**:
+  - Acts as a non-interactive container. No state transitions occur from user interaction.
+  - `toggle()`, `expand()`, `collapse()` are no-ops when `isExpandable` is `false`.
+  - `getTriggerProps()` and `getContentProps()` return empty objects.
+- **Expandable Card**:
+  - `Enter` or `Space` on the trigger toggles the `isExpanded` state.
+  - Clicking the trigger toggles the `isExpanded` state.
+  - `ArrowDown` or `ArrowRight` on the trigger opens the content (no-op if already expanded).
+  - `ArrowUp` or `ArrowLeft` on the trigger closes the content (no-op if already collapsed).
+  - When `isDisabled` is `true`, all user-driven interactions (click, keyboard) are no-ops.
+  - `setDisabled(value)` always updates the disabled state regardless of `isExpandable`.
+- **Linkage** (expandable only):
+  - `aria-controls` on the trigger matches the `id` of the content region.
+  - `aria-expanded` on the trigger reflects the `isExpanded` state.
+  - `aria-labelledby` on the content region matches the `id` of the trigger.
+
+## Transitions Table
+
+| Event / Action              | Guard                                            | Next State / Effect                                   |
+| --------------------------- | ------------------------------------------------ | ----------------------------------------------------- |
+| `toggle()`                  | `isExpandable && !isDisabled && !isExpanded`     | `isExpanded = true`; fires `onExpandedChange(true)`   |
+| `toggle()`                  | `isExpandable && !isDisabled && isExpanded`      | `isExpanded = false`; fires `onExpandedChange(false)` |
+| `toggle()`                  | `!isExpandable \|\| isDisabled`                  | no-op                                                 |
+| `expand()`                  | `isExpandable && !isDisabled && !isExpanded`     | `isExpanded = true`; fires `onExpandedChange(true)`   |
+| `expand()`                  | `!isExpandable \|\| isDisabled \|\| isExpanded`  | no-op                                                 |
+| `collapse()`                | `isExpandable && !isDisabled && isExpanded`      | `isExpanded = false`; fires `onExpandedChange(false)` |
+| `collapse()`                | `!isExpandable \|\| isDisabled \|\| !isExpanded` | no-op                                                 |
+| `handleClick()`             | any                                              | delegates to `toggle()`                               |
+| `handleKeyDown(Enter)`      | `isExpandable && !isDisabled`                    | delegates to `toggle()`; `preventDefault`             |
+| `handleKeyDown(Space)`      | `isExpandable && !isDisabled`                    | delegates to `toggle()`; `preventDefault`             |
+| `handleKeyDown(ArrowDown)`  | `isExpandable && !isDisabled && !isExpanded`     | delegates to `expand()`; `preventDefault`             |
+| `handleKeyDown(ArrowRight)` | `isExpandable && !isDisabled && !isExpanded`     | delegates to `expand()`; `preventDefault`             |
+| `handleKeyDown(ArrowDown)`  | `isExpandable && !isDisabled && isExpanded`      | no-op (already expanded); `preventDefault`            |
+| `handleKeyDown(ArrowRight)` | `isExpandable && !isDisabled && isExpanded`      | no-op (already expanded); `preventDefault`            |
+| `handleKeyDown(ArrowUp)`    | `isExpandable && !isDisabled && isExpanded`      | delegates to `collapse()`; `preventDefault`           |
+| `handleKeyDown(ArrowLeft)`  | `isExpandable && !isDisabled && isExpanded`      | delegates to `collapse()`; `preventDefault`           |
+| `handleKeyDown(ArrowUp)`    | `isExpandable && !isDisabled && !isExpanded`     | no-op (already collapsed); `preventDefault`           |
+| `handleKeyDown(ArrowLeft)`  | `isExpandable && !isDisabled && !isExpanded`     | no-op (already collapsed); `preventDefault`           |
+| `handleKeyDown(other)`      | any                                              | no-op; no `preventDefault`                            |
+| `handleKeyDown(any)`        | `!isExpandable \|\| isDisabled`                  | no-op; no `preventDefault`                            |
+| `setDisabled(value)`        | any                                              | `isDisabled = value`                                  |
+
+## Invariants
+
+1. `isExpandable`, `isExpanded`, and `isDisabled` are booleans.
+2. When `isExpandable` is `false`, `getTriggerProps()` and `getContentProps()` return empty objects (no ARIA attributes, no event handlers).
+3. When `isExpandable` is `false`, `toggle()`, `expand()`, and `collapse()` are no-ops.
+4. When `isExpandable` is `true`, `aria-expanded` on the trigger is `"true"` when `isExpanded` is `true`, and `"false"` otherwise.
+5. When `isExpandable` is `true`, `aria-controls` on the trigger always matches the `id` of the content region.
+6. When `isExpandable` is `true`, `aria-labelledby` on the content region always matches the `id` of the trigger.
+7. When `isDisabled` is `true`, user-driven interactions (`handleClick`, `handleKeyDown`) do not change `isExpanded`.
+8. Arrow keys (`ArrowDown`/`ArrowRight`) only expand; they never collapse. Arrow keys (`ArrowUp`/`ArrowLeft`) only collapse; they never expand.
+9. `getCardProps()` never produces interactive attributes (`tabindex`, keyboard handlers, `aria-expanded`). Interactive semantics live on the trigger.
+10. `onExpandedChange` is only called when `isExpanded` actually changes value, never on no-op actions.
+
+## Adapter Expectations
+
+This section defines what UIKit (`cv-card`) binds to from the headless model.
+
+### Signals read by adapter
+
+| Signal                 | UIKit usage                                                                                              |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| `state.isExpandable()` | Determines whether to render the trigger and toggle content visibility; sets `expandable` host attribute |
+| `state.isExpanded()`   | Reflects expanded state on host; controls content region visibility                                      |
+| `state.isDisabled()`   | Reflects disabled state on host; prevents interaction                                                    |
+
+### Actions called by adapter
+
+| Action                     | UIKit trigger                                                                |
+| -------------------------- | ---------------------------------------------------------------------------- |
+| `actions.toggle()`         | Programmatic toggle (e.g., from imperative `toggle()` method on element)     |
+| `actions.expand()`         | Programmatic expand (e.g., from imperative `expand()` method on element)     |
+| `actions.collapse()`       | Programmatic collapse (e.g., from imperative `collapse()` method on element) |
+| `actions.setDisabled(v)`   | When `disabled` attribute/property changes on the host element               |
+| `actions.handleClick()`    | Not called directly by adapter; included in `getTriggerProps()` spread       |
+| `actions.handleKeyDown(e)` | Not called directly by adapter; included in `getTriggerProps()` spread       |
+
+### Contracts spread by adapter
+
+| Contract            | Target element                           | Notes                                                                                                                                                                |
+| ------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getCardProps()`    | Card root element (`part="base"`)        | Spread as attributes on the outermost container                                                                                                                      |
+| `getTriggerProps()` | Header/trigger element (`part="header"`) | Spread onto the clickable header area; provides `role`, `aria-expanded`, `aria-controls`, `tabindex`, and event handlers. Only spread when `isExpandable` is `true`. |
+| `getContentProps()` | Body/content element (`part="body"`)     | Spread onto the content region; provides `id`, `role="region"`, `aria-labelledby`, `hidden`. Only spread when `isExpandable` is `true`.                              |
+
+### Options passed through from UIKit attributes
+
+| UIKit attribute | Headless option | Notes                                          |
+| --------------- | --------------- | ---------------------------------------------- |
+| `expandable`    | `isExpandable`  | Boolean attribute; enables disclosure behavior |
+| `expanded`      | `isExpanded`    | Boolean attribute; initial expanded state      |
+| `disabled`      | `isDisabled`    | Boolean attribute; prevents interaction        |
+
+### UIKit-only concerns (NOT in headless)
+
+- Visual variants (`elevated`, `outlined`, `filled`) are CSS-only; no headless state
+- Slot layout (`header`, `(default)`, `footer`, `image`) is a rendering concern
+- CSS animations for expand/collapse transitions
+- Lifecycle events (`cv-expand`, `cv-collapse`)
+- Imperative methods (`toggle()`, `expand()`, `collapse()`) that delegate to headless actions
+
+## Minimum Test Matrix
+
+- default state: `isExpandable = false`, `isExpanded = false`, `isDisabled = false`
+- static card: `getCardProps()` returns empty or minimal object (no interactive attributes)
+- static card: `getTriggerProps()` returns empty object
+- static card: `getContentProps()` returns empty object
+- static card: `toggle()`, `expand()`, `collapse()` are no-ops; `isExpanded` does not change
+- expandable card: `toggle()` toggles `isExpanded` between `true` and `false`
+- expandable card: `expand()` sets `isExpanded` to `true`; no-op if already expanded
+- expandable card: `collapse()` sets `isExpanded` to `false`; no-op if already collapsed
+- expandable card: `handleKeyDown(Enter)` toggles expanded state; calls `preventDefault`
+- expandable card: `handleKeyDown(Space)` toggles expanded state; calls `preventDefault`
+- expandable card: `ArrowDown` / `ArrowRight` expand a collapsed card; no-op on expanded card
+- expandable card: `ArrowUp` / `ArrowLeft` collapse an expanded card; no-op on collapsed card
+- expandable card: arrow keys call `preventDefault`
+- expandable card: all keyboard/click interactions are no-ops when disabled
+- expandable card: `aria-expanded` on trigger reflects `isExpanded`
+- expandable card: `aria-controls` on trigger matches content region `id`
+- expandable card: `aria-labelledby` on content matches trigger `id`
+- expandable card: content region has `hidden = true` when collapsed
+- expandable card: disabled trigger has `tabindex = '-1'` and `aria-disabled = 'true'`
+- `onExpandedChange` fires on actual state transitions, not on no-ops
+- `setDisabled(value)` updates disabled state regardless of expandable mode
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Layering**: `core -> interactions -> a11y-contracts -> adapters`; adapters remain thin mappings.
+- **Independence**: No imports from `@project/*`, `apps/*`, or other out-of-package modules.
+- **Verification**: Mandatory adapter integration tests and standalone package test execution.
+
+## Out of Scope (Current)
+
+- visual variants (`elevated`, `outlined`, `filled`) are UIKit/CSS-only concerns
+- sizes (card is a fluid container; no size state)
+- slot layout and image positioning (rendering concern)
+- clickable/linkable card (entire card as an anchor) — would require a separate interactive pattern
+- card groups, card grids, or masonry layouts
+- animation orchestration for expand/collapse (handled by UIKit visual layer)
+- drag-and-drop reordering of cards