@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Card/Card.module.scss

@@ -0,0 +1,264 @@
+@use './Card.tokens';
+
+.card {
+  background: var(--card-bg);
+  border: var(--border-width) solid var(--card-border-color);
+  border-radius: var(--card-radius);
+  box-shadow: var(--card-shadow);
+
+  // Default: clip children to the rounded border so square-cornered content
+  // (Tables with internal scrollWrap, images, full-bleed media) doesn't show
+  // a seam at the Card's rounded corners. Overlay primitives (DropdownMenu,
+  // Tooltip, Popover) portal out via Floating UI and aren't affected; focus
+  // rings are clipped, so flush focusables draw them inset.
+  // Opt out with `<Card overflow="visible">` when a child genuinely needs to
+  // overhang the card (decorative badges, hover lifts, etc).
+  overflow: hidden;
+}
+
+.overflowVisible {
+  // stylelint-disable-next-line scale-unlimited/declaration-strict-value -- CSS keyword
+  overflow: visible;
+}
+
+.fill {
+  height: 100%;
+  min-width: 0;
+}
+
+// Card owns this layout because it relates only its own Header and Body
+// compound pieces. It activates only for `<Card fill>` with a direct Body, so
+// ordinary fill Cards keep their existing block layout.
+.fillWithBody {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.fillWithBody > .header {
+  flex-shrink: 0;
+}
+
+// Tone-coded left-stripe via inset box-shadow. Drawn inside the card on top
+// of the existing border, so untoned cards stay pixel-identical to before
+// (no layout shift, no width change). The existing --shadow-sm stays on
+// every card; the inset stripe layers on top when `data-tone` is set.
+.card[data-tone='accent'] {
+  box-shadow:
+    inset var(--card-stripe-width) 0 0 var(--card-stripe-color-accent),
+    var(--card-shadow);
+}
+
+.card[data-tone='info'] {
+  box-shadow:
+    inset var(--card-stripe-width) 0 0 var(--card-stripe-color-info),
+    var(--card-shadow);
+}
+
+.card[data-tone='success'] {
+  box-shadow:
+    inset var(--card-stripe-width) 0 0 var(--card-stripe-color-success),
+    var(--card-shadow);
+}
+
+.card[data-tone='warning'] {
+  box-shadow:
+    inset var(--card-stripe-width) 0 0 var(--card-stripe-color-warning),
+    var(--card-shadow);
+}
+
+.card[data-tone='danger'] {
+  box-shadow:
+    inset var(--card-stripe-width) 0 0 var(--card-stripe-color-danger),
+    var(--card-shadow);
+}
+
+.paddingNone {
+  padding: 0;
+}
+
+.paddingSm {
+  padding: var(--card-padding-sm);
+}
+
+.paddingMd {
+  padding: var(--card-padding-md);
+}
+
+.paddingLg {
+  padding: var(--card-padding-lg);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--card-section-gap);
+  padding: var(--card-section-padding-y) var(--card-section-padding-x);
+  border-bottom: var(--border-width) solid var(--card-section-border-color);
+}
+
+.title {
+  // stylelint-disable-next-line property-disallowed-list -- native heading margin reset
+  margin: 0;
+  font-size: var(--card-title-font-size);
+  font-weight: var(--card-title-font-weight);
+  color: var(--card-title-fg);
+  min-width: 0;
+}
+
+.action {
+  flex-shrink: 0;
+}
+
+// With meta: grid, not flex. Flex shrink is weighted by size, so the title
+// would always give up a fraction of a pixel and wrap; here the auto title
+// track reaches its one-line width before the 1fr meta track gets anything,
+// so meta (min 0, ellipsis) absorbs every narrowing until it is gone. The
+// gaps live in padding, not column-gap, so a collapsed meta track costs the
+// title nothing beyond the one gap it has without meta.
+.withMeta {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  grid-auto-flow: column;
+  column-gap: 0;
+}
+
+// flex-shrink means nothing on a grid item; an auto track's floor is
+// min-content, so pin it to max-content to keep a text action from wrapping.
+.withMeta .action {
+  min-width: max-content;
+  padding-inline-start: var(--card-section-gap);
+}
+
+// With controls: the header is an inline-size container and an inner grid
+// holds the items, so a container query can re-lay them out. Wide: title ·
+// controls · meta (or an empty spacer) · action (or an empty placeholder), so
+// action always lands in column 4, right-aligned. The title track keeps a
+// short minimum (ellipsis below its natural width); meta truncates before the
+// title gives up anything. Gaps live in padding, as with meta.
+.withControls {
+  display: block;
+  container: card-header / inline-size;
+}
+
+.controlsGrid {
+  display: grid;
+  grid-auto-flow: column;
+  grid-template-columns:
+    minmax(var(--card-title-min-width), auto) max-content minmax(0, 1fr)
+    max-content;
+  align-items: center;
+}
+
+.withControls .title {
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.withControls .action {
+  min-width: max-content;
+  padding-inline-start: var(--card-section-gap);
+}
+
+.controls {
+  min-width: max-content;
+  padding-inline-start: var(--card-section-gap);
+}
+
+// SCSS constant because container-query conditions can't read custom
+// properties (same as Image.module.scss). Sized for the 96px title floor, a
+// two-option ButtonGroup (~175px) and an icon action, plus gaps (~323px).
+// ponytail: fixed threshold; wider controls overflow between it and their real need.
+$controls-wrap-below: 360px;
+
+// Narrow: controls move to a second row under the title (order, not
+// grid-column, so auto-placement does it). Row 1 is title · meta · action.
+@container card-header (max-width: #{$controls-wrap-below}) {
+  .controlsGrid {
+    grid-auto-flow: row;
+    grid-template-columns: minmax(0, auto) minmax(0, 1fr) max-content;
+    row-gap: var(--card-section-gap);
+  }
+
+  .controls {
+    order: 1;
+    padding-inline-start: 0;
+  }
+}
+
+.subtle {
+  background: var(--card-header-bg-subtle);
+}
+
+.meta {
+  min-width: 0;
+  padding-inline-start: var(--card-section-gap);
+  font-size: var(--card-meta-font-size);
+  color: var(--card-meta-fg);
+}
+
+.metaText {
+  display: block;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  text-align: end;
+}
+
+// In a fill Card (a sized cell, e.g. DashboardWidget) the meta box is sized
+// by its 1fr track, never by content, so size containment is safe there and
+// lets .metaText hide once only a clipped letter or a lone "…" would show.
+// Not on other Cards: in a shrink-to-fit parent containment would zero
+// meta's width and hide it for good; those keep the plain ellipsis. A fill
+// Card in a shrink-to-fit parent would hit the same trap; the meta JSDoc
+// warns about it.
+.fill .meta {
+  container: card-meta / inline-size;
+}
+
+// SCSS constant because container-query conditions can't read custom
+// properties (same as Image.module.scss).
+// ponytail: fixed threshold — fine for the muted sm text it sizes.
+$meta-hide-below: 48px;
+
+@container card-meta (max-width: #{$meta-hide-below}) {
+  // Clip, not visibility/display: the text stays in the accessibility tree.
+  .metaText {
+    clip-path: inset(50%);
+  }
+}
+
+.body {
+  min-height: 0;
+  padding: var(--card-body-padding-y) var(--card-body-padding-x);
+}
+
+.scroll {
+  // Intentional compound-internal layout exception: Body is the Card-owned
+  // flexible sibling beneath Header, not a consumer-positioned component.
+  flex: 1 1 auto;
+  overflow-y: auto;
+}
+
+.list {
+  list-style: none;
+  // stylelint-disable-next-line property-disallowed-list -- native <ul> margin reset
+  margin: 0;
+  // stylelint-disable-next-line property-disallowed-list -- native <ul> padding reset
+  padding: 0;
+}
+
+.listRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--card-section-gap);
+  padding: var(--card-section-padding-y) var(--card-section-padding-x);
+  border-bottom: var(--border-width) solid var(--card-section-border-color);
+}
+
+.listRow:last-child {
+  border-bottom: 0;
+}

package/src/components/Card/Card.tokens.scss

@@ -0,0 +1,55 @@
+// Card.tokens.scss — Component-scoped tokens for <Card>. Each token
+// defaults to the primitive the SCSS used before this migration.
+:root {
+  // Surface + border
+  --card-bg: var(--color-bg);
+  --card-border-color: var(--color-border);
+  --card-radius: var(--radius-lg);
+  --card-shadow: var(--shadow-sm);
+
+  // Tone stripe — width + per-tone color (inset box-shadow on the card)
+  --card-stripe-width: var(--border-width-strong);
+  --card-stripe-color-accent: var(--color-accent);
+  --card-stripe-color-info: var(--color-info);
+  --card-stripe-color-success: var(--color-success);
+
+  // @contrast --color-warning on --color-bg = 2.14:1 light
+  // @contrast --color-warning-strong on --color-bg = 5.95:1 light
+  // warning uses --color-warning-strong; the bare --color-warning measures 2.14:1 here, below
+  // WCAG AA for text and below 1.4.11's 3:1 for a graphical object. See #481.
+  --card-stripe-color-warning: var(--color-warning-strong);
+  --card-stripe-color-danger: var(--color-danger);
+
+  // Padding per size
+  --card-padding-sm: var(--space-3);
+  --card-padding-md: var(--space-4);
+  --card-padding-lg: var(--space-6);
+
+  // Header / list-row internal layout
+  --card-section-gap: var(--space-3);
+  --card-section-padding-y: var(--space-3);
+  --card-section-padding-x: var(--space-4);
+  --card-section-border-color: var(--color-border);
+
+  // Sunken, not muted: muted is the segmented ButtonGroup track and the ghost
+  // Button hover, so a muted header swallowed both. bg-subtle was the other
+  // candidate, but in light it sits ~1 step off --card-bg and the tint vanishes.
+  --card-header-bg-subtle: var(--color-bg-sunken);
+
+  // Body section spacing
+  --card-body-padding-y: var(--space-3);
+  --card-body-padding-x: var(--space-4);
+
+  // Title typography
+  --card-title-font-size: var(--font-size-md);
+  --card-title-font-weight: var(--font-weight-semibold);
+  --card-title-fg: var(--color-fg);
+
+  // Title floor beside `controls` before they wrap under it: 96px keeps a
+  // word like "Conditions" whole. No 96px step exists, hence the calc.
+  --card-title-min-width: calc(var(--space-12) * 2);
+
+  // Header meta (secondary text beside the title)
+  --card-meta-font-size: var(--font-size-sm);
+  --card-meta-fg: var(--color-fg-muted);
+}

package/src/components/Card/Card.tsx

@@ -0,0 +1,170 @@
+import {
+  Children,
+  Fragment,
+  forwardRef,
+  isValidElement,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import styles from './Card.module.scss';
+import { CardBody } from './CardBody';
+import { CardHeader } from './CardHeader';
+import { CardList } from './CardList';
+import { CardListRow } from './CardListRow';
+
+/** Inner padding. See CardProps#padding for guidance on each. */
+export type CardPadding = 'none' | 'sm' | 'md' | 'lg';
+
+/**
+ * Optional left-edge tone stripe color. When set on a Card, draws a 3px
+ * accent-colored bar on the left edge. Uses the same token vocabulary as Alert.
+ */
+export type CardTone = 'accent' | 'info' | 'success' | 'warning' | 'danger';
+
+/** How the Card clips its children. See CardProps#overflow. */
+export type CardOverflow = 'hidden' | 'visible';
+
+export interface CardProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Inner padding.
+   * - `none` — use when the card contains a table or list that should bleed
+   *   edge-to-edge; inner sections manage their own padding.
+   * - `sm` (12px) — dense info cards.
+   * - `md` (16px) — default for plain-content cards.
+   * - `lg` (24px) — emphasis cards, marketing-style panels.
+   *
+   * When omitted, defaults to `'md'` for plain content, or `'none'` when the
+   * card contains compound subcomponents (`Card.Header` / `Card.Body` /
+   * `Card.List` / `Card.ListRow`) so its sections bleed to the card edge
+   * automatically.
+   * Pass an explicit value to override the auto-detect.
+   *
+   * **Detection is shallow:** only direct children are inspected. Fragments
+   * (`<>...</>`) are transparent — the detection recurses into them, so
+   * conditional renders that wrap compound children in a Fragment still
+   * trigger the auto-detect. But wrapping a `Card.Header` in any other
+   * element (`<div>`, `<Stack>`, etc.) defeats the heuristic — pass
+   * `padding="none"` explicitly in that case.
+   */
+  padding?: CardPadding;
+  /**
+   * Optional left-edge tone stripe (3px). Useful for "stat card" / "status card"
+   * patterns where one card in a row needs visual emphasis. Default: no stripe
+   * (the card keeps its standard bordered look).
+   *
+   * Uses the same tone vocabulary as `Alert`: `accent` / `info` / `success` /
+   * `warning` / `danger`.
+   */
+  tone?: CardTone;
+  /**
+   * How the card clips its children at the rounded border.
+   * - `hidden` (default) — children are clipped to the rounded border. This
+   *   prevents the visible seam that appears at the corners when a child has
+   *   square corners (Table's internal scroll wrapper, images, full-bleed
+   *   media). Overlays in this library (DropdownMenu, Tooltip, Popover, Drawer,
+   *   Modal) portal to `document.body` and are NOT clipped by this. Focus
+   *   rings are NOT exempt: an `outline` is clipped by an ancestor's overflow,
+   *   so a focusable flush against the card edge loses that band — draw its
+   *   ring inset by passing `$offset: calc(-1 * var(--ring-offset))` to the
+   *   `focus-ring` mixin, not a separate `outline-offset` after the `@include`
+   *   (a `structure.test.ts` gate fails the build on that shape).
+   * - `visible` — opt out of clipping. Use when a direct child needs to
+   *   overhang the card edge — decorative badges that protrude from a corner,
+   *   hover-lift transforms whose shadow extends past the card border, etc.
+   *
+   * @default 'hidden'
+   */
+  overflow?: CardOverflow;
+  /**
+   * Fill the containing block's height and allow the Card to shrink within a
+   * narrow grid cell. Use in stretched Grid, Sortable, or DashboardCanvas
+   * cells whose wrapper already has a definite height. When a direct
+   * `Card.Body` child is present, `fill` also establishes Card's internal
+   * column and minimum-height chain; add `scroll` to the Body to keep a sibling
+   * Header fixed above a scrolling content region. Defaults to `false`.
+   * @default false
+   */
+  fill?: boolean;
+}
+
+const paddingClass: Record<CardPadding, string> = {
+  none: styles.paddingNone,
+  sm: styles.paddingSm,
+  md: styles.paddingMd,
+  lg: styles.paddingLg,
+};
+
+interface CompoundChildrenInfo {
+  hasCompound: boolean;
+  hasBody: boolean;
+}
+
+function inspectCompoundChildren(children: ReactNode): CompoundChildrenInfo {
+  return Children.toArray(children).reduce<CompoundChildrenInfo>(
+    (info, child) => {
+      if (!isValidElement(child)) return info;
+      const type = child.type;
+      if (type === CardBody) {
+        return { hasCompound: true, hasBody: true };
+      }
+      if (type === CardHeader || type === CardList || type === CardListRow) {
+        return { ...info, hasCompound: true };
+      }
+      // Fragments are transparent — Children.toArray preserves them as nodes,
+      // but a consumer who wraps compound children in a `<>` (e.g. for a
+      // conditional render) clearly still wants the auto-detect to fire.
+      if (type === Fragment) {
+        const nested = inspectCompoundChildren((child.props as { children?: ReactNode }).children);
+        return {
+          hasCompound: info.hasCompound || nested.hasCompound,
+          hasBody: info.hasBody || nested.hasBody,
+        };
+      }
+      return info;
+    },
+    { hasCompound: false, hasBody: false },
+  );
+}
+
+/**
+ * Bordered container for grouped content, with an optional compound API (`Card.Header` / `Body` / `List` / `ListRow`).
+ * @see docs/components/Card.md
+ */
+const CardRoot = forwardRef<HTMLDivElement, CardProps>(function Card(
+  { padding, tone, overflow = 'hidden', fill = false, className, children, ...props },
+  ref,
+) {
+  const compoundChildren = inspectCompoundChildren(children);
+  // Compound subcomponents (Card.Header / Card.Body / Card.List /
+  // Card.ListRow) manage their own internal padding and want to bleed to the
+  // card edge. When any are present and `padding` wasn't passed explicitly,
+  // default to 'none' so the consumer doesn't have to repeat themselves.
+  // Explicit `padding` wins.
+  const effectivePadding: CardPadding = padding ?? (compoundChildren.hasCompound ? 'none' : 'md');
+  // {...props} last so consumer overrides win (Pattern A).
+  return (
+    <div
+      ref={ref}
+      className={clsx(
+        styles.card,
+        paddingClass[effectivePadding],
+        overflow === 'visible' && styles.overflowVisible,
+        fill && styles.fill,
+        fill && compoundChildren.hasBody && styles.fillWithBody,
+        className,
+      )}
+      data-tone={tone}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+});
+
+export const Card = Object.assign(CardRoot, {
+  Body: CardBody,
+  Header: CardHeader,
+  List: CardList,
+  ListRow: CardListRow,
+});

package/src/components/Card/CardBody.tsx

@@ -0,0 +1,45 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import styles from './Card.module.scss';
+
+/** Props for the content region inside a compound Card. */
+export interface CardBodyProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Makes the body the flexible vertical scroll region of a `fill` Card while
+   * sibling `Card.Header` content stays fixed. The Card's parent must provide
+   * a definite height. Defaults to `false`.
+   * @default false
+   */
+  scroll?: boolean;
+}
+
+/**
+ * Padded content region for the Card compound API.
+ * @see docs/components/Card.md
+ */
+export const CardBody = forwardRef<HTMLDivElement, CardBodyProps>(function CardBody(
+  { scroll = false, className, ...props },
+  ref,
+) {
+  // {...props} last so consumer overrides win (Pattern A) — including
+  // tabIndex, so a consumer that gives the region a focusable descendant, or
+  // wants to manage focus itself, can opt out with tabIndex={-1}.
+  return (
+    <div
+      ref={ref}
+      // `scroll` is what makes this an overflow container, so `scroll` is what
+      // has to make it keyboard-reachable. Without it, content that overflows
+      // is unreachable for a keyboard-only user whenever it has no focusable
+      // descendant — axe `scrollable-region-focusable`, WCAG 2.1.1. The
+      // sharpest case is a loading body full of `Skeleton`s, every one of
+      // which is aria-hidden: a scrollable region with nothing in it to reach.
+      //
+      // The NAME still has to come from the consumer — the DS cannot know what
+      // the region holds — so pair this with `role="group"` and an
+      // `aria-label` when the content warrants announcing.
+      tabIndex={scroll ? 0 : undefined}
+      className={clsx(styles.body, scroll && styles.scroll, className)}
+      {...props}
+    />
+  );
+});

package/src/components/Card/CardHeader.tsx

@@ -0,0 +1,113 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './Card.module.scss';
+
+/** Heading level wrapping the title. Defaults to 'h3'. Same vocab as Accordion. */
+export type CardHeaderLevel = 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+export interface CardHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Heading level for the title text. Defaults to `'h3'` (assumes the page
+   * has an h1/h2 above). Override when this section sits beneath an h1
+   * directly (`headerLevel="h2"`) or further nested (`headerLevel="h4"`).
+   */
+  headerLevel?: CardHeaderLevel;
+  /**
+   * `'subtle'` paints the header on a tinted (sunken) surface, for a nested editable
+   * sub-section inside a `Card.Body` (e.g. a condition group). Defaults to
+   * `'default'`.
+   */
+  surface?: 'default' | 'subtle';
+  /**
+   * Optional interactive slot right after the title (e.g. a `ButtonGroup`
+   * mode switch). Rendered outside the heading, so it is not part of the
+   * heading's name. Order: title, controls, meta, action. Controls never
+   * shrink: on a wide header the title ellipsizes down to a short minimum
+   * width; on a narrow header (under ~360px of content) the controls wrap onto
+   * a second row under the title, which keeps the first row with meta and
+   * action. Keep titles short, or pass a `title` attribute for long ones.
+   */
+  controls?: ReactNode;
+  /**
+   * Optional right-aligned slot — typically a `<Link>` or `<Button>` that
+   * lets the user navigate to a full list or take a section-level action.
+   * Rendered inside a `<span>` that never shrinks or wraps (flex-shrink: 0;
+   * with `meta` or `controls`, min-width: max-content). Beside `controls` it is
+   * the removal/section action of a nested sub-group (e.g. a ghost delete
+   * button), right-aligned after any meta.
+   */
+  action?: ReactNode;
+  /**
+   * Optional secondary, non-interactive text beside the title — freshness
+   * ("Updated 3 minutes ago") or status. Muted and single-line; sits just
+   * before `action` and is the first thing to give way at narrow widths: it
+   * truncates with an ellipsis before the title gives up any width, while
+   * `action` keeps its width. In a `fill` Card (which needs a parent of
+   * definite width) it is also visually hidden, still read by screen
+   * readers, once only a sliver would show. Not part
+   * of the heading's name. Put controls in `controls` or `action`, never
+   * here. `false` and `''` count as no meta.
+   */
+  meta?: ReactNode;
+  /**
+   * Title content. Becomes the inner text of the heading element. Typically
+   * a plain string, but can contain inline elements if needed.
+   */
+  children: ReactNode;
+}
+
+/**
+ * Title row subcomponent for `<Card>` with optional right-aligned meta text and action slot.
+ * @see docs/components/Card.md
+ */
+export const CardHeader = forwardRef<HTMLDivElement, CardHeaderProps>(function CardHeader(
+  { headerLevel = 'h3', surface = 'default', controls, action, meta, children, className, ...rest },
+  ref,
+) {
+  // headerLevel is a string union of valid HTML heading tag names; cast to
+  // the union (not a single literal) so the JSX dispatch type is honest.
+  const Heading = headerLevel as 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  const hasMeta = meta != null && meta !== false && meta !== '';
+  const hasControls = controls != null && controls !== false && controls !== '';
+  const title = <Heading className={styles.title}>{children}</Heading>;
+  const metaNode = hasMeta && (
+    <span className={styles.meta}>
+      <span className={styles.metaText}>{meta}</span>
+    </span>
+  );
+  const actionNode = action != null ? <span className={styles.action}>{action}</span> : null;
+  // {...rest} last so consumer overrides win (Pattern A).
+  return (
+    <div
+      ref={ref}
+      className={clsx(
+        styles.header,
+        hasMeta && styles.withMeta,
+        hasControls && styles.withControls,
+        surface === 'subtle' && styles.subtle,
+        className,
+      )}
+      data-surface={surface === 'subtle' ? 'subtle' : undefined}
+      {...rest}
+    >
+      {hasControls ? (
+        // The header is the size container; this inner grid is what its
+        // container query re-lays out (a container can't restyle itself).
+        <div className={styles.controlsGrid}>
+          {title}
+          <span className={styles.controls}>{controls}</span>
+          {!hasMeta && <span aria-hidden="true" />}
+          {metaNode}
+          {/* Placeholder keeps the column count fixed when there is no action. */}
+          {actionNode ?? <span aria-hidden="true" />}
+        </div>
+      ) : (
+        <>
+          {title}
+          {metaNode}
+          {actionNode}
+        </>
+      )}
+    </div>
+  );
+});

package/src/components/Card/CardList.tsx

@@ -0,0 +1,24 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './Card.module.scss';
+
+export interface CardListProps extends HTMLAttributes<HTMLUListElement> {
+  /** Row items — typically `<Card.ListRow>` elements. */
+  children: ReactNode;
+}
+
+/**
+ * Semantic `<ul>` wrapper for a list of `<Card.ListRow>` items inside a `<Card>`.
+ * @see docs/components/Card.md
+ */
+export const CardList = forwardRef<HTMLUListElement, CardListProps>(function CardList(
+  { children, className, ...rest },
+  ref,
+) {
+  // {...rest} last so consumer overrides win (Pattern A).
+  return (
+    <ul ref={ref} className={clsx(styles.list, className)} {...rest}>
+      {children}
+    </ul>
+  );
+});