prime-ui-kit 0.7.13 → 0.9.1

package/src/components/tabs/COMPONENT.md

@@ -1,147 +1,254 @@
 # 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.
-
-## About
-
-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**
-
-- 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
-
+**Category:** navigation
+**Kind:** navigation
+
+> Folder tabs for navigating between content panels of one screen: the active tab rises out of the panel.
+
+## 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`).
+- Section bars that must survive narrow containers: with an icon on every tab they collapse to icons with tooltips.
+- Open documents or records the user switches between and closes, like browser tabs (`onRemove`, `minItemWidth`, `maxItemWidth`).
+
+## 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/`)
+## Anatomy
+```
+Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItemWidth; horizontal: the frame
+├─ Tabs.List              role="tablist" on a ScrollContainer, sliding folder / pill; collapses, then scrolls
+│  ├─ Tabs.Item           one tab (role="tab") in an item wrapper; onRemove adds a close button; parts:
+│  │  ├─ Tabs.Icon        decorative icon; hidden first, kept last
+│  │  ├─ Tabs.Label       title; keeps its width when it turns medium weight
+│  │  ├─ Tabs.Count       counter Badge, one tier below the tabs size
+│  │  └─ Tabs.Description muted second line; makes the tab two-line
+│  └─ Tabs.Separator      Divider hairline between groups of tabs
+└─ Tabs.Panel             role="tabpanel", rendered only while its tab is active
+```
 
-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).
+## API
 
-| 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) |
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-**LLM note:** Prefer reading `./examples/*.tsx` for runnable scenarios; this page keeps rules + API tables authoritative.
+### Tabs.Root
+`ref` → `HTMLDivElement`. `<div>` that owns the active value, size and orientation and lays out the list and the panel; horizontal, it is the frame: a sunken strip over the panel surface.
+
+| 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 with the new active value. |
+| `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: text, icon, spacing, folder radius and panel padding. A horizontal tab is the control height plus the folder rise on both sides; a vertical one is the control height. |
+| `fullWidth` | `boolean` | `true` | Horizontal tabs share the list width equally, within `minItemWidth` … `maxItemWidth`; `false` sizes each tab to its content within the same bounds. |
+| `tone` | `"neutral" \| "accent"` | `"neutral"` | Colour of the active tab: `neutral` is primary text with an accent icon, `accent` puts text and icon in accent. |
+| `minItemWidth` | `number \| string` | `2.5 × control height` | Narrowest a horizontal tab with a label gets, px or a CSS length; past it the list scrolls. Icon-only tabs are square. |
+| `maxItemWidth` | `number \| string` | `7 × control height` | Widest a horizontal tab gets, px or a CSS length (`"none"` lifts the cap); a longer label ends with an ellipsis. |
+| `labels` | `Partial<TabsLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — | `Tabs.List` and `Tabs.Panel`s. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">` | — | `className` and the other div attributes. |
 
-## Rules
+### Tabs.List
+`ref` → `HTMLDivElement`. `role="tablist"` on a `ScrollContainer` (horizontal, edge fade, hidden scrollbar) with the sliding folder (vertical: pill). When tabs do not fit or a label would be cut, it hides icons and descriptions, then labels (icons with tooltips stay; only when every tab has an icon); tabs then shrink to `minItemWidth` and the list scrolls.
 
-- **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`.
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | `Tabs.Item`s and `Tabs.Separator`s. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `aria-label` (name the list), `className` and the other div attributes; `role`, `aria-orientation` and `onKeyDown` are set by the list. |
 
-## API
+### Tabs.Item
+`ref` → `HTMLButtonElement`. One tab, a `<button role="tab">` in an item wrapper that also holds the close button of a removable tab; plain text children are wrapped in `Tabs.Label`.
 
-### Tabs.Root
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — (required) | Value that selects this tab and its panel. |
+| `disabled` | `boolean` | `false` | Disables the tab; clicks and arrow keys skip it. |
+| `onRemove` | `() => void` | — | Makes the tab closable: a close button (shown on the active tab, on hover and focus, always on touch screens), `Delete` / `Backspace` and a middle click. Closing the active tab first selects its neighbour; remove the item from your list here. |
+| `children` | `ReactNode` | — (required) | Plain text, or `Tabs.Icon` / `Tabs.Label` / `Tabs.Count` / `Tabs.Description`. A description makes the tab two-line. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" \| "type" \| "role" \| "onClick">` | — | `className`, `aria-*` and the other button attributes; your `onKeyDown` / `onAuxClick` run first and `preventDefault()` keeps the tab open. |
 
-| 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). |
+### Tabs.Icon
+`ref` → `HTMLSpanElement`. Decorative icon (`aria-hidden`) before the label; muted, accent on the active tab. Hidden first when tabs do not fit; the last thing left when nothing else fits.
 
-### Tabs.List
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="field.calendar" />`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
-| 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). |
+### Tabs.Label
+`ref` → `HTMLSpanElement`. Title; truncates and keeps a stable width when it turns medium weight.
 
-### Tabs.Tab
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Title text. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
-| 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). |
+### Tabs.Count
+`ref` → `HTMLSpanElement`. Counter `Badge` after the label, one tier below the tabs size.
 
-### Tabs.Icon
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Badge hue. |
+| `children` | `ReactNode` | — (required) | The number. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
-| 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 |
+### Tabs.Description
+`ref` → `HTMLSpanElement`. Muted second line; becomes the tab's `aria-describedby`.
 
-### Tabs.Label
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Second-line text; wrap a key value in `<strong>`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
-| 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 |
+### Tabs.Separator
+`ref` → `HTMLDivElement`. A `Divider` hairline between groups of tabs, across the list direction; hidden from assistive tech.
 
-### Tabs.Panel
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other div attributes. |
 
-| 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` |
+### Tabs.Panel
+`ref` → `HTMLDivElement`. `<div role="tabpanel">`, focusable, rendered only while its tab is active; horizontal, the padded surface the folder rises from. Its content enters each time it opens.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — (required) | Tab value this panel belongs to. |
+| `children` | `ReactNode` | — | Panel content. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
+
+## Variants
+Tabs have no `variant`: navigation tabs are always a folder (horizontal) or pills (vertical).
+
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | active tab in primary text, medium weight, its leading icon in `accent-text` | most screens | yes |
+| `accent` | active label and icon both in `accent-text` | the tabs are the main control of the screen and must read as selected at a glance | |
+
+### orientation
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `horizontal` | a `bg-sunken` strip over a padded `bg-surface` panel, tabs edge to edge; the active tab is the panel surface rising into the strip with concave flares, gliding between tabs; primary text, medium weight, accent icon; hover is the same shape in `fill-faint` | 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` | 12/16 text, folder radius 8, rise 4, panel padding 16 | dense panels | |
+| `s` | 13/20, radius 8, rise 4, padding 20 | compact cards | |
+| `m` | 14/20, radius 12, rise 8, padding 24 | default | yes |
+| `l` | 16/24, radius 16, rise 12, padding 24 | page-level sections | |
+| `xl` | 16/24, radius 16, rise 12, padding 32 | hero / landing sections | |
+
+A horizontal tab is the control height of the tier plus the rise above and below its content; a vertical tab is the control height, so a vertical list lines up with Button, Input and SegmentedControl of the same `size`.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fullWidth` | horizontal tabs share the list width equally (up to `maxItemWidth`), content centred; `false` sizes each tab to its content, the strip still spans the frame | `false` for tabs of very different label lengths | `true` |
+
+### minItemWidth · maxItemWidth
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| defaults | a horizontal tab is 2.5 to 7 control heights wide (90 … 252 at `m`); tabs never stretch into wide bars | most screens | yes |
+| lengths (`128`, `"16rem"`) | browser tabs: grow up to `maxItemWidth` with the label cut by an ellipsis past it, shrink to `minItemWidth` in a crowded list, then the list scrolls | open documents, records, chats — many tabs with long titles | |
+| `maxItemWidth="none"` | tabs share the whole strip | a few sections that must fill a wide frame | |
+
+### Item 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, 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; `<strong>` is primary / medium | dashboards with a summary per section | |
+| `onRemove` on Item | a ghost close button (`action.close`, two tiers below) at the end of the tab: on the active tab, on hover and focus, always on touch screens | open documents the user closes, like browser tabs | |
+
+Avoid icons or descriptions on only some tabs (uneven rows; without an icon on every tab the list cannot collapse to icons) and Tabs used as a filter — use SegmentedControl.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| active | `value` / `defaultValue` | item `aria-selected="true"`, `data-state="active"`, `tabIndex=0`; others `data-state="inactive"`, `tabIndex=-1` |
+| hover | pointer | text → primary; horizontal: the folder shape in `fill-faint`, under the folder; vertical: `fill-subtle` background |
+| pressed | pointer down | the tab content scales to `--prime-motion-press-scale-compact` |
+| focus-visible | keyboard | focus ring inside the tab, above the folder; the panel shows an inset ring (vertical: outer ring) |
+| disabled | `disabled` on Item | native `disabled`, `data-disabled="true"`, `text-disabled`; a removable tab loses its close button |
+| removable | `onRemove` on Item | item wrapper `data-removable="true"`, close button, tab `aria-keyshortcuts="Delete"` |
+| two-line | `Tabs.Description` child | `data-two-line="true"` |
+| collapsed | tabs wider than the list, or a label that would be cut (horizontal) | list `data-collapse="full" \| "compact" \| "icon"`: `compact` hides icons and descriptions; `icon` hides labels (sr-only, shown in a `Tooltip`), counts and close buttons, only when every tab has an icon |
+| overflow | tabs at `minItemWidth` (or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (ScrollContainer), faded edges; the active tab scrolls into view |
+
+Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; List `data-indicator="folder" | "pill"`; Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted; a panel's content enters each time it opens.
+
+## Layout & spacing
+- Horizontal: the root is the frame (`radius-xl`, `bg-sunken`), the list sits flush on the panel and runs edge to edge; the panel pads its content by tier (`--prime-space-4` … `--prime-space-8`). Do not wrap Tabs in a Card — it already is one.
+- Vertical list → panel: `var(--prime-space-6)`.
+- The list never wraps: it collapses, then scrolls horizontally with faded edges. Give the list's container a width (`min-width: 0` on flex children).
+- A vertical Tabs.Root is a size container: give it a width (it measures itself to switch to a row).
+- 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
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `ArrowLeft` · `ArrowRight` | Select the neighbouring tab, wrapping and skipping disabled ones; also work in a vertical list. |
+| `ArrowUp` · `ArrowDown` | The same in a vertical list. |
+| `Home` · `End` | First and last enabled tab. |
+| `Delete` · `Backspace` | Close a tab with `onRemove`; closing the active tab selects and focuses its neighbour. |
+| `Tab` | Enters the active tab (roving tabindex), then moves to the panel. |
+
+### ARIA
+- WAI-ARIA tabs pattern: `tablist` / `tab` / `tabpanel` with `aria-controls` / `aria-labelledby` wired automatically; give `Tabs.List` an `aria-label`.
+- Selection follows focus; the panel is focusable (`tabIndex=0`).
+- In a two-line tab the accessible name is label (+ count); `Tabs.Description` becomes `aria-describedby`.
+- `Tabs.Icon` and `Tabs.Separator` are `aria-hidden`.
+- When only icons are left, the label stays for screen readers (sr-only) and shows in a `Tooltip` on hover and focus.
+- The close button of a removable tab is named after it (`labels.remove`) and stays out of the Tab order; the tab announces `aria-keyshortcuts="Delete"`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `remove` | `"Закрыть вкладку «{label}»"` | Accessible name of the close button of a removable tab; `{label}` is the tab title (its value when the title is not text). |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Sections of one screen; the active tab rises into the panel and glides to the next one — `defaultValue`. |
+| [variants.tsx](examples/variants.tsx) | The active tab in primary text with an accent icon, or all in accent — `tone`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier: text, icon, folder radius and spacing grow together — `size`. |
+| [states.tsx](examples/states.tsx) | A disabled tab that clicks and arrow keys skip — `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | A muted icon before the label and a hairline before the service section — `Tabs.Icon`, `Tabs.Label`, `Tabs.Separator`. |
+| [orientation.tsx](examples/orientation.tsx) | Tabs over the panel and a side list of sections that stacks on top below 600px — `orientation`. |
+| [overflow.tsx](examples/overflow.tsx) | Drag the frame narrower: icons go first, then labels, and icons with tooltips stay; then the list scrolls — `Tabs.Icon`. |
+| [closable.tsx](examples/closable.tsx) | Open order cards as browser tabs: each closes by its button, Delete or a middle click; tabs stay between two widths and scroll past the narrower one — `onRemove`, `minItemWidth`, `maxItemWidth`. |
+| [two-line.tsx](examples/two-line.tsx) | A label and a counter on the first line, a summary on the second — `Tabs.Count`, `Tabs.Description`. |
+| [controlled.tsx](examples/controlled.tsx) | The active tab lives in parent state, e.g. synced with the URL — `value`, `onValueChange`. |
+
+## 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.
+- An icon on only some tabs → the list cannot collapse to icons and scrolls instead; give every tab an icon or none.
+- Tabs inside a `Card.Root` → a frame in a frame; the horizontal root is the surface.
+- Using Tabs to filter a list → use SegmentedControl.
+- `onClick` on `Tabs.Item` → use `onValueChange` on Root.
+- A hand-made × inside `Tabs.Item` → a button inside a tab button; pass `onRemove` instead.
+- `onRemove` that does not drop the tab from your list → the tab stays; the kit only moves the selection.
+- `Tabs.List` without `aria-label` → add one.
 
 ## Related
-
-- [Typography](../typography/COMPONENT.md)
-- [SegmentedControl](../segmented-control/COMPONENT.md)
-- [Breadcrumb](../breadcrumb/COMPONENT.md)
-- **Icon** — use inside `Tabs.Icon` for glyphs sized with the tab control tokens
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Button](../button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md)
+- **See also:** [SegmentedControl](../segmented-control/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Accordion](../accordion/COMPONENT.md)

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

@@ -0,0 +1,48 @@
+/** Open order cards as browser tabs: each closes by its button, Delete or a middle click; tabs stay between two widths and scroll past the narrower one — `onRemove`, `minItemWidth`, `maxItemWidth`. */
+import { Button, Tabs, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const ORDERS = [
+  { id: "10482", client: "Северный ветер", total: "184 200 ₽" },
+  { id: "10479", client: "ИП Корнеева", total: "36 900 ₽" },
+  { id: "10471", client: "Техноплан", total: "512 040 ₽" },
+  { id: "10466", client: "Балтийская логистическая компания", total: "97 300 ₽" },
+  { id: "10458", client: "ИП Гусев", total: "12 400 ₽" },
+];
+
+export default function TabsClosableExample() {
+  const [openOrders, setOpenOrders] = React.useState(ORDERS);
+
+  if (openOrders.length === 0) {
+    return (
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpenOrders(ORDERS)}>
+        Открыть заказы снова
+      </Button.Root>
+    );
+  }
+
+  return (
+    <Tabs.Root defaultValue="10479" minItemWidth={160} maxItemWidth={224}>
+      <Tabs.List aria-label="Открытые заказы">
+        {openOrders.map((order) => (
+          <Tabs.Item
+            key={order.id}
+            value={order.id}
+            onRemove={() =>
+              setOpenOrders((orders) => orders.filter((item) => item.id !== order.id))
+            }
+          >
+            {order.client}
+          </Tabs.Item>
+        ))}
+      </Tabs.List>
+      {openOrders.map((order) => (
+        <Tabs.Panel key={order.id} value={order.id}>
+          <Typography variant="body-m" tone="secondary">
+            Заказ № {order.id}, {order.client}, сумма {order.total}.
+          </Typography>
+        </Tabs.Panel>
+      ))}
+    </Tabs.Root>
+  );
+}

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

@@ -0,0 +1,33 @@
+/** The active tab lives in parent state, e.g. synced with the URL — `value`, `onValueChange`. */
+import { Tabs, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const QUEUES = [
+  { value: "new", label: "Новые", count: 12 },
+  { value: "progress", label: "В работе", count: 5 },
+  { value: "done", label: "Готово", count: 148 },
+];
+
+export default function TabsControlledExample() {
+  const [queue, setQueue] = React.useState("new");
+
+  return (
+    <Tabs.Root value={queue} onValueChange={setQueue}>
+      <Tabs.List aria-label="Заявки">
+        {QUEUES.map((item) => (
+          <Tabs.Item key={item.value} value={item.value}>
+            <Tabs.Label>{item.label}</Tabs.Label>
+            <Tabs.Count color={item.value === queue ? "blue" : "gray"}>{item.count}</Tabs.Count>
+          </Tabs.Item>
+        ))}
+      </Tabs.List>
+      {QUEUES.map((item) => (
+        <Tabs.Panel key={item.value} value={item.value}>
+          <Typography variant="body-m" tone="secondary">
+            Заявок в разделе «{item.label}»: {item.count}.
+          </Typography>
+        </Tabs.Panel>
+      ))}
+    </Tabs.Root>
+  );
+}

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

@@ -1,79 +1,18 @@
-.stack {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-m);
-}
-
-.body {
-  margin: 0;
-  color: var(--prime-sys-color-content-secondary);
-}
-
-.settingsRow {
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--prime-sys-spacing-l);
-  align-items: flex-start;
-}
-
-.settingsContent {
-  flex: 1 1 0;
-  min-width: min(100%, 20rem);
-}
-
-.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);
-}
-
-.fullWidthRoot {
-  width: 100%;
-  min-width: 0;
-}
-
-.fullWidthList {
-  width: 100%;
-  min-width: 0;
-}
-
-.flexTab {
-  flex: 1 1 0;
-  min-width: 0;
-  justify-content: center;
-}
-
-.narrowShell {
-  width: 100%;
-  max-width: 12rem;
-  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);
-}
-
-.sizesRow {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-x6);
-  align-items: stretch;
-  width: 100%;
-}
-
-.sizesGroup {
-  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);
+/* Layout of the Tabs scenarios: semantic tokens only. */
+
+/* A column for Tabs that fill their frame (a vertical root measures its own width, so it needs
+   one): wide enough to show the strip, narrower than the preview. */
+.frame {
+  box-sizing: border-box;
+  width: min(100%, calc(16 * var(--prime-control-m-height)));
+  margin-inline: auto;
+}
+
+/* The same column, which the reader can drag narrower to watch the tabs collapse and scroll. */
+.resizable {
+  composes: frame;
+  min-width: calc(3 * var(--prime-control-m-height));
+  max-width: 100%;
+  overflow: hidden;
+  resize: horizontal;
 }

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

@@ -0,0 +1,40 @@
+/** Tabs over the panel and a side list of sections that stacks on top below 600px — `orientation`. */
+import { Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { value: "profile", label: "Профиль", text: "Имя, должность и контакты сотрудника." },
+  { value: "notifications", label: "Уведомления", text: "Письма о заказах и еженедельная сводка." },
+  { value: "deletion", label: "Удаление", text: "Аккаунт и все данные будут удалены." },
+];
+
+export default function TabsOrientationExample() {
+  return (
+    <>
+      {(["horizontal", "vertical"] as const).map((orientation) => (
+        <Tabs.Root
+          key={orientation}
+          orientation={orientation}
+          defaultValue="notifications"
+          className={styles.frame}
+        >
+          <Tabs.List aria-label="Настройки">
+            {SECTIONS.map((section) => (
+              <Tabs.Item key={section.value} value={section.value}>
+                {section.label}
+              </Tabs.Item>
+            ))}
+          </Tabs.List>
+          {SECTIONS.map((section) => (
+            <Tabs.Panel key={section.value} value={section.value}>
+              <Typography variant="body-m" tone="secondary">
+                {section.text}
+              </Typography>
+            </Tabs.Panel>
+          ))}
+        </Tabs.Root>
+      ))}
+    </>
+  );
+}