prime-ui-kit 0.16.0 → 0.18.0

package/dist/skill/ux.md

@@ -55,8 +55,10 @@ Every word on screen must carry something the person does not see already.
   list already counts. The list label names the rows.
 - **No label that repeats its heading.** A field «Цена» inside the section «Цена» needs no label of
   its own beyond what the section says; a group of one field is the field.
-- **A unit lives in one place.** In the field (`Input.InlineAffix`) or in the heading, never both.
-  Prefer the field: the unit stays beside the number when the row stacks.
+- **A unit lives in one place.** In the field (`Input.InlineAffix`) or in the heading, never both;
+  never in the field's own label («Бюджет», not «Бюджет, ₽»). Prefer the field: the unit stays
+  beside the number when the row stacks, and a screen reader hears it with the field (the affix
+  describes the input; `aria-label="рублей"` on it when the sign reads badly).
 - **No text that explains the layout.** «Двигатель, места и скорость всегда первыми» — the lock on
   those rows says it. A hint says what the person cannot see (a format, a consequence, a limit).
 - **One name per thing.** The same action, entity and status keep one word on the whole screen
@@ -97,7 +99,7 @@ Pick the lightest step that keeps the person safe ([choosing.md](choosing.md) ha
 | One standalone action that is easy to redo by hand | `Button.Root holdToConfirm` |
 | Irreversible loss of work, or an outward action that cannot be called back once it leaves the product (an invoice or a message sent to a client, a payment) | `ConfirmDialog` that names the thing and the consequence |
 | Bulk destructive | `ConfirmDialog` that names the count («Удалить 12 счетов?») |
-| Leaving a form with changes | `Modal.Guard` / `Drawer.Guard dirty` |
+| Leaving a form with changes | `Modal.Guard` / `Drawer.Guard dirty`; a form that is the page — `Page.Guard dirty` |
 
 A confirm on every action trains people to click through it; the one that mattered is then missed.
 Which button starts each step and how the confirm behaves:

package/dist/tokens/layers.d.ts

@@ -6,6 +6,8 @@ type LayerTheme = {
     hi: number;
     /** Direction of control fills from their host: −1 darker, +1 lighter. */
     control: 1 | -1;
+    /** Steps from a track up to its selected segment (thumb). */
+    selected: number;
 };
 export declare const LIGHT_LAYERS: LayerTheme;
 export declare const DARK_LAYERS: LayerTheme;

package/dist/tokens/primitives.d.ts

@@ -15,6 +15,8 @@ export declare const primitiveTokens: {
             readonly 100: "#e8eaee";
             readonly 150: "#e0e3e8";
             readonly 300: "#b9bec8";
+            /** Dark muted text: AA on the hovered fill of the deepest layer. */
+            readonly 350: "#a1a8b6";
             readonly 400: "#949bab";
             readonly 500: "#636a79";
             readonly 600: "#575e6d";
@@ -131,9 +133,12 @@ export declare const primitiveTokens: {
             readonly 700: "#be185d";
         };
     };
-    /** 4px grid. Key = number of 4px steps (`4` → 16px). */
+    /**
+     * 4px grid. Key = number of 4px steps (`4` → 16px). `0` carries a unit: a unitless `0` is a
+     * number inside `calc()` / `max()`, and `calc(100% + 0)` is invalid (the declaration drops).
+     */
     readonly space: {
-        readonly 0: "0";
+        readonly 0: "0rem";
         readonly 1: "0.25rem";
         readonly 2: "0.5rem";
         readonly 3: "0.75rem";
@@ -165,6 +170,11 @@ export declare const primitiveTokens: {
             /** `… Fallback`: the metric-matched local faces of the opt-in `fonts.css`. */
             readonly sans: "\"Golos Text\", \"Golos Text Fallback\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
             readonly mono: "\"JetBrains Mono\", \"JetBrains Mono Fallback\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
+            /**
+             * Key caps: the mono faces for letters and digits, then the system UI face before the mono
+             * fallbacks — the mono faces have no ⇧ ⌥ ⌃ or ⌘, and Menlo draws them small and light.
+             */
+            readonly key: "\"JetBrains Mono\", \"JetBrains Mono Fallback\", ui-monospace, SFMono-Regular, system-ui, -apple-system, \"Segoe UI Symbol\", Menlo, Consolas, monospace";
         };
         /** Modular scale, ~1.2 in the body range, ~1.25 for headings. */
         readonly size: {

package/dist/tokens/semantic.d.ts

@@ -142,6 +142,12 @@ export declare const semanticTokens: {
         readonly control: {
             /** Switch thumb, slider thumb. */
             readonly thumb: "{color.white}";
+            /** A disabled switch thumb: quiet on the disabled track, like the rest of the control. */
+            readonly thumbDisabled: "{color.white}";
+        };
+        readonly skeleton: {
+            /** A loading placeholder: a wash over whatever layer it sits on, readable in both themes. */
+            readonly fill: "color-mix(in srgb, {color.gray.925} 6%, transparent)";
         };
         /**
          * The tooltip is an inverse chip: everything inside it (a Kbd, a secondary line) reads its
@@ -224,6 +230,7 @@ export declare const semanticTokens: {
         readonly family: {
             readonly sans: "{font.family.sans}";
             readonly mono: "{font.family.mono}";
+            readonly key: "{font.family.key}";
         };
         readonly weight: {
             readonly regular: "{font.weight.regular}";
@@ -794,6 +801,8 @@ export declare const semanticTokens: {
         readonly videoNote: "14.5rem";
         /** The box of a sent round video message (`VideoNote`): its diameter, at most the row. */
         readonly videoNoteBox: "16.75rem";
+        /** The square box of a sticker (`Message.Sticker`), at most the row. */
+        readonly sticker: "10rem";
         /**
          * A message changing size (a reaction row, a transcript that opens): the bubble's box, its
          * parts and the messages around glide in one calm stroke, between `fast` and `base`; zeroed

package/dist/tokens/themes/dark.d.ts

@@ -25,8 +25,9 @@ export declare const darkThemeOverrides: {
         readonly text: {
             readonly primary: "{color.gray.100}";
             readonly secondary: "{color.gray.300}";
-            readonly muted: "{color.gray.400}";
-            readonly placeholder: "{color.gray.400}";
+            /** gray.350: AA on every layer, its fill and the fill's hover (a hovered field, row, chip). */
+            readonly muted: "{color.gray.350}";
+            readonly placeholder: "{color.gray.350}";
             readonly disabled: "{color.gray.600}";
             readonly inverse: "{color.gray.925}";
         };
@@ -80,6 +81,10 @@ export declare const darkThemeOverrides: {
         };
         readonly control: {
             readonly thumb: "{color.gray.100}";
+            readonly thumbDisabled: "{color.gray.600}";
+        };
+        readonly skeleton: {
+            readonly fill: "color-mix(in srgb, {color.gray.100} 10%, transparent)";
         };
         /** A light chip over the dark UI: inverse like in light, so it reads over any layer. */
         readonly tooltip: {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "packageManager": "bun@1.3.13",
-  "description": "React 19 UI kit for product interfaces: 80 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y, Next.js App Router ready. Ships COMPONENT.md docs, copyable examples and an agent skill.",
+  "description": "React 19 UI kit for product interfaces: 79 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y, Next.js App Router ready. Ships COMPONENT.md docs, copyable examples and an agent skill.",
   "bin": {
     "prime-ui-kit": "bin/prime-ui-kit.js"
   },

package/src/components/avatar/COMPONENT.md

@@ -72,7 +72,7 @@ Avatar.Group           overlapping row, gives its size to members
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Avatar.Group
-`ref` → `HTMLDivElement`. An overlapping row (`role="group"`); members overlap by 25% with a ring in `--avatar-ring`.
+`ref` → `HTMLDivElement`. An overlapping row (`role="group"`); members overlap by an eighth of the diameter with a ring in `--avatar-ring`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -119,7 +119,7 @@ The soft fill is opaque: the soft hue is composited over the ground the avatar s
 ## Layout & spacing
 - Inline-flex, never shrinks, `vertical-align: middle`.
 - Avatar → name: space step 3 (12px) in lists and cards, step 2 (8px) in table cells.
-- Group: members overlap by 25% of the diameter with a 2px ring in the ground they stand on: the current layer of the surface around them (no surface sets anything), or `--avatar-ring` from a host whose ground is not a layer (a reaction chip sets its own fill); the fills of initials and «+N» are composited over the same ground.
+- Group: members overlap by an eighth of the diameter (initials are never cut) with a 2px ring in the ground they stand on: the current layer of the surface around them (no surface sets anything), or `--avatar-ring` from a host whose ground is not a layer (a reaction chip sets its own fill); the fills of initials and «+N» are composited over the same ground.
 - An icon fallback is half the diameter: a kit `Icon` reads `--prime-icon-size`, a raw svg too.
 
 ## Accessibility

package/src/components/avatar/examples/team-group.tsx

@@ -28,7 +28,7 @@ const MEMBERS: { name: string; initials: string; color: PaletteColor; src?: stri
 
 export default function AvatarTeamGroupExample() {
   return (
-    <Avatar.Group size="s" aria-label="Участники проекта: 7">
+    <Avatar.Group size="l" aria-label="Участники проекта: 7">
       {MEMBERS.map((member) => (
         <Avatar.Root key={member.initials} color={member.color} aria-label={member.name}>
           {member.src ? <Avatar.Image src={member.src} /> : null}

package/src/components/badge/COMPONENT.md

@@ -12,6 +12,7 @@
 - A selected value, keyword or applied filter the user can remove (`onRemove`).
 - Values in a filter panel that toggle on press and hide with a hover action (the `pressed` triad, `Badge.Action`).
 - A short code as a square tile (a file format «PDF») — `shape="square"`.
+- Several badges as one value (the tags of a client, a record's labels) — `Badge.Group`: it wraps and keeps one gap.
 
 ## When not to use
 - A multi-select field with chips → use [TagSelect](../tag-select/COMPONENT.md) (it renders badges itself).
@@ -33,6 +34,8 @@ Badge.Root          <span>: fill, tier dimensions
 │                   (a toggle <button> with the pressed triad; a <span> with a trailing segment; none when read-only)
 ├─ Badge.Action     optional end segment revealed on hover / focus (always shown on touch screens)
 └─ remove segment   with onRemove: full height, the whole end is the hit area (Icon action.close)
+
+Badge.Group         <div>: a wrapping row of Badge.Root, one value; `size` sets every badge's tier
 ```
 
 ## API
@@ -60,6 +63,14 @@ Badge.Root          <span>: fill, tier dimensions
 | `children` | `ReactNode` | — | Text, `Badge.Dot`, `Badge.Icon`, one `Badge.Action`. Only `Badge.Icon` children (no remove or action) make a square icon-only badge. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "onClick" \| "color">` | — | `aria-label` (an icon-only badge named by it is an image) and the other span attributes; no `onClick` — a pressable chip is the toggle. |
 
+### Badge.Group
+`ref` → `HTMLDivElement`. A row of badges as one value (the tags of a record): it wraps onto more lines, the badges a chip gap apart.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | the host tier, one step down | Tier of every badge in the group; a badge's own `size` wins. Small tiers stand closer. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the `Badge.Root`s), `className`, `aria-label` (a named group is `role="group"`) and the other div attributes. |
+
 ### Badge.Icon
 `ref` → `HTMLSpanElement`. A `<span>` holding one icon at the tier icon size. At the first or last position it becomes a full-height edge segment.
 
@@ -163,7 +174,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - `Badge.Dot` is 6px, 8px from `l`; alone it takes the tier of the surrounding control; `color` paints it in the solid step of that hue.
 - The root never clips: the text ellipsizes in its own box, so the segments' touch areas reach past the chip.
 - `Badge.Action` room is reserved, so revealing it never changes the badge width.
-- Several badges in a row: `gap: var(--prime-space-2)`.
+- Several badges in a row: `Badge.Group` — it wraps, badges 8 apart (4 at the `xs` and `s` tiers).
 - In a list row the badge is the trailing column; the title column gets `min-width: 0` and an ellipsis.
 
 ## Accessibility
@@ -206,6 +217,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 | [server-tags.tsx](examples/server-tags.tsx) | Order tags removed on the server: a badge waits dimmed with a spinner, leaves once the server agrees and stays with an announcement when it refuses — `onRemove`, `labels`. |
 | [filter-values.tsx](examples/filter-values.tsx) | Filter values as toggles with a hide action that slides in without changing the width — `pressed`, `onPressedChange`, `Badge.Action`, `persistent`. |
 | [square.tsx](examples/square.tsx) | File formats as square tiles of text, large enough for three letters; the hue sorts them by kind — `shape`, `size`, `color`. |
+| [tag-row.tsx](examples/tag-row.tsx) | The tags of a client as one value: the row wraps in a narrow column and keeps one gap between badges — `Badge.Group`, `size`. |
 | [controlled.tsx](examples/controlled.tsx) | Delivery cities as toggle chips whose state the screen owns: the summary counts the chosen ones — `pressed`, `onPressedChange`. |
 
 ## Mistakes
@@ -217,6 +229,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - Several removable badges with the default «Удалить» → pass `labels.remove` with the badge text.
 - A colored badge with no text → keep a word; color alone is not a signal.
 - An explicit `size` inside a control → drop it; the badge takes the tier one step down.
+- A row of badges in a hand-made flex wrapper with its own gap → `Badge.Group`.
 - `onRemove` together with `Badge.Action` → one end segment per badge.
 - Removing the badge from your list first and putting it back when the request fails → return the request's promise and remove it after it succeeds; the badge waits meanwhile.
 

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

@@ -23,3 +23,10 @@
   align-items: center;
   gap: var(--prime-space-2);
 }
+
+/* tag-row.tsx: a 320 px column, narrow enough for the row of badges to wrap. */
+.column {
+  display: grid;
+  gap: var(--prime-space-6);
+  inline-size: min(100%, calc(var(--prime-space-20) * 4));
+}

package/src/components/badge/examples/tag-row.tsx

@@ -0,0 +1,34 @@
+/** The tags of a client as one value: the row wraps in a narrow column and keeps one gap between badges — `Badge.Group`, `size`. */
+import { Badge } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TAGS = [
+  { label: "Ключевой клиент", color: "purple" },
+  { label: "Оптовые закупки", color: "blue" },
+  { label: "Отсрочка 30 дней", color: "orange" },
+  { label: "ЭДО", color: "teal" },
+  { label: "Москва", color: "gray" },
+  { label: "Новый договор", color: "green" },
+] as const;
+
+export default function BadgeTagRowExample() {
+  return (
+    <div className={styles.column}>
+      <Badge.Group aria-label="Теги клиента">
+        {TAGS.map((tag) => (
+          <Badge.Root key={tag.label} color={tag.color}>
+            {tag.label}
+          </Badge.Root>
+        ))}
+      </Badge.Group>
+      <Badge.Group size="s" aria-label="Теги заказа">
+        {TAGS.slice(0, 4).map((tag) => (
+          <Badge.Root key={tag.label} color={tag.color}>
+            {tag.label}
+          </Badge.Root>
+        ))}
+      </Badge.Group>
+    </div>
+  );
+}

package/src/components/banner/COMPONENT.md

@@ -29,8 +29,8 @@ Banner.Root                 <div>; variant, tone, size, placement
 │  ├─ Banner.Icon           one Icon on the first line (aria-hidden)
 │  ├─ Banner.Title
 │  ├─ Banner.Description
-│  └─ Banner.Actions        buttons; with onDismiss the close button is last here
-└─ close button             with onDismiss and no Actions: ghost icon Button (tone="inherit"), top-right
+│  └─ Banner.Actions        buttons; with onDismiss the close button is last here (wide banner)
+└─ close button             with onDismiss and no Actions, or Actions under the text: ghost icon Button (tone="inherit"), top-right
 ```
 
 ## API
@@ -72,7 +72,7 @@ Banner.Root                 <div>; variant, tone, size, placement
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
 ### Banner.Actions
-`ref` → `HTMLDivElement`. A `<div>` row of buttons; with `onDismiss` the close button becomes its last square button.
+`ref` → `HTMLDivElement`. A `<div>` row of buttons; with `onDismiss` the close button becomes its last square button (in the corner below 36rem).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -115,7 +115,7 @@ Banner.Root                 <div>; variant, tone, size, placement
 |---|---|---|
 | look | `variant`, `tone`, `size`, `placement` | `data-variant`, `data-tone`, `data-size`, `data-placement` |
 | dismissible | `onDismiss` | corner ghost Button (`xs`, `s` on `l` / `xl`), or the last outline Button in `Banner.Actions` |
-| narrow | own width < 36rem (a banner with `Banner.Actions` is a size container) | actions move under the text |
+| narrow | own width < 36rem (a banner with `Banner.Actions` is a size container) | actions move under the text; the close button returns to the corner |
 
 No `open` prop: the parent mounts and unmounts the banner. A mounted banner enters (a short fade and rise); an unmounted one closes up in place, so the content below glides up instead of jumping. To swap the banner for another block in the same spot (a «restore» button), wrap both in [Crossfade](../crossfade/COMPONENT.md).
 

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

@@ -8,7 +8,8 @@
   min-width: 0;
 }
 
-/* page-strip.tsx: the page strip above a card with an inset banner. */
+/* page-strip.tsx: a page — the strip spans its whole width, the content below keeps the page's
+   side padding, so the strip reads wider than the card with the inset banner. */
 .sections {
   display: flex;
   flex-direction: column;
@@ -17,6 +18,10 @@
   min-width: 0;
 }
 
+.pageBody {
+  padding-inline: var(--prime-layout-gutter);
+}
+
 /* narrow.tsx: a 320px column; the banner's container query moves actions under the text. */
 .narrow {
   width: min(100%, calc(var(--prime-space-20) * 4));

package/src/components/banner/examples/page-strip.tsx

@@ -6,7 +6,7 @@ import styles from "./examples.module.css";
 export default function BannerPageStripExample() {
   return (
     <div className={styles.sections}>
-      {/* In an app the strip stands first in the page, edge to edge above its content. */}
+      {/* In an app the strip stands first in the page, edge to edge above its padded content. */}
       <Banner.Root
         tone="warning"
         placement="page"
@@ -21,27 +21,29 @@ export default function BannerPageStripExample() {
           <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
         </Banner.Content>
       </Banner.Root>
-      <Card.Root variant="panel">
-        <Card.Header>
-          <Card.Title>Оплата</Card.Title>
-        </Card.Header>
-        <Card.Body>
-          <Banner.Root tone="danger">
-            <Banner.Content>
-              <Banner.Icon>
-                <Icon name="status.danger" />
-              </Banner.Icon>
-              <Banner.Title>Не удалось списать оплату</Banner.Title>
-              <Banner.Description>
-                Карта •••• 4242 отклонена банком. Обновите способ оплаты до 15 октября.
-              </Banner.Description>
-              <Banner.Actions>
-                <Button.Root tone="danger">Обновить карту</Button.Root>
-              </Banner.Actions>
-            </Banner.Content>
-          </Banner.Root>
-        </Card.Body>
-      </Card.Root>
+      <div className={styles.pageBody}>
+        <Card.Root variant="panel">
+          <Card.Header>
+            <Card.Title>Оплата</Card.Title>
+          </Card.Header>
+          <Card.Body>
+            <Banner.Root tone="danger">
+              <Banner.Content>
+                <Banner.Icon>
+                  <Icon name="status.danger" />
+                </Banner.Icon>
+                <Banner.Title>Не удалось списать оплату</Banner.Title>
+                <Banner.Description>
+                  Карта •••• 4242 отклонена банком. Обновите способ оплаты до 15 октября.
+                </Banner.Description>
+                <Banner.Actions>
+                  <Button.Root tone="danger">Обновить карту</Button.Root>
+                </Banner.Actions>
+              </Banner.Content>
+            </Banner.Root>
+          </Card.Body>
+        </Card.Root>
+      </div>
     </div>
   );
 }

package/src/components/breadcrumb/COMPONENT.md

@@ -23,7 +23,7 @@ import { Breadcrumb } from "prime-ui-kit";
 ## Anatomy
 ```
 Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels; auto-collapse into a «…» menu
-├─ Breadcrumb.Item        <li>: a link (href → LinkButton), text, or the current page (current)
+├─ Breadcrumb.Item        <li>: a link (href → LinkButton, or a router link with asChild), text, or the current page (current)
 └─ Breadcrumb.Ellipsis    <li> with «…» for levels skipped on purpose
 ```
 
@@ -32,7 +32,7 @@ Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Breadcrumb.Root
-`ref` → `HTMLElement` (the `<nav>`). `<nav aria-label>` with an `<ol>`; draws the chevrons between levels, sets the size and, on narrow containers, collapses the middle levels into a «…» menu button that lists them.
+`ref` → `HTMLElement` (the `<nav>`). `<nav aria-label>` with an `<ol>`; draws the chevrons between levels, sets the size and folds levels that do not fit into a «…» menu button that lists them: the middle ones, then the first one too.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -42,14 +42,15 @@ Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other `nav` attributes; an `aria-label` here overrides `labels.nav`. |
 
 ### Breadcrumb.Item
-`ref` → `HTMLLIElement`. `<li>`: a muted `LinkButton` (`href`), plain text, or the current page (`current`).
+`ref` → `HTMLLIElement`. `<li>`: a muted `LinkButton` (`href`, or the consumer's router link with `asChild`), plain text, or the current page (`current`). A press on the link goes through `Page.Guard`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `href` | `string` | — | Renders a link; without it the item is text. |
+| `href` | `string` | — | Renders a link; without it (and without `asChild`) the item is text. |
+| `asChild` | `boolean` | `false` | The single child (a router `Link`) is the level's link with the same look; its own text is the level. In the «…» menu of a folded path it is the menu item. |
 | `current` | `boolean` | — | Current page: `aria-current="page"` (on the link when `href` is set), primary text, medium weight. Usually the last item, without `href`. |
 | `aria-label` | `string` | — | Name of a link without visible text (e.g. a home icon); set on the link, not the `li`. |
-| `children` | `ReactNode` | — | Text or an `Icon`. A string also becomes the `title` of a text item (full text when truncated). |
+| `children` | `ReactNode` | — | Text or an `Icon`; with `asChild` one element. A string also becomes the `title` of a text item (full text when truncated). |
 | `…rest` | `Omit<LiHTMLAttributes<HTMLLIElement>, "aria-label">` | — | `className` and the other `li` attributes. |
 
 ### Breadcrumb.Ellipsis
@@ -77,6 +78,7 @@ Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels
 | text (no `href`, no `current`) | muted text | a level without its own page | yes |
 | current (`current`) | primary text, medium weight | the last item — this page | |
 | icon link (`href` + `aria-label`, `Icon` child) | icon at the tier icon size | a «home» root | |
+| router link (`asChild`, one `Link` child) | the same muted link, the consumer's element | an app with a client router: the path moves without a reload | |
 
 Use links for every ancestor and `current` on the last item; `s` above a `heading-m` page title. Avoid `href` on the current item and two `current` items.
 
@@ -85,15 +87,17 @@ Use links for every ancestor and `current` on the last item; `s` above a `headin
 |---|---|---|
 | current | `current` | `aria-current="page"` on the text span, or on the link when the item has `href` |
 | hover / focus-visible on links | pointer / keyboard | text → primary; focus ring from LinkButton |
-| truncation | width | each level truncates with an ellipsis, max width `2 × --prime-space-24` (192; `--prime-space-24 + --prime-space-6`, 120, when its container is below 30rem — its own for 3+ levels, the nearest one above for 1–2); the last item shrinks last |
-| auto-collapse | 3+ levels and a container `< 30rem` | `data-collapsible="true"`; middle levels are `display: none` and replaced by «… ›»: a ghost menu button (`Dropdown.Trigger`, named by `labels.ellipsis`) whose menu lists them — links stay links, a level without `href` is a disabled row |
+| truncation | width | each level truncates with an ellipsis, max width `2 × --prime-space-24` (192); the current page shrinks at half the rate of the others |
+| auto-collapse | 2+ levels whose whole path does not fit the width uncut (measured on every resize) | `data-collapsible="true"`, `data-collapsed="true"`; middle levels are `display: none` and replaced by «… ›»: a ghost menu button (`Dropdown.Trigger`, named by `labels.ellipsis`) whose menu lists them — links stay links, a level without `href` is a disabled row |
+| deep collapse | the path folded as above still does not fit | `data-collapsed="deep"`; the first level folds too: «…» › current page, the menu lists every level before it |
 | collapse menu open | a press, `Enter` or `ArrowDown` on the «…» | `aria-expanded="true"` on the button; a `role="menu"` panel at the tier size |
+| held | a `Page.Guard` that is `busy` or `dirty` on the page | a press on a level's link (in the path or the «…» menu) stops before it navigates; `dirty` asks first, then repeats it |
 
-Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
+Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`), `data-collapsed` (`"true"` / `"deep"`).
 
 ## Layout & spacing
-- A path of 1–2 levels takes its content width (at most the row), so in a flex row — the `AppHeader` start, before `AppHeader.Separator` and the title — what follows stands right after it. A path of 3+ levels is a size container (`container-type: inline-size`, `inline-size: 100%`) that folds its middle levels by its own width: inside a flex row give it `flex: 1 1 auto; min-width: 0`.
-- In an `AppHeader` the path up holds the list a record belongs to (1–2 levels); the record itself is the `AppHeader.Title` after the separator, not the breadcrumb's `current` item.
+- A single level takes its content width (at most the row). A path of 2+ levels fills the row (`inline-size: 100%`) and folds by that width, so a wider row unfolds it again; its intrinsic width stays the whole path, so a host that measures natural widths (the `Page.TopBar` plan) reads it uncut. Inside a flex row give it a box that takes the room it may use (`flex: 1 1 auto; min-width: 0`).
+- In a `Page.Heading` the path up holds the list a record belongs to (1–2 levels); the record itself is the `Page.Title` (in a top bar the path's last level, after the chevron), not the breadcrumb's `current` item.
 - Above a page title: `gap: var(--prime-space-2)` between the trail and the title row.
 - The list never wraps. Chevrons sit inside each level after the first, in the placeholder text color, at the tier icon size.
 
@@ -113,7 +117,7 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 
 - `nav` landmark with `aria-label` from `labels.nav`; an ordered list.
 - The current page has `aria-current="page"`; the chevrons are `aria-hidden` spans inside the levels, so every list item is a level.
-- Collapsed middle levels leave the layout and the tab order (no invisible focus stops); the automatic «…» is a menu button (`aria-haspopup="menu"`) named by `labels.ellipsis`, and its menu lists them as links.
+- Collapsed levels leave the layout and the tab order (no invisible focus stops); the automatic «…» is a menu button (`aria-haspopup="menu"`) named by `labels.ellipsis`, and its menu lists them as links.
 - Icon-only links need `aria-label` on the Item.
 
 ### Labels
@@ -132,13 +136,15 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 | [with-icon.tsx](examples/with-icon.tsx) | The root level as a home icon; a link without text is named for screen readers — `aria-label`. |
 | [overflow.tsx](examples/overflow.tsx) | A long path: levels truncate, and in a 320px container the middle ones collapse into a «…» menu that lists them — `Breadcrumb.Item`, `current`. |
 | [ellipsis.tsx](examples/ellipsis.tsx) | Levels skipped on purpose shown as «…» whose hidden text names them for screen readers — `Breadcrumb.Ellipsis`, `labels`. |
+| [router.tsx](examples/router.tsx) | Router links as the levels above: the path moves without a reload; render it inside a router — `asChild`, `current`. |
 
 ## Mistakes
 - Separators by hand between items → the root draws the chevrons.
 - `<Breadcrumb.Item href="…" current>` → the current page has no `href`.
 - Breadcrumb inside a flex row collapsing to zero width → give it `flex: 1 1 auto; min-width: 0`.
 - Home icon link without `aria-label` → add `aria-label="Главная"`.
+- `href` + `onClick` with `preventDefault()` and `navigate()` for a router → `asChild` with the router's `Link`.
 
 ## Related
 - **Built from:** [LinkButton](../link-button/COMPONENT.md) (`tone="muted"`), [Button](../button/COMPONENT.md) and [Dropdown](../dropdown/COMPONENT.md) (the collapse menu), Icon (`nav.chevronRight`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
-- **See also:** [Tabs](../tabs/COMPONENT.md), [PageContent](../page-content/COMPONENT.md), [Stepper](../stepper/COMPONENT.md)
+- **See also:** [Tabs](../tabs/COMPONENT.md), [Page](../../layout/page/COMPONENT.md), [Stepper](../stepper/COMPONENT.md)

package/src/components/breadcrumb/examples/router.tsx

@@ -0,0 +1,17 @@
+/** Router links as the levels above: the path moves without a reload; render it inside a router — `asChild`, `current`. */
+import { Breadcrumb } from "prime-ui-kit";
+import { Link } from "react-router-dom";
+
+export default function BreadcrumbRouterExample() {
+  return (
+    <Breadcrumb.Root>
+      <Breadcrumb.Item asChild>
+        <Link to="/crm">CRM</Link>
+      </Breadcrumb.Item>
+      <Breadcrumb.Item asChild>
+        <Link to="/crm/clients">Клиенты</Link>
+      </Breadcrumb.Item>
+      <Breadcrumb.Item current>ООО «Северный ветер»</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}

package/src/components/button/COMPONENT.md

@@ -66,7 +66,7 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | `labels` | `Partial<ButtonLabels>` | — | Built-in strings, see Labels. |
 | `asChild` | `boolean` | `false` | Merges Button props and styles onto the single child element (a link) instead of rendering `<button>`. `disabled`/`loading` become `aria-disabled`; `progress` and `holdToConfirm` need a `<button>`. |
 | `disabled` | `boolean` | — | Disabled state; `loading` also disables. With `asChild` the child leaves the Tab order and a link loses its `href`. |
-| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → a square icon-only button that needs `aria-label`. A changed label morphs letter by letter. With `asChild`, the one child element. |
+| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → a square icon-only button that needs `aria-label`. A changed label morphs letter by letter. With `asChild`, the one child element; its text is the label too. |
 | `aria-label` | `string` | — | The name of a button without a visible label; required with `shape="circle"`. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "size" \| "aria-pressed">` | — | `onClick`, `type` (`"button"` by default, not passed on with `asChild`), `className`, `aria-*`, `data-*` and the other button attributes. |
 
@@ -144,6 +144,7 @@ A Button lines up exactly with Input, Select, Datepicker trigger, SegmentedContr
 |---|---|---|---|
 | `fullWidth` | button fills the row | narrow forms, cards, mobile footers | off |
 | icon-only (children are only `Button.Icon`) | square, width = height | toolbars; needs `aria-label` | — |
+| icon only by the host (`data-button-label="icon"` on a wrapper, the `Page.TopBar` plan) | a Button with an icon and a label shows only its icon, square; the label and anything else beside the icon (a `Kbd` hint) stay transparent over it, the label as the name | a host short of width | — |
 | `pressed` / `defaultPressed` | on: accent soft fill and accent text over any variant; off: the variant's own look | a single toggle (favourite, pin, «show archived») | — (not a toggle) |
 | `current` | the selected look, `aria-current="page"` | the current page of a set (page numbers) | off |
 

package/src/components/button/examples/hold-to-confirm.tsx

@@ -28,7 +28,7 @@ export default function ButtonHoldToConfirmExample() {
       <Button.Icon>
         <Icon name="action.delete" />
       </Button.Icon>
-      Удерживайте, чтобы удалить проект
+      Удержите, чтобы удалить
     </Button.Root>
   );
 }

package/src/components/button/examples/on-colored-host.tsx

@@ -13,15 +13,15 @@ export default function ButtonOnColoredHostExample() {
         <Banner.Root key={text} variant="solid" tone={tone}>
           <Banner.Content>
             <Banner.Title>{text}</Banner.Title>
+            <Banner.Actions>
+              <Button.Root variant="soft" tone="inherit">
+                {action}
+              </Button.Root>
+              <Button.Root variant="ghost" tone="inherit">
+                {later}
+              </Button.Root>
+            </Banner.Actions>
           </Banner.Content>
-          <Banner.Actions>
-            <Button.Root variant="soft" tone="inherit">
-              {action}
-            </Button.Root>
-            <Button.Root variant="ghost" tone="inherit">
-              {later}
-            </Button.Root>
-          </Banner.Actions>
         </Banner.Root>
       ))}
     </>

package/src/components/button-group/COMPONENT.md

@@ -47,6 +47,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the `group`. |
 | `optional` | `boolean` | `false` | Muted marker after the label (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the control (`aria-describedby`). Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger inset ring, `aria-invalid` and `data-invalid` on the `group`; the control shakes once when an error arrives. |
 | `reserveSupportRow` | `boolean` | `false` | Always render the support row, so an appearing error does not shift the layout. |