prime-ui-kit 0.13.1 → 0.15.0

package/dist/skill/reference/layout/sidebar/examples/router.tsx

@@ -1,6 +1,6 @@
-/** A router link as the item: the router sets `aria-current` and the item shows as current; render it inside a router — `asChild`. */
+/** Router links as the brand and the items: the router sets `aria-current` and the item shows as current; render it inside a router — `asChild`. */
 import { Icon, Sidebar } from "prime-ui-kit";
-import { NavLink } from "react-router-dom";
+import { Link, NavLink } from "react-router-dom";
 
 import styles from "./examples.module.css";
 
@@ -14,6 +14,18 @@ export default function SidebarRouterExample() {
   return (
     <div className={styles.stage}>
       <Sidebar.Root offCanvas="never">
+        <Sidebar.Header>
+          <Sidebar.Brand asChild description="Документация">
+            <Link to="/">
+              <Sidebar.BrandLogo>
+                <span className={styles.logo}>
+                  <Icon name="object.book" />
+                </span>
+              </Sidebar.BrandLogo>
+              Prime UI
+            </Link>
+          </Sidebar.Brand>
+        </Sidebar.Header>
         <Sidebar.Content>
           {LINKS.map((link) => (
             <Sidebar.Item key={link.to} asChild>

package/dist/skill/reference/layout/sidebar/examples/structure.tsx

@@ -1,4 +1,4 @@
-/** Labelled groups and the optional item parts: a plain count, a coloured badge, a key hint, a trailing icon, a row action and a disabled section — `Sidebar.Group`, `Sidebar.ItemCount`, `color`, `Sidebar.ItemShortcut`, `Sidebar.ItemAction`, `disabled`. */
+/** Labelled groups and the optional item parts: a plain count, coloured and solid badges, a key hint, a trailing icon, row actions with the default and an own glyph and a disabled section — `Sidebar.Group`, `Sidebar.ItemCount`, `color`, `variant`, `Sidebar.ItemShortcut`, `Sidebar.ItemAction`, `disabled`. */
 import { Icon, Kbd, Sidebar } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -29,7 +29,9 @@ export default function SidebarStructureExample() {
                 <Icon name="object.bell" />
               </Sidebar.ItemIcon>
               Уведомления
-              <Sidebar.ItemCount color="red">7</Sidebar.ItemCount>
+              <Sidebar.ItemCount color="red" variant="solid">
+                7
+              </Sidebar.ItemCount>
             </Sidebar.Item>
           </Sidebar.Group>
           <Sidebar.Group label="Работа">
@@ -54,6 +56,9 @@ export default function SidebarStructureExample() {
               </Sidebar.ItemIcon>
               Интеграции
               <Sidebar.ItemCount color="orange">!</Sidebar.ItemCount>
+              <Sidebar.ItemAction label="Синхронизировать интеграции" onClick={() => {}}>
+                <Icon name="action.refresh" />
+              </Sidebar.ItemAction>
             </Sidebar.Item>
           </Sidebar.Group>
           <Sidebar.Group label="Администрирование">

package/dist/skill/responsive.md

@@ -47,10 +47,10 @@ Use these as they are; never wrap them in your own breakpoints.
 
 | Need | Built in |
 |---|---|
-| app frame | AppShell gutters 16 → 24 → 32; `AppHeader` un-sticks on screens lower than 480px, respects safe areas and, below 36rem of its width, drops the description and folds the search into an icon |
+| app frame | AppShell gutters 16 → 24 → 32; `AppHeader` un-sticks on screens lower than 480px, respects safe areas and, below 36rem of its width, drops the title icon, the title and its line of data truncate |
 | app navigation | Sidebar: on-canvas from 768px, an off-canvas panel below (`offCanvas="auto"`) opened by `AppHeader.MenuButton`, which shows itself below 768px; `BottomNav` in `AppShell.Footer` for 2–6 app sections on phones — flat or a floating glass capsule (`floating`) with an optional round `BottomNav.Action`, icons with or without labels (`iconOnly`); the shell hides it by itself while the Sidebar rail is on screen (from 768px with `offCanvas="auto"`) |
 | page panel | `PageToolbar` — search and filter first, one row when wide, stacked rows when narrow (below) |
-| page header | `PageContent.Header`: actions wrap under the title |
+| page header | `AppHeader`: the page's tools wrap under the title (`AppHeader.Tools`), the primary action takes its own row when the search would be squeezed; a document page's `PageContent.Header`: actions wrap under the title |
 | switchers | SegmentedControl and Tabs never wrap: they scroll inside themselves (hidden scrollbar, faded edges, a vertical wheel scrolls them sideways), the active item is scrolled into view, stretched items tend to equal width, the indicator moves only after a person's choice; Tabs collapse icons and descriptions first |
 | tables | DataTable scrolls inside itself, edge shadows show hidden columns, `stickyFirstColumn`, `DataTable.ColumnsMenu` for a column chooser, the toolbar stacks below a 30rem table, sticky head off on short screens |
 | floating layers | Popover (opened from a Trigger), Dropdown, Select (and Datepicker, ColorPresets) never wider than the viewport − 16, 8 from the edges, flip when out of room; below 640 they open as a bottom sheet — scrim, grab handle, swipe down to close, page scroll locked; Tooltip and TagSelect stay anchored |
@@ -208,9 +208,11 @@ export function OrdersPanel() {
 `toolbar`; the key column `hideable: false`); `stickyFirstColumn` for the name. On phones a table / cards switch in `PageToolbar.View` is fine — silently dropping columns
 by breakpoint is not. Never ask to rotate the phone.
 
-**Card grids.** Columns come from the card's minimum width, not from a list of breakpoints:
-`grid-template-columns: repeat(auto-fill, minmax(min(100%, calc(var(--prime-space-16) * 4)), 1fr))`.
-Cards align to the top; a card with a list shows 6–8 rows and scrolls inside (`ScrollContainer`).
+**Card grids.** The tiles of a page are `PageContent.Grid` + `PageContent.Cell span`: it folds by its own
+width (below 30rem every tile takes the row, then small tiles pair up, from 64rem each its span),
+not by the window. Tiles of a row share one height; a card with a list shows 6–8 rows and scrolls inside
+(`ScrollContainer`). A grid inside one block (thumbnails, fields) is the block's own
+`repeat(auto-fill, minmax(min(100%, …), 1fr))`.
 
 **Forms.** One column on phones. Pairs («от / до», two buttons) wrap with
 `flex: 1 1 calc(var(--prime-space-24) * 2)` instead of shrinking. Labels above fields (the kit's

package/dist/skill/ux.md

@@ -0,0 +1,145 @@
+# UX — what to show and how to arrange it
+
+The rest of the skill says how a screen looks. This file says what goes on it: which shape the data
+takes on screen, how many words it needs, how much friction an action deserves, what a person must
+never have to guess. Read it before the layout, and again when you change a screen someone already
+built.
+
+## 1. Brief before code
+
+Before the first line of JSX, write five lines (in your reply, not in a file):
+
+1. **Who and what for** — the person and the decision this screen helps them make («менеджер
+   выставляет счёт клиенту»).
+2. **The data** — every entity on the screen and its shape: one record, a collection, a value with
+   variants, a base value with overrides (§2).
+3. **The main action** — one per area; everything else is secondary.
+4. **States** — which of loading, empty, error, disabled, read-only, saving, saved this screen
+   really has.
+5. **The narrow screen** — what stacks, what scrolls, what moves to a menu.
+
+The layout follows from the brief. A screen laid out without it repeats labels, splits records and
+adds text that explains what the layout failed to show.
+
+## 2. The shape of the data decides the layout
+
+| The data | On screen | With |
+|---|---|---|
+| One record, read | label · value pairs | `DescriptionList` |
+| One record, edited | a form: fields 20 apart, groups 32 apart | `Fieldset`, fields |
+| One record of 2–4 short fields in a form | one row of fields | an `auto-fit` grid |
+| Records of one shape a person adds, edits, removes | one row per record, the headings once above | `FieldList` |
+| Records of one shape a person reads, sorts, filters | a table | `DataTable` |
+| One value in several units or currencies (a deposit in ₽, $, ฿) | the fields side by side in one row under one heading, the unit in each field | `Input.InlineAffix` |
+| A base value and its overrides (a price and its changes by month) | one list: the base is the first, pinned row | `FieldList` `getLocked` |
+| Small attributes of a record (an icon, a color, a flag) | compact controls in the record's row, not fields of their own | icon-only `Select`, `ColorPresets`, `Checkbox` |
+| Short texts in an order the person sets | one column, a handle per row | `FieldList` `reorderable` |
+| Settings that most people never touch | behind a disclosure, after the common ones | `Accordion`, a «Дополнительно» section |
+| A choice of 2–5 options | all visible | `Radio.Group`, `SegmentedControl` |
+| A choice of 6+ options | a list that opens | `Select` |
+| Many values picked from options | tags | `TagSelect` |
+
+One record is one row or one block, never half a record per line. If a record does not fit one
+row, it is not a row: open it in a `Drawer`.
+
+## 3. Label economy
+
+Every word on screen must carry something the person does not see already.
+
+- **A label once per column, not per row.** Records in rows have their headings above the first
+  row only (`FieldList` draws them and names every field by its heading for screen readers).
+- **No numbered labels.** «Преимущество 1», «Преимущество 2» repeat the heading and count what the
+  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.
+- **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
+  (and across screens): «Счёт», not «Счёт» in the title and «Инвойс» in the button.
+- **Count the labels.** On a form of repeating rows, labels on screen ≤ number of columns + the
+  list label. More means a layout bug.
+
+## 4. Words
+
+The kit's UI language is Russian; these are the rules of its copy.
+
+- **Buttons say the verb and the object:** «Выставить счёт», «Добавить позицию», «Удалить проект».
+  Never «ОК», «Да», «Подтвердить», «Отправить» without an object when the object is not obvious.
+- **A confirm names the thing and the loss:** «Удалить проект «Север»? Задачи и файлы удалятся
+  без возможности восстановления.» — not «Вы уверены?».
+- **An error says how to fix it:** «Формат: +7 912 404-18-20», «Не больше 2 000 символов» — not
+  «Неверное значение», «Ошибка».
+- **An empty state says what to do next** and offers it: «Счетов пока нет» + «Выставить счёт». A
+  filtered empty state offers to reset the filter.
+- **Sentence case** everywhere: «Новый счёт», not «Новый Счёт».
+- **Numbers as digits:** «3 файла», not «три файла».
+- **Typography:** quotes «ёлочки» (inner „лапки“), a dash — with spaces, ranges with an en dash
+  without spaces (10–20), `…` as one character, a non-breaking space before units and after short
+  words in a heading (`50 ГБ`, `2 000 ₽`).
+- **Numbers, money and dates through `Intl`**, never by hand: `Intl.NumberFormat("ru-RU", { style:
+  "currency", currency: "RUB" })`, `Intl.DateTimeFormat("ru-RU", { day: "numeric", month: "long" })`,
+  `date-fns` with the `ru` locale for relative dates.
+- **Loading text ends with `…`:** «Сохраняем…». The kit's own labels already do.
+
+## 5. Friction matches the cost of a mistake
+
+Pick the lightest step that keeps the person safe ([choosing.md](choosing.md) has the components):
+
+| The action | The step |
+|---|---|
+| Reversible, frequent (remove a row, archive, move) | do it at once, «Отменить» in a `Notification` (`action`, commit in `onDismiss`) |
+| One standalone action that is easy to redo by hand | `Button.Root holdToConfirm` |
+| Irreversible loss of work, or a weighty outward action (send an invoice) | `ConfirmDialog` that names the thing and the loss |
+| Bulk destructive | `ConfirmDialog` that names the count («Удалить 12 счетов?») |
+| Leaving a form with changes | `Modal.Guard` / `Drawer.Guard dirty` |
+
+A confirm on every action trains people to click through it; the one that mattered is then missed.
+
+## 6. Nothing to guess
+
+- **A disabled control says why** when the reason is not on screen: a `hint` under the field, a
+  line beside the button («Не больше 3», as `FieldList` does at `max`), a `Tooltip` on a wrapper.
+  An action a person may never take (no permission) is hidden, not disabled.
+- **The state of a screen is in the URL:** the tab, the filters, the search, the page, the open
+  record. A link copied from the address bar opens the same view; Back undoes the last navigation.
+- **Visible status for every action** (the kit does it when you use it): `loading` on the button,
+  «Сохранено» on a form that stays, a `Notification` for one that goes away, `aria-busy` rows while
+  a save runs.
+- **Recognition over recall:** options are listed, not typed; the current value is shown in the
+  control, not in a hint.
+
+## 7. Ask less
+
+- **Defaults:** prefill what the system knows or can guess — the current period, today's date, the
+  person's own company, the last used currency. An empty required field the person always fills the
+  same way is a missing default.
+- **The right control for the data:** `inputMode="numeric" | "decimal" | "tel" | "email"`,
+  `autoComplete` for personal data, `Datepicker` for a date, `Select` for a closed list. A free text
+  field for a closed set of values is a bug.
+- **Progressive disclosure:** the common 80% first; rare settings behind an `Accordion` item or a
+  «Дополнительно» section; a long create flow in steps (`Stepper`).
+- **Group by meaning, order by use:** fields in the order a person has the information (company →
+  contact → payment), the most used first in every list.
+
+## 8. Changing a screen someone built
+
+1. **Audit before editing.** Go through [checklist.md](checklist.md), [anti-slop.md](anti-slop.md)
+   and §2–§7 of this file for the whole screen, and list what breaks the rules.
+2. **Fix the shape first:** repeated labels, split records, wrong control for the data, text that
+   explains the layout — these come before spacing and color.
+3. **Keep what works:** the screen's skeleton, its data flow and its names, unless they are the
+   problem.
+4. Then make the requested change on the cleaned screen.
+
+## 9. Look at it before handing it over
+
+Code that passes every check can still read badly. Open the screen in a browser and look:
+
+- **Both themes**, **1280 px and 375 px** wide, and the narrow container of every panel.
+- **Count:** labels on a form of rows (§3), primary buttons per area (one), sizes per row (one).
+- **Read every text aloud:** a word that repeats its neighbour, a hint that explains the layout, a
+  button without an object — remove or rewrite it.
+- **Fill it badly:** the longest real name, an empty list, an error on every field, the slowest
+  load. Nothing overflows, jumps or flips.

package/dist/tokens/semantic.d.ts

@@ -638,6 +638,8 @@ export declare const semanticTokens: {
     readonly mediaViewer: {
         readonly pageGap: "{space.6}";
         readonly inset: "{space.4}";
+        /** The widest the caption and the video control bar stand. */
+        readonly barWidth: "40rem";
     };
     /**
      * Chat bubble geometry (`Message`): the corner radius (one on every corner of every bubble), the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "packageManager": "bun@1.3.13",
   "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": {

package/src/components/avatar/COMPONENT.md

@@ -67,7 +67,7 @@ Avatar.Group           overlapping row, gives its size to members
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `status` | `"online" \| "offline" \| "away" \| "busy"` | — (required) | Presence state: green, gray, warning or danger dot. |
+| `status` | `"online" \| "offline" \| "away" \| "busy"` | — (required) | Presence state, told by shape and color: `online` a full green dot, `away` a warning crescent, `busy` a danger dot with a bar, `offline` a hollow gray ring. |
 | `labels` | `Partial<AvatarStatusLabels>` | — | Accessible names of the states, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
@@ -129,7 +129,7 @@ No keyboard interaction.
 
 ### ARIA
 - `Avatar.Image` `alt`: empty when the name is written next to it, otherwise the name. Without a photo and without a name nearby, put `aria-label` on `Avatar.Root`.
-- `Avatar.Status` is `role="img"` with `aria-label` from `labels`.
+- `Avatar.Status` is `role="img"` with `aria-label` from `labels`. Every state has its own shape (full dot, crescent, dot with a bar, hollow ring), so presence never rests on color alone.
 - `Avatar.Group` is `role="group"`; give it `aria-label`. Give `Avatar.Overflow` an `aria-label` («Ещё 3 участника»).
 
 ### Labels
@@ -148,8 +148,8 @@ No keyboard interaction.
 | [overview.tsx](examples/overview.tsx) | A photo with initials underneath while it loads, and initials alone — `Avatar.Image`, `Avatar.Fallback`. |
 | [variants.tsx](examples/variants.tsx) | Every palette hue of the fallback; derive it from a stable user id — `color`. |
 | [sizes.tsx](examples/sizes.tsx) | Every diameter, 20 to 64 px; initials take 40% of it — `size`. |
-| [states.tsx](examples/states.tsx) | A loaded photo, a broken URL that falls back to initials, and an icon fallback for a guest. |
-| [presence.tsx](examples/presence.tsx) | A presence dot on the avatar edge, announced by its state name — `Avatar.Status`, `labels`. |
+| [states.tsx](examples/states.tsx) | A loaded photo, a broken URL that falls back to initials, and an icon fallback for a guest — `Avatar.Image`, `Avatar.Fallback`. |
+| [presence.tsx](examples/presence.tsx) | A presence dot on the avatar edge: each state has its own shape and color and is announced by its name — `Avatar.Status`, `labels`. |
 | [team-group.tsx](examples/team-group.tsx) | Project members as an overlapping row with a «+N» cell; the group size goes to every member — `Avatar.Group`, `Avatar.Overflow`, `size`. |
 | [src-from-state.tsx](examples/src-from-state.tsx) | A new photo source restarts loading; initials show until the new photo arrives — `src`. |
 

package/src/components/avatar/examples/presence.tsx

@@ -1,4 +1,4 @@
-/** A presence dot on the avatar edge, announced by its state name — `Avatar.Status`, `labels`. */
+/** A presence dot on the avatar edge: each state has its own shape and color and is announced by its name — `Avatar.Status`, `labels`. */
 import { Avatar, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

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

@@ -1,4 +1,4 @@
-/** A loaded photo, a broken URL that falls back to initials, and an icon fallback for a guest. */
+/** A loaded photo, a broken URL that falls back to initials, and an icon fallback for a guest — `Avatar.Image`, `Avatar.Fallback`. */
 import { Avatar, Icon, Typography } from "prime-ui-kit";
 
 const PHOTO = "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
@@ -7,7 +7,7 @@ export default function AvatarStatesExample() {
   return (
     <div>
       <div>
-        <Avatar.Root size="xl" color="green">
+        <Avatar.Root color="green">
           <Avatar.Image src={PHOTO} alt="Михаил Котов" />
           <Avatar.Fallback>МК</Avatar.Fallback>
         </Avatar.Root>
@@ -16,7 +16,7 @@ export default function AvatarStatesExample() {
         </Typography>
       </div>
       <div>
-        <Avatar.Root size="xl" color="orange">
+        <Avatar.Root color="orange">
           <Avatar.Image src="https://example.com/missing-avatar.png" alt="Сергей Лебедев" />
           <Avatar.Fallback>СЛ</Avatar.Fallback>
         </Avatar.Root>
@@ -25,9 +25,9 @@ export default function AvatarStatesExample() {
         </Typography>
       </div>
       <div>
-        <Avatar.Root size="xl" aria-label="Гость">
+        <Avatar.Root aria-label="Гость">
           <Avatar.Fallback>
-            <Icon name="field.email" />
+            <Icon name="object.user" />
           </Avatar.Fallback>
         </Avatar.Root>
         <Typography as="span" variant="caption" tone="muted">

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/examples.module.css

@@ -10,20 +10,13 @@
   width: min(100%, var(--prime-modal-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);
-}
-
 .badges {
   display: flex;
   flex-wrap: wrap;

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/banner/COMPONENT.md

@@ -46,7 +46,7 @@ Banner.Root                 <div>; variant, tone, size, placement
 | `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. |
 | `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. |
+| `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. |
 | `labels` | `Partial<BannerLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` (`alert`, `status`, `region`), `aria-label` and the other div attributes. |
 
@@ -117,7 +117,7 @@ Banner.Root                 <div>; variant, tone, size, 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 |
 
-No `open` prop: the parent mounts and unmounts the banner.
+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).
 
 ## Layout & spacing
 - `width: 100%`; text column capped at `--prime-layout-reading-max-width`.
@@ -134,7 +134,7 @@ No `open` prop: the parent mounts and unmounts the banner.
 ### ARIA
 - 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`; after dismissing, move focus somewhere sensible.
+- 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`).
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -150,9 +150,9 @@ No `open` prop: the parent mounts and unmounts the banner.
 | [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 and the parent unmounts the banner; the button name comes from labels — `onDismiss`, `labels`. |
+| [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`. |
 | [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. |
+| [narrow.tsx](examples/narrow.tsx) | Below 36rem of its own width the banner moves the actions under the text — `Banner.Actions`. |
 
 ## Mistakes
 - A hand-made × next to the banner → pass `onDismiss`.
@@ -162,4 +162,4 @@ No `open` prop: the parent mounts and unmounts the banner.
 
 ## Related
 - **Built from:** [Button](../button/COMPONENT.md) (close button), Icon (`action.close`)
-- **See also:** [Notification](../notification/COMPONENT.md), [Hint](../hint/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Badge](../badge/COMPONENT.md)
+- **See also:** [Crossfade](../crossfade/COMPONENT.md), [Notification](../notification/COMPONENT.md), [Hint](../hint/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Badge](../badge/COMPONENT.md)

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

@@ -1,18 +1,34 @@
-/** The parent owns visibility: the close button calls back and the parent unmounts the banner; the button name comes from labels — `onDismiss`, `labels`. */
-import { Banner, Button, Icon } from "prime-ui-kit";
+/** 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`. */
+import { Banner, Button, Crossfade, Icon } from "prime-ui-kit";
 import * as React from "react";
 
 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 (
-    <div className={styles.stack}>
+    <Crossfade state={visible ? "banner" : "restore"} className={styles.region}>
       {visible ? (
         <Banner.Root
+          ref={bannerRef}
           tone="accent"
-          onDismiss={() => setVisible(false)}
+          onDismiss={() => toggle(false)}
           labels={{ dismiss: "Скрыть объявление" }}
         >
           <Banner.Content>
@@ -24,15 +40,10 @@ export default function BannerDismissibleExample() {
           </Banner.Content>
         </Banner.Root>
       ) : (
-        <Button.Root
-          variant="outline"
-          tone="neutral"
-          className={styles.restore}
-          onClick={() => setVisible(true)}
-        >
+        <Button.Root ref={restoreRef} variant="outline" tone="neutral" onClick={() => toggle(true)}>
           Вернуть баннер
         </Button.Root>
       )}
-    </div>
+    </Crossfade>
   );
 }

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,16 +17,12 @@
   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));
 }
 
-/* dismiss.tsx */
-.restore {
-  align-self: flex-start;
+/* dismissible.tsx: the swapped region takes the row's width. */
+.region {
+  width: 100%;
 }

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

@@ -1,4 +1,4 @@
-/** Below 36rem of its own width the banner moves the actions under the text. */
+/** Below 36rem of its own width the banner moves the actions under the text — `Banner.Actions`. */
 import { Banner, Button, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

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

@@ -1,32 +1,26 @@
 /** An edge-to-edge strip above a page and a rounded block inside a card — `placement`. */
-import { Banner, Button, Card, Icon, Typography } from "prime-ui-kit";
+import { Banner, Button, Card, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
 export default function BannerPageStripExample() {
   return (
     <div className={styles.sections}>
-      <Card.Root>
-        <Banner.Root
-          tone="warning"
-          placement="page"
-          role="region"
-          aria-label="Пробный период"
-          onDismiss={() => undefined}
-        >
-          <Banner.Content>
-            <Banner.Icon>
-              <Icon name="status.warning" />
-            </Banner.Icon>
-            <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
-          </Banner.Content>
-        </Banner.Root>
-        <div className={styles.pageBody}>
-          <Typography as="h3" variant="heading-s">
-            Отчёты
-          </Typography>
-        </div>
-      </Card.Root>
+      {/* In an app the strip stands first in the page, edge to edge above its content. */}
+      <Banner.Root
+        tone="warning"
+        placement="page"
+        role="region"
+        aria-label="Пробный период"
+        onDismiss={() => undefined}
+      >
+        <Banner.Content>
+          <Banner.Icon>
+            <Icon name="status.warning" />
+          </Banner.Icon>
+          <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
+        </Banner.Content>
+      </Banner.Root>
       <Card.Root variant="panel">
         <Card.Header>
           <Card.Title>Оплата</Card.Title>