prime-ui-kit 0.3.1 → 0.3.2

package/src/components/button-group/examples/editor-toolbar.tsx

@@ -0,0 +1,46 @@
+import { Bold, Italic, Underline } from "lucide-react";
+import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Editor toolbar: icon segments share one outline; active format uses `pressed`.
+ * Meaning for assistive tech: `aria-label` on each icon-only `Item`.
+ */
+export default function EditorToolbarExample() {
+  const [marks, setMarks] = React.useState({ bold: true, italic: false, underline: false });
+
+  return (
+    <ButtonGroup.Root aria-label="Text formatting" size="m">
+      <ButtonGroup.Item
+        aria-label="Bold"
+        pressed={marks.bold}
+        type="button"
+        onClick={() => setMarks((m) => ({ ...m, bold: !m.bold }))}
+      >
+        <ButtonGroup.Icon>
+          <Bold />
+        </ButtonGroup.Icon>
+      </ButtonGroup.Item>
+      <ButtonGroup.Item
+        aria-label="Italic"
+        pressed={marks.italic}
+        type="button"
+        onClick={() => setMarks((m) => ({ ...m, italic: !m.italic }))}
+      >
+        <ButtonGroup.Icon>
+          <Italic />
+        </ButtonGroup.Icon>
+      </ButtonGroup.Item>
+      <ButtonGroup.Item
+        aria-label="Underline"
+        pressed={marks.underline}
+        type="button"
+        onClick={() => setMarks((m) => ({ ...m, underline: !m.underline }))}
+      >
+        <ButtonGroup.Icon>
+          <Underline />
+        </ButtonGroup.Icon>
+      </ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}

package/src/components/button-group/examples/form-footer.tsx

@@ -0,0 +1,19 @@
+import { ButtonGroup } from "prime-ui-kit";
+
+/**
+ * Form footer: native submit + reset in one segmented control.
+ */
+export default function FormFooterExample() {
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+      }}
+    >
+      <ButtonGroup.Root aria-label="Save or reset draft" size="m">
+        <ButtonGroup.Item type="submit">Save</ButtonGroup.Item>
+        <ButtonGroup.Item type="reset">Reset</ButtonGroup.Item>
+      </ButtonGroup.Root>
+    </form>
+  );
+}

package/src/components/button-group/examples/view-switcher.tsx

@@ -0,0 +1,25 @@
+import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+type ViewMode = "list" | "grid" | "board";
+
+/**
+ * View switcher: one active segment; state lives in the parent.
+ */
+export default function ViewSwitcherExample() {
+  const [mode, setMode] = React.useState<ViewMode>("list");
+
+  return (
+    <ButtonGroup.Root aria-label="View layout" size="m">
+      <ButtonGroup.Item pressed={mode === "list"} type="button" onClick={() => setMode("list")}>
+        List
+      </ButtonGroup.Item>
+      <ButtonGroup.Item pressed={mode === "grid"} type="button" onClick={() => setMode("grid")}>
+        Grid
+      </ButtonGroup.Item>
+      <ButtonGroup.Item pressed={mode === "board"} type="button" onClick={() => setMode("board")}>
+        Board
+      </ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}

package/src/components/button-group/examples/wizard-actions.tsx

@@ -0,0 +1,30 @@
+import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+const STEP_LAST = 2;
+
+/**
+ * Wizard step actions: Back disabled on first step; Next advances (demo stops at last step).
+ */
+export default function WizardActionsExample() {
+  const [step, setStep] = React.useState(0);
+
+  return (
+    <ButtonGroup.Root aria-label="Wizard navigation" size="m">
+      <ButtonGroup.Item
+        disabled={step === 0}
+        type="button"
+        onClick={() => setStep((s) => Math.max(0, s - 1))}
+      >
+        Back
+      </ButtonGroup.Item>
+      <ButtonGroup.Item
+        disabled={step >= STEP_LAST}
+        type="button"
+        onClick={() => setStep((s) => Math.min(STEP_LAST, s + 1))}
+      >
+        Next
+      </ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}

package/src/components/card/COMPONENT.md

@@ -1,286 +1,104 @@
 # Card
 
-**Проектирование по умолчанию:** для демо и экранов используйте **`variant`** и слоты как в примерах ниже; **`flat`** включайте, когда карточка должна визуально совпадать с плоским слоем страницы (без тени).
+**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).
 
 ## About
 
-Composable surfaces for **dashboard KPIs**, **lists**, **CTA tiles**, **split metrics**, **media headers**, and **chart shells**: layout presets driven by **`variant`** on **`Card.Root`**. Typography and spacing use semantic tokens (`--prime-sys-*`). The kit does not ship chart primitives — pass any chart, SVG sparkline, or [ProgressBar](../progress-bar/COMPONENT.md) into **`Card.Media`**, **`Card.Chart`** (**`panel`**, edge-to-edge), padded **`Card.Body`**, or **`Card.Cover`**.
+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`**.
 
-**Ссылки на паттерны карточек и дашбордов (для ориентира по типам плиток):**
-
-1. [Material Design 3 — Cards (guidelines)](https://m3.material.io/components/cards/guidelines)
-2. [IBM Carbon — Tile (usage)](https://carbondesignsystem.com/components/tile/usage/)
-3. [Ant Design — Card](https://ant.design/components/card)
-4. [Shopify Polaris — Legacy Card](https://polaris.shopify.com/components/layout-and-structure/legacy-card)
-5. [shadcn/ui — Card](https://ui.shadcn.com/docs/components/card)
-6. [Atlassian Design — Composition](https://atlassian.design/get-started/develop/composition)
-7. [PatternFly — Card](https://www.patternfly.org/components/card/)
-8. [GOV.UK Design System — Card](https://design-system.service.gov.uk/components/card/)
-9. [Nielsen Norman Group — Dashboard Design](https://www.nngroup.com/articles/dashboard-design/)
-10. [GitHub Primer — Card](https://primer.style/product/components/card/)
-
-**Кратко по смыслу:** MD3 и большинство дизайн-систем описывают карточку как контейнер с заголовком, опциональным медиа и действиями; Carbon использует **tile** для группировки на сетке; в дашбордах часто выделяют KPI, списки активности, CTA и сравнение метрик — см. NN/g про структуру дашборда. **Responsive dashboards (prime-ui-kit):** CSS Grid для рядов KPI (`repeat(auto-fill, minmax(...))`) — [prime-ui skill](https://github.com/esurkov1/prime-ui/blob/main/SKILL/SKILL.md).
+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 **`IconBox`** + **`Stack`** row as **`mini`**, then **`Media`** for a sparkline, ring, or thin progress strip (full width below).
+- **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`** (buttons / links).
-- **Use** **`variant="list"`** for activity or alerts: **`ListHeader`** (e.g. **`Title`** + link), **`List`** / **`ListItem`**.
-- **Use** **`variant="split"`** for two related metrics: **`Split`** with two **`SplitCell`** blocks (typically **`Label`** + **`Value`** each). Optionally **`IconBox`** + **`Stack`** (same pattern as **`mini`**) — **`IconBox`** surface + label/value column.
-- **Use** **`variant="cover"`** for media on top: **`Cover`** (image or block), then **`Stack`** and optional **`Actions`**.
-- **Do not use** as the only focus target for navigation; wrap a [LinkButton](../link-button/COMPONENT.md) or make an inner control focusable instead of the whole card, unless you add explicit `role`/`tabIndex` and keyboard handling.
-- **Do not use** decorative icons without **`aria-hidden`** when the text repeats the meaning.
-
-## Composition
-
-- **`Card.Root`** — required **`variant`**: `"mini"` \| `"mini-media"` \| `"metric"` \| `"panel"` \| `"stat-trend"` \| `"cta"` \| `"list"` \| `"split"` \| `"cover"`. Optional **`flat`** removes the default surface shadow (tile-like). 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/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 elsewhere 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`**.
+- **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.
 
-### Mini example
+## Canonical example
 
-```tsx
-import { Card } from "prime-ui-kit";
-
-export function MiniKpi() {
-  return (
-    <Card.Root variant="mini">
-      <Card.IconBox aria-hidden>…</Card.IconBox>
-      <Card.Stack>
-        <Card.Label>Age</Card.Label>
-        <Card.Value>36 years</Card.Value>
-      </Card.Stack>
-    </Card.Root>
-  );
-}
-```
-
-### Mini + media example
+Rich **`panel`**: section header with trailing control, padded intro in **`Body`**, and an edge-to-edge **`Chart`** region for a real chart root.
 
 ```tsx
-import { Card } from "prime-ui-kit";
+import { Card, Icon, Typography } from "prime-ui-kit";
 
-export function MiniKpiWithSparkline() {
-  return (
-    <Card.Root variant="mini-media">
-      <Card.IconBox aria-hidden>…</Card.IconBox>
-      <Card.Stack>
-        <Card.Label>Glucose</Card.Label>
-        <Card.Value>5.4 mmol/L</Card.Value>
-      </Card.Stack>
-      <Card.Media>
-        <svg aria-hidden viewBox="0 0 120 40" />
-      </Card.Media>
-    </Card.Root>
-  );
-}
-```
-
-### Metric example
-
-```tsx
-import { Badge } from "prime-ui-kit";
-import { Card } from "prime-ui-kit";
-
-export function MetricCard() {
-  return (
-    <Card.Root variant="metric">
-      <Card.HeaderRow>
-        <Card.Lead>
-          <Badge.Root color="blue" variant="filled" size="s">
-            CRP
-          </Badge.Root>
-        </Card.Lead>
-        <Card.Value>1.8 mg/L</Card.Value>
-      </Card.HeaderRow>
-      <Card.Description>Slightly elevated</Card.Description>
-    </Card.Root>
-  );
-}
-```
-
-### Panel example (chart only)
-
-```tsx
-import { Card } from "prime-ui-kit";
-
-export function ChartSection() {
-  return (
-    <Card.Root variant="panel">
-      <Card.SectionHeader>
-        <Card.SectionTitle>Revenue</Card.SectionTitle>
-      </Card.SectionHeader>
-      <Card.Chart>
-        <div id="revenue-chart" />
-      </Card.Chart>
-    </Card.Root>
-  );
-}
-```
-
-### Panel example (padded content + chart)
-
-```tsx
-import { Card } from "prime-ui-kit";
-
-export function ChartSectionWithIntro() {
+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>
-        <p>Short summary or filters.</p>
+        <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" />
+        <div id="revenue-chart" aria-hidden />
       </Card.Chart>
     </Card.Root>
   );
 }
 ```
 
-### Stat + trend example
+## Extended examples
 
-```tsx
-import { Card } from "prime-ui-kit";
-
-export function StatTrendCard() {
-  return (
-    <Card.Root variant="stat-trend">
-      <Card.Label>Revenue (30d)</Card.Label>
-      <Card.Value>$420k</Card.Value>
-      <Card.Delta trend="up">+18% vs prior month</Card.Delta>
-    </Card.Root>
-  );
-}
-```
-
-### CTA example
-
-```tsx
-import { Button, Card, LinkButton } from "prime-ui-kit";
-
-export function CtaCard() {
-  return (
-    <Card.Root variant="cta">
-      <Card.Title>Export report</Card.Title>
-      <Card.CtaBody>Download a CSV for the selected period.</Card.CtaBody>
-      <Card.Actions>
-        <LinkButton.Root href="#">Download</LinkButton.Root>
-        <Button.Root mode="ghost" type="button" variant="neutral">
-          Cancel
-        </Button.Root>
-      </Card.Actions>
-    </Card.Root>
-  );
-}
-```
-
-### List example
-
-```tsx
-import { Card } from "prime-ui-kit";
-import { LinkButton } from "prime-ui-kit";
-
-export function ListCard() {
-  return (
-    <Card.Root variant="list">
-      <Card.ListHeader>
-        <Card.Title>Recent activity</Card.Title>
-        <LinkButton.Root href="#">View all</LinkButton.Root>
-      </Card.ListHeader>
-      <Card.List>
-        <Card.ListItem>Payment received</Card.ListItem>
-        <Card.ListItem>New comment on ticket #12</Card.ListItem>
-      </Card.List>
-    </Card.Root>
-  );
-}
-```
-
-### Split example
-
-```tsx
-import { Card } from "prime-ui-kit";
+Copy-oriented scenarios (English copy) live next to this file:
 
-export function SplitCard() {
-  return (
-    <Card.Root variant="split">
-      <Card.Split>
-        <Card.SplitCell>
-          <Card.IconBox>{/* icon */}</Card.IconBox>
-          <Card.Stack>
-            <Card.Label>Conversion</Card.Label>
-            <Card.Value>3.8%</Card.Value>
-          </Card.Stack>
-        </Card.SplitCell>
-        <Card.SplitCell>
-          <Card.IconBox>{/* icon */}</Card.IconBox>
-          <Card.Stack>
-            <Card.Label>AOV</Card.Label>
-            <Card.Value>$64</Card.Value>
-          </Card.Stack>
-        </Card.SplitCell>
-      </Card.Split>
-    </Card.Root>
-  );
-}
-```
+| File | Scenario |
+|------|----------|
+| [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 |
 
-### Cover example
+Playground: more live variants under `playground/snippets/card/` (e.g. **`flat`**, **`row`**, **`stat-trend`**, chart-only panel).
 
-```tsx
-import { Card } from "prime-ui-kit";
+## Composition
 
-export function CoverCard() {
-  return (
-    <Card.Root variant="cover">
-      <Card.Cover>
-        <img alt="" src="/hero.jpg" />
-      </Card.Cover>
-      <Card.Stack>
-        <Card.Title>Campaign</Card.Title>
-        <Card.Label>Last 7 days</Card.Label>
-        <Card.Description>Compared to control.</Card.Description>
-      </Card.Stack>
-    </Card.Root>
-  );
-}
-```
+- **`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 — not reading `headingSection` / `headingSubsection` roles, so KPI copy stays visually consistent with form density.
+- 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`** is an **`h3`**; ensure heading levels match the page outline (skip levels appropriately).
+- **`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`** (inset content), optional **`Chart`** (full bleed). 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 rows in a grid stay aligned, or use one column on narrow viewports.
+- **`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.
-- **`Title`** is an **`h3`** (like **`SectionTitle`**); avoid duplicate heading levels on the same screen.
-- Decorative content in **`Cover`** should not rely on **`img alt`** alone for critical information — repeat key facts in **`Stack`**.
+- 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.
 
 ## API
@@ -413,7 +231,7 @@ export function CoverCard() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | One metric column: **`Label`** + **`Value`**, or **`IconBox`** + **`Stack`** (as in **`mini`**) when using the icon tile. |
+| children | `React.ReactNode` | — | No | One metric column: **`Label`** + **`Value`**, or **`IconBox`** + **`Stack`**. |
 | …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Attributes on the cell `div`. |
 
 ### Card.ListHeader

package/src/components/card/examples/cover-banner.module.css

@@ -0,0 +1,8 @@
+.banner {
+  min-height: var(--prime-sys-unit-8rem);
+  background: linear-gradient(
+    135deg,
+    var(--prime-sys-color-status-information-background) 0%,
+    var(--prime-sys-color-surface-raised) 100%
+  );
+}

package/src/components/card/examples/cta-cover.tsx

@@ -0,0 +1,44 @@
+import { Button, Card, LinkButton } from "prime-ui-kit";
+
+import bannerStyles from "./cover-banner.module.css";
+
+/** CTA tile: title, supporting copy, actions. */
+export function CtaCardExample() {
+  return (
+    <Card.Root variant="cta">
+      <Card.Title>Export workspace report</Card.Title>
+      <Card.CtaBody>
+        Download a CSV of segments and metrics for the selected date range.
+      </Card.CtaBody>
+      <Card.Actions>
+        <LinkButton.Root href="#" size="s">
+          Download CSV
+        </LinkButton.Root>
+        <Button.Root mode="ghost" size="s" type="button" variant="neutral">
+          Configure columns
+        </Button.Root>
+      </Card.Actions>
+    </Card.Root>
+  );
+}
+
+/** Cover: decorative top region, then stack and primary action. */
+export function CoverCardExample() {
+  return (
+    <Card.Root variant="cover">
+      <Card.Cover aria-hidden>
+        <div className={bannerStyles.banner} />
+      </Card.Cover>
+      <Card.Stack>
+        <Card.Title>Spring campaign</Card.Title>
+        <Card.Label>Reach and clicks — last 7 days</Card.Label>
+        <Card.Description>Compared to the control group.</Card.Description>
+      </Card.Stack>
+      <Card.Actions>
+        <Button.Root mode="filled" size="s" type="button" variant="primary">
+          Open report
+        </Button.Root>
+      </Card.Actions>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,7 @@
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(min(100%, 14rem), 1fr));
+  gap: var(--prime-sys-spacing-l);
+  width: 100%;
+  min-width: 0;
+}

package/src/components/card/examples/list-card.tsx

@@ -0,0 +1,20 @@
+import { Card, LinkButton } from "prime-ui-kit";
+
+/** Activity feed with header action. */
+export function ListCardExample() {
+  return (
+    <Card.Root variant="list">
+      <Card.ListHeader>
+        <Card.Title>Recent activity</Card.Title>
+        <LinkButton.Root href="#" size="s">
+          View all
+        </LinkButton.Root>
+      </Card.ListHeader>
+      <Card.List>
+        <Card.ListItem>Payment received — order #4821 · 12:04</Card.ListItem>
+        <Card.ListItem>New review on “Tablet Pro”</Card.ListItem>
+        <Card.ListItem>Warehouse sync completed</Card.ListItem>
+      </Card.List>
+    </Card.Root>
+  );
+}

package/src/components/card/examples/media-mini.tsx

@@ -0,0 +1,55 @@
+import { Card, Icon, ProgressBar } from "prime-ui-kit";
+
+import layoutStyles from "./layout.module.css";
+import sparkStyles from "./sparkline.module.css";
+
+function MiniSparkline() {
+  return (
+    <svg
+      className={sparkStyles.spark}
+      viewBox="0 0 120 40"
+      preserveAspectRatio="none"
+      aria-hidden="true"
+    >
+      <path
+        d="M0 28 L20 24 L40 26 L60 14 L80 18 L100 10 L120 6"
+        fill="none"
+        strokeWidth="2"
+        vectorEffect="non-scaling-stroke"
+      />
+    </svg>
+  );
+}
+
+/** Compact KPI rows with chart or progress in `Card.Media`. */
+export function MediaMiniExample() {
+  return (
+    <div className={layoutStyles.grid}>
+      <Card.Root variant="mini-media">
+        <Card.IconBox aria-hidden>
+          <Icon name="field.email" aria-hidden />
+        </Card.IconBox>
+        <Card.Stack>
+          <Card.Label>Glucose</Card.Label>
+          <Card.Value>5.4 mmol/L</Card.Value>
+        </Card.Stack>
+        <Card.Media>
+          <MiniSparkline />
+        </Card.Media>
+      </Card.Root>
+
+      <Card.Root variant="mini-media">
+        <Card.IconBox aria-hidden>
+          <Icon name="nav.layoutGrid" aria-hidden />
+        </Card.IconBox>
+        <Card.Stack>
+          <Card.Label>API usage</Card.Label>
+          <Card.Value>72%</Card.Value>
+        </Card.Stack>
+        <Card.Media>
+          <ProgressBar.Root value={72} size="s" />
+        </Card.Media>
+      </Card.Root>
+    </div>
+  );
+}