prime-ui-kit 0.7.13 → 0.9.1

package/src/components/card/COMPONENT.md

@@ -1,327 +1,192 @@
 # Card
 
-**Defaults:** use **`variant`** and documented slots as in the canonical example below. Set **`flat`** when the card should read as a flat surface on the page (no elevation shadow).
+**Category:** data-display
+**Kind:** composite
 
-## About
+> A filled surface block with structural templates for metrics, charts, lists, calls to action and covers.
 
-Composable surfaces for **dashboard KPIs**, **lists**, **CTA tiles**, **split metrics**, **media headers**, and **chart shells**: layout presets are driven by **`variant`** on **`Card.Root`**. Typography and spacing use semantic tokens (`--prime-sys-*`). The kit does not ship chart primitives — mount a chart library root, SVG, or [ProgressBar](../progress-bar/COMPONENT.md) inside **`Card.Media`**, **`Card.Chart`** (**`panel`**, edge-to-edge), padded **`Card.Body`**, or **`Card.Cover`**.
+## When to use
+- KPI tiles on a dashboard (`mini`, `stat-trend`, `split`).
+- A chart or text widget with a header and controls (`panel`).
+- A settings or profile form grouped on its own surface (`panel` + `Body` + `Footer`).
+- An activity list (`list`), a call to action (`cta`), a tile with an image on top (`cover`).
 
-Further reading: [Material Design 3 — Cards](https://m3.material.io/components/cards/guidelines), [IBM Carbon — Tile](https://carbondesignsystem.com/components/tile/usage/), [Nielsen Norman Group — Dashboard Design](https://www.nngroup.com/articles/dashboard-design/).
-
-- **Use** **`variant="mini"`** for a compact KPI: optional **`IconBox`** + **`Stack`** with **`Label`** and **`Value`**.
-- **Use** **`variant="mini-media"`** for the same leading row as **`mini`**, then **`Media`** for a sparkline, ring, or thin progress strip.
-- **Use** **`variant="metric"`** for a title row: **`HeaderRow`** with **`Lead`** (badge or icon) and **`Value`**, plus **`Description`** underneath.
-- **Use** **`variant="panel"`** for a titled block: **`SectionHeader`** + **`Body`** (padded copy or tables) and/or **`Chart`** (full-width chart area, no inner padding).
-- **Use** **`variant="stat-trend"`** for a large KPI with period delta: **`Label`**, **`Value`**, **`Delta`** (`trend`: `up` | `down` | `neutral`).
-- **Use** **`variant="cta"`** for a call-to-action tile: **`Title`**, **`CtaBody`**, **`Actions`**.
-- **Use** **`variant="list"`** for activity or alerts: **`ListHeader`**, **`List`** / **`ListItem`**.
-- **Use** **`variant="split"`** for two related metrics: **`Split`** with two **`SplitCell`** blocks (often **`IconBox`** + **`Stack`** each).
-- **Use** **`variant="cover"`** for media on top: **`Cover`**, then **`Stack`** and optional **`Actions`**.
-- **Do not use** the whole card as the only focus target for navigation; prefer [LinkButton](../link-button/COMPONENT.md) or an inner control, unless you add explicit `role` / `tabIndex` and keyboard handling.
-- **Do not use** decorative icons without **`aria-hidden`** when the text already conveys the meaning.
-
-## Canonical example
-
-Rich **`panel`**: section header with trailing control, padded intro in **`Body`**, and an edge-to-edge **`Chart`** region for a real chart root.
+## When not to use
+- A whole page region with a title and description → [PageContent](../page-content/COMPONENT.md) sections; do not wrap every section in a card.
+- Tabular data → use [DataTable](../data-table/COMPONENT.md) (it has its own fill).
+- A message about the page state → [Banner](../banner/COMPONENT.md); nothing to show yet → [EmptyPage](../empty-page/COMPONENT.md).
+- Content that floats over the page → [Popover](../popover/COMPONENT.md), [Modal](../modal/COMPONENT.md) or [Drawer](../drawer/COMPONENT.md).
 
+## Import
 ```tsx
-import { Card, Icon, Typography } from "prime-ui-kit";
-
-export function RevenuePanelCard() {
-  return (
-    <Card.Root variant="panel">
-      <Card.SectionHeader>
-        <Card.SectionTitle>Revenue</Card.SectionTitle>
-        <Card.SectionTrailing>
-          <Icon name="nav.layoutGrid" aria-hidden />
-        </Card.SectionTrailing>
-      </Card.SectionHeader>
-      <Card.Body>
-        <Typography.Root variant="body-small" tone="muted">
-          Quarter-to-date summary; the chart mounts below with no horizontal or vertical padding inside
-          Card.Chart.
-        </Typography.Root>
-      </Card.Body>
-      <Card.Chart>
-        <div id="revenue-chart" aria-hidden />
-      </Card.Chart>
-    </Card.Root>
-  );
-}
+import { Card } from "prime-ui-kit";
 ```
 
-## Playground snippets
-
-Live demos use these files (same order as the **Card** section in the playground):
-
-| Scenario | Snippet | Notes |
-|----------|---------|-------|
-| Mini | [`mini.tsx`](../../../playground/snippets/card/mini.tsx) | `variant="mini"`: **`IconBox`** + **`Stack`** (**`Label`**, **`Value`**) |
-| Mini + media | [`mini-media.tsx`](../../../playground/snippets/card/mini-media.tsx) | `variant="mini-media"`: same as mini + bottom **`Media`** |
-| Metric | [`metric.tsx`](../../../playground/snippets/card/metric.tsx) | `variant="metric"`: **`HeaderRow`** (**`Lead`**, **`Value`**) + **`Description`** |
-| Stat + trend | [`stat-trend.tsx`](../../../playground/snippets/card/stat-trend.tsx) | `variant="stat-trend"`: **`Value`** + **`Delta`** (`trend`) |
-| CTA | [`cta.tsx`](../../../playground/snippets/card/cta.tsx) | `variant="cta"`: **`Title`**, **`CtaBody`**, **`Actions`** |
-| List | [`list.tsx`](../../../playground/snippets/card/list.tsx) | `variant="list"`: **`ListHeader`**, **`List`** / **`ListItem`** |
-| Split | [`split.tsx`](../../../playground/snippets/card/split.tsx) | `variant="split"`: **`Split`** with two **`SplitCell`** blocks |
-| Cover | [`cover.tsx`](../../../playground/snippets/card/cover.tsx) | `variant="cover"`: **`Cover`**, **`Stack`**, **`Actions`** |
-| Panel (chart only) | [`panel.tsx`](../../../playground/snippets/card/panel.tsx) | `variant="panel"`: **`SectionHeader`** + edge-to-edge **`Chart`** |
-| Panel (body + chart) | [`panel-content-chart.tsx`](../../../playground/snippets/card/panel-content-chart.tsx) | same **`panel`**: **`Body`** + **`Chart`** |
-| Flat surface | [`flat.tsx`](../../../playground/snippets/card/flat.tsx) | **`flat`** prop: shadow vs no shadow on **`mini`** |
-| KPI grid | [`row.tsx`](../../../playground/snippets/card/row.tsx) | several mini cards in playground `introFeatureGrid` |
-
-Supporting CSS modules in that folder: `flat.module.css`, `mini-media.module.css`, `variants-stack.module.css`.
-
-## Extended examples
-
-Copy-oriented scenarios (English copy, `prime-ui-kit` imports) live next to this file. For single-variant demos, see **Playground snippets** above.
-
-| File | Scenario |
-|------|----------|
-| [examples/mini-kpi.tsx](./examples/mini-kpi.tsx) | **`mini`**: компактный KPI с иконкой |
-| [examples/metric-dashboard.tsx](./examples/metric-dashboard.tsx) | KPI row: **`stat-trend`**, **`metric`**, **`mini-media`** |
-| [examples/list-card.tsx](./examples/list-card.tsx) | Activity list with header link |
-| [examples/media-mini.tsx](./examples/media-mini.tsx) | **`mini-media`**: sparkline and **`ProgressBar`** |
-| [examples/split-layout.tsx](./examples/split-layout.tsx) | **`split`**: two metrics in one tile |
-| [examples/cta-cover.tsx](./examples/cta-cover.tsx) | **`cta`** tile and **`cover`** with gradient banner |
-
-## Composition
-
-- **`Card.Root`** — required **`variant`**: `"mini"` \| `"mini-media"` \| `"metric"` \| `"panel"` \| `"stat-trend"` \| `"cta"` \| `"list"` \| `"split"` \| `"cover"`. Optional **`flat`** removes the default surface shadow. Sets `data-variant` / `data-flat` for styling.
-- **`Card.IconBox`** — square leading area in **`mini`** and **`mini-media`**: background **`status-information-background`**, radius **`size-control-m-radius`**, icon color via **`status-information-foreground`** (decorative icons: **`aria-hidden`**).
-- **`Card.Lead`** — left cluster in **`HeaderRow`** (badge from [Badge](../badge/COMPONENT.md), raw icon, or both).
-- **`Card.HeaderRow`** — top row for **`metric`**: typically **`Lead`** + **`Value`**.
-- **`Card.Stack`** — vertical block for **`Label`** + **`Value`** in **`mini`** and **`mini-media`**.
-- **`Card.Label`** — secondary line (muted).
-- **`Card.Value`** — primary metric string.
-- **`Card.Description`** — supporting line under the header row (`p`).
-- **`Card.Media`** — bottom region with top border; place charts or progress here.
-- **`Card.SectionHeader`** — bar with bottom border for **`panel`**.
-- **`Card.SectionTitle`** — `h3` title.
-- **`Card.SectionTrailing`** — optional actions or icon on the right.
-- **`Card.Body`** — **`panel`**: padded region for text, summaries, or tables. With **`variant="panel"`**, the shell has a **minimum height**; a **single element child** can stretch inside the padded box. Override height via **`className`** on **`Root`** if needed.
-- **`Card.Chart`** — **`panel`**: **no** horizontal or vertical inner padding; mount the chart library root here for **edge-to-edge** drawing under the header. Optional after **`Body`**; then **`Chart`** fills remaining height.
-- **`Card.Title`** — **`h3`** with **`title`** styles; use in **`cta`**, **`list`** header, **`cover`** stack.
-- **`Card.Delta`** — supporting line for **`stat-trend`**; optional **`trend`** sets `data-trend` for color (`up` \| `down` \| `neutral`).
-- **`Card.CtaBody`** — body copy in **`cta`**.
-- **`Card.Actions`** — row of actions (border-top); use in **`cta`** and **`cover`**.
-- **`Card.Cover`** — top media region for **`cover`** (image or decorative block; keep meaningful images described in text for a11y).
-- **`Card.Split`** / **`Card.SplitCell`** — two-column grid for **`split`**.
-- **`Card.ListHeader`** — top bar for **`list`** (border-bottom).
-- **`Card.List`** / **`Card.ListItem`** — semantic **`ul`** / **`li`** for **`list`**.
-
-## Rules
-
-- Typography follows the **control `m` tier** (`--prime-sys-size-control-m-text` for values and section titles, `--prime-sys-size-control-m-supportText` for labels and descriptions), aligned with [Label](../label/COMPONENT.md) / [Input](../input/COMPONENT.md) defaults.
-- Prefer **`flat`** on dense dashboards if shadows feel noisy; default shadow uses **`--prime-sys-elevation-shadow-surface`**.
-- **`SectionTitle`** and **`Title`** are **`h3`**; match heading levels to the page outline.
-- **`Description`** is a **`p`** — only one block per card unless you compose custom markup inside **`Body`** for **`panel`**.
-- **`variant="panel"`** sets a **minimum height** on **`Root`**. Order after **`SectionHeader`**: optional **`Body`**, optional **`Chart`**. If both are present, **`Body`** sizes to its content and **`Chart`** takes the **remaining height**. A **single element child** in **`Chart`** (or in **`Body`** when it is the only block) stretches within that region.
-- For **`mini-media`**, keep **`Media`** height predictable so grid rows align, or use one column on narrow viewports.
-- Icons in **`IconBox`** / **`Lead`** should not be the sole carrier of meaning; pair with visible text.
-- Decorative content in **`Cover`** should not rely on imagery alone for critical information — repeat key facts in **`Stack`**.
-- **`List`** uses a real **`ul`**; keep **`ListItem`** text meaningful for screen readers.
+## Anatomy
+```
+Card.Root variant="panel"        Header(Title, …trailing) · Body · Media · Footer
+Card.Root variant="mini"         Icon · Label · Value · Media?
+Card.Root variant="stat-trend"   Label · Value · Delta
+                                 or Header(Badge or Icon, Value) · Description
+Card.Root variant="split"        Body(cell × 2: any element, e.g. <div> with Icon · Label · Value)
+Card.Root variant="cta"          Title · Description · Footer
+Card.Root variant="list"         Header(Title, …trailing) · List(ListItem …)
+Card.Root variant="cover"        Media · Body(Title, Description) · Footer
+```
 
 ## API
 
-### Card.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| variant | `"mini" \| "mini-media" \| "metric" \| "panel" \| "stat-trend" \| "cta" \| "list" \| "split" \| "cover"` | — | Yes | Layout preset and padding. |
-| flat | `boolean` | `false` | No | When `true`, no drop shadow (surface still bordered). |
-| className | `string` | — | No | Extra class on the root. |
-| children | `React.ReactNode` | — | No | Slots listed in Composition. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native attributes on the root `div`. |
-
-### Card.IconBox
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Icon node. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the wrapper `div`. |
-
-### Card.Lead
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Badge, icon, or group. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the wrapper `div`. |
-
-### Card.HeaderRow
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Typically `Lead` + `Value`. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the flex row. |
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-### Card.Stack
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | `Label` + `Value` for mini. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the stack `div`. |
-
-### Card.Label
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Secondary label text. |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Attributes on the `span`. |
-
-### Card.Value
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Primary value. |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Attributes on the `span`. |
-
-### Card.Description
+### Card.Root
+`ref` → `HTMLDivElement`. The filled surface (card fill, radius 12, raised shadow, no border) and a size container; `variant` picks the template layout of its parts.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Supporting copy. |
-| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | Attributes on the `p`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"panel" \| "mini" \| "stat-trend" \| "split" \| "cta" \| "list" \| "cover"` | `"panel"` | Structural template: titled block with zones (`panel`), KPI tiles, a call to action, a list or a cover tile. |
+| `flat` | `boolean` | `false` | No raised shadow: a flat tile for dense grids. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` + `aria-labelledby` for a landmark block, and the other div attributes. |
 
-### Card.Media
+### Card.Header
+`ref` → `HTMLDivElement`. The top row: `Card.Title` first, anything after it (a control, a quiet caption) at the end. In `panel` and `list` it is a padded zone with a faint hairline below; in `stat-trend` it can pair a leading badge or icon with a compact `Card.Value`. Wraps below 22rem.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Chart, SVG, or progress. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the region `div`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
 
 ### Card.Title
+`ref` → `HTMLHeadingElement`. The card heading (`<h3>`, title-s; title-m in `cta`).
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Heading text (`h3`). |
-| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | Attributes on the `h3`. |
-
-### Card.Delta
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| trend | `"up" \| "down" \| "neutral"` | — | No | Sets `data-trend` for color. |
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Delta / period copy. |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Attributes on the `span`. |
-
-### Card.CtaBody
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Supporting copy in **`cta`**. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the `div`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level that fits the page outline; the look does not change. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
 
-### Card.Actions
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Buttons / links row. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the `div`. |
-
-### Card.Cover
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Image or media block (`cover` variant). |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the `div`. |
-
-### Card.Split
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Typically two **`SplitCell`** children. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the grid `div`. |
-
-### Card.SplitCell
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | One metric column: **`Label`** + **`Value`**, or **`IconBox`** + **`Stack`**. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the cell `div`. |
-
-### Card.ListHeader
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Title row for **`list`**. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the `div`. |
-
-### Card.List
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | **`ListItem`** nodes. |
-| …rest | `React.HTMLAttributes<HTMLUListElement>` | — | No | Attributes on the `ul` (forwardRef). |
-
-### Card.ListItem
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Row content. |
-| …rest | `React.HTMLAttributes<HTMLLIElement>` | — | No | Attributes on the `li` (forwardRef). |
-
-### Card.SectionHeader
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Title row content. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the header `div`. |
-
-### Card.SectionTitle
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Heading text. |
-| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | Attributes on the `h3`. |
-
-### Card.SectionTrailing
+### Card.Description
+`ref` → `HTMLParagraphElement`. Secondary text (`<p>`, body-s, wraps): under the title of `cta` and `cover`, under the header of `stat-trend`.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Icons or actions. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the trailing `div`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
 
 ### Card.Body
+`ref` → `HTMLDivElement`. The padded content zone (gap 16). In `split` it is the two-cell grid: each child is a cell (stacked below 22rem); in `cover` it holds the title and the description 4 apart.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Padded **`panel`** content (text, tables). One **element** child can stretch inside the padded area. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the body `div`. |
-
-### Card.Chart
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | **`panel`** chart root; **no** inner padding (edge-to-edge). |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the chart region `div`. |
-
-## Imports
-
-```ts
-import { Card } from "prime-ui-kit";
-```
-
-CSS for this component is included in the main bundle (`prime-ui-kit/styles.css` / `bundle.css`) when you import the library styles.
+### Card.Media
+`ref` → `HTMLDivElement`. A chart, an image or a gauge: edge to edge under the header or the body in `panel`, the 128–192px cover on top in `cover`, the full-width bottom slot in `mini`. A chart SVG needs a CSS height.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
+
+### Card.Footer
+`ref` → `HTMLDivElement`. The bottom row of buttons, wrapping: right-aligned under a faint hairline in `panel` and `list`, under a full-width hairline in `cta`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
+
+### Card.Icon
+`ref` → `HTMLDivElement`. The 40px accent tile of a KPI holding one icon; it spans the label and the value rows in `mini` and a `split` cell.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
+
+### Card.Label · Card.Value · Card.Delta
+`ref` → `HTMLSpanElement`. Metric text: the label (body-s, truncates), the value (tabular, sized by the template and the card width) and the change.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Delta: color by meaning, not by sign (churn up is `danger`). |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
+
+### Card.List · Card.ListItem
+`ref` → `HTMLUListElement` / `HTMLLIElement`. The `list` template: a `<ul>` of `<li>` rows with faint hairlines between them; head it with `Card.Header`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
+
+## Variants
+
+### variant (structural templates)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `panel` | no root padding; `Header` with a faint hairline, padded `Body`, edge-to-edge `Media`, right-aligned `Footer` | chart widgets, settings forms, any titled block | yes |
+| `mini` | 40px accent `Icon` tile beside the label and the title-l value; a `Media` child is a full-width bottom slot | a compact KPI tile, with a sparkline or a ProgressBar | |
+| `stat-trend` | label, large value (adapts to the card width), delta; or a `Header` (lead left, heading-m value right) + description | the main number of a dashboard row; a KPI with a qualifier badge | |
+| `split` | `Body` with two metric cells and a faint hairline; stacked below 22rem | two related metrics in one tile | |
+| `cta` | title, body-s text, `Footer` under a hairline | a call to action | |
+| `list` | `Header` with a hairline, items with faint hairlines | recent events, short lists | |
+| `cover` | 128–192px `Media` on top, title and description, `Footer` | campaign, project or product tiles | |
+
+### tone (Delta)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | `text-secondary` | a change with no good/bad meaning | yes |
+| `success` | `success-text` | the change is good | |
+| `warning` | `warning-text` | the change needs attention | |
+| `danger` | `danger-text` | the change is bad | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `flat` | same fill, no shadow | dense grids of tiles | `false` |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| template | `variant` | `data-variant` |
+| flat | `flat` | `data-flat` |
+| card width | container queries | `split` stacks below 22rem, `Header` wraps below 22rem, the `stat-trend` value changes at 20rem / 36rem |
+
+Card is static: no hover, focus or press of its own.
+
+## Layout & spacing
+- Grid of cards: `repeat(auto-fit, minmax(min(100%, 14rem), 1fr))`, gap `--prime-space-4`.
+- Padding `--prime-card-padding-m` (20); `Body` gap `--prime-card-gap` (16); fields inside `Body` 20 apart, on the surface field fill.
+- Long values wrap, labels truncate; a chart SVG needs a CSS height.
+- In a `Header` the title takes the free width; a control or a caption after it sits at the end without a wrapper.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- `Card.Root` is a plain `<div>`; give it `role="region"` + `aria-labelledby` only when it is a landmark-worthy block.
+- `Card.Title` renders `<h3>`; directly under the page title pass `as="h2"`.
+- Decorative icons in `Card.Icon` and cover images in `Card.Media` get `aria-hidden`; controls in `Card.Header` need their own names.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A company settings panel: a header, fields on the surface fill and buttons in the footer — `Card.Header`, `Card.Body`, `Card.Footer`. |
+| [variants.tsx](examples/variants.tsx) | KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change — `variant`, `Card.Delta`. |
+| [kpi-media.tsx](examples/kpi-media.tsx) | A KPI with a sparkline or a fill level in the bottom slot of `mini` — `Card.Media`. |
+| [panel-chart.tsx](examples/panel-chart.tsx) | A chart widget: a header with a period switch, a summary line and an edge-to-edge chart — `Card.Header`, `Card.Media`. |
+| [content-templates.tsx](examples/content-templates.tsx) | Content templates: a call to action, an events list and a campaign tile with a cover — `Card.Footer`, `Card.List`, `Card.Media`. |
+| [flat.tsx](examples/flat.tsx) | A flat tile without the raised shadow next to the default one, for dense grids — `flat`. |
+| [narrow.tsx](examples/narrow.tsx) | The card is a size container: the split template stacks its cells below 22rem and the trend value shrinks below 20rem. |
+
+## Mistakes
+- A `<div>` with a border styled as a card → use `Card.Root`; depth comes from fill, not lines.
+- Wrapping every page section in a card → use PageContent sections.
+- `Card.Delta tone="success"` for every «+» → choose the tone by meaning.
+- Custom padding on a `panel` root → padding belongs to `Header` / `Body` / `Footer`.
+- A wrapper `<div>` around the label and the value of `mini` → put `Icon`, `Label`, `Value` straight into the root (or into a `split` cell); the template lays them out.
+- A chart SVG with only a `viewBox` → give it a CSS height.
+
+## Related
+- **Built from:** —
+- **See also:** [PageContent](../page-content/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Badge](../badge/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/card/examples/content-templates.tsx

@@ -0,0 +1,67 @@
+/** Content templates: a call to action, an events list and a campaign tile with a cover — `Card.Footer`, `Card.List`, `Card.Media`. */
+import { Button, Card, LinkButton, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EVENTS = [
+  { text: "Оплачен заказ № 4821", time: "12:04" },
+  { text: "Новый отзыв на «Планшет Pro»", time: "11:47" },
+  { text: "Синхронизация складов завершена", time: "10:30" },
+];
+
+export default function CardContentTemplatesExample() {
+  return (
+    <div className={styles.grid}>
+      <Card.Root variant="cta">
+        <Card.Title>Экспорт отчёта</Card.Title>
+        <Card.Description>
+          Сводка по сегментам и метрикам за выбранный период в CSV или XLSX.
+        </Card.Description>
+        <Card.Footer>
+          <Button.Root size="s">Скачать CSV</Button.Root>
+          <Button.Root variant="ghost" tone="neutral" size="s">
+            Настроить
+          </Button.Root>
+        </Card.Footer>
+      </Card.Root>
+
+      <Card.Root variant="list">
+        <Card.Header>
+          <Card.Title>Последние события</Card.Title>
+          <LinkButton href="#" size="s">
+            Все
+          </LinkButton>
+        </Card.Header>
+        <Card.List>
+          {EVENTS.map((e) => (
+            <Card.ListItem key={e.text}>
+              <span className={styles.listRow}>
+                <Typography as="span" variant="body-m" truncate>
+                  {e.text}
+                </Typography>
+                <Typography as="span" variant="caption" tone="muted" className={styles.listMeta}>
+                  {e.time}
+                </Typography>
+              </span>
+            </Card.ListItem>
+          ))}
+        </Card.List>
+      </Card.Root>
+
+      <Card.Root variant="cover">
+        <Card.Media aria-hidden>
+          <div className={styles.cover} />
+        </Card.Media>
+        <Card.Body>
+          <Card.Title>Кампания «Осень»</Card.Title>
+          <Card.Description>Охват и клики за 7 дней</Card.Description>
+        </Card.Body>
+        <Card.Footer>
+          <Button.Root variant="outline" tone="neutral" size="s">
+            Открыть отчёт
+          </Button.Root>
+        </Card.Footer>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/card/examples/examples.module.css

@@ -0,0 +1,84 @@
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--prime-space-14) * 4)), 1fr));
+  gap: var(--prime-space-4);
+  width: 100%;
+  min-width: 0;
+}
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+  width: 100%;
+  min-width: 0;
+}
+
+/* Width probes for the container-query demo: 18rem and 40rem. */
+.w18 {
+  width: min(100%, calc(var(--prime-space-24) * 3));
+}
+
+.w40 {
+  width: min(100%, calc(var(--prime-space-20) * 8));
+}
+
+/* 36rem. */
+.panel {
+  width: min(100%, calc(var(--prime-space-24) * 6));
+}
+
+/* Sparkline: fixed height from tokens, stretches to the card width. */
+.spark {
+  display: block;
+  width: 100%;
+  height: var(--prime-space-10);
+  color: var(--prime-color-accent-default);
+  overflow: visible;
+}
+
+.chart {
+  display: block;
+  width: 100%;
+  /* Fixed height: a viewBox-only SVG would otherwise scale to a square of the card width. */
+  height: calc(var(--prime-space-24) * 2);
+  color: var(--prime-color-accent-default);
+}
+
+.chartFill {
+  fill: var(--prime-color-accent-soft);
+}
+
+.chartLine {
+  fill: none;
+  stroke: currentColor;
+  stroke-width: calc(2 * var(--prime-border-width));
+  vector-effect: non-scaling-stroke;
+}
+
+.cover {
+  background: linear-gradient(
+    135deg,
+    var(--prime-color-accent-soft) 0%,
+    var(--prime-color-palette-sky-soft) 100%
+  );
+}
+
+.listRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
+  min-width: 0;
+}
+
+.listMeta {
+  flex: none;
+  font-variant-numeric: tabular-nums;
+}
+
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+}