prime-ui-kit 0.2.5 → 0.3.1

package/src/components/card/COMPONENT.md

@@ -0,0 +1,489 @@
+# Card
+
+**Проектирование по умолчанию:** для демо и экранов используйте **`variant`** и слоты как в примерах ниже; **`flat`** включайте, когда карточка должна визуально совпадать с плоским слоем страницы (без тени).
+
+## 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`**.
+
+**Ссылки на паттерны карточек и дашбордов (для ориентира по типам плиток):**
+
+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).
+
+- **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="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`**.
+
+### Mini 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
+
+```tsx
+import { Card } 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() {
+  return (
+    <Card.Root variant="panel">
+      <Card.SectionHeader>
+        <Card.SectionTitle>Revenue</Card.SectionTitle>
+      </Card.SectionHeader>
+      <Card.Body>
+        <p>Short summary or filters.</p>
+      </Card.Body>
+      <Card.Chart>
+        <div id="revenue-chart" />
+      </Card.Chart>
+    </Card.Root>
+  );
+}
+```
+
+### Stat + trend example
+
+```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";
+
+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>
+  );
+}
+```
+
+### Cover example
+
+```tsx
+import { Card } from "prime-ui-kit";
+
+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>
+  );
+}
+```
+
+## 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.
+- 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).
+- **`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.
+- 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`**.
+- **`List`** uses a real **`ul`**; keep **`ListItem`** text meaningful for screen readers.
+
+## 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. |
+
+### 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
+
+| 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`. |
+
+### Card.Media
+
+| 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`. |
+
+### Card.Title
+
+| 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`. |
+
+### 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`** (as in **`mini`**) when using the icon tile. |
+| …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
+
+| 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`. |
+
+### Card.Body
+
+| 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 | 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.

package/src/components/checkbox/COMPONENT.md

@@ -0,0 +1,98 @@
+# Checkbox
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A compound checkbox: a visually hidden native `input type="checkbox"`, a decorative box with check or indeterminate mark, and optional label, hint, and error text wired to `aria-describedby` and invalid state.
+
+- **When to use** — explicit consent, terms, or other “yes/no” fields that submit with the form (`name`, `value`, `required`).
+- **When to use** — row or “select all” patterns where the parent shows **indeterminate** when only some children are checked.
+- **When to use** — independent toggles (filters, optional features) rather than one-of-many choices.
+- **When to use** — hint text or inline validation aligned under the label column.
+- **When not to use** — exactly one option from a set of alternatives (prefer [Radio](../radio/COMPONENT.md)).
+- **When not to use** — a single binary setting where a switch fits the product language (prefer [Switch](../switch/COMPONENT.md)).
+- **When not to use** — you need `asChild` or fully custom markup; the control is a fixed [Label](../label/COMPONENT.md) row with a hidden input and SVG.
+
+## Composition
+
+- **`Checkbox.Root`** — wraps the field in a `div` with `data-size`, `data-variant`, `data-disabled`, `data-invalid`, `data-checked`, `data-indeterminate`; provides context and `ControlSizeProvider` for child parts.
+- **`Checkbox.Label`** — required for the control: hosts the native checkbox and decorative SVG, then optional text in a trailing column; sets `htmlFor` to the input id.
+- **`Checkbox.Hint`** — optional; registers hint text and contributes its id to the input’s `aria-describedby`.
+- **`Checkbox.Error`** — optional; error-styled [Hint](../hint/COMPONENT.md) and registers invalid state when mounted (with `variant="error"` on the root when you want error chrome without the slot).
+- **Order:** `Root` → `Label` (always) → `Hint` / `Error` below when needed. Public API: `Checkbox` with `Root`, `Label`, `Hint`, `Error`.
+
+### Minimal example
+
+```tsx
+import { Checkbox } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Checkbox.Root name="terms" value="yes">
+      <Checkbox.Label>Accept terms</Checkbox.Label>
+    </Checkbox.Root>
+  );
+}
+```
+
+## Rules
+
+- Вертикальный ритм между **подписью и hint** задаётся самим компонентом; не вставляйте между ними лишний [Typography](../typography/COMPONENT.md) с другой ролью чтения без необходимости.
+- Support **controlled** (`checked` + `onChange`) and **uncontrolled** (`defaultChecked`); internal state updates from the change handler before your `onChange` runs.
+- **`indeterminate`** only affects visuals and the DOM `indeterminate` property; it is not a separate submitted value—clear or sync it in your handler when the user clicks.
+- Set **`aria-label`** or **`aria-labelledby`** on **`Checkbox.Root`** when **`Checkbox.Label`** has no visible text (icon-only or header “select all” cell).
+- **`aria-describedby`** on the root is merged with hint and error ids when those slots are mounted; include your own ids in `aria-describedby` if you need extra descriptors.
+- **`variant="error"`** or a mounted **`Checkbox.Error`** sets `aria-invalid` and error styling; **`disabled`** disables the input and dims hint styling.
+- Focus and keyboard activation use the native checkbox; the visible focus ring targets the decorative control via `focus-visible`.
+- There is no loading or `asChild` API; **`size`** on the root does not forward to the DOM input (layout token only).
+
+## API
+
+### Checkbox.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| variant | `"default" \| "error"` | `"default"` | no | Error-colored outline for `error`; `invalid` is also true when `Checkbox.Error` is mounted. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Box and typography scale. |
+| indeterminate | `boolean` | `false` | no | Indeterminate visuals; syncs `input.indeterminate`. |
+| id | `string` | auto (`useId`) | no | Stable input id; paired with `Checkbox.Label` via `htmlFor`. |
+| className | `string` | — | no | Class on the field wrapper `div`. |
+| checked | `boolean` | — | no | Controlled checked state. |
+| defaultChecked | `boolean` | `false` | no | Initial checked state when uncontrolled. |
+| onChange | `React.ChangeEventHandler<HTMLInputElement>` | — | no | Fired on toggle; internal checked state updates before this runs. |
+| disabled | `boolean` | — | no | Disables the input and label row. |
+| aria-describedby | `string` | — | no | Combined with hint and error ids when those slots exist. |
+| children | `React.ReactNode` | — | no | Typically `Label`, optional `Hint` / `Error`. |
+| ref | `React.Ref<HTMLInputElement>` | — | no | Ref to the native checkbox input. |
+| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | — | no | Other native attributes forwarded to the hidden `input` (e.g. `name`, `value`, `required`, `readOnly`, `form`). `type` is always `checkbox`. |
+
+### Checkbox.Label
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | no | Label text beside the box; omit for a box-only control and set an accessible name on `Root`. |
+| className | `string` | — | no | Class on the label row. |
+| …rest | `Omit<React.HTMLAttributes<HTMLLabelElement>, "htmlFor" \| "size">` | — | no | Other label attributes; `htmlFor` is managed internally. |
+
+### Checkbox.Hint
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Supplementary text below the label. |
+| className | `string` | — | no | Additional class on the hint. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally. |
+
+### Checkbox.Error
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Error message text. |
+| className | `string` | — | no | Additional class on the message. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally. |
+
+## Related
+
+- [Radio](../radio/COMPONENT.md) — one-of-many choice with the same validation variants.
+- [Switch](../switch/COMPONENT.md) — binary setting with a different control pattern.
+- [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — primitives used inside the checkbox; pair with [Input](../input/COMPONENT.md) in larger forms.

package/src/components/code-block/COMPONENT.md

@@ -0,0 +1,58 @@
+# CodeBlock
+
+## About
+
+`CodeBlock` is a static presentation component: it renders a TS or TSX source string with syntax highlighting and a light or dark token palette. The kit exposes a single part, `Root`, which outputs a `pre` whose inner `code` markup is produced by `highlightTsxHtml`.
+
+- **When to use** — partner docs, marketing pages, or in-app help where you need a short snippet that matches the kit’s typography and theme.
+- **When to use** — API reference cards, integration guides, or internal tools showing request bodies, configs, or generated output you control.
+- **When to use** — pairing a snippet with surrounding copy (`Typography`, labels) where the block should stay non-interactive and read-only.
+- **When not to use** — raw or untrusted user input as `code` (markup is injected via `dangerouslySetInnerHTML`).
+- **When not to use** — languages other than TS/TSX or cases that need a full parser or line numbers, copy buttons, and tabs (add those in your app layer).
+- **When not to use** — when you need a focusable, editable code field (use an input or a dedicated editor instead).
+
+## Composition
+
+- The public API is the `CodeBlock` object with one subpart: **`Root`**.
+- **`Root`** renders a native **`pre`**. Highlighted content is injected as a single inner **`code`** element; do not pass `children` or `dangerouslySetInnerHTML` yourself — they are excluded from the props type.
+- Pass the source as the **`code`** string prop. Optional **`colorScheme`** selects the highlighting palette (`data-theme` on `pre`).
+
+### Minimal example
+
+```tsx
+import { CodeBlock } from "prime-ui-kit";
+
+export function Example() {
+  return <CodeBlock.Root code='export const n = 1;' />;
+}
+```
+
+## Rules
+
+- **`code`** is required. The implementation applies **`trimEnd()`** before highlighting; leading indentation in the string is preserved aside from trailing whitespace on the whole string.
+- **`colorScheme`** defaults to **`"light"`**; use **`"dark"`** when the block sits on a dark surface so token colors stay readable.
+- **Security:** inner HTML comes from **`highlightTsxHtml`**. Only pass **trusted** strings (constants, vetted CMS content, sanitized backend output).
+- **Highlighting** uses a TS/TSX-oriented heuristic in the kit, not a full language grammar — rare syntax may not get the expected classes.
+- **No built-in `size`:** font size and line height follow the parent; control rhythm with wrapper layout and typography tokens.
+- **Accessibility:** treat the block as static prose context; add **`aria-label`**, **`aria-describedby`**, or nearby headings via standard **`pre`** attributes spread from **`…rest`** when screen readers need an explicit label.
+- **Focus:** the component does not set **`tabIndex`**; make it focusable only if your UX requires it.
+
+## API
+
+### CodeBlock.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `code` | `string` | — | Yes | TS/TSX source; trailing whitespace is trimmed with `trimEnd()` before highlighting. |
+| `colorScheme` | `CodeBlockColorScheme` (`"light" \| "dark"`) | `"light"` | No | Token palette / `data-theme` on the root `pre`. |
+| `className` | `string` | — | No | Additional class on the root `pre`. |
+| `…rest` | `Omit<React.HTMLAttributes<HTMLPreElement>, "children" \| "dangerouslySetInnerHTML">` | — | No | Other native `pre` attributes (`id`, `style`, ARIA, `data-*`, event handlers, etc.). `children` and `dangerouslySetInnerHTML` are omitted. |
+
+The package also exports **`CodeBlockColorScheme`** and **`CodeBlockRootProps`** for typing.
+
+## Related
+
+- [Typography](../typography/COMPONENT.md) — headings and body copy around snippets.
+- [Button](../button/COMPONENT.md) — switching multiple samples from parent state.
+- [Segmented control](../segmented-control/COMPONENT.md) — compact mode or sample switching in toolbars.
+- [Kbd](../kbd/COMPONENT.md) — shortcut hints next to prose, without duplicating the code block’s role.