prime-ui-kit 0.3.1 → 0.4.0

package/src/components/digit-input/COMPONENT.md

@@ -2,9 +2,22 @@
 
 **Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
 
-## About
+## Canonical
 
-`DigitInput` is a single OTP-style control: a horizontal row of one-character fields that merge into one digit string, with paste support and automatic focus moves between cells.
+- **Import:** `import { DigitInput } from "prime-ui-kit"`.
+- **Surface:** только **`DigitInput.Root`** — горизонтальный ряд ячеек (`<fieldset>` + несколько `<input>`).
+- **Значение:** одна строка из цифр; длина задаётся **`length`** (по умолчанию **`4`**).
+- **Размер ячеек:** **`size`**: `"s"` \| `"m"` \| `"l"` \| `"xl"` (по умолчанию **`m`**).
+- **Режимы:** контролируемый (`value` + `onChange`) или неконтролируемый (`defaultValue`); опционально **`onComplete`**, **`disabled`**, **`hasError`**, **`className`**.
+- **Подписи и ошибки:** снаружи — [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md); встроенных слотов нет.
+- **Playground:** секция **`playground/sections/DigitInputSection.tsx`**; исходники демо — **`playground/snippets/digit-input/*.tsx`** (импорты **`@/`**). Сниппеты **`playground/snippets/slider-digit/`** относятся к **Slider** с режимом «цифры», а не к **DigitInput**.
+- **Примеры для копирования:** [`examples/`](./examples/) — продуктовые сценарии и зеркала сниппетов с импортом **`prime-ui-kit`**.
+
+## Extended
+
+### About
+
+`DigitInput` — один OTP-стиль контроль: горизонтальный ряд полей по одному символу, общая строка цифр, вставка из буфера и автоматический перенос фокуса между ячейками.
 
 - **Use** for short numeric codes (SMS/OTP, PIN, pickup codes) where one digit per box matches user expectations.
 - **Use** when you want `inputMode="numeric"`, `maxLength={1}` per cell, and `autoComplete="one-time-code"` without wiring it yourself.
@@ -14,7 +27,19 @@
 - **Do not use** for free-form numbers (amounts, phone as one field); this component is fixed-length, one digit per slot.
 - **Do not expect** arrow keys to move between cells; only typing, Backspace on an empty cell, and pointer focus apply.
 
-## Composition
+### Playground snippets
+
+Демо совпадают по порядку и смыслу с **`playground/sections/DigitInputSection.tsx`**. В сниппетах — импорты **`@/`**; зеркальные рецепты с **`prime-ui-kit`** — в **`examples/`** (та же разметка и пропы, раскладка через простой column flex и токены отступов).
+
+| Блок | Сниппет | Зеркало в `examples/` |
+| ---- | ------- | ---------------------- |
+| **Размеры** | [`sizes.tsx`](../../../playground/snippets/digit-input/sizes.tsx) | [`sizes.tsx`](./examples/sizes.tsx) — **`size`** **`s`**, **`m`**, **`l`**, **`xl`** при **`length={4}`** и одинаковом **`defaultValue`** для сравнения масштаба. |
+| **Состояния** | [`states.tsx`](../../../playground/snippets/digit-input/states.tsx) | [`states.tsx`](./examples/states.tsx) — без флагов, **`hasError`**, **`disabled`**. |
+| **Контролируемый режим** | [`controlled.tsx`](../../../playground/snippets/digit-input/controlled.tsx) | [`controlled.tsx`](./examples/controlled.tsx) — **`value`** + **`onChange`**, подпись со строкой и счётчиком **`(n/4)`**. |
+| **Композиция** | [`composition.tsx`](../../../playground/snippets/digit-input/composition.tsx) | [`composition.tsx`](./examples/composition.tsx) — **[Label](../label/COMPONENT.md)** + **DigitInput** + **[Hint](../hint/COMPONENT.md)** без слотов на корне. |
+| **Специфичные фичи** | [`features.tsx`](../../../playground/snippets/digit-input/features.tsx) | [`features.tsx`](./examples/features.tsx) — разные **`length`** / **`defaultValue`**, демо **`onComplete`** после последней цифры. |
+
+### Composition
 
 - Public API is **`DigitInput.Root` only** (`DigitInput = { Root }`). There are no inner slots (`Label`, `Icon`, etc.) on this component.
 - The root renders a native **`fieldset`** with `aria-label="Digit input"` and **`length`** separate `<input type="text">` cells (`inputMode="numeric"`, `maxLength={1}`, `autoComplete="one-time-code"`).
@@ -30,7 +55,19 @@ export function OneTimeCode() {
 }
 ```
 
-## Rules
+### Scenarios (recipes)
+
+Продуктовые сценарии (импорт **`prime-ui-kit`**). Для построчного соответствия демо плейграунда см. **Playground snippets** выше.
+
+| Сценарий | Файл |
+| -------- | ---- |
+| Вход по SMS / OTP, `length={6}`, контролируемое значение, подсказка про вставку | [`examples/otp-login.tsx`](./examples/otp-login.tsx) |
+| PIN, крупные ячейки для тача (`size="l"`) | [`examples/pin.tsx`](./examples/pin.tsx) |
+| Шаг верификации: код + кнопка «Продолжить» до заполнения | [`examples/verification-step.tsx`](./examples/verification-step.tsx) |
+| Неверный код: `hasError` и `Hint` с `variant="error"` | [`examples/error-state.tsx`](./examples/error-state.tsx) |
+| Повторная отправка кода и сброс поля через родительское состояние | [`examples/resend-and-clear.tsx`](./examples/resend-and-clear.tsx) |
+
+### Rules
 
 - **Controlled:** pass `value` and `onChange`; the live string is always normalized to digits only and truncated to `length`.
 - **Uncontrolled:** use `defaultValue` (defaults to `""`); still pass `onChange` if you need to observe updates.
@@ -42,6 +79,17 @@ export function OneTimeCode() {
 - **`disabled`** disables every cell; **`hasError`** drives error styling on the root via `data-has-error`.
 - **No portal, no polymorphic root, no `variant`:** visual scale is only `size` (`s` | `m` | `l` | `xl`); width follows cell layout, not a `fullWidth` prop.
 
+## LLM note
+
+- Для разметки и комбинаций пропов сначала смотри **`playground/snippets/digit-input/*.tsx`** и зеркала **`examples/sizes.tsx`**, **`states.tsx`**, **`controlled.tsx`**, **`composition.tsx`**, **`features.tsx`**.
+- Нормализация: в **`value` / `onChange` / paste** нецифровые символы **удаляются**, строка **обрезается** до **`length`**. Алфавитно-цифровые коды **не поддерживаются**.
+- **`onComplete(value)`** вызывается **один раз**, когда длина строки **впервые** стала **`length`**, будучи до этого **меньше**; при редактировании уже полной строки без укорочения **не** вызывается снова.
+- **Backspace** на **пустой** ячейке только **переносит фокус** назад; **не** стирает предыдущую цифру автоматически.
+- После ввода цифры фокус **переходит вперёд** (если есть следующая ячейка). **Стрелки** между ячейками **не** обрабатываются.
+- **Paste** с любой ячейки: цифры подставляются **вперёд** от индекса; нецифры отбрасываются.
+- Каждая ячейка: **`inputMode="numeric"`**, **`maxLength={1}`**, **`autoComplete="one-time-code"`** (задано в реализации).
+- Нет **`fullWidth`**, **`variant`**, портала и полиморфного корня; ошибка только через **`hasError`** → `data-has-error` на корне.
+
 ## API
 
 ### DigitInput.Root

package/src/components/digit-input/examples/composition.tsx

@@ -0,0 +1,24 @@
+import { DigitInput, Hint, Label } from "prime-ui-kit";
+
+/**
+ * Подпись и подсказка рядом с группой ячеек — типичный блок ввода кода в форме.
+ * Паритет с `playground/snippets/digit-input/composition.tsx`.
+ */
+export default function DigitInputCompositionExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: "var(--prime-sys-spacing-m)",
+      }}
+    >
+      <Label.Root size="m">Код из сообщения</Label.Root>
+      <DigitInput.Root length={4} size="m" />
+      <Hint.Root size="m" variant="default">
+        Вставьте код из буфера: цифры распределятся по ячейкам с текущей позиции.
+      </Hint.Root>
+    </div>
+  );
+}

package/src/components/digit-input/examples/controlled.tsx

@@ -0,0 +1,26 @@
+import { DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Значение держит родитель: `value` и `onChange`; подпись показывает прогресс заполнения.
+ * Паритет с `playground/snippets/digit-input/controlled.tsx`.
+ */
+export default function DigitInputControlledExample() {
+  const [code, setCode] = React.useState("");
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-s)",
+        alignItems: "flex-start",
+      }}
+    >
+      <DigitInput.Root length={4} value={code} onChange={setCode} />
+      <p style={{ margin: 0 }}>
+        Собранная строка: {code.length > 0 ? code : "пусто"} ({code.length}/4)
+      </p>
+    </div>
+  );
+}

package/src/components/digit-input/examples/error-state.tsx

@@ -0,0 +1,14 @@
+import { DigitInput, Hint, Label } from "prime-ui-kit";
+
+/** Отклонённый код: визуальная ошибка на группе и текст подсказки в тоне danger. */
+export default function ErrorStateExample() {
+  return (
+    <>
+      <Label.Root size="m">Код подтверждения</Label.Root>
+      <DigitInput.Root defaultValue="1230" hasError length={4} size="m" />
+      <Hint.Root size="m" variant="error">
+        Неверный код. Запросите новый или проверьте ввод.
+      </Hint.Root>
+    </>
+  );
+}

package/src/components/digit-input/examples/features.tsx

@@ -0,0 +1,30 @@
+import { DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Разная длина ряда, начальное значение, колбэк по завершении ввода.
+ * Паритет с `playground/snippets/digit-input/features.tsx`.
+ */
+export default function DigitInputFeaturesExample() {
+  const [completed, setCompleted] = React.useState<string | null>(null);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <p style={{ margin: 0 }}>Пропы length и defaultValue без внешнего состояния</p>
+      <DigitInput.Root length={4} defaultValue="2184" />
+      <DigitInput.Root length={6} defaultValue="12" />
+      <p style={{ margin: 0 }}>onComplete — один раз при заполнении последней ячейки</p>
+      <DigitInput.Root length={4} onComplete={(v) => setCompleted(v)} />
+      <p style={{ margin: 0 }}>
+        {completed ? `Последний полный код: ${completed}` : "Введите четыре цифры подряд"}
+      </p>
+    </div>
+  );
+}

package/src/components/digit-input/examples/otp-login.tsx

@@ -0,0 +1,17 @@
+import { DigitInput, Hint, Label } from "prime-ui-kit";
+import * as React from "react";
+
+/** SMS / OTP: шесть ячеек, контролируемое значение, подсказка про вставку из буфера. */
+export default function OtpLoginExample() {
+  const [code, setCode] = React.useState("");
+
+  return (
+    <>
+      <Label.Root size="m">Код из SMS</Label.Root>
+      <DigitInput.Root length={6} size="m" value={code} onChange={setCode} />
+      <Hint.Root size="m" variant="default">
+        Вставьте код из сообщения — цифры заполнят ячейки с текущей позиции.
+      </Hint.Root>
+    </>
+  );
+}

package/src/components/digit-input/examples/pin.tsx

@@ -0,0 +1,11 @@
+import { DigitInput, Label } from "prime-ui-kit";
+
+/** PIN: четыре цифры, увеличенный размер ячеек для удобного ввода на тач-экране. */
+export default function PinExample() {
+  return (
+    <>
+      <Label.Root size="l">PIN-код</Label.Root>
+      <DigitInput.Root length={4} size="l" />
+    </>
+  );
+}

package/src/components/digit-input/examples/resend-and-clear.tsx

@@ -0,0 +1,23 @@
+import { Button, DigitInput, Label } from "prime-ui-kit";
+import * as React from "react";
+
+/** Повторная отправка кода: сброс поля через родительское состояние. */
+export default function ResendAndClearExample() {
+  const [code, setCode] = React.useState("");
+
+  return (
+    <>
+      <Label.Root size="m">Код</Label.Root>
+      <DigitInput.Root length={4} size="m" value={code} onChange={setCode} />
+      <Button.Root
+        mode="stroke"
+        size="m"
+        type="button"
+        variant="neutral"
+        onClick={() => setCode("")}
+      >
+        Отправить снова
+      </Button.Root>
+    </>
+  );
+}

package/src/components/digit-input/examples/sizes.tsx

@@ -0,0 +1,23 @@
+import { DigitInput } from "prime-ui-kit";
+
+/**
+ * Четыре размера ячеек: `size` s, m, l, xl — те же токены контролов, что у поля ввода.
+ * Паритет с `playground/snippets/digit-input/sizes.tsx`.
+ */
+export default function DigitInputSizesExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "center",
+      }}
+    >
+      <DigitInput.Root size="s" length={4} defaultValue="1234" />
+      <DigitInput.Root size="m" length={4} defaultValue="1234" />
+      <DigitInput.Root size="l" length={4} defaultValue="1234" />
+      <DigitInput.Root size="xl" length={4} defaultValue="1234" />
+    </div>
+  );
+}

package/src/components/digit-input/examples/states.tsx

@@ -0,0 +1,22 @@
+import { DigitInput } from "prime-ui-kit";
+
+/**
+ * Обычное поле, визуальная ошибка (`hasError`) и отключённый ввод (`disabled`).
+ * Паритет с `playground/snippets/digit-input/states.tsx`.
+ */
+export default function DigitInputStatesExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "center",
+      }}
+    >
+      <DigitInput.Root length={4} defaultValue="42" />
+      <DigitInput.Root length={4} defaultValue="12" hasError />
+      <DigitInput.Root length={4} defaultValue="99" disabled />
+    </div>
+  );
+}

package/src/components/digit-input/examples/verification-step.tsx

@@ -0,0 +1,21 @@
+import { Button, DigitInput, Hint, Label } from "prime-ui-kit";
+import * as React from "react";
+
+/** Шаг подтверждения: кнопка «Продолжить» активна только после ввода полного кода. */
+export default function VerificationStepExample() {
+  const [code, setCode] = React.useState("");
+  const isComplete = code.length === 6;
+
+  return (
+    <>
+      <Label.Root size="m">Код из письма</Label.Root>
+      <DigitInput.Root length={6} size="m" value={code} onChange={setCode} />
+      <Button.Root disabled={!isComplete} size="m" type="button" variant="primary">
+        Продолжить
+      </Button.Root>
+      <Hint.Root size="m" variant="default">
+        Введите шестизначный код со страницы подтверждения email.
+      </Hint.Root>
+    </>
+  );
+}

package/src/components/divider/COMPONENT.md

@@ -1,70 +1,102 @@
 # Divider
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+## Canonical
 
-## About
+- **What:** `Divider.Root` draws a horizontal or vertical separator (pseudo-element lines) with optional **children** (label, icon + text). Nested controls inherit **`size`** via **`ControlSizeProvider`**.
+- **Defaults:** `orientation="horizontal"`, `variant="default"`, `size="m"`. **`align`** defaults to **`start`** for **`variant="text"`**, otherwise **`center`**.
+- **Import:** `import { Divider } from "prime-ui-kit"`.
 
-`Divider` is a non-interactive visual separator: a horizontal or vertical line drawn with pseudo-elements, optionally wrapping a label or icon so control sizing matches the chosen `size`.
+```tsx
+import { Divider } from "prime-ui-kit";
+
+export function Example() {
+  return <Divider.Root />;
+}
+```
+
+## Extended
+
+### About
+
+`Divider` is a non-interactive visual separator: a line built from `::before` / `::after`, optionally wrapping a label or icon. **`Icon`** inside **`children`** does not use its own size classes — glyph size follows **`--prime-divider-icon`** from the root **`data-size`**.
 
 **When to use**
 
 - Separate blocks in a form, card, or settings column without an extra bordered panel.
-- Add a vertical bar between adjacent toolbar or inline actions.
-- Mark rhythm between stacked sections when the parent is a flex column with `gap` (`variant="line-spacing"`).
-- Show a short section title inline with the line (`variant="text"`), alongside real headings or `section` structure where it matters.
+- Full-width rows in a list-like shell (`examples/list-separators.tsx`).
+- Section-style labels inline with the line (`variant="text"`) — see `examples/section-breaks.tsx`.
+- Between flex children in a column when rhythm comes from the parent **`gap`** (`variant="line-spacing"`) — see `examples/line-spacing-column.tsx`.
+- A vertical bar between toolbar actions (`orientation="vertical"`); parent row should **`align-items: stretch`** so the line gets height.
 
 **When not to use**
 
-- As the only semantic boundary for document structure — prefer meaningful headings or `hr` when the split carries meaning for assistive tech.
-- For switchable or collapsible grouping — use [Tabs](../tabs/COMPONENT.md) or [Accordion](../accordion/COMPONENT.md) instead.
-- In vertical orientation when the flex row has no definite height — the line needs stretch from the parent (`align-items: stretch`).
-- When the stroke is purely decorative noise next to text that already states the structure — hide it from AT (`role` / `aria-hidden`; see Rules).
+- As the only semantic boundary for document structure — use real headings / **`section`** (and **`hr`** when a thematic break is appropriate).
+- For switchable or collapsible grouping — use [Tabs](../tabs/COMPONENT.md) or [Accordion](../accordion/COMPONENT.md).
+- **`orientation="vertical"`** in a row with no definite height — the vertical line needs stretch from the parent.
+- Purely decorative repetition next to text that already states structure — hide from AT (**`role="presentation"`**, **`aria-hidden`**) per **Rules**.
 
-## Composition
+### Composition
 
-- Single public part: **`Divider.Root`** — a `div` root with line segments from `::before` / `::after`; optional **`children`** render inside a **`span`** (content slot) wrapped in **`ControlSizeProvider`** so nested controls inherit the same `size`.
-- **`Icon`** in the content slot does not apply its own `size` classes — width/height come from **`--prime-divider-icon`** on the root (`data-size`), so the glyph matches the divider tier.
-- No required child order beyond placing **`Divider.Root`** where the separator should appear in the layout.
+- Single public part: **`Divider.Root`** — optional **`children`** render in an inner **`span`** (**`styles.content`**).
+- Place **`Divider.Root`** in document order where the break should appear; no required child structure beyond optional slot content.
 
-### Minimal example
+### Examples (source)
 
-```tsx
-import { Divider } from "prime-ui-kit";
+| Scenario | File |
+|----------|------|
+| Section breaks (`variant="text"`) | [`examples/section-breaks.tsx`](examples/section-breaks.tsx) |
+| Splits inside one card | [`examples/card-splits.tsx`](examples/card-splits.tsx) |
+| List row separators | [`examples/list-separators.tsx`](examples/list-separators.tsx) |
+| Inset copy in a stack, full-bleed rules | [`examples/inset-stack.tsx`](examples/inset-stack.tsx) |
+| `line-spacing` + vertical toolbar | [`examples/line-spacing-column.tsx`](examples/line-spacing-column.tsx) |
 
-export function Example() {
-  return <Divider.Root />;
-}
-```
+Shared layout tokens for the examples: [`examples/divider-examples.module.css`](examples/divider-examples.module.css).
+
+Playground snippets (same demos as `playground/sections/DividerSection.tsx`):
+
+- **`variants.tsx`** — empty horizontal line; **`default`** with centered label; **`variant="text"`**; **`line-spacing`** between rows in a column; **`orientation="vertical"`** between toolbar-style buttons; full-width line between list rows (**`size="s"`**).
+- **`sizes.tsx`** — **`variant="text"`** at **`size`** **`s`**, **`m`**, and **`xl`** (three steps to compare label scale and spacing).
+- **`composition.tsx`** — **`Icon`** + label inside **`variant="text"`** **`size="m"`**; second divider at **`size="xl"`** with icon + label.
 
-## Rules
+### Rules
 
-- **Non-interactive:** there are no `disabled`, `loading`, or focus states; behavior comes only from standard HTML attributes on the root.
-- **`variant="default"`** — full-width line with an optional centered label (`align` defaults to **`center`** unless overridden).
-- **`variant="text"`** — section-style label; **`align`** defaults to **`start`** if you omit it.
-- **`variant="line-spacing"`** — intended between flex children; vertical rhythm comes from the parent’s **`gap`**, not from stretching the divider like a spacer block.
+- **Non-interactive:** no disabled/loading/focus states; behavior is plain **`div`** semantics unless you set **`role`** / **`aria-*`**.
+- **`variant="default"`** — full-width line; optional centered label unless **`align`** overrides.
+- **`variant="text"`** — uppercase section label styling; **`align`** defaults to **`start`**.
+- **`variant="line-spacing"`** — **`flex: 0 0 auto`** so it does not act as a flex grow spacer; spacing is the parent’s **`gap`**.
 - **Semantics:** default **`role="separator"`**; for **`orientation="vertical"`**, **`aria-orientation="vertical"`** is set automatically.
-- **Pure decoration:** if the line adds no information, set **`role="presentation"`** (or **`none`**) and **`aria-hidden`** so screen readers are not given a redundant separator.
-- **Sizing note:** rendered stroke thickness aligns with internal tokens for the chosen `data-size`; when matching adjacent controls, rely on the same **`size`** rather than ad hoc pixel tweaks.
+- **Decoration:** redundant lines → **`role="presentation"`** (or **`none`**) and **`aria-hidden`** (see list example).
+- **Sizing:** match adjacent controls with the same **`size`** prop; do not patch stroke width with ad hoc pixels.
 
-## API
+### API
 
-### Divider.Root
+#### Divider.Root
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| orientation | `"horizontal"` \| `"vertical"` | `"horizontal"` | No | Line direction across the row or between siblings in a row. |
-| align | `"start"` \| `"center"` \| `"end"` | `center` for `variant="default"` or `"line-spacing"`; `start` for `variant="text"` | No | How the line segments balance around the label. |
-| variant | `"default"` \| `"line-spacing"` \| `"text"` | `"default"` | No | Visual mode and flex participation (`line-spacing` for gap-driven stacks). |
-| size | `"s"` \| `"m"` \| `"l"` \| `"xl"` | `"m"` | No | Spacing, label typography, and nested control size context. |
-| children | `React.ReactNode` | — | No | Label, icon + text, or omit for a solid line. Nested **`Icon`** follows divider icon tokens, not `Icon` `size`. |
-| className | `string` | — | No | Additional class on the root element. |
-| role | `string` | `"separator"` | No | ARIA role; use `presentation` / `none` for decorative lines. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `aria-*`, `data-*`, event handlers, and other div props. |
-
-## Related
-
-- [Typography](../typography/COMPONENT.md) — body and heading text beside labels.
-- [Button](../button/COMPONENT.md) — toolbar actions often separated with a vertical divider.
-- [Link button](../link-button/COMPONENT.md) — inline actions in the same toolbar pattern.
-- [Tabs](../tabs/COMPONENT.md) — switchable sections instead of a static line.
-- [Accordion](../accordion/COMPONENT.md) — collapsible sections when separation should be interactive.
+| orientation | `"horizontal"` \| `"vertical"` | `"horizontal"` | No | Line direction. |
+| align | `"start"` \| `"center"` \| `"end"` | `center` for `default` / `line-spacing`; `start` for `text` | No | Balance of `::before` / `::after` stubs around content. |
+| variant | `"default"` \| `"line-spacing"` \| `"text"` | `"default"` | No | Visual mode and flex participation. |
+| size | `"s"` \| `"m"` \| `"l"` \| `"xl"` | `"m"` | No | Gap, label type, icon scale, **`ControlSizeProvider`** value. |
+| children | `React.ReactNode` | — | No | Label, icon + text, or omit for a solid line. |
+| className | `string` | — | No | Extra class on the root. |
+| role | `string` | `"separator"` | No | Override for decorative separators. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `aria-*`, `data-*`, etc. |
+
+### Related
+
+- [Typography](../typography/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [Link button](../link-button/COMPONENT.md)
+- [Tabs](../tabs/COMPONENT.md)
+- [Accordion](../accordion/COMPONENT.md)
+
+## LLM note
+
+- One export shape: **`Divider.Root`** only; no subcomponents.
+- **`variant` × `align` defaults:** `text` → **`align` `start`**; else **`center`** (explicit **`align`** always wins).
+- **`line-spacing`:** use only when the parent flex column uses **`gap`** for vertical rhythm; divider must not be relied on for layout height.
+- **Vertical:** requires ancestor **`align-items: stretch`** (or explicit height) so `::before`/`::after` flex segments fill the row.
+- **Children:** toggles inner **`span`** and **`ControlSizeProvider`**; **`Icon`** ignores its own **`size`** when inside divider content.
+- **a11y:** default **`separator`** is announced; for decorative list lines between items, mirror **`examples/list-separators.tsx`**: **`ul`/`li`**, separator **`li`** with **`aria-hidden`**, **`Divider.Root`** with **`role="presentation"`**.
+- **Playground alignment:** `variants.tsx` is one frame (empty line, `default` label, `text`, `line-spacing` column, vertical toolbar, list-row separator); `sizes.tsx` is `text` at **s / m / xl**; `composition.tsx` is icon + text at **m** and **xl**.

package/src/components/divider/examples/card-splits.tsx

@@ -0,0 +1,27 @@
+import { Divider } from "prime-ui-kit";
+
+import s from "./divider-examples.module.css";
+
+/** Inside one card: horizontal rules separate header, body, and a summary footer without extra bordered panels. */
+export default function DividerCardSplitsExample() {
+  return (
+    <section className={s.card}>
+      <div className={s.stack}>
+        <div>
+          <h3 className={s.subheading}>Order summary</h3>
+          <p className={s.muted}>Ships in 2–3 business days</p>
+        </div>
+
+        <Divider.Root size="m" />
+
+        <p className={s.body}>
+          Subtotal, shipping, and tax are estimated until checkout. You can edit the cart before
+          paying.
+        </p>
+
+        <Divider.Root size="m">Total</Divider.Root>
+        <p className={s.body}>$128.00 USD</p>
+      </div>
+    </section>
+  );
+}

package/src/components/divider/examples/divider-examples.module.css

@@ -0,0 +1,137 @@
+/* Layout shells for COMPONENT.md examples — semantic tokens only */
+
+.shell {
+  box-sizing: border-box;
+  width: 100%;
+  max-width: min(100%, 26.25rem);
+}
+
+.card {
+  composes: shell;
+  padding: var(--prime-sys-spacing-x4);
+  border: 1px solid var(--prime-sys-color-border-subtle);
+  border-radius: var(--prime-sys-shape-radius-l);
+  background-color: var(--prime-sys-color-surface-default);
+}
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.stackLoose {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x4);
+}
+
+.heading {
+  margin: 0;
+  font-size: var(--prime-sys-typography-sizeScale-l);
+  font-weight: var(--prime-sys-typography-weight-semibold);
+}
+
+.subheading {
+  margin: 0;
+  font-size: var(--prime-sys-typography-sizeScale-m);
+  font-weight: var(--prime-sys-typography-weight-semibold);
+}
+
+.body {
+  margin: 0;
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  color: var(--prime-sys-color-content-secondary);
+  line-height: var(--prime-sys-typography-lineHeightScale-s);
+}
+
+.muted {
+  margin: 0;
+  font-size: var(--prime-sys-typography-sizeScale-xs);
+  color: var(--prime-sys-color-content-muted);
+}
+
+.list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  border: 1px solid var(--prime-sys-color-border-subtle);
+  border-radius: var(--prime-sys-shape-radius-m);
+  overflow: hidden;
+  background-color: var(--prime-sys-color-surface-raised);
+}
+
+.listRow {
+  padding: var(--prime-sys-spacing-x3) var(--prime-sys-spacing-x4);
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.listSep {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.insetBody {
+  margin: 0;
+  padding-left: var(--prime-sys-spacing-x4);
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.rowWithIcon {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.iconStub {
+  flex-shrink: 0;
+  width: 2.25rem;
+  height: 2.25rem;
+  border-radius: var(--prime-sys-shape-radius-m);
+  background-color: var(--prime-sys-color-surface-accentSoft);
+}
+
+.rowMain {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-xs);
+}
+
+.rowTitle {
+  margin: 0;
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  font-weight: var(--prime-sys-typography-weight-medium);
+}
+
+.rowDesc {
+  margin: 0;
+  font-size: var(--prime-sys-typography-sizeScale-xs);
+  color: var(--prime-sys-color-content-muted);
+}
+
+.toolbar {
+  display: flex;
+  align-items: stretch;
+  gap: var(--prime-sys-spacing-x2);
+  min-height: 2.5rem;
+  padding: 0 var(--prime-sys-spacing-x3);
+  border: 1px solid var(--prime-sys-color-border-subtle);
+  border-radius: var(--prime-sys-shape-radius-m);
+  background-color: var(--prime-sys-color-surface-raised);
+  width: fit-content;
+}
+
+.toolbarBtn {
+  align-self: center;
+  padding: var(--prime-sys-spacing-xs) var(--prime-sys-spacing-m);
+  border: none;
+  background: transparent;
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  font-weight: var(--prime-sys-typography-weight-medium);
+  cursor: pointer;
+}