prime-ui-kit 0.15.0 → 0.17.0

package/src/components/badge/COMPONENT.md

@@ -6,11 +6,12 @@
 > The kit's one chip: a static label for a status, category or count, a removable value or applied filter, and a pressable toggle with a hover action — in a palette color.
 
 ## When to use
-- Status or category of a row in a table or list («Оплачен», «Черновик», «Бета»).
+- Status of a row in a table or list («Оплачен», «Просрочен») — `tone`; a category («Бета», a team, a tag) — `color`.
 - Counters inside buttons and fields («Входящие 12», «−25%»).
 - A workflow state with a leading dot (`Badge.Dot`).
 - 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 (`onPress`, `Badge.Action`).
+- 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"`.
 
 ## When not to use
 - A multi-select field with chips → use [TagSelect](../tag-select/COMPONENT.md) (it renders badges itself).
@@ -29,7 +30,7 @@ import { Badge } from "prime-ui-kit";
 Badge.Root          <span>: fill, tier dimensions
 ├─ [start segment]  Badge.Icon or Badge.Dot at the start edge: full height, mark centred
 ├─ body             text, Badge.Dot, inline Badge.Icon
-│                   (a <button> with onPress; a <span> with a trailing segment; none when read-only)
+│                   (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)
 ```
@@ -39,21 +40,25 @@ Badge.Root          <span>: fill, tier dimensions
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Badge.Root
-`ref` → `HTMLSpanElement`. The chip: fill, tier dimensions; a read-only badge is one `<span>`, `onPress` makes the body a `<button>`, `onRemove` adds a remove segment.
+`ref` → `HTMLSpanElement`. The chip: fill, tier dimensions; a read-only badge is one `<span>`, the `pressed` triad makes the body a toggle `<button>`, `onRemove` adds a remove segment.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Palette hue. Categorizes; the text carries the meaning. |
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` without `tone` | Palette hue: a category (a team, a tag); the text carries the meaning. Not together with `tone`. |
+| `tone` | `"neutral" \| "success" \| "warning" \| "danger" \| "info"` | — | A status in the role colors (paid, overdue, failed); `neutral` is the gray hue. Not together with `color`. |
 | `variant` | `"solid" \| "soft" \| "outline"` | `"soft"` | Treatment. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | — | Badge tier, 16 · 20 · 24 · 28 · 32 px high. Without it the badge follows the surrounding control one tier down; outside a control it is `m`. |
+| `shape` | `"chip" \| "square"` | `"chip"` | `square` — a tile as wide as it is tall, the text centred: a file format («PDF»), a short code. |
 | `onRemove` | `() => void \| Promise<void>` | — | Adds the full-height remove segment at the end; called on its click. Return the request's promise: the badge waits with a spinner; take it out of your list before resolving; on reject it stays. |
 | `loading` | `boolean` | `false` | The badge waits on a request (a value its owner is still creating): dimmed, `aria-busy`, a spinner in the remove segment, which takes no press. A promise from `onRemove` does the same on its own. |
-| `onPress` | `(event: MouseEvent<HTMLButtonElement>) => void` | — | Makes the body a `<button>` covering the whole badge (a toggle chip, a filter value); gets the event, so Alt / Shift clicks can mean more. |
-| `pressed` | `boolean` | — | Toggle state of a pressable badge: `aria-pressed` on the body, `data-pressed` on the root. |
+| `pressed` | `boolean` | — | A toggle chip (a filter value): the body becomes a `<button>` over the whole badge with `aria-pressed`; on takes the selected look (accent soft). |
+| `defaultPressed` | `boolean` | — | The initial state of an uncontrolled toggle chip; a press flips it. |
+| `onPressedChange` | `(pressed: boolean) => void` | — | Fires with the new state when the toggle chip is pressed. |
 | `disabled` | `boolean` | — | Muted look for every variant, `aria-disabled`; the body button, remove and action get native `disabled`. |
+| `className` | `string` | — | Class on the badge. |
 | `labels` | `Partial<BadgeLabels>` | — | Built-in strings, see Labels. |
 | `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` | `HTMLAttributes<HTMLSpanElement>` | — | `className`, `aria-label` (icon-only) and the other span attributes. |
+| `…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.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.
@@ -61,14 +66,17 @@ Badge.Root          <span>: fill, tier dimensions
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — (required) | The icon (`Icon`). |
-| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+| `className` | `string` | — | Class on the icon box. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | The other span attributes. |
 
 ### Badge.Dot
-`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` dot in the text color; at an edge it becomes a segment. Alone (a marker on an icon, before a label) it takes the host tier and the color set on it.
+`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` dot in the text color; at an edge it becomes a segment. Alone (a marker on an icon, before a label) it takes the host tier.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | — | A dot of its own hue (the solid step) instead of the text color: a project color, an attention mark. |
+| `className` | `string` | — | Class on the dot. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "color">` | — | The other span attributes. |
 
 ### Badge.Action
 `ref` → `HTMLButtonElement`. A `<button>` segment at the end, revealed on hover and focus (always shown on touch); the width never changes. One per badge, not together with `onRemove`.
@@ -78,7 +86,7 @@ Badge.Root          <span>: fill, tier dimensions
 | `label` | `string` | — (required) | Accessible name and tooltip («Скрыть billing»). |
 | `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void` | — (required) | Runs the action. |
 | `persistent` | `boolean` | `false` | Keeps the action shown, not only on hover and focus (while the state it sets is on). |
-| `pressed` | `boolean` | — | Toggle state of the action: `aria-pressed`. |
+| `pressed` | `boolean` | — | Toggle state of the action: `aria-pressed`; on, the segment stays shown with the pressed wash. |
 | `disabled` | `boolean` | `false` | The action is unavailable. |
 | `children` | `ReactNode` | — | A custom glyph at the tier icon size; a minus by default. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "onClick" \| "children">` | — | `className` and the other button attributes. |
@@ -92,18 +100,31 @@ Badge.Root          <span>: fill, tier dimensions
 | `solid` | saturated hue fill, contrasting text | one label per area that must stand out | |
 | `outline` | transparent, 1px inset line in the hue text at 32% | a quiet secondary label next to soft badges | |
 
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | the gray hue | draft, archived, cancelled | |
+| `success` | the success role colors | paid, published, done | |
+| `warning` | the warning role colors | waiting, needs attention | |
+| `danger` | the danger role colors | failed, overdue, rejected | |
+| `info` | the info role colors | issued, in progress | |
+
+A status takes `tone`; a category takes `color`. The two never go together (the type refuses it).
+
 ### color
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `gray` | neutral wash | draft, archived, cancelled | yes |
-| `blue` | blue | in progress, counters | |
-| `green` | green | success, paid, published | |
-| `orange` | orange | waiting, needs attention | |
-| `red` | red | failed, rejected, urgent | |
-| `yellow` | yellow | paused, under review | |
+| `gray` | neutral wash | a category without a hue of its own | yes (without `tone`) |
+| `blue` · `green` · `orange` · `red` · `yellow` | palette hues | teams, projects, tags, file kinds | |
 | `purple` | purple | roles, private categories | |
 | `sky` · `pink` · `teal` | extra hues | more categories | |
 
+### shape
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `chip` | as wide as its content | every badge | yes |
+| `square` | a tile as wide as it is tall, the text centred and clipped | a file format, a short code | |
+
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -123,22 +144,24 @@ Badge.Root          <span>: fill, tier dimensions
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| hue / treatment | `color`, `variant` | `data-color`, `data-variant` (always set) |
+| hue / treatment | `color` or `tone`, `variant` | `data-color` (a hue, or gray for `neutral`), `data-tone`, `data-variant` (always set); `data-shape="square"` for a tile |
 | size | `size`, else the control, else `m` | `data-size`, `data-tier` (visual tier) |
 | icon segments | edge `Badge.Icon` / `Badge.Dot`, icon-only | `data-icon-start`, `data-icon-end`, `data-icon-only` |
 | plain text | read-only, text children only | `data-text-only`: the root is one block box that ellipsizes; otherwise each text run sits in its own block span |
 | removable | `onRemove` | `data-removable`; the remove segment takes a `fill-subtle-active` wash on hover |
 | removing | `onRemove` returned a pending promise, or `loading` | `data-pending`, `aria-busy`; the content quiets to 0.6 (`fast`, both ways), a `Spinner` stands in for the ×, the segment gets `aria-disabled` and takes no second press; rejected — the badge stays and `labels.removeFailed` is announced |
-| leaving | the owner took the badge out after its remove segment | a copy stays in place and closes up — fades, settles to 0.96 and shrinks to nothing with its gap (`fast`, `exit`) — so the badges after it glide in; off under reduced motion |
-| pressable / pressed | `onPress`, `pressed` | `data-pressable`, `data-pressed`, `aria-pressed` on the body; `fill-subtle` wash on hover |
+| leaving | the owner took the badge out (after its remove segment, or any change of the list) | a copy stays in place and closes up — fades, settles and shrinks to nothing with its gap (`fast`, `exit`, `internal/partPresence`) — so the badges after it glide in; off under reduced motion |
+| toggle / pressed | the `pressed` / `defaultPressed` / `onPressedChange` triad | `data-pressable`, `aria-pressed` on the body; on adds `data-pressed` and the selected look (accent soft), gliding in and out (`fast`); hover washes a step of the badge's text color over its fill |
 | action | `Badge.Action` | `data-action="reveal" \| "persistent"`; the text slides and the segment fades in over `fast` |
-| disabled | `disabled` | `data-disabled`, `aria-disabled`; inner buttons disabled |
+| disabled | `disabled` | `data-disabled`, `aria-disabled`; inner buttons disabled, no hover wash |
+| icon-only, named | only `Badge.Icon` children and `aria-label` | `role="img"` with that name |
 | count | a number as the only child | the digits roll to the new value when the number changes |
 
 ## Layout & spacing
 - Inline-flex, `width: fit-content`, `max-width: 100%`; text never wraps and ends in an ellipsis.
 - Segments are `mark + padding + gap` wide and full height; the mark sits with equal space to the edge and to the text.
-- `Badge.Dot` is 6px, 8px from `l`; alone it takes the tier of the surrounding control.
+- `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)`.
 - In a list row the badge is the trailing column; the title column gets `min-width: 0` and an ellipsis.
@@ -146,17 +169,21 @@ Badge.Root          <span>: fill, tier dimensions
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
-| `Tab` | Focuses the body of a pressable badge, then its action or remove segment. |
-| `Enter` · `Space` | Presses the focused body, remove or action button. |
+| `Tab` | Focuses the body of a toggle chip, then its action or remove segment. |
+| `Enter` · `Space` | Presses the focused body (the toggle flips), remove or action button. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - A read-only badge is plain text in a `<span>`, no role.
-- `onPress` makes the body a `<button>` with `aria-pressed` when `pressed` is set; remove and `Badge.Action` are separate buttons with their own names.
+- The `pressed` triad makes the body a `<button>` with `aria-pressed`; remove and `Badge.Action` are separate buttons with their own names.
 - Give every remove button a unique name with `labels.remove`; after removing, move focus to a neighbouring badge or the source field.
 - While a removal is saved the badge has `aria-busy` and the segment `aria-disabled`; once a removal waits, the badge mounts a polite live region that speaks `labels.removeFailed` if the promise rejects.
-- `Badge.Dot` is `aria-hidden`; icon-only badges need `aria-label`. Color never carries meaning alone.
+- `Badge.Dot` is `aria-hidden`; an icon-only badge needs `aria-label` and then is `role="img"`. Color never carries meaning alone, a `tone` neither.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -169,18 +196,23 @@ Badge.Root          <span>: fill, tier dimensions
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | Publication statuses: soft badges where the text carries the meaning and the hue repeats it — `color`. |
+| [overview.tsx](examples/overview.tsx) | Invoice statuses: soft badges where the text carries the meaning and the tone repeats it — `tone`. |
 | [variants.tsx](examples/variants.tsx) | Every palette hue in every treatment; the text must read without the color — `variant`, `color`. |
 | [sizes.tsx](examples/sizes.tsx) | Every badge tier, 16 to 32 px high — `size`. |
-| [states.tsx](examples/states.tsx) | An inactive badge, a pressable toggle off and on, a removable one and one that waits on a request — `disabled`, `onPress`, `pressed`, `onRemove`, `loading`. |
-| [with-icon.tsx](examples/with-icon.tsx) | A leading dot, a leading or trailing icon and an icon-only square with a name — `Badge.Dot`, `Badge.Icon`, `aria-label`. |
-| [in-controls.tsx](examples/in-controls.tsx) | Inside a button or a field the badge takes the tier one step down without `size`. |
+| [states.tsx](examples/states.tsx) | An inactive badge, a toggle chip off and on, a removable one and one that waits on a request — `disabled`, `pressed`, `onRemove`, `loading`. |
+| [with-icon.tsx](examples/with-icon.tsx) | A leading dot in the text color or its own hue, a leading or trailing icon and an icon-only square with a name — `Badge.Dot`, `color`, `Badge.Icon`, `aria-label`. |
+| [in-controls.tsx](examples/in-controls.tsx) | Inside a button or a field the badge takes the tier one step down by itself — `Badge.Root`. |
 | [applied-filters.tsx](examples/applied-filters.tsx) | Applied filters: each badge drops its filter and names it for screen readers — `onRemove`, `labels`. |
 | [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 — `onPress`, `pressed`, `Badge.Action`, `persistent`. |
+| [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`. |
+| [controlled.tsx](examples/controlled.tsx) | Delivery cities as toggle chips whose state the screen owns: the summary counts the chosen ones — `pressed`, `onPressedChange`. |
 
 ## Mistakes
-- `<Badge.Root onClick={…}>` → use `onPress` for a toggle, or a `Button` for a command.
+- `<Badge.Root onClick={…}>` → the type refuses it: a toggle chip is the `pressed` triad, a command is a `Button`.
+- A status in a palette hue (`color="red"` for «Просрочен») → `tone="danger"`; `color` is for categories.
+- A toggle drawn by switching `color` → the `pressed` triad: the selected look comes with `aria-pressed`.
+- A square format tile styled by a host class → `shape="square"`.
 - A custom × or hover button next to a badge → use `onRemove` or `Badge.Action`.
 - 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.
@@ -189,5 +221,5 @@ Badge.Root          <span>: fill, tier dimensions
 - 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.
 
 ## Related
-- **Built from:** `Icon` (remove ×, `Badge.Action` −), [Spinner](../spinner/COMPONENT.md) (removing)
+- **Built from:** `Icon` (remove ×, `Badge.Action` −), [Spinner](../spinner/COMPONENT.md) (removing), `internal/chipTier` (tiers), `internal/glyphSwap` (× ⇄ spinner), `internal/partPresence` (leaving), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [TagSelect](../tag-select/COMPONENT.md), [Select](../select/COMPONENT.md) (row badges), [SegmentedControl](../segmented-control/COMPONENT.md) (`Count`, color dots), [SmartFilter](../smart-filter/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [Avatar](../avatar/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)

package/src/components/badge/examples/controlled.tsx

@@ -0,0 +1,32 @@
+/** Delivery cities as toggle chips whose state the screen owns: the summary counts the chosen ones — `pressed`, `onPressedChange`. */
+import { Badge, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const CITIES = ["Москва", "Казань", "Екатеринбург", "Новосибирск"];
+
+export default function BadgeControlledExample() {
+  const [chosen, setChosen] = React.useState<string[]>(["Москва"]);
+  const toggle = (city: string, pressed: boolean) =>
+    setChosen((prev) => (pressed ? [...prev, city] : prev.filter((item) => item !== city)));
+
+  return (
+    <div className={styles.filters}>
+      <div className={styles.badges}>
+        {CITIES.map((city) => (
+          <Badge.Root
+            key={city}
+            pressed={chosen.includes(city)}
+            onPressedChange={(pressed) => toggle(city, pressed)}
+          >
+            {city}
+          </Badge.Root>
+        ))}
+      </div>
+      <Typography variant="body-s" tone="muted">
+        {chosen.length > 0 ? `Доставка в: ${chosen.join(", ")}` : "Города доставки не выбраны"}
+      </Typography>
+    </div>
+  );
+}

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

@@ -7,14 +7,14 @@
   align-items: flex-end;
   justify-content: center;
   gap: var(--prime-space-3);
-  width: min(100%, var(--prime-modal-width-m));
+  width: min(100%, var(--prime-layout-form-width-m));
 }
 
 /* applied-filters.tsx, server-tags.tsx: a row of badges above a list. */
 .filters {
   display: grid;
   gap: var(--prime-space-3);
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 .badges {

package/src/components/badge/examples/filter-values.tsx

@@ -1,4 +1,4 @@
-/** Filter values as toggles with a hide action that slides in without changing the width — `onPress`, `pressed`, `Badge.Action`, `persistent`. */
+/** Filter values as toggles with a hide action that slides in without changing the width — `pressed`, `onPressedChange`, `Badge.Action`, `persistent`. */
 import { Badge } from "prime-ui-kit";
 import * as React from "react";
 
@@ -10,8 +10,7 @@ const VALUES = ["Москва", "Казань", "Новосибирск", "Со
 
 export default function BadgeFilterValuesExample() {
   const [modes, setModes] = React.useState<Record<string, Mode>>({ Казань: "show", Сочи: "hide" });
-  const set = (value: string, mode: Exclude<Mode, undefined>) =>
-    setModes((prev) => ({ ...prev, [value]: prev[value] === mode ? undefined : mode }));
+  const set = (value: string, mode: Mode) => setModes((prev) => ({ ...prev, [value]: mode }));
 
   return (
     <div className={styles.badges}>
@@ -20,16 +19,15 @@ export default function BadgeFilterValuesExample() {
         return (
           <Badge.Root
             key={value}
-            color={mode === "show" ? "blue" : mode === "hide" ? "red" : "gray"}
             pressed={mode === "show"}
-            onPress={() => set(value, "show")}
+            onPressedChange={(pressed) => set(value, pressed ? "show" : undefined)}
           >
             {mode === "hide" ? `НЕ ${value}` : value}
             <Badge.Action
               label={mode === "hide" ? `Не скрывать ${value}` : `Скрыть ${value}`}
               pressed={mode === "hide"}
               persistent={mode === "hide"}
-              onClick={() => set(value, "hide")}
+              onClick={() => set(value, mode === "hide" ? undefined : "hide")}
             />
           </Badge.Root>
         );

package/src/components/badge/examples/in-controls.tsx

@@ -1,4 +1,4 @@
-/** Inside a button or a field the badge takes the tier one step down without `size`. */
+/** Inside a button or a field the badge takes the tier one step down by itself — `Badge.Root`. */
 import { Badge, Button, Input } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

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

@@ -1,13 +1,14 @@
-/** Publication statuses: soft badges where the text carries the meaning and the hue repeats it — `color`. */
+/** Invoice statuses: soft badges where the text carries the meaning and the tone repeats it — `tone`. */
 import { Badge } from "prime-ui-kit";
 
 export default function BadgeOverviewExample() {
   return (
     <>
-      <Badge.Root>Черновик</Badge.Root>
-      <Badge.Root color="blue">На ревью</Badge.Root>
-      <Badge.Root color="green">Опубликован</Badge.Root>
-      <Badge.Root color="red">Ошибка</Badge.Root>
+      <Badge.Root tone="neutral">Черновик</Badge.Root>
+      <Badge.Root tone="info">Выставлен</Badge.Root>
+      <Badge.Root tone="success">Оплачен</Badge.Root>
+      <Badge.Root tone="warning">Ждёт оплаты</Badge.Root>
+      <Badge.Root tone="danger">Просрочен</Badge.Root>
     </>
   );
 }

package/src/components/badge/examples/square.tsx

@@ -0,0 +1,21 @@
+/** File formats as square tiles of text, large enough for three letters; the hue sorts them by kind — `shape`, `size`, `color`. */
+import { Badge } from "prime-ui-kit";
+
+const FORMATS = [
+  { format: "PDF", color: "red" },
+  { format: "XLS", color: "green" },
+  { format: "DOC", color: "blue" },
+  { format: "ZIP", color: "gray" },
+] as const;
+
+export default function BadgeSquareExample() {
+  return (
+    <>
+      {FORMATS.map((item) => (
+        <Badge.Root key={item.format} shape="square" size="xl" color={item.color}>
+          {item.format}
+        </Badge.Root>
+      ))}
+    </>
+  );
+}

package/src/components/badge/examples/states.tsx

@@ -1,4 +1,4 @@
-/** An inactive badge, a pressable toggle off and on, a removable one and one that waits on a request — `disabled`, `onPress`, `pressed`, `onRemove`, `loading`. */
+/** An inactive badge, a toggle chip off and on, a removable one and one that waits on a request — `disabled`, `pressed`, `onRemove`, `loading`. */
 import { Badge, Typography } from "prime-ui-kit";
 
 const noop = () => undefined;
@@ -15,15 +15,15 @@ export default function BadgeStatesExample() {
         </Typography>
       </div>
       <div>
-        <Badge.Root color="blue" onPress={noop} pressed={false}>
+        <Badge.Root pressed={false} onPressedChange={noop}>
           Москва
         </Badge.Root>
         <Typography as="span" variant="caption" tone="muted">
-          onPress
+          pressed: false
         </Typography>
       </div>
       <div>
-        <Badge.Root color="blue" onPress={noop} pressed>
+        <Badge.Root pressed onPressedChange={noop}>
           Москва
         </Badge.Root>
         <Typography as="span" variant="caption" tone="muted">

package/src/components/badge/examples/with-icon.tsx

@@ -1,4 +1,4 @@
-/** A leading dot, a leading or trailing icon and an icon-only square with a name — `Badge.Dot`, `Badge.Icon`, `aria-label`. */
+/** A leading dot in the text color or its own hue, a leading or trailing icon and an icon-only square with a name — `Badge.Dot`, `color`, `Badge.Icon`, `aria-label`. */
 import { Badge, Icon, Typography } from "prime-ui-kit";
 
 export default function BadgeWithIconExample() {
@@ -13,6 +13,15 @@ export default function BadgeWithIconExample() {
           Badge.Dot
         </Typography>
       </div>
+      <div>
+        <Badge.Root>
+          <Badge.Dot color="purple" />
+          Проект «Север»
+        </Badge.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          Badge.Dot · color
+        </Typography>
+      </div>
       <div>
         <Badge.Root color="purple">
           <Badge.Icon>

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
@@ -44,9 +44,9 @@ Banner.Root                 <div>; variant, tone, size, placement
 |---|---|---|---|
 | `variant` | `"solid" \| "soft" \| "outline"` | `"soft"` | `soft` tinted fill, `solid` saturated fill for urgent messages, `outline` card fill with a tone ring. |
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"info"` | Semantic color of the message. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Spacing, icon and title follow the control tier; the description is one step smaller. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Spacing, icon and title follow the control tier; the description is one step smaller. Without it the tier of the host. |
 | `placement` | `"inset" \| "page"` | `"inset"` | `inset` — rounded block in the flow or in a card; `page` — edge-to-edge strip above a page, content aligned to the page column. |
-| `onDismiss` | `() => void` | — | Renders a close button (top-right, or last in `Banner.Actions`) and calls this on click; the parent unmounts the banner, which closes up in place, and moves focus to a sensible place. |
+| `onDismiss` | `() => void` | — | Renders a close button (top-right, or last in `Banner.Actions`) and calls this on click; the parent unmounts the banner, which closes up in place; focus inside it moves to the next tab stop of the page. |
 | `labels` | `Partial<BannerLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` (`alert`, `status`, `region`), `aria-label` and the other div attributes. |
 
@@ -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).
 
@@ -127,14 +127,18 @@ No `open` prop: the parent mounts and unmounts the banner. A mounted banner ente
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Actions and the close button are regular buttons in Tab order. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The banner has no role of its own: give an error after an action `role="alert"`, a calm status `role="status"`, a page strip `role="region"` with `aria-label`.
 - The icon is `aria-hidden`: the title carries the meaning, not the color.
-- The close button is named by `labels.dismiss`. It leaves with the banner, so after dismissing the parent moves focus to a sensible place: the control that takes the banner's spot, or the next heading or action of the section (see `dismissible.tsx`).
+- The close button is named by `labels.dismiss`. It leaves with the banner, and focus inside the banner moves to the next tab stop of the page (the previous one at its end); inside `Crossfade` it moves to the state that takes the banner's place (see `dismissible.tsx`).
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -146,11 +150,11 @@ No `open` prop: the parent mounts and unmounts the banner. A mounted banner ente
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | A maintenance notice: icon, title and description on a soft info fill. |
+| [overview.tsx](examples/overview.tsx) | A maintenance notice: icon, title and description on a soft info fill — `Banner.Icon`, `Banner.Title`, `Banner.Description`. |
 | [variants.tsx](examples/variants.tsx) | Every treatment on every tone: soft by default, solid for urgent, outline for calm — `variant`, `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier: padding, icon and title follow the control tier, the description is one step smaller — `size`. |
 | [structure.tsx](examples/structure.tsx) | Optional parts: a one-line title, a title with a description, and actions where the close button joins the row — `Banner.Description`, `Banner.Actions`, `onDismiss`. |
-| [dismissible.tsx](examples/dismissible.tsx) | The parent owns visibility: the close button calls back, the banner closes up and focus moves to the restore button; the button name comes from labels — `onDismiss`, `labels`. |
+| [dismissible.tsx](examples/dismissible.tsx) | The parent owns visibility: the close button calls back, the banner fades into the restore button and focus follows it; the button name comes from labels — `onDismiss`, `labels`. |
 | [page-strip.tsx](examples/page-strip.tsx) | An edge-to-edge strip above a page and a rounded block inside a card — `placement`. |
 | [narrow.tsx](examples/narrow.tsx) | Below 36rem of its own width the banner moves the actions under the text — `Banner.Actions`. |
 

package/src/components/banner/examples/dismissible.tsx

@@ -1,4 +1,4 @@
-/** The parent owns visibility: the close button calls back, the banner closes up and focus moves to the restore button; the button name comes from labels — `onDismiss`, `labels`. */
+/** The parent owns visibility: the close button calls back, the banner fades into the restore button and focus follows it; the button name comes from labels — `onDismiss`, `labels`. */
 import { Banner, Button, Crossfade, Icon } from "prime-ui-kit";
 import * as React from "react";
 
@@ -6,29 +6,13 @@ import styles from "./examples.module.css";
 
 export default function BannerDismissibleExample() {
   const [visible, setVisible] = React.useState(true);
-  const bannerRef = React.useRef<HTMLDivElement>(null);
-  const restoreRef = React.useRef<HTMLButtonElement>(null);
-  const toggled = React.useRef(false);
-
-  // The pressed button leaves with its block: focus goes to the control that takes its place.
-  React.useEffect(() => {
-    if (!toggled.current) return;
-    if (visible) bannerRef.current?.querySelector("button")?.focus();
-    else restoreRef.current?.focus();
-  }, [visible]);
-
-  const toggle = (next: boolean) => {
-    toggled.current = true;
-    setVisible(next);
-  };
 
   return (
     <Crossfade state={visible ? "banner" : "restore"} className={styles.region}>
       {visible ? (
         <Banner.Root
-          ref={bannerRef}
           tone="accent"
-          onDismiss={() => toggle(false)}
+          onDismiss={() => setVisible(false)}
           labels={{ dismiss: "Скрыть объявление" }}
         >
           <Banner.Content>
@@ -40,7 +24,7 @@ export default function BannerDismissibleExample() {
           </Banner.Content>
         </Banner.Root>
       ) : (
-        <Button.Root ref={restoreRef} variant="outline" tone="neutral" onClick={() => toggle(true)}>
+        <Button.Root variant="outline" tone="neutral" onClick={() => setVisible(true)}>
           Вернуть баннер
         </Button.Root>
       )}

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/overview.tsx

@@ -1,4 +1,4 @@
-/** A maintenance notice: icon, title and description on a soft info fill. */
+/** A maintenance notice: icon, title and description on a soft info fill — `Banner.Icon`, `Banner.Title`, `Banner.Description`. */
 import { Banner, Icon } from "prime-ui-kit";
 
 export default function BannerOverviewExample() {

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>
   );
 }