@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/ButtonGroup/ButtonGroup.spec.md

@@ -0,0 +1,220 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:ButtonGroup
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-25
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/ButtonGroup/ButtonGroup.test.tsx,
+    packages/core/src/Layer/layerScopedContext.test.tsx,
+    packages/core/src/hooks/useListFocus.test.tsx,
+  ]
+modules: []
+families: [family:buttons]
+design_specs: []
+architecture:
+  [
+    architecture:component-size-cascade,
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-038, spec:AST-085]
+---
+
+# ButtonGroup component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                      |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes. ButtonGroup takes `label`, `orientation`, `size`, `elevation`, `isDisabled`, and Button or IconButton children.                                                                                                                 |
+| Behavior                | A labelled `role="group"` that joins its Button members into one connected surface, gives them a default size and its disabled state, owns one shared elevation, and is one Tab stop with arrow-key roving.                                   |
+| End-user impact         | Keyboard users reach the whole group with one Tab and move through it with arrows, which skip disabled members. A disabled group without tooltips has no Tab stop, so keyboard users cannot find it or hear that it is disabled.              |
+| Builder impact          | None.                                                                                                                                                                                                                                         |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Disabled members use native `disabled`, the Tab stop leaves disabled and busy-only members, and wrapped members lose connected geometry; all are listed under Current-state impact. |
+| Review checks           | Reject a group without a name, gaps between members, rounded inner corners, a shadow on a member, more than one Tab stop, arrows that land on a disabled member, or arrows that steal keys from a member's open menu.                         |
+| Governing rules         | `family:buttons` FR3, FR8, FR10–FR12, AV5; `architecture:component-size-cascade` INV3–INV8; `spec:AST-085` FR1, FR7; `spec:AST-038` FR7, FR8.                                                                                                 |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ButtonGroup presents a few related actions as one connected control. It owns
+the group's accessible name, connected geometry, shared elevation, inherited
+size and disabled state, and the group's single-Tab-stop keyboard model, as
+`family:buttons` assigns. Consumer usage lives in `ButtonGroup.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; `orientation="horizontal"`, `size="md"`,
+  `elevation="none"`, `isDisabled={false}`
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The group root: role, accessible name, orientation and disabled exposure, and
+  the `button-group` target.
+- Connected geometry its Button members paint: outer-only corners, leading-edge
+  dividers, and no press scale.
+- One shared resting elevation, and flat members.
+- The default size and disabled state it gives its members.
+- Roving focus: one Tab stop, arrow keys, Home and End.
+
+**Does not own / non-goals**
+
+- Each member's own surface, naming, activation, pending, and disabled rendering
+  — owned by `component:Button` and `component:IconButton`. A press that slides across
+  members acts on the lifted member, as `family:action-groups` owns.
+- A member's menu or other layer, and keys pressed inside it — owned by that
+  member (for example `component:DropdownMenu`).
+- Selection state across toggles — owned by `component:ToggleButtonGroup`.
+- Horizontal overflow — uncontracted; the group does not wrap or collapse.
+- Nested ButtonGroups — unsupported; behavior is uncontracted.
+
+## Public concepts
+
+| Concept     | Closed values or states      | Meaning                                   | Availability by variant/orientation/state | Default                   | Owner                   | Stability | Invalid-value behavior           |
+| ----------- | ---------------------------- | ----------------------------------------- | ----------------------------------------- | ------------------------- | ----------------------- | --------- | -------------------------------- |
+| Orientation | `horizontal`, `vertical`     | Direction of the row and of arrow keys.   | Always.                                   | `horizontal`              | `component:ButtonGroup` | Stable    | TypeScript rejects other values. |
+| Size        | `sm`, `md`, `lg`             | Default size for members.                 | Always; a member's own `size` wins.       | Inherited size, else `md` | `family:buttons`        | Stable    | TypeScript rejects other values. |
+| Elevation   | `none`, `low`, `med`, `high` | Shadow under the whole connected surface. | Always; members paint none.               | `none`                    | `family:buttons`        | Stable    | TypeScript rejects other values. |
+| Disabled    | off, on                      | Every Button member is disabled.          | Always.                                   | off                       | `component:ButtonGroup` | Stable    | Not applicable.                  |
+
+## Behavioral and layout contract
+
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Basis                                                                               |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| FR1  | The root is one element with `role="group"` and `aria-label` set to `label`. It reflects orientation as `data-orientation`, never `aria-orientation`, and sets `aria-disabled="true"` only while disabled. `ref`, `data-testid`, `className`, `style`, `xstyle`, and other DOM props reach it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `family:buttons` FR11; current source and tests                                     |
+| FR2  | Members sit edge to edge with no gap, stretched across the cross axis: a row when horizontal, a column when vertical.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `family:buttons` FR12; current source                                               |
+| FR3  | Group geometry is painted by Astryx Button members; other children keep their own paint. Only the group's outer corners are rounded: the first member's leading corners and the last member's trailing corners. A trailing layer element a member renders after itself (popover, template, or dialog) does not count as a member, so the real last member keeps its rounded corners. Any other following element, including a display-contents wrapper or a raw button, counts as a member. A Button member wrapped in a Tooltip or HoverCard MUST join the connected surface like a direct member (`family:buttons` FR12). Implementation gap: inside that display-contents wrapper the Button is both the first and the last child, so in a group of two or more it keeps all four corners rounded wherever it sits, and draws no divider when it is not first.                                                                                        | `family:buttons` FR12; current tests                                                |
+| FR4  | Every Button member after the first draws a divider on its leading edge (inline-start when horizontal, block-start when vertical) in the border color, or in the on-accent color on a primary or destructive member; a wrapped member does not (FR3 gap). Members do not take Button's press scale.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `family:buttons` FR12; current source                                               |
+| FR5  | The group paints the shadow for its `elevation`, following the element radius. Every Button member paints no shadow and reflects `data-elevation="none"`, whatever its own `elevation` says.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `family:buttons` FR8, FR10; current tests                                           |
+| FR6  | The group provides its resolved size to descendants up to the next layer boundary (`spec:AST-038` FR7, FR8): an explicit `size`, then the nearest outer provider, then `md`. A member's own `size` wins.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `architecture:component-size-cascade` INV3–INV8; current source; `spec:AST-038` FR7 |
+| FR7  | While disabled, every Button member MUST be disabled under `component:Button` FR10: focusable with `aria-disabled`, inert, and never running its action, so the group keeps its Tab stop (`spec:AST-085` FR1, FR7). Implementation gap: members without a tooltip render native `disabled`, so a disabled group contributes no Tab stop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `family:buttons` FR3; `spec:AST-085` FR7; current tests                             |
+| FR8  | The group is one Tab stop. The stop starts on the first enabled member and moves with arrow navigation. A link member counts as a member. The stop MUST always sit on exactly one member, and a member that becomes busy or disabled MUST keep it (`component:Button` FR9, FR10; `spec:AST-085` FR1, FR7). Implementation gap: the group repairs the stop only after its own renders and when focus enters a member, and each repair keeps an enabled holder or gives the stop to the first enabled member. Between repairs the stop can sit on a member that has become busy-only, disabled, or unmounted, so the group can have a second stop or none; focus that arrives by pointer or by code does not take the stop, so the next Tab or Shift+Tab can stop inside the group; and a fully disabled group repairs nothing, so a group disabled from its first render gives each tooltip-bearing member its own stop and native-disabled members none. | `family:buttons` AV5; WAI-ARIA APG roving tabindex; current tests                   |
+| FR9  | Horizontal groups move with Left and Right in visual order, reversed under RTL; vertical groups move with Up and Down. Home and End jump to the first and last enabled member. Movement wraps at the ends and skips natively disabled and `aria-disabled` members, busy-only members (`component:Button` FR9) included; a member busy with an interruptible action stays in the order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `family:buttons` AV5; current tests                                                 |
+| FR10 | Keys pressed inside a member's open layer (such as a DropdownMenu) belong to that layer, and the group keeps its Tab stop on its own members. A group inside a popover or other layer still handles its own arrow keys. The group's context does not reach Buttons rendered inside a member's layer (`spec:AST-038` FR7).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Current source and tests; `spec:AST-038` FR7                                        |
+| FR11 | The root carries `astryx-button-group` and reflects `data-size`, `data-orientation`, and `data-elevation`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `family:buttons` FR10; `architecture:component-theming-surface`; tests              |
+
+### Allowed variation
+
+- **AV1 — Members.** Button, IconButton, and a Button-triggered DropdownMenu are
+  supported members; variants may differ between members.
+- **AV2 — Theme paint.** Themes may restyle the group and member surfaces
+  through `button-group` and `button` without changing connected geometry.
+
+### Representative states
+
+| State                 | Required invariant                                                                                                                                                                                                                | Allowed variation       |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| Horizontal, at rest   | Named group; one Tab stop on the first member; outer corners only.                                                                                                                                                                | Member variants.        |
+| Vertical              | Column; Up and Down move focus; block-start dividers.                                                                                                                                                                             | —                       |
+| Elevated              | Shadow on the group; members flat.                                                                                                                                                                                                | Tier.                   |
+| Trailing DropdownMenu | The menu trigger keeps rounded trailing corners; arrows inside the open menu stay with it.                                                                                                                                        | Menu content.           |
+| One member disabled   | Arrows skip it. Implementation gap: the Tab stop leaves it when the group repairs (FR8).                                                                                                                                          | Tooltip present or not. |
+| Group disabled        | `aria-disabled` on the group; every member focusable and inert; one Tab stop. Implementation gap: native-disabled members give no Tab stop; disabled from the first render, tooltip-bearing members are one stop each (FR7, FR8). | —                       |
+
+### Transformation and precedence order
+
+- **ORD1 — Member size.** Member `size`, then the group's resolved size.
+- **ORD2 — Member elevation.** Inside a group, always `none`; the group's
+  `elevation` paints.
+- **ORD3 — Member availability.** A member is disabled when the group or the
+  member is disabled; neither can re-enable the other. Otherwise Button's own
+  availability rules apply.
+
+### Performance and resources
+
+- **PR1 — Tab-stop repair.** The group repairs the Tab stop after each of its
+  own renders and when focus enters a member; it adds no global listener
+  beyond the press tracking `family:action-groups` FR5 gives it.
+
+## Accessibility contract
+
+- **AR1 — Group name.** The group exposes `role="group"` and its `label` as
+  its accessible name; members keep their own names (`family:buttons` FR11).
+- **AR2 — Keyboard.** FR8–FR10 are the keyboard contract.
+- **AR3 — Disabled exposure.** A disabled group exposes `aria-disabled` on the
+  group; members expose disabled per `component:Button` AR5 (FR7 gap).
+- **AR4 — Focus indicator.** Each member paints Button's focus indicator.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                    | Representation authority | Hierarchy role | Component contract |
+| ---------------- | --------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Button           | Members joined into one surface with outer-only corners.              | Current source and tests | Prominent      | FR2, FR3           |
+| Divider          | Thin leading-edge border between members; on-accent on solid members. | Current source           | Supporting     | FR4                |
+| Group shadow     | One shadow under the connected surface.                               | Current source and tests | Supporting     | FR5                |
+
+No design record governs ButtonGroup. The root carries the `button-group`
+target; the Button and Divider anatomy parts are painted by each member's
+`button` target. The consumer anatomy names no root part, so this record
+carries no anatomy-theming map.
+
+## Family and system relationships
+
+- `family:buttons` assigns ButtonGroup connected geometry, roving focus,
+  inherited size and disabled state, and one shared elevation (FR8, FR11,
+  FR12); ButtonGroup adopts them.
+- `component:Button` paints the connected geometry from the group's context
+  and owns each member's behavior.
+- `architecture:component-size-cascade` owns size inheritance (FR6).
+- `spec:AST-085` FR7 applies to group disablement; the gap is FR7 here.
+
+## Verification map
+
+| Contract             | Verification                                                                                                                                                                                                                                                                                       | Representative states                                               | Mutation or failure expectation                                                                                                                                                                                                                                               | Audit section                     |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1, AR1             | `ButtonGroup.test.tsx` role, label, ref, `data-testid`, orientation                                                                                                                                                                                                                                | Horizontal and vertical                                             | A missing name, `aria-orientation`, a dropped ref, or a dropped `data-testid` fails. Evidence gap: no test passes `className`, `style`, or `xstyle`.                                                                                                                          | `audit:ButtonGroup/accessibility` |
+| FR3                  | `ButtonGroup.test.tsx` trailing-radius suite                                                                                                                                                                                                                                                       | Tooltip, link, DropdownMenu, HoverCard, and raw-button members      | A square trailing member, or a rounded inner member, fails. Evidence gap: the suite renders wrapped members only last and asserts the member before them; no test checks a wrapped member's own corners or divider in any position.                                           | `audit:ButtonGroup/layout`        |
+| FR5, FR11            | `ButtonGroup.test.tsx` elevation suite                                                                                                                                                                                                                                                             | Every tier; member with its own elevation                           | Identical classes for two tiers, a mismatched `data-elevation`, or a member not reporting `none` fails.                                                                                                                                                                       | `audit:ButtonGroup/theming`       |
+| FR11 (target, size)  | Evidence gap: no test asserts `astryx-button-group` or `data-size` on the root                                                                                                                                                                                                                     | Each size                                                           | —                                                                                                                                                                                                                                                                             | `audit:ButtonGroup/theming`       |
+| FR7, AR3             | `ButtonGroup.test.tsx` disabled cases                                                                                                                                                                                                                                                              | Group disabled                                                      | An operable member fails. Native-disabled and no-Tab-stop assertions match the FR7 gap.                                                                                                                                                                                       | `audit:ButtonGroup/accessibility` |
+| FR8, AR2             | `ButtonGroup.test.tsx` roving-tabindex suite                                                                                                                                                                                                                                                       | Enter and leave; disabled member; unmount; becomes disabled; link   | Two Tab stops or a lost stop fails. The suite asserts that a disabled member never holds the stop and that the stop is repaired away from it, matching the FR8 gap. Evidence gap: no test of a busy or self-unmounted holder, pointer focus, or a group disabled after mount. | `audit:ButtonGroup/accessibility` |
+| FR9, FR10, AR2       | `ButtonGroup.test.tsx` keyboard-navigation suite; `useListFocus.test.tsx` "useListFocus disabled-item skipping" for `aria-disabled` items and Home and End; `layerScopedContext.test.tsx` "ends group-owned disabled state while preserving explicit and inner-group state" for the layer boundary | Arrows, Home, End, vertical, RTL, open menu, group inside a popover | Wrong direction, no wrap, landing on a disabled member, stealing a menu's keys, or group state leaking into a member's layer fails. Evidence gap: no test skips a busy or tooltip-disabled Button member.                                                                     | `audit:ButtonGroup/accessibility` |
+| FR2, FR3, FR4, FR6   | Evidence gap: no assertion of gap-free layout, divider paint, the absent press scale, non-Button children keeping their own paint, or member size inheritance beyond rendering                                                                                                                     | —                                                                   | —                                                                                                                                                                                                                                                                             | `audit:ButtonGroup/layout`        |
+| ORD2                 | `ButtonGroup.test.tsx` elevation suite                                                                                                                                                                                                                                                             | Member with its own elevation                                       | A member not reporting `none` fails.                                                                                                                                                                                                                                          | `audit:ButtonGroup/theming`       |
+| ORD1, ORD3, PR1, AR4 | Evidence gap: no test asserts member size precedence, a member `isDisabled` inside an enabled group, when the Tab stop is repaired, or the member focus indicator                                                                                                                                  | —                                                                   | —                                                                                                                                                                                                                                                                             | `audit:ButtonGroup/behavior`      |
+
+## Current-state impact
+
+- **Disabled focusability (FR7, AR3).** A disabled group renders its members
+  with native `disabled`, so the group has no Tab stop, against `spec:AST-085`
+  FR1 and FR7 and `family:buttons` FR3. The group's tests assert that state.
+- **Tab stop (FR8).** The Tab stop leaves a disabled or busy-only member when the
+  group repairs it; between repairs the group can have a second stop or none,
+  including after a pointer click on a member or when the holder unmounts or
+  disables itself; and a group disabled from its first render gives each
+  tooltip-bearing member its own stop, against `spec:AST-085` FR1 and FR7.
+- **Wrapped members (FR3, FR4).** A Button wrapped in a Tooltip or HoverCard
+  keeps four rounded corners in any position, and no divider when it is not
+  first, against
+  `family:buttons` FR12.
+
+## Decision log
+
+No component-local decision. ButtonGroup applies `family:buttons`.
+
+## 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/Calendar/__tests__/Calendar.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(internal/a11y-spec/src/patterns/grid|internal/a11y-spec/src/harness|packages/core/src/Calendar/|packages/core/src/hooks/useGridFocus|apps/storybook/stories/CalendarGridA11y)
 
 /**
  * @file Calendar.a11y.chromium.spec.ts

package/src/Card/Card.spec.md

@@ -0,0 +1,205 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Card
+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:
+  [
+    .github/visual-baseline/manifest.json,
+    packages/core/src/Card/Card.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    packages/core/src/theme/extensibleAxes.test.ts,
+    apps/storybook/stories/Card.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:container-padding,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Card component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                 |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | A container with sizing props, `padding` on the spacing scale, a theme-extensible `variant`, and a resting `elevation`.                                                                                  |
+| Behavior                | Card paints a rounded surface, publishes its padding to descendants through the container-padding protocol, and only the `default` variant draws a border.                                               |
+| End-user impact         | Readers see grouped content on a consistent surface; with the default border and theme border width, content insets stay on the spacing scale whether or not a border is drawn, except at zero padding.  |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                             |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.                                                                  |
+| Review checks           | Reject a card that holds its track at min-content width, a variant that falls through to another variant, a lost padding publication, or a published inset that drifts further from the applied padding. |
+| Governing rules         | `architecture:container-padding` (container publisher); `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`.                                         |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Card groups related content on a contained surface. It owns the surface's
+paint, border, radius, and elevation, its sizing, and the padding it publishes
+so Layout and other descendants align to it.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Published inset exceeds applied padding (FR3).** At nonzero padding a
+  `default` card applies padding reduced by its border width but publishes
+  border plus padding (at `padding={0}` the two match). Every child that bleeds
+  to the published inset, on any edge — a full-bleed Divider, a Layout, or a
+  List `outset` or `bleed` box — overshoots the padding edge by the border
+  width. A fixed-height card holding such a child scrolls by that amount on
+  each axis the child bleeds on (both for a Layout) and becomes an unnamed tab
+  stop even when its content fits: in Chromium when it holds nothing
+  focusable, in Firefox even when it holds a focusable child. `architecture:container-padding` INV11
+  has a host publish its applied padding, and `component:List` FR8 counts a
+  Card's content area as such a host, so a `default` card at nonzero padding
+  does not yet meet List FR8: List `outset` and `bleed` lists cross its padding edge by the border width, and `bleed` rows with them.
+
+## Ownership boundary
+
+**Owns**
+
+- The Container: surface paint, border, radius, elevation, sizing, and
+  clipping.
+- Resolving and publishing card padding as a container publisher.
+
+**Does not own / non-goals**
+
+- Content structure inside the card — owned by the caller and Layout.
+- Interaction — owned by `component:ClickableCard` and
+  `component:SelectableCard`, which compose Card.
+- The padding protocol itself — owned by `architecture:container-padding`.
+
+## Public concepts
+
+| Concept   | Closed values or states                                                                                                                  | Meaning                                                 | Availability by variant/orientation/state | Default            | Owner            | Stability | Invalid-value behavior                                                                              |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------- | ------------------ | ---------------- | --------- | --------------------------------------------------------------------------------------------------- |
+| Variant   | `default`, `transparent`, `muted`, `blue`, `cyan`, `gray`, `green`, `orange`, `pink`, `purple`, `red`, `teal`, `yellow`; theme additions | Surface paint; only `default` draws a border.           | Always                                    | `default`          | `component:Card` | Stable    | A theme-added value is reflected on `card` and renders the base surface with no fill and no border. |
+| Elevation | `none`, `low`, `med`, `high`                                                                                                             | Resting shadow from the shadow token scale.             | Always                                    | `none`             | `component:Card` | Stable    | TypeScript rejects other values.                                                                    |
+| Padding   | Spacing steps 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10; omitted                                                                              | Uniform padding; omitted uses the theme's card padding. | Always                                    | theme card padding | `component:Card` | Stable    | TypeScript rejects other values.                                                                    |
+| Sizing    | `width`, `height`, `maxWidth`, `minHeight`: numbers in pixels or CSS strings                                                             | The card's box size.                                    | Always                                    | unset              | `component:Card` | Stable    | Strings pass through as CSS.                                                                        |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Basis                    |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | Card renders one `div` carrying the `card` target, which reflects `variant` and `elevation`, with `--radius-container` corners and a box shadow composed of the selection ring and the elevation shadow.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests |
+| FR2 | `default` paints `--color-background-card` with a `--border-width` solid `--color-border` border; `transparent` paints nothing; `muted` paints `--color-background-muted`; each palette variant paints its `--color-background-<name>` tint. A theme-added variant falls through to the base surface, never to another variant.                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
+| FR3 | Card resolves padding as a container publisher: an omitted `padding` uses the theme's card padding (spacing step 4 with no theme), and a step applies uniformly to every edge. With the `default` border, each edge's padding is reduced by the global `--border-width` token (stopping at zero), so border plus padding matches the borderless inset. The published inset matches the padding the card applies (`architecture:container-padding` INV11). Implementation gap: at nonzero padding a `default` card publishes border plus padding, one border width more than its applied padding, so a full-bleed child overshoots the padding edge, a fixed-height card scrolls by that width, and the card does not yet meet `component:List` FR8 (Current-state impact). | Current source and tests |
+| FR4 | Card has zero minimum width, so it yields to its track instead of holding it at its min-content width, and clips overflow without becoming a scroll container. A `height` other than `auto` makes it scroll. `width`, `height`, `maxWidth`, and `minHeight` apply as given, and a caller minimum can win over `width`.                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests |
+| FR5 | `elevation` sets the elevation shadow to none or the low, medium, or high shadow token.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests |
+| FR6 | `ref` reaches the `div`. Supported DOM, ARIA, data, and event props reach the element carrying the target; `xstyle`, `className`, and `style` merge in that order after component styles, and a caller `className` joins the target class rather than replacing it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Theme paint and padding.** A theme may restyle `card` per `variant`
+  and `elevation`, including border width and color, and set the card padding.
+- **AV2 — Content.** Any content may fill the card.
+
+### Representative states
+
+| State               | Required invariant                                                                                 | Allowed variation |
+| ------------------- | -------------------------------------------------------------------------------------------------- | ----------------- |
+| Default             | Card surface with border; inset equals the theme card padding.                                     | Content.          |
+| Borderless variant  | No border; same inset as `default` except at `padding={0}`, where `default` adds its border width. | Variant.          |
+| Theme-added variant | Base surface; `data-variant` names the added value.                                                | Theme paint.      |
+| Fixed height        | Scrolls its content; still yields in its track.                                                    | Height.           |
+| Elevated            | Elevation shadow alongside any ring.                                                               | Elevation.        |
+
+### Transformation and precedence order
+
+- **ORD1 — Padding.** `padding` step → theme card padding → spacing step 4;
+  then subtract the border width per edge for `default`, stopping at zero.
+- **ORD2 — Shadow.** Ring and elevation compose in one shadow list; neither
+  replaces the other.
+
+### Performance and resources
+
+- **PR1 — Static render.** Card holds no state and uses no hooks.
+
+## Accessibility contract
+
+- **AR1 — No semantics added.** Card adds no role, name, or tab stop of its own;
+  its content's semantics pass through. Exception: a fixed-height card whose
+  content overflows is a scroll container (FR4), and browsers may make it an
+  unnamed tab stop so keyboard users can scroll it (Chromium when it holds
+  nothing focusable; Firefox even when it holds a focusable child).
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                           | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------ | ------------------------ | -------------- | ------------------ |
+| Container        | A rounded surface with background, optional border, padding. | Current source and docs  | Supporting     | FR1–FR5            |
+| Content          | Caller content inside the published inset.                   | Current source and docs  | Prominent      | FR3, AR1           |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Container": {"target": "card"},
+  "Content": {
+    "none": {
+      "reason": "intentional: caller content keeps its own styling and has no component-owned paint target"
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- `architecture:container-padding` names Card a container publisher; FR3 records
+  how Card resolves and publishes its padding.
+- `component:ClickableCard` and `component:SelectableCard` compose Card; a
+  selection ring composes with Card's elevation shadow (ORD2).
+- `architecture:component-theming-surface` sets the rules the `card` target
+  follows (INV6) and qualifies `variant` as a theme-extensible axis (INV14).
+
+## Verification map
+
+| Contract            | Verification                                                                                                                                                                            | Representative states                                         | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                  | Audit section         |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| FR1, FR2, FR5, ORD2 | `Card.test.tsx` reflection, built-in variant, elevation, and theme-added variant tests; stable visual baselines `core-card--default` and `core-card--theme-added-variant` (probe theme) | Every built-in variant; elevations; added value; default card | A lost reflection, an elevation without its own class, or a theme-added value falling through to another variant fails; a changed default surface, border, radius, or rest shadow, or a theme-added card that loses its theme paint, comes back changed for review. Gap: the palette tints, the elevation shadow values, and the ring-and-shadow composition have no automated check beyond those two baselines. | `audit:Card/theming`  |
+| FR3                 | `Card.stories.tsx` in a browser                                                                                                                                                         | Default and borderless variants; padding steps                | Gap: no unit test asserts padding publication or the border subtraction; an inset mismatch is visible only in the rendered fixture. The full-bleed overshoot in a default card has no automated check.                                                                                                                                                                                                           | `audit:Card/layout`   |
+| FR4                 | `Card.test.tsx` sizing suite                                                                                                                                                            | Every variant; fixed height; caller minimum                   | A held min-content width, a scroll container without fixed height, or a lost caller minimum fails.                                                                                                                                                                                                                                                                                                               | `audit:Card/layout`   |
+| FR6                 | `Card.test.tsx` ref, passthrough, and className tests                                                                                                                                   | Ref; extra props; className                                   | A ref on another element, a prop on an element other than the target, or a replaced target class fails. Gap: no test asserts the `xstyle`, `className`, `style` merge order.                                                                                                                                                                                                                                     | `audit:Card/behavior` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                           | Consumer anatomy and current target                           | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                    | `audit:Card/theming`  |
+| AR1, PR1            | Source review                                                                                                                                                                           | Every variant                                                 | Gap: no automated check fails if Card adds a role, tab stop, state, or hook. No test covers the fixed-height overflow tab stop, with or without focusable content. No test covers the tab stop a fixed-height default card gains from a bleeding child's overshoot.                                                                                                                                              | `audit:Card/behavior` |
+
+## 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.

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

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(internal/a11y-spec/src/patterns/carousel|packages/core/src/Carousel/|apps/storybook/stories/CarouselA11y)
 
 /**
  * @file Carousel.a11y.chromium.spec.ts