An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): Card records its shipped contract as current (#8757)
Cindy Zhangdaab0b6e2f55
diff --git a/packages/core/src/Card/Card.spec.md b/packages/core/src/Card/Card.spec.mdnew file mode 100644index 0000000000..2e27cdb648--- /dev/null+++ b/packages/core/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.