prime-ui-kit 0.9.2 → 0.10.0

package/src/components/progress-bar/examples/examples.module.css

@@ -8,3 +8,10 @@
   width: min(100%, var(--prime-modal-width-s));
   min-width: 0;
 }
+
+/* Buttons under a bar that drive it. */
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-2);
+}

package/src/components/progress-bar/examples/milestone.tsx

@@ -0,0 +1,43 @@
+/** A rare milestone: the last invoice of the quarter fills the bar, the tone turns success and a short confetti burst marks it — `value`, `tone`, `celebrate()`. */
+import { Button, celebrate, ProgressBar } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const INVOICES = 12;
+
+export default function ProgressBarMilestoneExample() {
+  const [paid, setPaid] = React.useState(INVOICES - 1);
+  const closed = paid === INVOICES;
+
+  return (
+    <div className={styles.column}>
+      <ProgressBar
+        value={paid}
+        max={INVOICES}
+        tone={closed ? "success" : "accent"}
+        label={
+          closed
+            ? "III квартал закрыт: все счета оплачены"
+            : `Оплачено счетов: ${paid} из ${INVOICES}`
+        }
+      />
+      <div className={styles.actions}>
+        <Button.Root
+          variant={closed ? "soft" : "solid"}
+          tone={closed ? "neutral" : "accent"}
+          onClick={(event) => {
+            if (closed) {
+              setPaid(INVOICES - 1);
+              return;
+            }
+            setPaid(INVOICES);
+            celebrate({ origin: event.currentTarget });
+          }}
+        >
+          {closed ? "Вернуть последний счёт" : "Отметить оплату ООО «Вектор»"}
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-bar/examples/steps.tsx

@@ -0,0 +1,35 @@
+/** The scale as whole cells that fill one after another: 2 of 5 onboarding steps, forward and back — `steps`, `max`. */
+import { Button, ProgressBar } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const TOTAL = 5;
+
+export default function ProgressBarStepsExample() {
+  const [done, setDone] = React.useState(2);
+
+  return (
+    <div className={styles.column}>
+      <ProgressBar
+        steps
+        value={done}
+        max={TOTAL}
+        label={`Настройка компании: ${done} из ${TOTAL}`}
+      />
+      <div className={styles.actions}>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          disabled={done === 0}
+          onClick={() => setDone(done - 1)}
+        >
+          Назад
+        </Button.Root>
+        <Button.Root disabled={done === TOTAL} onClick={() => setDone(done + 1)}>
+          Следующий шаг
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/radio/COMPONENT.md

@@ -109,7 +109,7 @@ No `variant` / `tone` / `color`.
 |---|---|---|
 | unselected | group `value` ≠ option `value` | `data-state="unchecked"` on the option; circle `fill-strong`, hover `fill-strong-hover` |
 | selected | group `value` = option `value` | `data-state="checked"`; accent circle with a thumb-coloured dot that grows in |
-| invalid | `invalid` or a non-empty `error` on the group | `data-invalid="true"`, `aria-invalid` on the group and the inputs; danger ring on unselected circles |
+| invalid | `invalid` or a non-empty `error` on the group | `data-invalid="true"`, `aria-invalid` on the group and the inputs; danger ring on unselected circles; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | group or option `disabled` | `data-disabled="true"`, native `disabled` on every radio; `fill-muted` circle, `cursor: not-allowed` |
 | pressed | pointer press | the circle scales to the compact press scale |
 | focus-visible | keyboard | outer focus ring around the circle |

package/src/components/select/COMPONENT.md

@@ -159,7 +159,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 |---|---|---|
 | empty | no value | `data-placeholder="true"` on Value, placeholder color |
 | open | `open` / click / arrows | trigger `data-state="open"`, `aria-expanded`; panel `data-state`, `data-side`; chevron turns 180° |
-| invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the trigger; error text below |
+| invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the trigger; error text below; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | native `disabled`, `data-disabled="true"` |
 | loading | `loading` | `data-loading="true"`, `aria-busy`; status row in the list |
 | searching | typing in the search | panel `data-searching="true"`; groups without matches and separators hide; the match in an option's title, description and plain text is a `<mark>` in `accent-text` (not in the trigger) |
@@ -209,7 +209,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | [overview.tsx](examples/overview.tsx) | A labelled field with a placeholder; picking an option closes the list and shows its label — `label`, `placeholder`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier; the label, the list rows and the hint take the tier of the field — `size`. |
 | [states.tsx](examples/states.tsx) | A default field next to a disabled, a loading, an invalid one and a list with nothing in it — `disabled`, `loading`, `invalid`, `labels`. |
-| [validation.tsx](examples/validation.tsx) | Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. |
+| [validation.tsx](examples/validation.tsx) | Live validation: unassigning the owner shakes the field and drops the error in, picking someone clears it; required and optional markers and a hint — `required`, `optional`, `hint`, `error`. |
 | [with-icon.tsx](examples/with-icon.tsx) | A leading icon in the trigger and an icon before every option label — `Select.TriggerIcon`, `Select.ItemIcon`. |
 | [multiple.tsx](examples/multiple.tsx) | Several values: checkboxes in the list, the list stays open on a pick, labels joined in the trigger — `multiple`. |
 | [searchable.tsx](examples/searchable.tsx) | A long list with a search field: options match their label and keywords, groups and the separator hide while searching — `searchable`, `keywords`, `Select.Group`. |
@@ -217,7 +217,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | [rich-options.tsx](examples/rich-options.tsx) | Options with a picture, a second line and a price; the trigger draws the picked option with the same parts — `renderValue`, `Select.ItemText`, `Select.ItemDescription`, `Select.ItemMeta`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the value: the plan drives the price under the field and a button resets it — `value`, `onValueChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the list: a button opens it from code, a pick or Escape closes it — `open`, `onOpenChange`. |
-| [in-form.tsx](examples/in-form.tsx) | Regional settings form: the required country is checked on submit, the error replaces the hint — `required`, `error`, `hint`. |
+| [in-form.tsx](examples/in-form.tsx) | Regional settings form: the required country is checked on submit, the error shakes the field and leaves once a country is picked, a calm note confirms the save — `required`, `error`, `hint`. |
 
 ## Mistakes
 - A Label + `aria-labelledby` next to the field → pass `label`, `hint`, `error` to `Select.Root`.

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

@@ -23,6 +23,7 @@
 
 .formActions {
   display: flex;
+  align-items: center;
   justify-content: flex-end;
   gap: var(--prime-space-2);
 }

package/src/components/select/examples/in-form.tsx

@@ -1,4 +1,4 @@
-/** Regional settings form: the required country is checked on submit, the error replaces the hint — `required`, `error`, `hint`. */
+/** Regional settings form: the required country is checked on submit, the error shakes the field and leaves once a country is picked, a calm note confirms the save — `required`, `error`, `hint`. */
 import { Button, Select, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -7,10 +7,12 @@ import styles from "./examples.module.css";
 export default function SelectInFormExample() {
   const [country, setCountry] = React.useState("");
   const [error, setError] = React.useState<string>();
+  const [saved, setSaved] = React.useState(false);
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
     setError(country ? undefined : "Выберите страну");
+    setSaved(Boolean(country));
   };
 
   return (
@@ -33,6 +35,7 @@ export default function SelectInFormExample() {
           onValueChange={(value) => {
             setCountry(value);
             setError(undefined);
+            setSaved(false);
           }}
         >
           <Select.Trigger>
@@ -44,7 +47,12 @@ export default function SelectInFormExample() {
             <Select.Item value="am">Армения</Select.Item>
           </Select.Content>
         </Select.Root>
-        <Select.Root label="Часовой пояс" hint="Время в отчётах и уведомлениях" defaultValue="msk">
+        <Select.Root
+          label="Часовой пояс"
+          hint="Время в отчётах и уведомлениях"
+          defaultValue="msk"
+          onValueChange={() => setSaved(false)}
+        >
           <Select.Trigger>
             <Select.Value />
           </Select.Trigger>
@@ -56,7 +64,21 @@ export default function SelectInFormExample() {
         </Select.Root>
       </div>
       <div className={styles.formActions}>
-        <Button.Root variant="ghost" tone="neutral" type="reset">
+        {saved ? (
+          <Typography as="p" variant="body-s" tone="secondary">
+            Настройки сохранены
+          </Typography>
+        ) : null}
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          type="reset"
+          onClick={() => {
+            setCountry("");
+            setError(undefined);
+            setSaved(false);
+          }}
+        >
           Отменить
         </Button.Root>
         <Button.Root type="submit">Сохранить</Button.Root>

package/src/components/select/examples/validation.tsx

@@ -1,7 +1,10 @@
-/** Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. */
+/** Live validation: unassigning the owner shakes the field and drops the error in, picking someone clears it; required and optional markers and a hint — `required`, `optional`, `hint`, `error`. */
 import { Select } from "prime-ui-kit";
+import * as React from "react";
 
 export default function SelectValidationExample() {
+  const [owner, setOwner] = React.useState("anna");
+
   return (
     <>
       <Select.Root label="Страна" required hint="Определяет валюту счетов" defaultValue="ru">
@@ -16,13 +19,15 @@ export default function SelectValidationExample() {
       <Select.Root
         label="Ответственный"
         required
-        error="Назначьте ответственного"
-        placeholder="Не выбран"
+        error={owner === "none" ? "Назначьте ответственного" : undefined}
+        value={owner}
+        onValueChange={setOwner}
       >
         <Select.Trigger>
           <Select.Value />
         </Select.Trigger>
         <Select.Content>
+          <Select.Item value="none">Не назначен</Select.Item>
           <Select.Item value="anna">Анна Петрова</Select.Item>
           <Select.Item value="ivan">Иван Смирнов</Select.Item>
         </Select.Content>

package/src/components/skeleton/examples/with-crossfade.tsx

@@ -5,9 +5,9 @@ import * as React from "react";
 import styles from "./examples.module.css";
 
 const PAYMENTS = [
-  { id: "p1", payer: "ООО «Гранит»", amount: "₽ 94 750" },
-  { id: "p2", payer: "ИП Орлов Д. С.", amount: "₽ 18 000" },
-  { id: "p3", payer: "АО «Альфа Медиа»", amount: "₽ 380 000" },
+  { id: "p1", payer: "ООО «Гранит»", amount: "94 750 ₽" },
+  { id: "p2", payer: "ИП Орлов Д. С.", amount: "18 000 ₽" },
+  { id: "p3", payer: "АО «Альфа Медиа»", amount: "380 000 ₽" },
 ];
 
 const LOAD_MS = 1500;

package/src/components/slider/COMPONENT.md

@@ -110,7 +110,7 @@ Tone never carries meaning alone: the label names what the value means.
 |---|---|---|
 | default | — | `data-size`, `data-tone`; track `fill-strong`, tone pill up to the thumb centre, opaque thumb |
 | hover | pointer (fine pointers only) | light liquid glass: the thumb grows to 110%, turns translucent and slightly frosted |
-| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the root, `aria-invalid` on the input; the error replaces the hint, danger focus ring |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the root, `aria-invalid` on the input; the error replaces the hint, danger focus ring; the control shakes once when an error arrives (`data-shake` on the frame) |
 | pressed | dragging | clear glass: the thumb grows to 125%, the rounded end of the fill shows through |
 | focus-visible | keyboard | outer focus ring around the thumb |
 | disabled | `disabled` | `data-disabled="true"` on the root, native `disabled`; muted track and fill, flat thumb, `cursor: not-allowed` |

package/src/components/sparkline/COMPONENT.md

@@ -0,0 +1,98 @@
+# Sparkline
+
+**Category:** data-display
+**Kind:** primitive
+
+> A small line chart with its headline — the latest value, its change against the point before and its date — where any point can be scrubbed.
+
+## When to use
+- A metric card on a dashboard: revenue, orders, sign-ups over the last days or weeks.
+- A trend next to a number where the shape matters more than exact axes.
+- A detail page header that shows how a value moved.
+
+## When not to use
+- Exact values on axes, several series, or a legend → a full chart library; Sparkline has no axes.
+- Progress toward a goal → [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- A list of values to compare → [DataTable](../data-table/COMPONENT.md).
+
+## Import
+```tsx
+import { Sparkline, type SparklinePoint } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Sparkline              <div>; the headline and the chart
+├─ head                title (label) · date of the shown point
+├─ value row           value (rolling digits when settled) · change Badge with the trend arrow
+└─ plot                role="slider" over the svg line and area
+   └─ cursor           guide line and dot of the shown point (aria-hidden)
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Sparkline
+`ref` → `HTMLDivElement` (the root). A headline (title · date, value · change) over a line chart; the chart is a `role="slider"` that picks a point.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `SparklinePoint[]` | — (required) | Points oldest first, `{ label, value }`; `label` names the point («8 окт»). Two or more draw a line. A new array cross-fades the line in. |
+| `label` | `string` | — (required) | Visible title above the value and the accessible name of the chart. |
+| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a value in the headline and the spoken point («312 400 ₽»). |
+| `labels` | `Partial<SparklineLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `data-*` and the other div attributes on the root. |
+
+## Variants
+No variants: one accent line on the surface it sits on. Put it in a `Card` for a dashboard tile.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| at rest | — | the latest point; the value rolls its digits when `data` changes |
+| scrubbing | pointer or touch over the plot | `data-scrubbing` on the root; the cursor and the headline follow the pointer with no easing (direct manipulation), digits change in place |
+| keyboard | arrows, Home, End on the focused plot | `aria-valuenow` / `aria-valuetext`; the cursor glides to the point (`base` · emphasized) |
+| settle | pointer leaves, touch ends, focus leaves | the cursor glides back to the latest point |
+| new series | a new `data` array | the line cross-fades in (swap motion); the trend arrow turns half a turn between up and down |
+
+## Layout & spacing
+- Takes the width of its container; the plot is 80 px high and inset by the dot radius so the cursor is never clipped.
+- In a dashboard, wrap it in `Card.Root` + `Card.Body`; several cards go in a grid.
+- Below 320 px the value row wraps the change badge under the value.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `←` · `→` | Previous or next point. |
+| `Home` · `End` | First or last point. |
+| `Tab` | Focuses the chart; leaving focus returns to the latest point. |
+
+### ARIA
+- The plot is `role="slider"` named by `label`; `aria-valuetext` speaks the point («8 окт: 312 400 ₽», `labels.point`).
+- The headline with the latest value and change reads as plain text.
+- The change carries a sign and an arrow, never color alone.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `point` | `"{label}: {value}"` | Spoken value of the chosen point (`aria-valuetext`); `{label}` and `{value}` are replaced. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Revenue for 30 days in a dashboard card: drag across the chart, the headline follows and the trend arrow turns — `data`, `label`, `formatValue`. |
+| [period.tsx](examples/period.tsx) | Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`. |
+
+## Mistakes
+- A new array on every render (`data={rows.map(...)}` inline) → the line cross-fades on every render; memoize the series.
+- Formatting inside `label` of a point («312 400 ₽») → the point label is its name («8 окт»); format values with `formatValue`.
+- A Sparkline without a container width (inside an inline flex row) → give it a width or put it in a `Card`.
+
+## Related
+- **Built from:** [Badge](../badge/COMPONENT.md)
+- **See also:** [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -0,0 +1,13 @@
+/* Layout of the Sparkline scenarios: semantic tokens only. */
+
+/* A dashboard card's width: the chart takes the card width. */
+.card {
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+/* The period switch above the chart inside the card body. */
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+}

package/src/components/sparkline/examples/overview.tsx

@@ -0,0 +1,27 @@
+/** Revenue for 30 days in a dashboard card: drag across the chart, the headline follows and the trend arrow turns — `data`, `label`, `formatValue`. */
+import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const MONTHS = ["янв", "фев", "мар", "апр", "мая", "июн", "июл", "авг", "сен", "окт", "ноя", "дек"];
+
+/** Daily revenue, 9 September — 8 October 2026. */
+const REVENUE: SparklinePoint[] = Array.from({ length: 30 }, (_, i) => {
+  const day = new Date(2026, 8, 9 + i);
+  return {
+    label: `${day.getDate()} ${MONTHS[day.getMonth()]}`,
+    value: Math.round(260 + 40 * Math.sin(i / 3.2) + 28 * Math.sin(i / 1.4 + 1) + i * 2.6) * 1000,
+  };
+});
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+export default function SparklineOverviewExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body>
+        <Sparkline data={REVENUE} label="Выручка за 30 дней" formatValue={formatRubles} />
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/sparkline/examples/period.tsx

@@ -0,0 +1,46 @@
+/** Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`. */
+import { Card, SegmentedControl, Sparkline, type SparklinePoint } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Period = "week" | "month" | "quarter";
+
+const series = (labels: string[], base: number, swing: number): SparklinePoint[] =>
+  labels.map((label, i) => ({
+    label,
+    value: Math.round((base + swing * Math.sin(i / 1.7) + (swing / 4) * i) / 100) * 100,
+  }));
+
+const SERIES: Record<Period, SparklinePoint[]> = {
+  week: series(["2 окт", "3 окт", "4 окт", "5 окт", "6 окт", "7 окт", "8 окт"], 41_000, 6_000),
+  month: series(
+    ["сен, 1 нед.", "сен, 2 нед.", "сен, 3 нед.", "сен, 4 нед.", "окт, 1 нед."],
+    286_000,
+    32_000,
+  ),
+  quarter: series(["авг", "сен", "окт"], 1_240_000, 160_000),
+};
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+export default function SparklinePeriodExample() {
+  const [period, setPeriod] = React.useState<Period>("month");
+
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body className={styles.body}>
+        <SegmentedControl.Root
+          value={period}
+          onValueChange={(value) => setPeriod(value as Period)}
+          aria-label="Период"
+        >
+          <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
+          <SegmentedControl.Item value="quarter">Квартал</SegmentedControl.Item>
+        </SegmentedControl.Root>
+        <Sparkline data={SERIES[period]} label="Новые заказы" formatValue={formatRubles} />
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/switch/COMPONENT.md

@@ -87,7 +87,7 @@ No `variant` / `tone` / `color`.
 |---|---|---|
 | off | `checked={false}` / default | `data-state="unchecked"`; track `fill-strong` (hover `fill-strong-hover`), thumb at the start |
 | on | `checked` / `defaultChecked` | `data-state="checked"`; accent track, the thumb glides to the end |
-| invalid | `invalid` or a non-empty `error` | `data-invalid="true"`, `aria-invalid`; danger ring on the off track and on focus |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"`, `aria-invalid`; danger ring on the off track and on focus; the row shakes once when an error arrives (`data-shake`) |
 | disabled | `disabled` | `data-disabled="true"`; off track `fill-muted`, on track `accent-soft`, `cursor: not-allowed` |
 | read-only | `readOnly` | `aria-readonly="true"` on the input, `data-readonly="true"` on the field; no hover or press, default cursor |
 | pressed | pointer press | the track scales to the compact press scale (not when disabled or read-only) |

package/src/components/tabs/COMPONENT.md

@@ -26,8 +26,8 @@ import { Tabs } from "prime-ui-kit";
 
 ## 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.Root                 value, size, orientation, tone, fullWidth, min/maxItemWidth; the frame (a layer)
+├─ Tabs.List              role="tablist" on a ScrollContainer, sliding folder; 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
@@ -42,14 +42,14 @@ Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItem
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### 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.
+`ref` → `HTMLDivElement`. `<div>` that owns the active value, size and orientation and lays out the list and the panel. It is the frame and a layer of the surface ladder in both orientations: a strip two steps off the layer and the panel in the layer's own color — above the panel when horizontal, at its inline start when vertical.
 
 | 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. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | List direction and arrow keys. Vertical: a column of sections at the panel's inline start, the active one the panel reaching into the column; when the container is narrower than 600px the column becomes the horizontal strip above the panel. |
 | `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 fill the list and tend to equal widths within `minItemWidth` … `maxItemWidth`, never narrower than their content: a long label keeps its width, short ones share the rest; when they do not fit, the list collapses, then scrolls. `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. |
@@ -60,7 +60,7 @@ Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItem
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">` | — | `className` and the other div attributes. |
 
 ### Tabs.List
-`ref` → `HTMLDivElement`. `role="tablist"` on a `ScrollContainer` (horizontal, edge fade, hidden scrollbar) with the sliding folder (vertical: pill), which glides only into a choice by click or keys and is placed without motion on mount, resize and collapse. 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); then the list scrolls; a label is never cut to make room. The active tab is kept in view: only the list scrolls, never the page.
+`ref` → `HTMLDivElement`. `role="tablist"` on a `ScrollContainer` (horizontal, edge fade, hidden scrollbar) with the sliding folder (in both orientations), which glides only into a choice by click or keys and is placed without motion on mount, resize and collapse. 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); then the list scrolls; a label is never cut to make room. The active tab is kept in view and clear of the edge fades (the first and the last tab scroll all the way to the end); only the list scrolls, never the page.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -128,7 +128,7 @@ Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItem
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
 
 ## Variants
-Tabs have no `variant`: navigation tabs are always a folder (horizontal) or pills (vertical).
+Tabs have no `variant`: navigation tabs are always a folder — rising from the panel's top edge (horizontal) or reaching out of its side (vertical).
 
 ### tone
 | Value | Looks like | Use when | Default |
@@ -139,8 +139,8 @@ Tabs have no `variant`: navigation tabs are always a folder (horizontal) or pill
 ### 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 | |
+| `horizontal` | a layer of the surface ladder: a `fill-muted-hover` strip (two steps off the layer) over a padded panel in the layer's own color, tabs edge to edge; the active tab is the panel 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` | the same folder on its side: a column of sections in the `fill-muted-hover` strip at the panel's inline start; the active section is the panel reaching into the column, rounded on the outer side, with concave flares above and below where it meets the panel; hover is the same shape in `fill-faint`. Below a 600px container the column becomes the horizontal strip above the panel (it scrolls, never wraps) | settings pages with a side list of sections | |
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -180,26 +180,25 @@ Avoid icons or descriptions on only some tabs (uneven rows; without an icon on e
 | 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 |
+| hover | pointer | text → primary; the folder shape in `fill-faint`, under the folder |
 | 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) |
+| focus-visible | keyboard | focus ring inside the tab, above the folder; the panel shows an inset 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 their narrowest (content width, `minItemWidth` or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (ScrollContainer), faded edges; the active tab is kept in view on mount and on every value change — only the list scrolls, never the page |
+| overflow | tabs at their narrowest (content width, `minItemWidth` or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (ScrollContainer), faded edges as deep as the hidden part at most (they grow and melt with the scroll, never switch); the active tab is kept in view and clear of the fades on mount and on every value change, the first and the last tab scroll all the way to the end — only the list scrolls, never the page |
 
 The indicator glides (`emphasized` + `base`, `data-animate="true"`) only into a choice by click, arrow keys or closing the active tab; on mount, a value set from outside, a resize, font loading, tabs added or removed and collapse it is placed without motion, and it stays still under `prefers-reduced-motion`. The list scrolls smoothly to the active tab only after such a choice too.
 
-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.
+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"`, its indicator `data-axis="x" | "y"` (follows the list's direction, so a vertical list in a narrow container gets the top folder); 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 root is the frame and a layer of the ladder in both orientations (`data-depth`, `radius-xl`, the strip two steps off the layer); the list sits flush on the panel; 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: the column is as wide as its widest section (at least four control heights, at most 40% of the root), inset by the folder rise from the frame on the outer side, flush with the panel on the other.
 - The list never wraps: it collapses, then scrolls horizontally with faded edges (hidden scrollbar, `overscroll-behavior: contain`). Give the list's container a width (`min-width: 0` on flex children).
 - A horizontal tab is never narrower than its content (`min-width: max-content`; the tab bounds that content between `minItemWidth` and `maxItemWidth`), so a label is never cut to make room. Full width, tabs tend to equal widths, not widths in proportion to their labels (`flex: 1 1 0`): a long label keeps its width, the short ones share the rest.
 - 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
 
@@ -235,7 +234,7 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 | [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`. |
+| [orientation.tsx](examples/orientation.tsx) | Account settings with a side list of sections: the active section reaches out of the panel, and below 600px the list moves above it — `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 the list scrolls when they do not fit — `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`. |

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

@@ -8,6 +8,20 @@
   margin-inline: auto;
 }
 
+/* A settings block: wide enough for the side list next to a form, never wider than the preview. */
+.wide {
+  box-sizing: border-box;
+  width: min(100%, calc(20 * var(--prime-control-m-height)));
+  margin-inline: auto;
+}
+
+/* Fields and switches of a settings section: field → field rhythm (foundation §1). */
+.form {
+  display: grid;
+  gap: var(--prime-space-5);
+  max-width: calc(10 * var(--prime-control-m-height));
+}
+
 /* The same column, which the reader can drag narrower to watch the tabs collapse and scroll. */
 .resizable {
   composes: frame;