prime-ui-kit 0.14.0 → 0.16.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/applied-filters.tsx

@@ -8,23 +8,9 @@ const INITIAL = ["Москва", "Санкт-Петербург", "Есть в
 
 export default function BadgeAppliedFiltersExample() {
   const [filters, setFilters] = React.useState(INITIAL);
-  const titleId = React.useId();
 
   return (
-    <section className={styles.filters} aria-labelledby={titleId}>
-      <div className={styles.filtersHeader}>
-        <Typography as="h3" variant="title-s" id={titleId}>
-          Фильтры
-        </Typography>
-        <Button.Root
-          variant="ghost"
-          tone="neutral"
-          size="s"
-          onClick={() => setFilters(filters.length > 0 ? [] : INITIAL)}
-        >
-          {filters.length > 0 ? "Сбросить все" : "Вернуть"}
-        </Button.Root>
-      </div>
+    <div className={styles.filters}>
       {filters.length > 0 ? (
         <div className={styles.badges}>
           {filters.map((label) => (
@@ -36,12 +22,20 @@ export default function BadgeAppliedFiltersExample() {
               {label}
             </Badge.Root>
           ))}
+          <Button.Root variant="ghost" tone="neutral" size="s" onClick={() => setFilters([])}>
+            Сбросить все
+          </Button.Root>
         </div>
       ) : (
-        <Typography variant="body-s" tone="muted">
-          Фильтры не выбраны — показаны все товары.
-        </Typography>
+        <div className={styles.badges}>
+          <Typography variant="body-s" tone="muted">
+            Фильтры не выбраны — показаны все товары.
+          </Typography>
+          <Button.Root variant="ghost" tone="neutral" size="s" onClick={() => setFilters(INITIAL)}>
+            Вернуть
+          </Button.Root>
+        </div>
       )}
-    </section>
+    </div>
   );
 }

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,21 +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: a filter panel above a list. */
+/* 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));
-}
-
-.filtersHeader {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--prime-space-3);
+  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/server-tags.tsx

@@ -19,13 +19,9 @@ function deleteTag(tag: string) {
 export default function BadgeServerTagsExample() {
   const [tags, setTags] = React.useState(TAGS);
   const [failure, setFailure] = React.useState<string | null>(null);
-  const titleId = React.useId();
 
   return (
-    <section className={styles.filters} aria-labelledby={titleId}>
-      <Typography as="h3" variant="title-s" id={titleId}>
-        Теги заказа № 4821
-      </Typography>
+    <div className={styles.filters}>
       <div className={styles.badges}>
         {tags.map((tag) => (
           <Badge.Root
@@ -56,6 +52,6 @@ export default function BadgeServerTagsExample() {
           {failure}
         </Typography>
       ) : null}
-    </section>
+    </div>
   );
 }

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

@@ -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. |
 
@@ -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,7 @@
   min-width: 0;
 }
 
-/* placement.tsx: a page frame above a card. */
+/* page-strip.tsx: the page strip above a card with an inset banner. */
 .sections {
   display: flex;
   flex-direction: column;
@@ -17,10 +17,6 @@
   min-width: 0;
 }
 
-.pageBody {
-  padding: var(--prime-space-5) var(--prime-space-4) var(--prime-space-8);
-}
-
 /* 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() {