prime-ui-kit 0.7.11 → 0.9.0

package/src/components/tabs/COMPONENT.md

@@ -1,147 +1,187 @@
 # Tabs
 
-**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
+**Category:** navigation
 
-## About
+> Tabs for navigating between content panels of one screen.
 
-Compound tabs: a `tablist` of triggers, an animated indicator, and one visible `tabpanel` at a time. Values on `Tabs.Tab` and `Tabs.Panel` must align so the active pair matches.
+## When to use
+- Splitting one screen into sections that are viewed one at a time (Overview / Orders / Reviews).
+- Settings pages with a side list of sections (`orientation="vertical"`).
+- Dashboard sections that need a counter or a one-line summary per tab (`Tabs.Count`, `Tabs.Description`).
 
-**When to use**
-
-- Switching sections on one view (settings areas, product detail blocks, dashboard sub-views) without a full route change.
-- Controlled `value` / `onValueChange` when the active tab must follow the URL, client store, or a wizard step.
-- `orientation="vertical"` for a sidebar-style rail next to the main panel (see settings layout recipes in the kit).
-
-**When not to use**
-
-- Primary navigation between top-level pages — prefer links and routes (see [Breadcrumb](../breadcrumb/COMPONENT.md) for hierarchy).
-- Two to four lightweight mutually exclusive options without rich panels — consider [SegmentedControl](../segmented-control/COMPONENT.md).
-- Expecting inactive panel subtrees to stay mounted — hidden panels are not rendered (see Rules).
-
-## Composition
-
-- **`Tabs.Root`** — context wrapper (`div` with `data-orientation`, `data-size`). Place **`Tabs.List`** and **`Tabs.Panel`** in tree order (list first, then panels) for a typical reading order; panels may sit inside a layout wrapper as long as they remain under the same root.
-- **`Tabs.List`** — `role="tablist"` with `aria-orientation`, keyboard handling, indicator, and **`ControlSizeProvider`**. Children should be **`Tabs.Tab`** triggers only.
-- **`Tabs.Tab`** — `role="tab"` / `button type="button"`. Optional **`Tabs.Icon`** and **`Tabs.Label`**; `value` must match a **`Tabs.Panel`** `value`.
-- **`Tabs.Panel`** — `role="tabpanel"`; renders **only** when its `value` equals the root’s active value.
-
-### Canonical example
+## When not to use
+- Choosing a value or a mode (period, list view, filter) → use [SegmentedControl](../segmented-control/COMPONENT.md).
+- Toolbar toggles or joined actions → use [ButtonGroup](../button-group/COMPONENT.md).
+- Collapsible sections that can be open together → use [Accordion](../accordion/COMPONENT.md).
+- Steps of a sequential process → use [Stepper](../stepper/COMPONENT.md).
+- App-level navigation between pages → use [Sidebar](../../layout/sidebar/COMPONENT.md).
 
+## Import
 ```tsx
-import { Tabs, Typography } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <Tabs.Root defaultValue="general">
-      <Tabs.List>
-        <Tabs.Tab value="general">
-          <Tabs.Label>General</Tabs.Label>
-        </Tabs.Tab>
-        <Tabs.Tab value="privacy">
-          <Tabs.Label>Privacy</Tabs.Label>
-        </Tabs.Tab>
-      </Tabs.List>
-      <Tabs.Panel value="general">
-        <Typography.Root as="p" variant="body-default" tone="muted">
-          Workspace name, locale, and default landing behavior.
-        </Typography.Root>
-      </Tabs.Panel>
-      <Tabs.Panel value="privacy">
-        <Typography.Root as="p" variant="body-default" tone="muted">
-          Data retention, export, and who can see activity in this project.
-        </Typography.Root>
-      </Tabs.Panel>
-    </Tabs.Root>
-  );
-}
+import { Tabs } from "prime-ui-kit";
 ```
 
-### Scenarios (playground + `examples/`)
-
-Live demos use **`playground/snippets/tabs/*.tsx`** (see **`playground/sections/TabsSection.tsx`**). The same scenarios have package-oriented copies under **`examples/`** (aligned with those snippets).
-
-| Scenario | Notes | Example |
-|----------|--------|---------|
-| Sizes | Four rows: `size` **`s`** / **`m`** / **`l`** / **`xl`**. First tab: **`Tabs.Icon`** + **`Tabs.Label`**; others **`Tabs.Label`** only. | [`./examples/06-sizes-s-m-l-xl.tsx`](./examples/06-sizes-s-m-l-xl.tsx) |
-| States | One **`Tabs.Tab`** with **`disabled`** — no click, skipped in arrow-key cycle. | [`./examples/07-horizontal-disabled.tsx`](./examples/07-horizontal-disabled.tsx) |
-| Orientation | **`orientation="vertical"`** — list beside panels; vertical arrow keys. | [`./examples/01-settings-vertical-rail.tsx`](./examples/01-settings-vertical-rail.tsx) |
-| Controlled | **`value`** + **`onValueChange`** on **`Tabs.Root`** (URL, store, wizard step). | [`./examples/05-controlled-active-tab.tsx`](./examples/05-controlled-active-tab.tsx) |
-| Composition | Several **`Tabs.Icon`** slots per trigger (left/right of **`Tabs.Label`**) and two icons in one tab. | [`./examples/03-tab-triggers-with-icons.tsx`](./examples/03-tab-triggers-with-icons.tsx) |
-| Full width | No **`fullWidth`** prop: **`className`** on root / **`Tabs.List`** / **`Tabs.Tab`** (`w-full`, **`flex-1`**, **`min-w-0`**) so triggers share width. | [`./examples/02-dashboard-subviews.tsx`](./examples/02-dashboard-subviews.tsx) |
-| Long labels | Narrow container; **`Tabs.Label`** truncates with ellipsis without wrapping the whole tab row. | [`./examples/04-long-labels-narrow.tsx`](./examples/04-long-labels-narrow.tsx) |
-
-**LLM note:** Prefer reading `./examples/*.tsx` for runnable scenarios; this page keeps rules + API tables authoritative.
-
-## Rules
-
-- **Uncontrolled:** omit `value`, set `defaultValue` on `Tabs.Root` (implementation default for `defaultValue` is `""` if omitted). **Controlled:** pass `value` and `onValueChange`; state follows `useControllableState` semantics.
-- **Disabled tabs:** `disabled` on `Tabs.Tab` sets native `disabled`, `data-disabled`, and excludes the tab from arrow-key traversal; disabled targets are skipped.
-- **Keyboard** (focus inside `Tabs.List`): **ArrowLeft** / **ArrowRight** in horizontal mode, **ArrowUp** / **ArrowDown** in vertical mode; **Home** / **End** move to first / last **enabled** tab; focus moves to the newly selected tab after arrow navigation.
-- **Focus order:** the selected tab has `tabIndex={0}`; others use `tabIndex={-1}`.
-- **ARIA:** `aria-controls` / `aria-labelledby` wire tab buttons to panels; list `aria-orientation` mirrors `orientation`.
-- **`Tabs.Icon`** sets `aria-hidden="true"` on the wrapper span; ensure the tab still has a clear name (e.g. `Tabs.Label` or visible text).
-- **Inactive panels:** `Tabs.Panel` returns `null` when inactive—avoid putting expensive trees in panels without app-level lazy loading or conditional data fetching.
-- **No `asChild`:** each tab is always a `<button>`; there is no built-in URL synchronization.
-- **Pairs:** for every panel `value` you expose, provide a corresponding tab (and vice versa) so the tab/panel relationship stays consistent for assistive tech.
-- **Layout:** full-width or custom layout uses `className` and your own flex/grid CSS on the root, list, or tabs—there is no dedicated `fullWidth` prop on `Tabs`.
+## Anatomy
+- `Tabs.Root` — state, size and orientation; lays out the list and the panel.
+  - `Tabs.List` — `role="tablist"` with the sliding indicator; scrolls instead of wrapping.
+    - `Tabs.Trigger` — one tab (`role="tab"`). Plain text, or parts:
+      - `Tabs.Icon` — decorative icon.
+      - `Tabs.Label` — title; truncates, keeps a stable width when it becomes medium weight.
+      - `Tabs.Count` — counter badge, one tier below the tabs size.
+      - `Tabs.Description` — muted second line; makes the trigger two-line.
+  - `Tabs.Panel` — `role="tabpanel"`, rendered only while its tab is active.
 
 ## API
+No part forwards a ref.
 
 ### Tabs.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string` | — | No | Active tab in controlled mode; must match **`value`** on one **`Tabs.Tab`**. |
-| defaultValue | `string` | `""` | No | Initial tab when uncontrolled (omit **`value`**). |
-| onValueChange | `(value: string) => void` | — | No | Fired when the user or keyboard changes the tab. |
-| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | No | Tab list axis and arrow-key direction (**Left/Right** vs **Up/Down**). |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Trigger height, type scale, padding, and icon size from one control token tier. |
-| children | `React.ReactNode` | — | Yes | **`Tabs.List`**, **`Tabs.Tab`**, **`Tabs.Panel`**, and layout wrappers under the same root. |
-| className | `string` | — | No | Extra class on the root wrapper (e.g. **`w-full`** on a card). |
++ native `<div>` props (except `defaultValue`, `children`).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Active tab (controlled). |
+| `defaultValue` | `string` | `""` | Initial active tab (uncontrolled). With `""` no tab is selected. |
+| `onValueChange` | `(value: string) => void` | — | Called when the active tab changes. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | List direction and arrow keys. A vertical list stacks above the panel when the container is narrower than 600px. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier: tab height, text, icon, radius, spacing. |
+| `children` | `ReactNode` | — (required) | `Tabs.List` and `Tabs.Panel`s. |
+| `className` | `string` | — | Extra class on the root. |
 
 ### Tabs.List
++ native `<div>` props (pass `aria-label`) except `role`, `aria-orientation`, `onKeyDown`, `onScroll` — they are set after the spread and override yours.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | Yes | **`Tabs.Tab`** triggers; the active indicator is rendered inside the list. |
-| className | `string` | — | No | Class on **`role="tablist"`** (e.g. stretch to full width). |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | `Tabs.Trigger`s. |
+| `className` | `string` | — | Extra class. |
 
-### Tabs.Tab
+### Tabs.Trigger
++ native `<button>` props except `value`, `children`, `type`, `role`, `onClick`.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string` | — | Yes | Unique id; must match the associated **`Tabs.Panel`** **`value`**. |
-| disabled | `boolean` | `false` | No | Not selectable; omitted from arrow-key focus order. |
-| children | `React.ReactNode` | — | Yes | Button contents: **`Tabs.Icon`**, **`Tabs.Label`**, or custom markup. |
-| className | `string` | — | No | Class on the trigger (e.g. **`flex-1`**, **`min-w-0`** for full-width rows). |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — (required) | Value that selects this tab and its panel. |
+| `disabled` | `boolean` | `false` | Disables the tab; arrow keys skip it. |
+| `children` | `ReactNode` | — (required) | Plain text (auto-wrapped in `Tabs.Label`) or `Tabs.Icon` / `Tabs.Label` / `Tabs.Count` / `Tabs.Description`. |
+| `className` | `string` | — | Extra class. |
 
-### Tabs.Icon
+### Tabs.Icon, Tabs.Label, Tabs.Description
++ native `<span>` props.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | Yes | Icon (e.g. kit **`Icon`**); wrapper uses **`aria-hidden`**. |
-| className | `string` | — | No | Class on the `span` |
-| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other span attributes |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Icon SVG / title text / second-line text (wrap a key value in `<strong>`). |
+| `className` | `string` | — | Extra class. |
 
-### Tabs.Label
+### Tabs.Count
+No native props.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | Yes | Tab label text; can ellipsis when space is tight. |
-| className | `string` | — | No | Class on the `span` |
-| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other span attributes |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Badge hue. |
+| `children` | `ReactNode` | — (required) | The number. |
+| `className` | `string` | — | Extra class. |
 
 ### Tabs.Panel
++ native `<div>` props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — (required) | Tab value this panel belongs to. |
+| `children` | `ReactNode` | — (required) | Panel content. |
+| `className` | `string` | — | Extra class. |
+
+## Variants
+Tabs have no `variant`: navigation tabs are always underline (horizontal) or pill (vertical).
+
+### orientation
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `horizontal` | regular-weight secondary text over a `border-subtle` hairline; the active tab is primary text, medium weight, with a 2px accent bar under its text that slides between tabs | switching sections above the content | yes |
+| `vertical` | items padded like controls, no rail; active item is a `fill-muted` pill with a short accent mark at the start; hover `fill-subtle`; below a 600px container it becomes a scrolling row above the panel | settings pages with a side list of sections | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28px tabs, 12/16 text, gap between tabs 12 | dense panels | |
+| `s` | 32px, 13/20, gap 16 | compact cards | |
+| `m` | 36px, 14/20, gap 20 | default | yes |
+| `l` | 40px, 16/24, gap 24 | page-level sections | |
+| `xl` | 48px, 16/24, gap 32 | hero / landing sections | |
+
+Tab height equals the control height: Tabs line up with Button, Input and SegmentedControl of the same `size`.
+
+### Trigger content
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| text | label only | most tabs | yes |
+| `Tabs.Icon` + `Tabs.Label` | muted icon before the label; the active tab's leading icon turns accent | sections with recognizable icons | |
+| `Tabs.Count` | soft badge after the label, one badge tier below the tabs size, tabular numbers | showing how many items a section has | |
+| `Tabs.Description` (two-line) | label (+ count) on line 1, `body-s` muted text on line 2; tab height grows; `<strong>` is primary/medium | dashboards with a summary per section | |
+
+**Combinations**
+- Recommended: `Tabs.Count color="blue"` on the active tab and `gray` on others (see `controlled.tsx`); per-section hues in two-line dashboards.
+- Avoid: icons on only some tabs; a `Tabs.Description` on only some tabs (rows of uneven height); Tabs used as a filter — use SegmentedControl.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| active | `value` / `defaultValue` | trigger `aria-selected="true"`, `data-state="active"`, `tabIndex=0`; others `data-state="inactive"`, `tabIndex=-1` |
+| hover | pointer | text → primary (vertical: `fill-subtle` background) |
+| focus-visible | keyboard | focus ring inside the tab (`--prime-focus-offset-inset`); panel shows the outer ring |
+| disabled | `disabled` on Trigger | native `disabled`, `data-disabled="true"`, `text-disabled` |
+| two-line | `Tabs.Description` child | `data-two-line="true"` |
+| overflow | list wider than its container | `data-overflow-start` / `data-overflow-end="true"` on the list, faded edges; the active tab scrolls into view |
+
+Other attributes: Root `data-orientation`, `data-size`; List `data-indicator="bar" | "pill"`; Trigger `data-value`; Label `data-text`. Controlled: `value` + `onValueChange`; uncontrolled: `defaultValue`. Inactive panels are unmounted.
+
+## Layout & spacing
+- List → panel: `var(--prime-space-4)`; vertical list → panel: `var(--prime-space-6)`.
+- The list never wraps; it scrolls horizontally with faded edges. Give the list's container a width (`min-width: 0` on flex children).
+- In a vertical layout align the panel heading with the first tab by making the heading row one control tall (`min-height: var(--prime-control-m-height)`).
+
+## Accessibility
+- WAI-ARIA tabs pattern: `tablist` / `tab` / `tabpanel` with `aria-controls` / `aria-labelledby` wired automatically; give `Tabs.List` an `aria-label`.
+- Keyboard: horizontal ← →, vertical ↑ ↓ (← → also work), Home / End; selection follows focus and wraps; disabled tabs are skipped. Roving tabindex — Tab enters the active tab, then moves to the panel (`tabIndex=0`).
+- In a two-line tab the accessible name is label (+ count); `Tabs.Description` becomes `aria-describedby`.
+- `Tabs.Icon` is `aria-hidden`. No `labels` keys.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [horizontal.tsx](examples/horizontal.tsx) | Underline tabs with panels | switching panels of one screen |
+| [sizes.tsx](examples/sizes.tsx) | Every size next to a Button of the same size | aligning tabs with controls |
+| [states.tsx](examples/states.tsx) | Icons, disabled tab, overflow at phone width | icons, unavailable sections, narrow screens |
+| [controlled.tsx](examples/controlled.tsx) | `value` + `onValueChange` with `Tabs.Count` | tab in app state / URL |
+| [two-line.tsx](examples/two-line.tsx) | Label + Count + Description | dashboards with per-section summary |
+| [vertical.tsx](examples/vertical.tsx) | Vertical settings tabs in a card | settings pages |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string` | — | Yes | Must match the active **`Tabs.Tab`**; otherwise the panel is not rendered (**`null`**). |
-| children | `React.ReactNode` | — | Yes | **`role="tabpanel"`** body below (or beside) the list. |
-| className | `string` | — | No | Class on the panel `div` |
+```tsx
+import { Tabs } from "prime-ui-kit";
 
-## Related
+export function ShopTabs() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List aria-label="Магазин">
+        <Tabs.Trigger value="overview">Обзор</Tabs.Trigger>
+        <Tabs.Trigger value="orders">Заказы</Tabs.Trigger>
+      </Tabs.List>
+      <Tabs.Panel value="overview">Сводка по магазину.</Tabs.Panel>
+      <Tabs.Panel value="orders">Последние заказы.</Tabs.Panel>
+    </Tabs.Root>
+  );
+}
+```
+
+## Mistakes
+- `<Tabs.Root>` without `defaultValue`/`value` → no tab is active; pass the first tab's value.
+- `variant="pills"` / `variant="underline"` → Tabs have no variant; use `orientation`, or SegmentedControl for a pill switch.
+- Using Tabs to filter a list → use SegmentedControl.
+- `onClick` on `Tabs.Trigger` → use `onValueChange` on Root.
+- `Tabs.List` without `aria-label` → add one.
 
-- [Typography](../typography/COMPONENT.md)
+## Related
 - [SegmentedControl](../segmented-control/COMPONENT.md)
-- [Breadcrumb](../breadcrumb/COMPONENT.md)
-- **Icon** — use inside `Tabs.Icon` for glyphs sized with the tab control tokens
+- [ButtonGroup](../button-group/COMPONENT.md)
+- [Accordion](../accordion/COMPONENT.md)
+- [Badge](../badge/COMPONENT.md)

package/src/components/tabs/examples/controlled.tsx

@@ -0,0 +1,39 @@
+/** Controlled tabs (`value` + `onValueChange`) with `Tabs.Count` counters. Use when the active tab lives in app state or the URL. */
+import { Tabs, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const tabs = [
+  { value: "new", label: "Новые", count: 12 },
+  { value: "progress", label: "В работе", count: 5 },
+  { value: "done", label: "Готово", count: 148 },
+];
+
+export default function TabsControlledExample() {
+  const [value, setValue] = React.useState("new");
+  const current = tabs.find((t) => t.value === value);
+
+  return (
+    <Tabs.Root value={value} onValueChange={setValue}>
+      <Tabs.List aria-label="Заявки">
+        {tabs.map((t) => (
+          <Tabs.Trigger key={t.value} value={t.value}>
+            <Tabs.Label>{t.label}</Tabs.Label>
+            <Tabs.Count color={t.value === value ? "blue" : "gray"}>{t.count}</Tabs.Count>
+          </Tabs.Trigger>
+        ))}
+      </Tabs.List>
+      {tabs.map((t) => (
+        <Tabs.Panel key={t.value} value={t.value}>
+          <Typography.Root variant="body-m" tone="secondary">
+            Заявок в разделе «{current?.label}»:{" "}
+            <Typography.Root as="span" variant="body-m" tone="muted" className={styles.count}>
+              {current?.count}
+            </Typography.Root>
+          </Typography.Root>
+        </Tabs.Panel>
+      ))}
+    </Tabs.Root>
+  );
+}

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

@@ -1,79 +1,98 @@
+/* Layout for the Tabs examples: semantic tokens only. */
+
 .stack {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-sys-spacing-m);
+  gap: var(--prime-space-8);
+  width: 100%;
+  min-width: 0;
 }
 
-.body {
-  margin: 0;
-  color: var(--prime-sys-color-content-secondary);
+.group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-2);
+  width: 100%;
+  min-width: 0;
 }
 
-.settingsRow {
+.sizes {
   display: flex;
-  flex-wrap: wrap;
-  gap: var(--prime-sys-spacing-l);
-  align-items: flex-start;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+  width: 100%;
+  min-width: 0;
 }
 
-.settingsContent {
-  flex: 1 1 0;
-  min-width: min(100%, 20rem);
+/* label · tabs · button of the same tier on one baseline row */
+.sizeRow {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-4);
+  min-width: 0;
 }
 
-.surface {
-  width: 100%;
-  max-width: min(100%, 36rem);
-  padding: var(--prime-sys-spacing-m);
-  border-radius: var(--prime-sys-shape-radius-m);
-  border: var(--prime-sys-unit-1px) solid var(--prime-sys-color-border-subtle);
+.sizeRow > :nth-child(2) {
+  flex: 0 1 auto;
+  min-width: 0;
 }
 
-.fullWidthRoot {
-  width: 100%;
-  min-width: 0;
+.caption {
+  flex: none;
+  width: var(--prime-space-8);
 }
 
-.fullWidthList {
-  width: 100%;
-  min-width: 0;
+/* ≈375px — a phone-width container. */
+.narrow {
+  width: min(100%, calc(var(--prime-drawer-width-s) + var(--prime-space-4)));
 }
 
-.flexTab {
-  flex: 1 1 0;
-  min-width: 0;
-  justify-content: center;
+.card {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+  width: min(100%, calc(var(--prime-modal-width-l) - var(--prime-space-4)));
+  padding: var(--prime-card-padding-m);
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-card-bg);
+  box-shadow: var(--prime-card-shadow);
+  --prime-color-field-bg: var(--prime-color-field-bg-surface);
 }
 
-.narrowShell {
-  width: 100%;
-  max-width: 12rem;
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+  max-width: calc(var(--prime-drawer-width-s) + var(--prime-space-6));
+}
+
+/* Settings panel: the heading row is one control tall, so it lines up with the first tab. */
+.section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
   min-width: 0;
 }
 
-.controlledCaption {
-  margin: var(--prime-sys-spacing-s) 0 0;
-  color: var(--prime-sys-color-content-muted);
-  font-size: var(--prime-sys-typography-role-bodySmall-fontSize);
+.sectionHead {
+  display: flex;
+  align-items: center;
+  min-height: var(--prime-control-m-height);
 }
 
-.sizesRow {
+.rows {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-sys-spacing-x6);
-  align-items: stretch;
-  width: 100%;
+  gap: var(--prime-space-5);
 }
 
-.sizesGroup {
+/* Fleet dashboard: two-line underline tabs across the frame. */
+.fleet {
   width: 100%;
   min-width: 0;
 }
 
-.sizesLabel {
-  margin: 0 0 var(--prime-sys-spacing-x2);
-  font-size: var(--prime-sys-size-control-s-supportText);
-  font-weight: var(--prime-sys-typography-weight-medium);
-  line-height: var(--prime-sys-typography-body-lineHeight);
-  color: var(--prime-sys-color-content-secondary);
+.count {
+  font-variant-numeric: tabular-nums;
 }

package/src/components/tabs/examples/horizontal.tsx

@@ -0,0 +1,30 @@
+/** Horizontal tabs: text over a hairline with a 2px accent bar under the active label that slides on change. Use to switch between panels of one screen. */
+import { Tabs, Typography } from "prime-ui-kit";
+
+const panels = [
+  { value: "overview", label: "Обзор", text: "Сводка по магазину за выбранный период." },
+  { value: "orders", label: "Заказы", text: "Последние заказы и их статусы." },
+  { value: "reviews", label: "Отзывы", text: "Новые отзывы покупателей." },
+  { value: "settings", label: "Настройки магазина", text: "Название, валюта и способы доставки." },
+];
+
+export default function TabsHorizontalExample() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List aria-label="Магазин">
+        {panels.map((p) => (
+          <Tabs.Trigger key={p.value} value={p.value}>
+            {p.label}
+          </Tabs.Trigger>
+        ))}
+      </Tabs.List>
+      {panels.map((p) => (
+        <Tabs.Panel key={p.value} value={p.value}>
+          <Typography.Root variant="body-m" tone="secondary">
+            {p.text}
+          </Typography.Root>
+        </Tabs.Panel>
+      ))}
+    </Tabs.Root>
+  );
+}

package/src/components/tabs/examples/sizes.tsx

@@ -0,0 +1,30 @@
+/** Tabs at every size tier next to a Button of the same size; the tab height equals the control height. Use to align tabs with toolbar controls. */
+import { Button, type ControlSize, Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const sizes: ControlSize[] = ["xs", "s", "m", "l", "xl"];
+
+export default function TabsSizesExample() {
+  return (
+    <div className={styles.sizes}>
+      {sizes.map((size) => (
+        <div key={size} className={styles.sizeRow}>
+          <Typography.Root as="span" variant="code" tone="muted" className={styles.caption}>
+            {size}
+          </Typography.Root>
+          <Tabs.Root size={size} defaultValue="all">
+            <Tabs.List aria-label={`Заявки, ${size}`}>
+              <Tabs.Trigger value="all">Все</Tabs.Trigger>
+              <Tabs.Trigger value="active">Активные</Tabs.Trigger>
+              <Tabs.Trigger value="archive">Архив</Tabs.Trigger>
+            </Tabs.List>
+          </Tabs.Root>
+          <Button.Root variant="outline" tone="neutral" size={size}>
+            Фильтр
+          </Button.Root>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/tabs/examples/states.tsx

@@ -0,0 +1,61 @@
+/** Icons with labels, a disabled tab skipped by arrows, and overflow in a phone-width container (scrolls with faded edges). Use to check icon, disabled and narrow-screen behaviour. */
+import { Bell, CreditCard, Shield, User } from "lucide-react";
+import { Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function TabsStatesExample() {
+  return (
+    <div className={styles.stack}>
+      <div className={styles.group}>
+        <Typography.Root variant="caption" weight="medium" tone="secondary">
+          Иконки и disabled
+        </Typography.Root>
+        <Tabs.Root defaultValue="profile">
+          <Tabs.List aria-label="Аккаунт">
+            <Tabs.Trigger value="profile">
+              <Tabs.Icon>
+                <User />
+              </Tabs.Icon>
+              <Tabs.Label>Профиль</Tabs.Label>
+            </Tabs.Trigger>
+            <Tabs.Trigger value="security">
+              <Tabs.Icon>
+                <Shield />
+              </Tabs.Icon>
+              <Tabs.Label>Безопасность</Tabs.Label>
+            </Tabs.Trigger>
+            <Tabs.Trigger value="billing" disabled>
+              <Tabs.Icon>
+                <CreditCard />
+              </Tabs.Icon>
+              <Tabs.Label>Оплата</Tabs.Label>
+            </Tabs.Trigger>
+          </Tabs.List>
+        </Tabs.Root>
+      </div>
+
+      <div className={styles.group}>
+        <Typography.Root variant="caption" weight="medium" tone="secondary">
+          Переполнение в 375px
+        </Typography.Root>
+        <div className={styles.narrow}>
+          <Tabs.Root defaultValue="notifications">
+            <Tabs.List aria-label="Настройки">
+              <Tabs.Trigger value="general">Общие</Tabs.Trigger>
+              <Tabs.Trigger value="team">Команда</Tabs.Trigger>
+              <Tabs.Trigger value="notifications">
+                <Tabs.Icon>
+                  <Bell />
+                </Tabs.Icon>
+                <Tabs.Label>Уведомления</Tabs.Label>
+              </Tabs.Trigger>
+              <Tabs.Trigger value="integrations">Интеграции</Tabs.Trigger>
+              <Tabs.Trigger value="api">API</Tabs.Trigger>
+            </Tabs.List>
+          </Tabs.Root>
+        </div>
+      </div>
+    </div>
+  );
+}