prime-ui-kit 0.15.0 → 0.17.0

package/dist/skill/reference/components/description-list/examples/screen.tsx

@@ -1,6 +1,5 @@
-/** A nested record: the path, the title with its status and due date and the record's actions by weight in the app header, a main column with the line items and a side column with the client's details and the history — `orientation`. */
+/** A nested record: the path, the title with its status and due date and the record's actions by weight in its top bar, a main column with the line items and their totals and a side column with the client's details and the history — `align`, `orientation`. */
 import {
-  AppHeader,
   Avatar,
   Breadcrumb,
   Button,
@@ -8,11 +7,9 @@ import {
   DataTable,
   type DataTableColumn,
   DescriptionList,
-  Dropdown,
   Icon,
   LinkButton,
-  PageContent,
-  PageToolbar,
+  Page,
   Timeline,
   Typography,
 } from "prime-ui-kit";
@@ -75,140 +72,128 @@ const COLUMNS: DataTableColumn<Line>[] = [
 
 export default function DescriptionListScreenExample() {
   return (
-    <>
-      {/* A nested record titles itself in the app header: the path up to the list, the record as the
-          only h1 with its status and due date under it, the record's actions in the tools row. */}
-      <AppHeader.Root>
-        <AppHeader.Start>
+    <Page.Root>
+      {/* A nested record titles itself in its top bar: the path up to the list, the record as the
+          only h1 with its status and due date under it, the record's actions at the end. */}
+
+      <Page.TopBar>
+        <Page.Heading>
           <Breadcrumb.Root>
             <Breadcrumb.Item href="#invoices">Счета</Breadcrumb.Item>
           </Breadcrumb.Root>
-          <AppHeader.Separator />
-          <AppHeader.Title>
-            Счёт № 2026-0418
-            <AppHeader.Description>Отправлен · оплатить до 14 октября</AppHeader.Description>
-          </AppHeader.Title>
-        </AppHeader.Start>
-        <AppHeader.Tools>
-          <PageToolbar.Root aria-label="Счёт № 2026-0418">
-            <PageToolbar.Actions>
-              <Dropdown.Root>
-                <Dropdown.Trigger>
-                  <Button.Root variant="soft" tone="neutral" aria-label="Другие действия">
-                    <Button.Icon>
-                      <Icon name="action.more" />
-                    </Button.Icon>
-                  </Button.Root>
-                </Dropdown.Trigger>
-                <Dropdown.Content>
-                  <Dropdown.Item>Дублировать</Dropdown.Item>
-                  <Dropdown.Item>Скачать PDF</Dropdown.Item>
-                  <Dropdown.Separator />
-                  <Dropdown.Item tone="danger">Аннулировать счёт</Dropdown.Item>
-                </Dropdown.Content>
-              </Dropdown.Root>
-              <Button.Root variant="soft" tone="neutral" aria-label="Напомнить клиенту">
-                <Button.Icon>
-                  <Icon name="action.send" />
-                </Button.Icon>
-              </Button.Root>
-              <Button.Root>Отметить оплату</Button.Root>
-            </PageToolbar.Actions>
-          </PageToolbar.Root>
-        </AppHeader.Tools>
-      </AppHeader.Root>
-
-      <PageContent.Root>
-        <PageContent.Body>
-          <div className={styles.columns}>
-            <PageContent.Section label="Позиции" className={styles.main}>
-              <DataTable
-                columns={COLUMNS}
-                rows={LINES}
-                getRowKey={(row) => row.id}
-                paging="none"
-                highlightRowOnHover={false}
-              />
-              {/* Totals line up with the «Сумма» column of the table above: a layout of its own. */}
-              <dl className={styles.totals}>
-                {TOTALS.map((row) => (
-                  <div key={row.label} className={styles.totalRow}>
-                    <dt>
-                      <Typography variant="body-m" tone="secondary">
-                        {row.label}
+          <Page.Title>Счёт № 2026-0418</Page.Title>
+          <Page.Description>Отправлен · оплатить до 14 октября</Page.Description>
+        </Page.Heading>
+        {/* By weight: when the row runs short the soft actions show only their icons, then fold
+            into «⋯»; the primary action stays. */}
+        <Page.Actions>
+          <Button.Root variant="soft" tone="neutral">
+            <Button.Icon>
+              <Icon name="action.copy" />
+            </Button.Icon>
+            Дублировать
+          </Button.Root>
+          <Button.Root variant="soft" tone="neutral">
+            <Button.Icon>
+              <Icon name="action.download" />
+            </Button.Icon>
+            Скачать PDF
+          </Button.Root>
+          <Button.Root variant="soft" tone="neutral">
+            <Button.Icon>
+              <Icon name="action.send" />
+            </Button.Icon>
+            Напомнить
+          </Button.Root>
+          <Button.Root>
+            <Button.Icon>
+              <Icon name="action.check" />
+            </Button.Icon>
+            Отметить оплату
+          </Button.Root>
+        </Page.Actions>
+      </Page.TopBar>
+      <Page.Body>
+        <div className={styles.columns}>
+          <Page.Section label="Позиции" className={styles.main}>
+            <DataTable
+              columns={COLUMNS}
+              rows={LINES}
+              getRowKey={(row) => row.id}
+              paging="none"
+              highlightRowOnHover={false}
+            />
+            {/* The totals end where the «Сумма» column of the table above ends. */}
+            <DescriptionList.Root align="end" className={styles.totals}>
+              {TOTALS.map((row) => (
+                <DescriptionList.Item key={row.label} label={row.label}>
+                  {row.value}
+                </DescriptionList.Item>
+              ))}
+              <DescriptionList.Item
+                label={
+                  <Typography as="span" variant="title-m">
+                    К оплате
+                  </Typography>
+                }
+              >
+                <Typography as="span" variant="title-m" numeric="tabular">
+                  {MONEY.format(NET + VAT)}
+                </Typography>
+              </DescriptionList.Item>
+            </DescriptionList.Root>
+          </Page.Section>
+          <aside className={styles.aside} aria-label="Клиент и история">
+            <Card.Root variant="panel">
+              <Card.Header>
+                <Card.Title as="h2">Клиент</Card.Title>
+              </Card.Header>
+              <Card.Body>
+                <div className={styles.client}>
+                  <span className={styles.person}>
+                    <Avatar.Root color="teal">
+                      <Avatar.Fallback>СВ</Avatar.Fallback>
+                    </Avatar.Root>
+                    <span className={styles.personText}>
+                      <Typography as="span" variant="title-s">
+                        ООО «Северный ветер»
                       </Typography>
-                    </dt>
-                    <dd>
-                      <Typography variant="body-m" className={styles.amount}>
-                        {row.value}
+                      <Typography as="span" variant="caption" tone="muted">
+                        ИНН 7704 512 908
                       </Typography>
-                    </dd>
-                  </div>
-                ))}
-                <div className={styles.totalRow}>
-                  <dt>
-                    <Typography variant="title-m">К оплате</Typography>
-                  </dt>
-                  <dd>
-                    <Typography variant="title-m" className={styles.amount}>
-                      {MONEY.format(NET + VAT)}
-                    </Typography>
-                  </dd>
-                </div>
-              </dl>
-            </PageContent.Section>
-            <aside className={styles.aside} aria-label="Клиент и история">
-              <Card.Root variant="panel">
-                <Card.Header>
-                  <Card.Title as="h2">Клиент</Card.Title>
-                </Card.Header>
-                <Card.Body>
-                  <div className={styles.client}>
-                    <span className={styles.person}>
-                      <Avatar.Root color="teal">
-                        <Avatar.Fallback>СВ</Avatar.Fallback>
-                      </Avatar.Root>
-                      <span className={styles.personText}>
-                        <Typography as="span" variant="title-s">
-                          ООО «Северный ветер»
-                        </Typography>
-                        <Typography as="span" variant="caption" tone="muted">
-                          ИНН 7704 512 908
-                        </Typography>
-                      </span>
                     </span>
-                    <DescriptionList.Root orientation="vertical">
-                      <DescriptionList.Item label="Контакт">
-                        Ольга Мартынова, финансовый директор
-                      </DescriptionList.Item>
-                      <DescriptionList.Item label="Почта для счетов">
-                        <LinkButton href="mailto:billing@veter.ru">billing@veter.ru</LinkButton>
-                      </DescriptionList.Item>
-                    </DescriptionList.Root>
-                  </div>
-                </Card.Body>
-              </Card.Root>
-              <Card.Root variant="panel">
-                <Card.Header>
-                  <Card.Title as="h2">История</Card.Title>
-                </Card.Header>
-                <Card.Body>
-                  <Timeline.Root>
-                    <Timeline.Group>
-                      {HISTORY.map((event) => (
-                        <Timeline.Item key={event.id}>
-                          <Timeline.Title>{event.title}</Timeline.Title>
-                          <Timeline.Meta>{event.date}</Timeline.Meta>
-                        </Timeline.Item>
-                      ))}
-                    </Timeline.Group>
-                  </Timeline.Root>
-                </Card.Body>
-              </Card.Root>
-            </aside>
-          </div>
-        </PageContent.Body>
-      </PageContent.Root>
-    </>
+                  </span>
+                  <DescriptionList.Root orientation="vertical">
+                    <DescriptionList.Item label="Контакт">
+                      Ольга Мартынова, финансовый директор
+                    </DescriptionList.Item>
+                    <DescriptionList.Item label="Почта для счетов">
+                      <LinkButton href="mailto:billing@veter.ru">billing@veter.ru</LinkButton>
+                    </DescriptionList.Item>
+                  </DescriptionList.Root>
+                </div>
+              </Card.Body>
+            </Card.Root>
+            <Card.Root variant="panel">
+              <Card.Header>
+                <Card.Title as="h2">История</Card.Title>
+              </Card.Header>
+              <Card.Body>
+                <Timeline.Root>
+                  <Timeline.Group>
+                    {HISTORY.map((event) => (
+                      <Timeline.Item key={event.id}>
+                        <Timeline.ItemTitle>{event.title}</Timeline.ItemTitle>
+                        <Timeline.ItemMeta>{event.date}</Timeline.ItemMeta>
+                      </Timeline.Item>
+                    ))}
+                  </Timeline.Group>
+                </Timeline.Root>
+              </Card.Body>
+            </Card.Root>
+          </aside>
+        </div>
+      </Page.Body>
+    </Page.Root>
   );
 }

package/dist/skill/reference/components/description-list/examples/sizes.tsx

@@ -1,15 +1,13 @@
 /** Every tier changes the label and value type and the gap between pairs — `size`. */
 import { DescriptionList, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function DescriptionListSizesExample() {
   return (
-    <div className={styles.sizes}>
+    <div>
       {SIZES.map((size) => (
-        <div key={size} className={styles.size}>
+        <div key={size}>
           <DescriptionList.Root size={size}>
             <DescriptionList.Item label="Счёт">№ 4821 от 3 октября</DescriptionList.Item>
             <DescriptionList.Item label="Сумма">94 750 ₽</DescriptionList.Item>

package/dist/skill/reference/components/description-list/examples/structure.tsx

@@ -1,4 +1,4 @@
-/** Optional pieces of a pair: a Badge or a link as the value, a row action and an empty value with its own mark — `DescriptionList.ItemAction`, `labels`. */
+/** Optional pieces of a pair: a Badge or a link as the value, a row action that is a link and an empty value with its own mark — `DescriptionList.ItemAction`, `asChild`, `labels`. */
 import { Badge, DescriptionList, Icon, LinkButton } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -8,18 +8,17 @@ export default function DescriptionListStructureExample() {
     <div className={styles.column}>
       <DescriptionList.Root labels={{ empty: "Нет", emptyText: "Нет данных" }}>
         <DescriptionList.Item label="Статус">
-          <Badge.Root color="green">Оплачен</Badge.Root>
+          <Badge.Root tone="success">Оплачен</Badge.Root>
         </DescriptionList.Item>
         <DescriptionList.Item label="Договор">
           <LinkButton href="#contract-118">Договор № 118 от 12 марта</LinkButton>
         </DescriptionList.Item>
         <DescriptionList.Item label="Почта">
           finance@severny-veter.ru
-          <DescriptionList.ItemAction
-            label="Написать"
-            onClick={() => window.open("mailto:finance@severny-veter.ru")}
-          >
-            <Icon name="action.send" />
+          <DescriptionList.ItemAction label="Написать" asChild>
+            <a href="mailto:finance@severny-veter.ru">
+              <Icon name="action.send" />
+            </a>
           </DescriptionList.ItemAction>
         </DescriptionList.Item>
         <DescriptionList.Item label="Скидка">{null}</DescriptionList.Item>

package/dist/skill/reference/components/description-list/examples/totals.tsx

@@ -0,0 +1,40 @@
+/** The totals of an invoice: every amount at the end of its row in tabular figures, the amount due a step larger — `align`. */
+import { Card, DescriptionList, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TOTALS = [
+  { label: "Без НДС", value: "400 000 ₽" },
+  { label: "Скидка 5%", value: "−20 000 ₽" },
+  { label: "НДС 20%", value: "76 000 ₽" },
+];
+
+export default function DescriptionListTotalsExample() {
+  return (
+    <Card.Root variant="panel" className={styles.column}>
+      <Card.Header>
+        <Card.Title>Итого по счёту № 2026-0418</Card.Title>
+      </Card.Header>
+      <Card.Body>
+        <DescriptionList.Root align="end">
+          {TOTALS.map((row) => (
+            <DescriptionList.Item key={row.label} label={row.label}>
+              {row.value}
+            </DescriptionList.Item>
+          ))}
+          <DescriptionList.Item
+            label={
+              <Typography as="span" variant="title-m">
+                К оплате
+              </Typography>
+            }
+          >
+            <Typography as="span" variant="title-m" numeric="tabular">
+              456 000 ₽
+            </Typography>
+          </DescriptionList.Item>
+        </DescriptionList.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/digit-input/COMPONENT.md

@@ -37,7 +37,7 @@ DigitInput            field frame: label row → cells → support row (hint | e
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `length` | `number` | `4` | Number of cells. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier: the cell is a square on its own scale, two steps above the control heights (36 · 40 · 48 · 56 · 64); label and hint follow the field tier. Without it the tier of its host (LoginForm, a panel), else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier: the cell is a square on its own scale, two steps above the control heights (36 · 40 · 48 · 56 · 64); label and hint follow the field tier. Without it the tier of its host (LoginForm, a panel), else `m`. |
 | `label` | `ReactNode` | — | Label above the cells; names the group (`aria-labelledby`) and focuses the first cell on click. Without it the group is named by `labels.group`. |
 | `required` | `boolean` | — | Red `*` after the label and native `required` on every cell. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
@@ -82,7 +82,8 @@ No `variant` or `tone`.
 | `groupSize` | an extra gap before every group (`3` → 123 456) | codes of six digits and longer | — |
 | `mask` | dots instead of digits | PIN codes | `false` |
 | `required` / `optional` | red `*` / muted «необязательно» after the label | mark the minority of the form | — |
-| `focusRing={false}` | no focus ring; the focus fill and the caret remain | a single code on a screen where focus is obvious | `true` |
+| `focusRing` | `false`: no focus ring; the focus fill and the caret remain | a single code on a screen where focus is obvious | `true` |
+| `autoFocus` | the entry cell takes focus on mount | the code is the one task of its step (a verification screen) | `false` |
 
 **Combinations**
 - Recommended: `onComplete` returning the check's promise — the field waits, shows success or clears and shows the reason; or, checking by hand, `error` set after a rejected code and cleared in `onValueChange`.
@@ -94,7 +95,7 @@ No `variant` or `tone`.
 | State | Driven by | DOM |
 |---|---|---|
 | hover | — | cell fill darkens (not on focused or disabled cells) |
-| focus | keyboard / click | focused cell: focus fill and its content selected so a new digit replaces it; one inset ring for the row appears on the cell and glides to the next one (`fast` · emphasized) instead of each cell drawing its own; the code has no gaps, so focusing a cell past the first empty one moves focus to that entry cell |
+| focus | keyboard / click | focused cell: focus fill and its content selected so a new digit replaces it; one inset ring for the row appears on the cell and glides to the next one (`fast` · emphasized) instead of each cell drawing its own; the code has no gaps, so focusing a cell past the first empty one moves focus to that entry cell; the code is one tab stop (the focused cell, else the entry cell) |
 | filled cell | a digit in the cell | `data-filled="true"` on the cell; the digit fades in as it lands |
 | checking | `onComplete` returned a pending promise | `aria-busy` and `data-pending="true"` on the fieldset, cells `readonly` and quiet to 0.6 (`fast`, both ways); typing waits for the answer |
 | refused | that promise rejected | the code clears and focus goes to the first cell; the reason (the rejection's message, else `labels.failed`) becomes the error (unless you pass `error`) and shakes in, a polite live region speaks it; typing again takes it away |
@@ -110,21 +111,26 @@ No `variant` or `tone`.
 ## Layout & spacing
 - The field hugs its cells (label left-aligned above them); with `fullWidth` it fills the container.
 - The code is always one row: in a container narrower than the row the cells narrow and keep the tier height, so no digit or group wraps to a second line.
+- On a coarse pointer an `xs` or `s` cell grows to the 44 px touch target itself (an input takes no taps through a hit area drawn around it).
 - Label → cells: tier `label-gap`; cells → hint: tier `hint-gap` — the same rhythm as every field.
 - Put the submit button below or next to the code; with the same `size` it lines up with the cells.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
-| `0`–`9` | Types into the first empty cell and moves to the next one. |
+| `0–9` | Types into the first empty cell and moves to the next one. |
 | `Backspace` | Clears the cell; on an empty cell moves to the previous one. |
 | `ArrowLeft` · `ArrowRight` | Moves between filled cells and the entry cell. |
 | `Home` · `End` | Jumps to the first cell / the entry cell. |
-| `Tab` | Leaves the code. |
+| `Tab` | Enters the code at the entry cell; from any cell, leaves it. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The cells sit in a `<fieldset>` (`role="group"`) named by the `label` (`aria-labelledby`) or `labels.group`; clicking the label focuses the first cell.
 - Each cell is named by `labels.cell` («Цифра 1 из 6») and has `autocomplete="one-time-code"` and `inputmode="numeric"`, so SMS codes are suggested on phones.
 - The hint or the error is linked to the group through `aria-describedby`; invalid cells carry `aria-invalid`.
@@ -163,5 +169,5 @@ No `variant` or `tone`.
 - A hand-made «checking…» state, a disabled field and a manual reset after a wrong code → return the check's promise from `onComplete`.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Input](../input/COMPONENT.md), [LoginForm](../login-form/COMPONENT.md)

package/dist/skill/reference/components/digit-input/examples/examples.module.css

@@ -1,11 +1,11 @@
 /* Layout of the DigitInput scenarios: semantic tokens only. */
 
-/* full-width.tsx, in-form.tsx: a phone-width column, code above the action (group → action 24). */
+/* full-width.tsx: a phone-width column, code above the action (group → action 24). */
 .panel {
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-6);
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 /* in-form.tsx: the form hugs the cells; as a grid item the button stretches to the code's width. */

package/dist/skill/reference/components/digit-input/examples/grouped.tsx

@@ -1,11 +1,11 @@
 /** A long code read in chunks with a wider gap between groups — `groupSize`. */
-import { DigitInput } from "prime-ui-kit";
+import { DigitInput, Fieldset } from "prime-ui-kit";
 
 export default function DigitInputGroupedExample() {
   return (
-    <>
+    <Fieldset aria-label="Подтверждение входа">
       <DigitInput label="Код из приложения" length={6} groupSize={3} defaultValue="482915" />
-      <DigitInput label="Резервный код" length={8} groupSize={4} />
-    </>
+      <DigitInput label="Резервный код" length={6} groupSize={2} />
+    </Fieldset>
   );
 }

package/dist/skill/reference/components/digit-input/examples/in-form.tsx

@@ -32,7 +32,7 @@ export default function DigitInputInFormExample() {
         length={PIN_LENGTH}
         mask
         required
-        hint={`Для примера — ${PIN}`}
+        hint="Четыре цифры, которые вы задали при выпуске карты"
         error={error}
         onValueChange={() => {
           setError(undefined);

package/dist/skill/reference/components/digit-input/examples/sizes.tsx

@@ -5,10 +5,12 @@ const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function DigitInputSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
-        <DigitInput key={size} size={size} label={size} defaultValue="2048" />
+        <div key={size}>
+          <DigitInput size={size} label={size} defaultValue="2048" />
+        </div>
       ))}
-    </>
+    </div>
   );
 }

package/dist/skill/reference/components/digit-input/examples/states.tsx

@@ -3,11 +3,19 @@ import { DigitInput } from "prime-ui-kit";
 
 export default function DigitInputStatesExample() {
   return (
-    <>
-      <DigitInput label="default" defaultValue="42" />
-      <DigitInput label="disabled" defaultValue="42" disabled />
-      <DigitInput label="invalid" defaultValue="4271" invalid />
-      <DigitInput label="success" defaultValue="4821" success hint="Код подтверждён" />
-    </>
+    <div>
+      <div>
+        <DigitInput label="default" defaultValue="42" />
+      </div>
+      <div>
+        <DigitInput label="disabled" defaultValue="42" disabled />
+      </div>
+      <div>
+        <DigitInput label="invalid" defaultValue="4271" invalid />
+      </div>
+      <div>
+        <DigitInput label="success" defaultValue="4821" success hint="Код подтверждён" />
+      </div>
+    </div>
   );
 }

package/dist/skill/reference/components/digit-input/examples/validation.tsx

@@ -18,7 +18,7 @@ export default function DigitInputValidationExample() {
         onValueChange={() => setError(undefined)}
         onComplete={(value) => setError(value === CODE ? undefined : "Неверный код")}
       />
-      <DigitInput label="Код приглашения" optional />
+      <DigitInput label="Код приглашения" length={6} optional />
     </>
   );
 }

package/dist/skill/reference/components/divider/COMPONENT.md

@@ -9,10 +9,10 @@
 - Separate rows of a list or groups inside one panel, menu or card.
 - An «или» between two alternative actions (sign in / get a link by email).
 - A section heading drawn on a line (`align="start"`).
-- A vertical break between groups of buttons in a toolbar row.
+- A vertical break between groups of buttons in a toolbar row; `inset` makes it one text line tall (a header).
 
 ## When not to use
-- To separate cards or panels from each other → use fill and spacing ([Card](../card/COMPONENT.md), [PageContent](../page-content/COMPONENT.md) sections), never a line.
+- To separate cards or panels from each other → use fill and spacing ([Card](../card/COMPONENT.md), [Page](../../layout/page/COMPONENT.md) sections), never a line.
 - Separators inside a dropdown menu → `Dropdown.Separator` ([Dropdown](../dropdown/COMPONENT.md)).
 - Row lines of a table → [DataTable](../data-table/COMPONENT.md) draws them itself.
 
@@ -38,7 +38,8 @@ Divider          <div role="separator">; the line is drawn by ::before / ::after
 |---|---|---|---|
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` stretches to the height of its flex row and sets `aria-orientation`. |
 | `align` | `"start" \| "center" \| "end"` | `"center"` | Position of the label on the line; `start` reads as a section heading. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the label: type, gap and icon size. Match the content around the divider. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the label: type, gap and icon size. Without it the tier of the content around (a menu, a panel with a size), else `m`. |
+| `inset` | `boolean` | `false` | The line stands off its neighbours by the tier gap; a vertical one is one text line tall, centred in its row (a header, a toolbar). |
 | `children` | `ReactNode` | — | Label: text, an `Icon`, or both. Omit for a plain line. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` (`"presentation"` for a purely visual line), `aria-label` and the other div attributes. |
 
@@ -65,27 +66,39 @@ No `variant`, `tone` or `color`: one hairline in `border-subtle`, label in `text
 | `m` | label 13/20, icon 16 | regular content | yes |
 | `l` · `xl` | label 14/20 · 16/24, icon 20 | large panels | |
 
+Without `size` the divider takes the tier of the content around it (a menu, a panel with a size), else `m`. The label type is a text role: caption for xs and s, body-s for m, body-m for l, body-l for xl.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `inset` | the tier gap on both sides of the line; vertical: one text line tall, centred in the row | a break between groups in a header or a toolbar | off |
+
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | plain line | no children | `:empty`, one line |
-| labelled | children | two line halves, each at least `--prime-space-6` long |
-| orientation / align / size | props | `data-orientation`, `data-align`, `data-size`, `aria-orientation` when vertical |
+| labelled | children that draw something (`false`, `null` and `""` do not) | two line halves, each at least `--prime-space-6` long; the separator is named by its label (`aria-labelledby`) |
+| orientation / align / size / inset | props | `data-orientation`, `data-align`, `data-size`, `data-inset`, `aria-orientation` when vertical |
 
 ## Layout & spacing
-- No margins: the parent's `gap` sets the rhythm around the line.
+- No margins: the parent's `gap` sets the rhythm around the line (`inset` adds the tier gap).
 - Horizontal: `width: 100%` in its flex column. Vertical: `align-self: stretch` in a flex row.
-- Label gap and icon size follow the tier (`--prime-control-<size>-gap`, `-icon`).
+- Label gap and icon size follow the tier (the shared tier table, `internal/fieldTier`).
+- Bleed: a host whose padding the line should cross (a menu panel) sets `--divider-bleed` to that padding; the line reaches past it on both sides, inline for a horizontal line, block for a vertical one.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `role="separator"`; vertical sets `aria-orientation="vertical"`.
 - A purely visual line between rows that are separate anyway → `role="presentation"`.
-- The label is read as the separator's text; an icon-only divider needs `aria-label`.
+- A labelled separator is named by its label (`aria-labelledby`); an icon-only divider needs `aria-label`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -95,19 +108,20 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | Hairlines between the rows of a settings list. |
+| [overview.tsx](examples/overview.tsx) | Hairlines between the rows of a settings card — `Divider`. |
 | [sizes.tsx](examples/sizes.tsx) | The label at every tier, matching the content around it — `size`. |
-| [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and an icon alone on the line; the divider sizes it. |
+| [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and an icon alone on the line named by `aria-label`; the divider sizes the icon — `Icon`, `aria-label`. |
 | [align.tsx](examples/align.tsx) | The label at the start, the center or the end of the line; `start` heads a section — `align`. |
-| [vertical.tsx](examples/vertical.tsx) | A vertical line between groups of toolbar buttons — `orientation`. |
-| [or-separator.tsx](examples/or-separator.tsx) | An "or" line between two ways to sign in. |
+| [vertical.tsx](examples/vertical.tsx) | Vertical lines between groups of toolbar buttons: one as tall as the row, one inset to a text line — `orientation`, `inset`. |
+| [or-separator.tsx](examples/or-separator.tsx) | An "or" line between two ways to sign in, its label naming the separator — `Divider`. |
 
 ## Mistakes
 - Margins on the divider → spacing via the parent `gap`.
 - Lines between cards → separate cards by fill and spacing.
 - `<Icon size="l" />` inside the label → leave the size to the divider.
 - A vertical divider in a block container (no height) → place it in a flex row.
+- A host class that shortens a vertical divider or pulls it across padding → `inset`, or `--divider-bleed`.
 
 ## Related
-- **Built from:** —
-- **See also:** [Dropdown](../dropdown/COMPONENT.md) (`Dropdown.Separator`), [Select](../select/COMPONENT.md) (`Select.Separator`), [Accordion](../accordion/COMPONENT.md), [Card](../card/COMPONENT.md), [PageContent](../page-content/COMPONENT.md)
+- **Built from:** `internal/fieldClasses` (the tier table), `internal/textRole` (the label type), `internal/hasContent`
+- **See also:** [Dropdown](../dropdown/COMPONENT.md) (`Dropdown.Separator`), [Select](../select/COMPONENT.md) (`Select.Separator`), [Accordion](../accordion/COMPONENT.md), [Card](../card/COMPONENT.md), [Page](../../layout/page/COMPONENT.md)