prime-ui-kit 0.20.1 → 0.21.1

package/dist/skill/reference/layout/sidebar/examples/account-profile.tsx

@@ -0,0 +1,66 @@
+/** The signed-in person opens a profile panel, not a menu, so the row draws no chevron — `Sidebar.Account`, `description`. */
+import { Avatar, Button, DescriptionList, Drawer, Icon, Sidebar } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const PROFILE = [
+  { term: "Почта", value: "anna@company.ru" },
+  { term: "Роль", value: "Руководитель отдела продаж" },
+  { term: "Часовой пояс", value: "Москва, UTC+3" },
+];
+
+export default function SidebarAccountProfileExample() {
+  return (
+    <div className={styles.stage}>
+      <Sidebar.Root offCanvas="never">
+        <Sidebar.Content>
+          <Sidebar.Item current>
+            <Sidebar.ItemIcon>
+              <Icon name="nav.home" />
+            </Sidebar.ItemIcon>
+            Обзор
+          </Sidebar.Item>
+          <Sidebar.Item>
+            <Sidebar.ItemIcon>
+              <Icon name="object.document" />
+            </Sidebar.ItemIcon>
+            Сделки
+          </Sidebar.Item>
+        </Sidebar.Content>
+        <Sidebar.Footer>
+          <Drawer.Root>
+            <Drawer.Trigger>
+              <Sidebar.Account description="anna@company.ru">
+                <Avatar.Root color="purple">
+                  <Avatar.Fallback>АС</Avatar.Fallback>
+                </Avatar.Root>
+                Анна Смирнова
+              </Sidebar.Account>
+            </Drawer.Trigger>
+            <Drawer.Content size="s">
+              <Drawer.Header>
+                <Drawer.Title>Анна Смирнова</Drawer.Title>
+                <Drawer.Description>Профиль</Drawer.Description>
+              </Drawer.Header>
+              <Drawer.Body>
+                <DescriptionList.Root>
+                  {PROFILE.map(({ term, value }) => (
+                    <DescriptionList.Item key={term} label={term}>
+                      {value}
+                    </DescriptionList.Item>
+                  ))}
+                </DescriptionList.Root>
+              </Drawer.Body>
+              <Drawer.Footer>
+                <Button.Root variant="outline" tone="neutral">
+                  Выйти
+                </Button.Root>
+              </Drawer.Footer>
+            </Drawer.Content>
+          </Drawer.Root>
+        </Sidebar.Footer>
+      </Sidebar.Root>
+      <div className={styles.content} />
+    </div>
+  );
+}

package/dist/skill/responsive.md

@@ -119,7 +119,7 @@ const FIELDS: SmartFilterField[] = [
   { key: "city", label: "Город", options: [{ value: "msk", label: "Москва" }] },
 ];
 
-export function OrdersPage() {
+export function DealsPage() {
   const [section, setSection] = useState("all");
   const [period, setPeriod] = useState("30d");
   const [filter, setFilter] = useState<SmartFilterValue>({});
@@ -136,10 +136,10 @@ export function OrdersPage() {
       <Page.Root>
         <Page.TopBar>
           <Page.Heading>
-            <Page.Title>Заказы</Page.Title>
-            <Page.Description>128 в работе · 6 ждут оплаты</Page.Description>
+            <Page.Title>Сделки</Page.Title>
+            <Page.Description>128 в работе · 6,5 млн ₽</Page.Description>
           </Page.Heading>
-          <Page.Tools aria-label="Заказы">
+          <Page.Tools aria-label="Сделки">
             <SegmentedControl.Root value={section} onValueChange={setSection} aria-label="Раздел">
               <SegmentedControl.Item value="all">
                 Все<SegmentedControl.Count>128</SegmentedControl.Count>
@@ -170,14 +170,14 @@ export function OrdersPage() {
               <Button.Icon>
                 <Icon name="action.add" />
               </Button.Icon>
-              Новый заказ
+              Новая сделка
             </Button.Root>
           </Page.Actions>
           <Page.Chips>
             <SmartFilter.Chips />
           </Page.Chips>
         </Page.TopBar>
-        <Page.Body>{/* the orders table */}</Page.Body>
+        <Page.Body>{/* the deals as a board or a list: the filter in the bar narrows both views */}</Page.Body>
       </Page.Root>
     </SmartFilter.Root>
   );
@@ -210,6 +210,28 @@ export function OrdersPage() {
   segments' padding, and one whose items all have icons then collapses to icons (each named by its
   tooltip) before it scrolls. On a 320px phone two sections with counts fit a line of their own;
   more, or long labels, scroll — keep the section a person needs first at the start.
+- **Overflow is never fixed by merging.** A tab or a section is one topic; when the topics outgrow
+  the line the strip scrolls as above — never two topics joined in one tab («Доступ и история»),
+  never the last ones hidden in a «Ещё» of your own, never a second row. Shorten a label to one word
+  first; a topic that is rarely opened still keeps its own tab, at the end.
+
+```tsx partial
+// bad — the history folded into «Доступ» because five tabs did not fit the drawer
+<Tabs.Item value="access">Доступ и история</Tabs.Item>
+```
+
+```tsx good
+// good — every topic its own tab; the strip scrolls when it runs out of width
+<Tabs.Root defaultValue="profile">
+  <Tabs.List>
+    <Tabs.Item value="profile">Профиль</Tabs.Item>
+    <Tabs.Item value="access">Доступ</Tabs.Item>
+    <Tabs.Item value="notifications">Уведомления</Tabs.Item>
+    <Tabs.Item value="security">Безопасность</Tabs.Item>
+    <Tabs.Item value="history">История</Tabs.Item>
+  </Tabs.List>
+</Tabs.Root>
+```
 - Your duty as its host: give the switcher a bounded width. A flex or grid child that holds one sets
   `min-width: 0`, otherwise the switcher grows the row instead of scrolling
   ([foundation §9](reference/foundation.md#9-layout-and-responsiveness)).

package/dist/skill/ux.md

@@ -32,19 +32,55 @@ adds text that explains what the layout failed to show.
 | 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` |
+| 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`, `Switch` |
 | 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 |
 | One of a few options, sent with a form | all visible | `Radio.Group` |
 | One of a few modes of what the screen shows | all visible | `SegmentedControl` |
 | One of many options | a list that opens | `Select` |
 | Many values picked from options | tags | `TagSelect` |
+| A section named after a set of records (sessions, devices, API keys, members) | the records themselves, each with its own actions | `List` with `List.ItemActions` |
 
 How many options count as «a few» and the other selection cases: [choosing.md](choosing.md#2-inside-a-category).
 
 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`.
 
+**A section is what its name says.** A heading that names a set of records — «Сеансы», «Устройства»,
+«Ключи API», «Участники» — promises those records: show them, one row each (where, when, which one is
+this one), with the action on one record in its row and the action on all of them in the section's
+actions. One button standing for the set («Выйти на других устройствах») leaves the person to act on
+records they cannot see. A set that can be empty shows its empty state, never a missing section.
+
+```tsx partial
+// bad — «Сеансы» with nothing but a button
+<Drawer.Section label="Сеансы">
+  <Button.Root variant="soft" tone="neutral">Выйти на других устройствах</Button.Root>
+</Drawer.Section>
+```
+
+```tsx good
+// good — the sessions themselves, an end per row, the end of all of them beside the heading
+<Drawer.Section label="Сеансы">
+  <Drawer.Actions>
+    <Button.Root variant="soft" tone="neutral">Завершить остальные</Button.Root>
+  </Drawer.Actions>
+  <List.Root aria-label="Сеансы">
+    <List.Item value="mac">
+      <List.ItemText>Chrome · macOS</List.ItemText>
+      <List.ItemDescription>Москва · это устройство</List.ItemDescription>
+    </List.Item>
+    <List.Item value="iphone">
+      <List.ItemText>Safari · iPhone</List.ItemText>
+      <List.ItemDescription>Казань · вчера в 21:40</List.ItemDescription>
+      <List.ItemActions>
+        <Button.Root size="s" variant="ghost" tone="neutral">Завершить</Button.Root>
+      </List.ItemActions>
+    </List.Item>
+  </List.Root>
+</Drawer.Section>
+```
+
 ## 3. Label economy
 
 Every word on screen must carry something the person does not see already.
@@ -60,7 +96,21 @@ Every word on screen must carry something the person does not see already.
   beside the number when the row stacks, and a screen reader hears it with the field (the affix
   describes the input; `aria-label="рублей"` on it when the sign reads badly).
 - **No text that explains the layout.** «Двигатель, места и скорость всегда первыми» — the lock on
-  those rows says it. A hint says what the person cannot see (a format, a consequence, a limit).
+  those rows says it.
+- **A hint is the few words the label and the control leave out** — two to five: a format («ДД.ММ.ГГГГ»),
+  a limit («До 10 МБ»), a consequence nobody would expect («Увидит клиент»). Never what the control
+  already shows («Применяется сразу» under a Switch, «Время в CRM показывается в этом поясе» under
+  «Часовой пояс»), never the obvious outcome of the action or what stays unchanged («пароль
+  останется прежним», «история его действий останется»), never the label again in other words. A
+  field that needs no hint has none; a hint that needs a sentence is a missing label or a missing
+  control.
+
+| bad hint | good |
+|---|---|
+| «Часовой пояс» — «Время в CRM показывается в этом поясе» | no hint |
+| «Звук» (Switch) — «Применяется сразу, без сохранения» | no hint |
+| «Отключить доступ» — «Сотрудник не сможет войти, история его действий останется» | «Входы прекратятся» |
+| «Почта для входа» — «На эту почту придёт ссылка для входа в систему» | «Для входа и уведомлений» |
 - **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
@@ -157,3 +207,48 @@ Code that passes every check can still read badly. Open the screen in a browser
   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.
+
+## 10. Where a setting lives
+
+A setting lives with what it governs, as a field of the form that already holds its neighbours.
+
+- **Group by what it changes, not by how it looks.** A signal (a sound, a desktop banner, an e-mail
+  digest) changes how the person is told — it goes to the notifications; the theme, the language and
+  the time zone change how the app reads — profile preferences; what one record does goes to that
+  record. Ask «what would a person open to change this?» and put it there.
+- **No section for one setting.** A section with a single field joins the closest section; a new
+  section starts at three related fields.
+- **A stored preference is a field.** A setting with options (the theme: «Системная», «Светлая»,
+  «Тёмная») is a `Select` beside its related fields in the profile form — never a `SegmentedControl`,
+  which switches what a screen shows right now ([a flag, a level, a set](choosing.md#a-flag-a-level-a-set)).
+
+```tsx partial
+// bad — a section «Оформление» for the theme as a switch, and the dialog sounds next to it
+<Drawer.Section label="Оформление">
+  <SegmentedControl.Root label="Тема" defaultValue="system">…</SegmentedControl.Root>
+  <Switch.Root><Switch.Label>Звуки диалогов</Switch.Label></Switch.Root>
+</Drawer.Section>
+```
+
+```tsx good
+// good — the theme is one field of the profile, the sounds live with the notifications
+<>
+  <Drawer.Section label="Профиль">
+    <Select.Root label="Тема" defaultValue="system">
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        <Select.Item value="system">Системная</Select.Item>
+        <Select.Item value="light">Светлая</Select.Item>
+        <Select.Item value="dark">Тёмная</Select.Item>
+      </Select.Content>
+    </Select.Root>
+  </Drawer.Section>
+  <Drawer.Section label="Уведомления">
+    <Switch.Root name="dialogSounds">
+      <Switch.Label>Звуки диалогов</Switch.Label>
+    </Switch.Root>
+  </Drawer.Section>
+</>
+```

package/dist/tokens/semantic.d.ts

@@ -117,6 +117,7 @@ export declare const semanticTokens: {
             readonly fg: "{color.white}";
             readonly soft: "{color.green.100}";
             readonly text: "{color.green.700}";
+            readonly border: "{color.green.500}";
         };
         readonly warning: {
             readonly default: "{color.orange.700}";
@@ -410,7 +411,7 @@ export declare const semanticTokens: {
             /** State that glides into place (thumbs, indicators, checkmarks); pair with `base`. */
             readonly emphasized: "{easing.emphasized}";
         };
-        /** Step between items of a staggered first render. */
+        /** Step between items of a staggered entrance of parts that appear after their page is shown. */
         readonly stagger: "{duration.80}";
         /**
          * Period unit of a loading loop (Spinner turns once in 3 units, 6 under reduced motion). A

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

@@ -60,6 +60,7 @@ export declare const darkThemeOverrides: {
             readonly fg: "{color.gray.950}";
             readonly soft: "color-mix(in srgb, {color.green.500} 16%, transparent)";
             readonly text: "{color.green.300}";
+            readonly border: "{color.green.400}";
         };
         readonly warning: {
             readonly default: "{color.orange.400}";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "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

@@ -121,6 +121,7 @@ The soft fill is opaque: the soft hue is composited over the ground the avatar s
 - Avatar → name: space step 3 (12px) in lists and cards, step 2 (8px) in table cells.
 - Group: members overlap by an eighth of the diameter (initials are never cut) with a 2px ring in the ground they stand on: the current layer of the surface around them (no surface sets anything), or `--avatar-ring` from a host whose ground is not a layer (a reaction chip sets its own fill); the fills of initials and «+N» are composited over the same ground.
 - An icon fallback is half the diameter: a kit `Icon` reads `--prime-icon-size`, a raw svg too.
+- In a leading media slot (`Drawer.Icon`, `Modal.Icon`, `Sheet.Icon`, `Card.Icon`) the avatar takes the slot's size (`l`, 40px) whatever `size` it was given, also through a wrapper component of yours; the slot then draws no tile.
 
 ## Accessibility
 

package/src/components/badge/COMPONENT.md

@@ -35,7 +35,9 @@ Badge.Root          <span>: fill, tier dimensions
 ├─ Badge.Action     optional end segment revealed on hover / focus (always shown on touch screens)
 └─ remove segment   with onRemove: full height, the whole end is the hit area (Icon action.close)
 
-Badge.Group         <div>: a wrapping row of Badge.Root, one value; `size` sets every badge's tier
+Badge.Group         <div>: a row of Badge.Root, one value; `size` sets every badge's tier
+├─ Badge.Root …     one per value; with overflow="count" the ones that do not fit are hidden
+└─ «+N» badge       overflow="count": a focusable Badge.Root in a Tooltip listing the hidden values
 ```
 
 ## API
@@ -64,12 +66,14 @@ Badge.Group         <div>: a wrapping row of Badge.Root, one value; `size` sets
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "onClick" \| "color">` | — | `aria-label` (an icon-only badge named by it is an image) and the other span attributes; no `onClick` — a pressable chip is the toggle. |
 
 ### Badge.Group
-`ref` → `HTMLDivElement`. A row of badges as one value (the tags of a record): it wraps onto more lines, the badges a chip gap apart.
+`ref` → `HTMLDivElement`. A row of badges as one value (the tags of a record): it wraps onto more lines, the badges a chip gap apart, or with `overflow` stays on one line behind a «+N» badge.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | the host tier, one step down | Tier of every badge in the group; a badge's own `size` wins. Small tiers stand closer. |
-| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the `Badge.Root`s), `className`, `aria-label` (a named group is `role="group"`) and the other div attributes. |
+| `overflow` | `"wrap" \| "count"` | `"wrap"` | `wrap` — the row wraps onto more lines. `count` — one line (a table cell): the badges that fit the container, the rest behind a focusable «+N» badge whose tooltip lists them. |
+| `labels` | `Partial<BadgeGroupLabels>` | — | Built-in strings of the «+N» badge, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the `Badge.Root`s, one per value), `className`, `aria-label` (a named group is `role="group"`) and the other div attributes. |
 
 ### Badge.Icon
 `ref` → `HTMLSpanElement`. A `<span>` holding one icon at the tier icon size. At the first or last position it becomes a full-height edge segment.
@@ -146,6 +150,12 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 | `xl` | 32px high, text 14, icon 16 | large headers | |
 | — (omitted) | one tier below the surrounding control | inside Button, Input, Tabs | yes (inside controls) |
 
+### overflow (Badge.Group)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `wrap` | the row wraps onto more lines | tags of a record in a card, a form, a detail pane | yes |
+| `count` | one line: the badges that fit, then «+N» | a table cell, a list row — a set of values that must keep the row's height | |
+
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -167,6 +177,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 | 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 |
+| overflowed | `Badge.Group overflow="count"`, the badge does not fit the row | `data-overflowed` on the badge (out of the flow, `visibility: hidden`); the group's `data-overflow="count"`; re-measured on every resize of the row or a badge (`useResizeEffect`), the «+N» text from `labels.more` |
 
 ## Layout & spacing
 - Inline-flex, `width: fit-content`, `max-width: 100%`; text never wraps and ends in an ellipsis.
@@ -175,6 +186,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - 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: `Badge.Group` — it wraps, badges 8 apart (4 at the `xs` and `s` tiers).
+- `overflow="count"` fits the container, not the viewport: a DataTable cell, a 320px column. At least the first badge stays; when it alone does not fit it ellipsizes.
 - In a list row the badge is the trailing column; the title column gets `min-width: 0` and an ellipsis.
 
 ## Accessibility
@@ -184,7 +196,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 
 | Key | Action |
 |---|---|
-| `Tab` | Focuses the body of a toggle chip, then its action or remove segment. |
+| `Tab` | Focuses the body of a toggle chip, then its action or remove segment; in `Badge.Group` with `overflow` the «+N» badge, which opens its tooltip with the hidden values. |
 | `Enter` · `Space` | Presses the focused body (the toggle flips), remove or action button. |
 
 ### ARIA
@@ -195,15 +207,25 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - 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`; an icon-only badge needs `aria-label` and then is `role="img"`. Color never carries meaning alone, a `tone` neither.
+- `overflow="count"`: the badges that did not fit are `visibility: hidden` (out of the tree and the Tab order); the «+N» badge is a tab stop read as `labels.moreCount`; its tooltip, open while it has focus, lists the hidden values as its description.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
+#### Badge.Root
+
 | Key | Default | Used for |
 |---|---|---|
 | `remove` | `"Удалить"` | Accessible name of the remove segment; include the badge text («Убрать фильтр «Москва»»). |
 | `removeFailed` | `"Не удалось удалить"` | Spoken when the `onRemove` promise rejects and the badge stays; name the badge («Фильтр «Москва» не убран»). |
 
+#### Badge.Group
+
+| Key | Default | Used for |
+|---|---|---|
+| `more` | `"+{count}"` | Visible text of the badge for the badges that did not fit; `{count}` — how many. |
+| `moreCount` | `"Ещё {count}"` | What assistive tech reads for that badge instead of its visible text; `{count}` — how many. The values themselves come in its tooltip. |
+
 ## Examples
 | Example | Shows |
 |---|---|
@@ -218,6 +240,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 | [filter-values.tsx](examples/filter-values.tsx) | Filter values as toggles with a hide action that slides in without changing the width — `pressed`, `onPressedChange`, `Badge.Action`, `persistent`. |
 | [square.tsx](examples/square.tsx) | File formats as square tiles of text, large enough for three letters; the hue sorts them by kind — `shape`, `size`, `color`. |
 | [tag-row.tsx](examples/tag-row.tsx) | The tags of a client as one value: the row wraps in a narrow column and keeps one gap between badges — `Badge.Group`, `size`. |
+| [overflow-count.tsx](examples/overflow-count.tsx) | The sections of each role in one line of a narrow cell: what does not fit waits behind «+N» with the full list in its tooltip — `Badge.Group`, `overflow`. |
 | [controlled.tsx](examples/controlled.tsx) | Delivery cities as toggle chips whose state the screen owns: the summary counts the chosen ones — `pressed`, `onPressedChange`. |
 
 ## Mistakes
@@ -230,9 +253,10 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - A colored badge with no text → keep a word; color alone is not a signal.
 - An explicit `size` inside a control → drop it; the badge takes the tier one step down.
 - A row of badges in a hand-made flex wrapper with its own gap → `Badge.Group`.
+- A set of values in a table cell that wraps and grows the row, or a hand-made «+N» → `Badge.Group overflow="count"`.
 - `onRemove` together with `Badge.Action` → one end segment per badge.
 - Removing the badge from your list first and putting it back when the request fails → return the request's promise and remove it after it succeeds; the badge waits meanwhile.
 
 ## Related
-- **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)
+- **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), [Tooltip](../tooltip/COMPONENT.md) (the «+N» list), `useResizeEffect` (fitting the row), `internal/formatLabel` (`labels`)
 - **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/examples.module.css

@@ -30,3 +30,17 @@
   gap: var(--prime-space-6);
   inline-size: min(100%, calc(var(--prime-space-20) * 4));
 }
+
+/* overflow-count.tsx: rows of a narrow table — the role, then its sections in a cell. */
+.roles {
+  display: grid;
+  gap: var(--prime-space-3);
+  inline-size: min(100%, var(--prime-layout-form-width-s));
+}
+
+.role {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  align-items: center;
+  gap: var(--prime-space-3);
+}

package/src/components/badge/examples/overflow-count.tsx

@@ -0,0 +1,32 @@
+/** The sections of each role in one line of a narrow cell: what does not fit waits behind «+N» with the full list in its tooltip — `Badge.Group`, `overflow`. */
+import { Badge, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const ROLES = [
+  {
+    name: "Администратор",
+    sections: ["Сделки", "Контакты", "Счета", "Отчёты", "Склад", "Настройки"],
+  },
+  { name: "Менеджер", sections: ["Сделки", "Контакты", "Задачи"] },
+  { name: "Бухгалтер", sections: ["Счета", "Акты", "Платежи", "Отчёты"] },
+];
+
+export default function BadgeOverflowCountExample() {
+  return (
+    <div className={styles.roles}>
+      {ROLES.map((role) => (
+        <div key={role.name} className={styles.role}>
+          <Typography as="span" variant="body-m">
+            {role.name}
+          </Typography>
+          <Badge.Group overflow="count" aria-label={`Разделы роли «${role.name}»`}>
+            {role.sections.map((section) => (
+              <Badge.Root key={section}>{section}</Badge.Root>
+            ))}
+          </Badge.Group>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/banner/COMPONENT.md

@@ -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; 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).
+No `open` prop: the parent mounts and unmounts the banner. A banner that appears on a page already shown enters (a short fade and rise), one that mounts with its page stands still; 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`.

package/src/components/card/COMPONENT.md

@@ -9,6 +9,7 @@
 - KPI tiles on a dashboard (`mini`, `stat-trend`, `split`).
 - A chart or text widget with a header and controls (`panel`).
 - A settings or profile form grouped on its own surface (`panel` + `Body` + `Footer`).
+- A block about one person or object — a linked account, a contact — headed by its picture (`Card.Icon` with an `Avatar.Root` in `Card.Header`).
 - An activity list (`list`), a call to action (`cta`), a tile with an image on top (`cover`).
 - A tile that is itself the way to its details — a KPI that opens its report, a project tile (`asChild` with a link or a button).
 
@@ -25,7 +26,7 @@ import { Card } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Card.Root variant="panel"        Header(Title, Description?, …trailing) · Body · Media · Footer
+Card.Root variant="panel"        Header(Icon?, Title, Description?, …trailing) · Body · Media · Footer
 Card.Root variant="mini"         Icon · Label · Value · Meta? · Media?
 Card.Root variant="stat-trend"   Label · Value · Delta · Meta?
                                  or Header(Badge or Icon, Value) · Description
@@ -52,7 +53,7 @@ Card.Root asChild                <a> or <button> (the only child) holding the pa
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` + `aria-labelledby` for a landmark block, and the other div attributes. |
 
 ### Card.Header
-`ref` → `HTMLDivElement`. The top row: `Card.Title` first, anything after it (a control, a quiet caption) at the end. Wraps below 22rem.
+`ref` → `HTMLDivElement`. The top row: an optional `Card.Icon`, `Card.Title` with an optional `Card.Description` under it, anything else (a control, a caption) at the end. Wraps below 22rem.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -95,7 +96,7 @@ Card.Root asChild                <a> or <button> (the only child) holding the pa
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
 
 ### Card.Icon
-`ref` → `HTMLDivElement`. The 40px accent tile of a KPI holding one icon; it spans the label and the value rows in `mini` and a `split` cell.
+`ref` → `HTMLDivElement`. The 40px accent tile of one icon: beside the label and value in `mini` and a `split` cell, first in `Card.Header`. An `Avatar.Root` or `Thumbnail.Root` inside (also in a wrapper) is the record's picture: no tile, 40px, `aria-hidden`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -179,6 +180,7 @@ Without `asChild` a card is static: no hover, focus or press of its own. With it
 - Depth comes from nesting (foundation §4): on the page — the AppShell panel is the page — a card is layer 1 (white in light) with the raised whisper; inside another card it is the next layer, a flat tile. The ladder stops at layer 4.
 - Long values wrap; labels truncate, except in a `mini` tile and a `split` cell, where a label beside the icon wraps instead; a chart SVG needs a CSS height.
 - In a `Header` the title takes the free width; a control or a caption after it sits at the end without a wrapper. A `Card.Description` in the header stacks under the title, 4 apart; the control stays at the end, centred on both lines.
+- A `Card.Icon` in a `Header` leads the row, 12 before the title, centred on the title and the description: the accent tile, or the record's picture — an `Avatar.Root` or a `Thumbnail.Root` anywhere inside, also from your own wrapper component, with no tile; it takes 40 px whatever size it was given — for a card about one person or object (a linked account, a contact).
 - `Card.Meta` in `stat-trend` takes the bottom of the tile (`margin-top: auto`), so tiles of one row line their meta up; in `mini` and a `split` cell it sits in the text column under the value.
 
 ## Accessibility
@@ -212,6 +214,7 @@ No `labels`.
 | [variants.tsx](examples/variants.tsx) | KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change in every tone and a reference line — `variant`, `Card.Delta`, `tone`, `Card.Meta`. |
 | [kpi-media.tsx](examples/kpi-media.tsx) | A KPI with a sparkline or a fill level in the bottom slot of `mini` — `Card.Media`. |
 | [panel-chart.tsx](examples/panel-chart.tsx) | A chart widget: a header with a short description and a period switch, and a Sparkline with the period total over its chart — `Card.Header`, `Card.Description`, `Card.Body`. |
+| [person-header.tsx](examples/person-header.tsx) | A linked Telegram account in an employee card: the avatar leads the header, the handle stands under the name and the unlink button sits at the end — `Card.Icon`, `Avatar.Root`, `Card.Description`. |
 | [interactive.tsx](examples/interactive.tsx) | Whole cards as links to their reports: one tab stop each, a lift on hover, a press and the focus ring — `asChild`. |
 | [content-templates.tsx](examples/content-templates.tsx) | Content templates: a call to action, an events list and a campaign tile with a cover — `Card.Footer`, `Card.List`, `Card.Media`. |
 | [flat.tsx](examples/flat.tsx) | A flat tile without the raised shadow next to the default one, for dense grids — `flat`. |
@@ -225,6 +228,7 @@ No `labels`.
 - `Card.Delta tone="success"` for every «+» → choose the tone by meaning.
 - Custom padding on a `panel` root → padding belongs to `Header` / `Body` / `Footer`.
 - A wrapper `<div>` around the label and the value of `mini` → put `Icon`, `Label`, `Value` straight into the root (or into a `split` cell); the template lays them out.
+- An avatar, a name and a handle hand-laid in `Card.Body` with a button beside them → `Card.Header` with `Card.Icon` (the `Avatar.Root`), `Card.Title`, `Card.Description` and the button.
 - A chart SVG with only a `viewBox` → give it a CSS height.
 - A hand-drawn trend SVG in a chart widget → `Sparkline` in the `Body` (or `Media`); a chart with a legend and states → `ChartFrame`.
 - A clickable `<div>` card with `onClick` → `asChild` with a real `<a href>` (Cmd-click, a new tab) or a `<button>`.
@@ -233,5 +237,5 @@ No `labels`.
 - Skeletons placed by hand inside `Card.Value` → `Card.Root loading`; keep the parts mounted while loading so each holds its place.
 
 ## Related
-- **Built from:** [Skeleton](../skeleton/COMPONENT.md)
+- **Built from:** [Skeleton](../skeleton/COMPONENT.md), `internal/mediaSlot` (a record's Avatar or Thumbnail in `Card.Icon`)
 - **See also:** [Page](../../layout/page/COMPONENT.md), [DescriptionList](../description-list/COMPONENT.md) (record details inside a `Card.Body`), [Fieldset](../fieldset/COMPONENT.md) (groups of fields inside a settings card), [DataTable](../data-table/COMPONENT.md), [Badge](../badge/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Sparkline](../sparkline/COMPONENT.md) (a trend with its total inside a `panel`), [ChartFrame](../chart-frame/COMPONENT.md) (a full chart with legend and states)

package/src/components/card/examples/person-header.tsx

@@ -0,0 +1,38 @@
+/** A linked Telegram account in an employee card: the avatar leads the header, the handle stands under the name and the unlink button sits at the end — `Card.Icon`, `Avatar.Root`, `Card.Description`. */
+import { Avatar, Button, Card, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const ACCOUNT = {
+  name: "Анна Соколова",
+  initials: "АС",
+  handle: "@a.sokolova",
+  linkedAt: "Привязан 12 сентября",
+};
+
+export default function CardPersonHeaderExample() {
+  return (
+    <div className={styles.panel}>
+      <Card.Root>
+        <Card.Header>
+          <Card.Icon>
+            <Avatar.Root color="blue">
+              <Avatar.Fallback>{ACCOUNT.initials}</Avatar.Fallback>
+            </Avatar.Root>
+          </Card.Icon>
+          <Card.Title>{ACCOUNT.name}</Card.Title>
+          <Card.Description>{ACCOUNT.handle}</Card.Description>
+          <Button.Root variant="outline" tone="neutral">
+            Отвязать
+          </Button.Root>
+        </Card.Header>
+        <Card.Body>
+          <Typography as="p" variant="body-s" tone="secondary">
+            {ACCOUNT.linkedAt}. Бот присылает сюда новые заказы клиентов сотрудника и напоминания о
+            просроченных счетах.
+          </Typography>
+        </Card.Body>
+      </Card.Root>
+    </div>
+  );
+}