prime-ui-kit 0.9.2 → 0.9.3

package/src/components/login-form/examples/register.tsx

@@ -1,4 +1,4 @@
-/** Sign-up: five fields in one column, a password mismatch shown as the field error — `error`, `LoginForm.Form`. */
+/** Sign-up: five fields in one column, a strength meter on the new password and a mismatch shown as the field error — `strength`, `error`, `LoginForm.Form`. */
 import { Button, Divider, Icon, Input, LinkButton, LoginForm } from "prime-ui-kit";
 import * as React from "react";
 
@@ -45,7 +45,7 @@ export default function LoginFormRegisterExample() {
                 <Input.Field placeholder="@login" />
               </Input.Wrapper>
             </Input.Root>
-            <Input.Root label="Пароль" required hint="Минимум 6 символов">
+            <Input.Root label="Пароль" required hint="Минимум 8 символов" strength>
               <Input.Wrapper>
                 <Input.Field
                   type="password"

package/src/components/login-form/examples/reset-password.tsx

@@ -1,4 +1,4 @@
-/** A new password after the e-mail link: two fields and a mismatch error under the second one — `error`. */
+/** A new password after the e-mail link: a strength meter on the first field and a mismatch error under the second one — `strength`, `error`. */
 import { Button, Icon, Input, LoginForm } from "prime-ui-kit";
 import * as React from "react";
 
@@ -23,7 +23,7 @@ export default function LoginFormResetPasswordExample() {
         </LoginForm.Header>
         <LoginForm.Body>
           <LoginForm.Form onSubmit={(e) => e.preventDefault()}>
-            <Input.Root label="Новый пароль" required hint="Минимум 6 символов">
+            <Input.Root label="Новый пароль" required hint="Минимум 8 символов" strength>
               <Input.Wrapper>
                 <Input.Field
                   type="password"

package/src/components/modal/COMPONENT.md

@@ -107,7 +107,7 @@ No DOM: clone the single child and chain its `onClick` (unless the child's handl
 | `children` | `ReactElement` | — (required) | One element, usually a Button. |
 
 ## Variants
-The dialog has one look: `bg-raised`, `--prime-modal-radius` (16), `shadow-modal`, on a `bg-scrim`. Header, body and footer are separated by faint inset hairlines.
+The dialog has one look: the floating layer of the ladder (`data-depth="floating"`: white in light, a step above a card in dark), `--prime-modal-radius` (16), `shadow-modal`, on a `bg-scrim`. Header, body and footer are separated by faint inset hairlines.
 
 ### size (Content)
 | Value | Looks like | Use when | Default |
@@ -165,7 +165,7 @@ Loading or disabled actions use the Button props (`loading`, `disabled`) inside
 ## Layout & spacing
 - Dialog padding `--prime-modal-padding` (24) on every zone; header 24 top / 20 bottom, body 20 with a 16 gap between blocks, footer 20 top / 24 bottom.
 - Max height = viewport minus `--prime-modal-viewport-padding` on both sides; only the body scrolls.
-- Fields inside get the surface field fill; cards inside become sunken tiles. Group fields with a 20 gap.
+- Fields inside take the floating layer's fill; a card inside is the next layer (`floating-1`), a flat tile. Group fields with a 20 gap.
 - Narrow viewport (< 640px): bottom sheet, full width, top corners `--prime-sheet-radius`, a grab handle strip on top, up to `100dvh − --prime-sheet-top-gap` high, the bottom safe-area inset below the content.
 
 ## Accessibility

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

@@ -16,6 +16,6 @@
   width: 100%;
   padding: var(--prime-space-4);
   border-radius: var(--prime-card-radius);
-  background: var(--prime-color-card-bg);
-  box-shadow: var(--prime-card-shadow);
+  background: var(--prime-color-layer-nested);
+  box-shadow: var(--prime-shadow-raised);
 }

package/src/components/page-content/examples/examples.module.css

@@ -5,7 +5,7 @@
   width: 100%;
   padding: var(--prime-layout-gutter-m);
   border-radius: var(--prime-card-radius);
-  background: var(--prime-color-bg-canvas);
+  background: var(--prime-color-layer-current);
   container-type: inline-size;
 }
 

package/src/components/popover/COMPONENT.md

@@ -77,7 +77,7 @@ No DOM: clone the single child and merge `ref` and `onClick`. Trigger toggles th
 `ref` → the element. `<div>` (title + description with a 4 px step) / `<h2>` (names the dialog) / `<p>` (describes it) / `<div>` (buttons at the end, stacked full width on phones, below 640 px). + native props.
 
 ## Variants
-The panel has one look: `bg-raised` fill, `--prime-panel-radius`, `shadow-overlay`, no border. Fields inside get the surface field fill; cards inside become sunken tiles.
+The panel has one look: the floating layer of the ladder (`data-depth="floating"`), `--prime-panel-radius`, `shadow-overlay`, no border. Fields inside take that layer's fill; a card inside is the next layer, a flat tile.
 
 ### size (Content)
 | Value | Looks like | Use when | Default |

package/src/components/progress-bar/COMPONENT.md

@@ -51,6 +51,7 @@ A native `<progress>` (transparent, for assistive tech) under the drawn line.
 | `value` | `number` | — (required) | The current value, clamped to `0…max`. |
 | `max` | `number` | `100` | Top of the scale. |
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"accent"` | Fill color, telling the outcome. |
+| `steps` | `boolean` | `false` | Draws the scale as `max` equal cells (2–12), each filled whole; `value` rounds to a cell. In one change the cells go one after another — from the start when filling, from the end when emptying. For a level out of a few: password strength, onboarding steps. |
 
 ### ProgressBar · segments mode
 A `role="group"` bar of parts, named by `label` and described by the distribution text.
@@ -100,8 +101,9 @@ A `role="group"` bar of parts, named by `label` and described by the distributio
 | tone / size | props | `data-tone` (value mode), `data-size` on the root |
 | value | `value`, `max` | native `value` / `max`; the drawn pill slides by `translate` over `slow` + `standard`, RTL aware |
 | segments | `segments`, `max`, `segmentGap` | `data-segment-gap` on the group, `data-tone` per part; widths animate by `flex-grow` over `slow` |
+| steps | `steps` (value mode) | `data-steps="true"` on the bar; `max` cells (2–12), filled ones `data-filled`; a cell fills from its start edge (`base` · emphasized), cells of one change go half a stagger step apart — from the start when filling, from the end when emptying |
 | empty segments | `segments` empty or all `0` | only the track; accessible text `labels.empty` / `labels.allEmpty` |
-| reduced motion | `prefers-reduced-motion` | fill and widths change instantly |
+| reduced motion | `prefers-reduced-motion` | fill, widths and cells change instantly |
 
 Always controlled: pass the current `value` or `segments` on every render.
 
@@ -137,6 +139,8 @@ No keyboard interaction.
 | [sizes.tsx](examples/sizes.tsx) | Every tier: the line grows from 4 to 8 px like the Slider track — `size`. |
 | [custom-max.tsx](examples/custom-max.tsx) | A scale of steps instead of percent: 3 of 5 profile steps — `max`. |
 | [segments.tsx](examples/segments.tsx) | Parts of a whole in one bar: joined or separate pills, free capacity up to `max` and an empty list — `segments`, `segmentGap`, `max`. |
+| [steps.tsx](examples/steps.tsx) | The scale as whole cells that fill one after another: 2 of 5 onboarding steps, forward and back — `steps`, `max`. |
+| [milestone.tsx](examples/milestone.tsx) | 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()`. |
 
 ## Mistakes
 - No `label` and no `aria-label` → the bar has no accessible name.

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/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/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/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;