prime-ui-kit 0.20.1 → 0.21.0

package/dist/skill/reference/components/smart-filter/COMPONENT.md

@@ -93,6 +93,7 @@ One entry of `fields`: data, not a part. Selected values missing from `options`
 | `finite` | `boolean` | `true` | `options` fields: a fixed set — hiding every value is refused. `false` for an open set (services, users). |
 | `multiple` | `boolean` | `true` | `options` fields: many values at once. `false` — one value and no hiding: a press picks only that value, a second press clears it (an API that takes one value per field). |
 | `formatValue` | `(value: number) => string` | Russian digit groups | `range` fields: a bound in the chip («1 000 ₽»). |
+| `calendar` | `Pick<DatepickerPanelProps, "months" \| "presets" \| "prompt" \| "footer" \| "withTime" \| "isDayDisabled" \| "disableFuture" \| "today" \| "locale" \| "weekStartsOn" \| "labels">` | — | `date-range` fields: the calendar of the period, as on a report's own Datepicker — `presets`, `months`, `prompt`, `footer`, `withTime`; the chip names a matching preset («Период: Этот месяц»). Without it the panel opens one month with no presets. |
 
 ### Functions
 
@@ -233,7 +234,7 @@ same height and type.
 | [overview.tsx](examples/overview.tsx) | Filters above a request list: the filter button and the search, applied filters as tags, rows narrowed by the value and the text — `fields`, `value`, `search`, `matchesSmartFilter`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: the filter button, the search, the tags and the panel follow one tier — `size`. |
 | [many-values.tsx](examples/many-values.tsx) | An open set of twenty services, degraded ones marked with an icon, collapsed after eight; typing narrows the panel and marks the match in accent — `finite`, `icon`, `collapsedLimit`. |
-| [ranges.tsx](examples/ranges.tsx) | Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `matchesSmartFilter`, `isSmartFilterRange`. |
+| [ranges.tsx](examples/ranges.tsx) | Deals narrowed by an amount from–to and a period from a calendar with presets, two months and an Apply footer; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `calendar`, `matchesSmartFilter`, `isSmartFilterRange`. |
 | [single-value.tsx](examples/single-value.tsx) | For an API that takes one value per field: the filter button without a search, a press picks only that value and nothing can be hidden — `searchable`, `multiple`. |
 | [option-groups.tsx](examples/option-groups.tsx) | Values of different kinds in one field: owner types and people under their own headings — `options`, `group`. |
 | [controlled.tsx](examples/controlled.tsx) | A saved view sets the value from outside; the selection is read back as the list to ask the server for — `value`, `onValueChange`, `resolveSmartFilterValues`. |

package/dist/skill/reference/components/smart-filter/examples/ranges.tsx

@@ -1,6 +1,7 @@
-/** Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `matchesSmartFilter`, `isSmartFilterRange`. */
+/** Deals narrowed by an amount from–to and a period from a calendar with presets, two months and an Apply footer; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `calendar`, `matchesSmartFilter`, `isSmartFilterRange`. */
 import {
   Card,
+  DEFAULT_DATEPICKER_PRESETS,
   formatDateValue,
   isSmartFilterRange,
   matchesSmartFilter,
@@ -17,7 +18,12 @@ const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
 
 const FIELDS: SmartFilterField[] = [
   { key: "amount", label: "Сумма", kind: "range", formatValue: formatRubles },
-  { key: "closed", label: "Период", kind: "date-range" },
+  {
+    key: "closed",
+    label: "Период",
+    kind: "date-range",
+    calendar: { presets: DEFAULT_DATEPICKER_PRESETS, months: 2, prompt: true, footer: true },
+  },
   {
     key: "stage",
     label: "Этап",

package/dist/skill/reference/components/spinner/COMPONENT.md

@@ -68,7 +68,7 @@ Spinner          <span role="status">; size and tone
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| appearing | mounted | fades in over `fast` (`internal/enterMotion`), so a spinner that comes and goes never blinks |
+| appearing | mounted into a host already shown | fades in over `fast` (`internal/enterMotion`), so a spinner that comes and goes never blinks; one that mounts with its page stands still |
 | spinning | mounted | the ring turns at a constant speed (`--prime-motion-loop × 3` per turn, linear) |
 | reduced motion | `prefers-reduced-motion` | the ring keeps turning, twice as slow (`--prime-motion-loop × 6` per turn) and linear: a loading cue is information, so the token is not zeroed |
 | size / tone | `size`, `tone` | `data-size` (the explicit size, else the host control tier, else `m`), `data-tone` (only for a non-default tone) |

package/dist/skill/reference/components/tabs/COMPONENT.md

@@ -35,7 +35,7 @@ Tabs.Root                 value, size (else the host tier), orientation, tone, f
 │  │  ├─ Tabs.Count       counter Badge, one tier below the tabs size
 │  │  └─ Tabs.Description muted second line; makes the tab two-line
 │  └─ Tabs.Separator      Divider hairline between groups of tabs
-└─ Tabs.Panel             role="tabpanel", rendered only while its tab is active; no fill, no padding
+└─ Tabs.Panel             role="tabpanel", rendered only while its tab is active (keepMounted: kept hidden once opened); no fill, no padding
 ```
 
 ## API
@@ -120,11 +120,12 @@ Tabs.Root                 value, size (else the host tier), orientation, tone, f
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other div attributes. |
 
 ### Tabs.Panel
-`ref` → `HTMLDivElement`. `<div role="tabpanel">`, focusable, rendered only while its tab is active. No fill and no padding: its content is the host's content, aligned with the strip's edges. Its content enters each time it opens.
+`ref` → `HTMLDivElement`. `<div role="tabpanel">`, focusable, rendered only while its tab is active (with `keepMounted`, kept hidden once opened). No fill and no padding: its content is the host's content, aligned with the strip's edges. Content opened after mount enters.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `string` | — (required) | Tab value this panel belongs to. |
+| `keepMounted` | `boolean` | `false` | Once opened, the panel stays mounted and `hidden` while another tab is active: its data, form draft and scroll survive a switch. A panel never opened is not mounted. |
 | `children` | `ReactNode` | — | Panel content. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
 
@@ -187,13 +188,14 @@ Avoid icons or descriptions on only some tabs (uneven rows; without an icon on e
 | disabled | `disabled` on Item | native `disabled`, `data-disabled="true"`, `text-disabled`; a removable tab loses its close button |
 | removable | `onRemove` on Item | item wrapper `data-removable="true"`, close button, tab `aria-keyshortcuts="Delete"` |
 | closing, confirm pending | `onRemove` returned a promise that has not settled | the close button is `loading` (`aria-busy`); the tab, its selection and focus stay; resolved → the neighbour takes over, rejected → nothing changes |
+| kept | `keepMounted` on Panel, its tab once opened and now inactive | the panel stays mounted with `hidden` (out of the layout, the tab order and the accessibility tree); its tab keeps `aria-controls`; shown again, its content enters as on a first open |
 | two-line | `Tabs.Description` child | `data-two-line="true"` |
 | collapsed | tabs wider than the list, or a label that would be cut (horizontal) | list `data-collapse="full" \| "compact" \| "icon"`: `compact` hides icons and descriptions; `icon` takes labels, counts and close buttons out of the row — a `VisuallyHidden` copy of the label names the tab and a `Tooltip` shows it — only when every tab has an icon |
 | overflow | tabs at their narrowest (content width, `minItemWidth` or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (the switcher row, a ScrollContainer), faded edges as deep as the hidden part at most (they grow and melt with the scroll, never switch); when the end edge would cut only a tab's empty side, the tabs at `minItemWidth` widen a little (`--tabs-peek`, up to 30%) so a label fades out at the edge and shows that more tabs follow; the active tab is kept in view and clear of the fades on mount and on every value change, the first and the last tab scroll all the way to the end — only the list scrolls, never the page. A column (a wide vertical list) has plain edges |
 
 The indicator glides (`emphasized` + `base`, `data-animate="true"`) only into a choice by click, arrow keys or closing the active tab; on mount, a value set from outside, a resize, font loading, tabs added or removed and collapse it is placed without motion, and it stays still under `prefers-reduced-motion`. The list scrolls smoothly to the active tab only after such a choice too.
 
-Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; the folder (the list's first child, `data-indicator`) `data-axis="x" | "y"` (follows the list's direction, so a vertical list in a narrow container gets the top folder); Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted, and a tab points at its panel (`aria-controls`) only while the panel is in the document; a panel's content enters each time it opens.
+Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; the folder (the list's first child, `data-indicator`) `data-axis="x" | "y"` (follows the list's direction, so a vertical list in a narrow container gets the top folder); Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted (unless `keepMounted`), and a tab points at its panel (`aria-controls`) only while the panel is in the document; a panel's content enters each time it opens after mount (the panel shown on mount stands still).
 
 ## Layout & spacing
 - Tabs are a bar, not a surface: the root has no fill, padding, radius or `data-depth`. On a page or in a `Card.Body`, put it straight into the host's padded region and the panel content straight into `Tabs.Panel`. The strip's edges and the panel content share the host's content edge; the panel stands one tier gap below the strip (`--prime-space-3` … `--prime-space-8`).
@@ -261,7 +263,7 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 | [overflow.tsx](examples/overflow.tsx) | Drag the frame narrower: icons go first, then labels, and icons with tooltips stay; then the list scrolls — `Tabs.Icon`. |
 | [closable.tsx](examples/closable.tsx) | Open order cards as browser tabs: each closes by its button, Delete or a middle click; tabs stay between two widths, and the list scrolls when they do not fit — `onRemove`, `minItemWidth`, `maxItemWidth`. |
 | [two-line.tsx](examples/two-line.tsx) | A label and a counter on the first line, a summary on the second — `Tabs.Count`, `Tabs.Description`. |
-| [in-drawer.tsx](examples/in-drawer.tsx) | Order details in a Drawer: the tab bar runs along the bottom of the header, the active tab is the body rising into it, and every panel is the body's own content — `Tabs.Root`, `Tabs.List`, `Tabs.Panel`. |
+| [in-drawer.tsx](examples/in-drawer.tsx) | Order details in a Drawer: the tab bar runs along the bottom of the header and scrolls sideways when the tabs outgrow the drawer, the active tab is the body rising into it, every panel is the body's own content, and the delivery form keeps its edits across tabs — `Tabs.Root`, `Tabs.List`, `Tabs.Panel`, `keepMounted`. |
 | [controlled.tsx](examples/controlled.tsx) | The active tab lives in parent state, e.g. synced with the URL — `value`, `onValueChange`. |
 
 ## Mistakes
@@ -274,6 +276,7 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 - A hand-made × inside `Tabs.Item` → a button inside a tab button; pass `onRemove` instead.
 - `onRemove` that does not drop the tab from your list → the tab stays; the kit only moves the selection.
 - `Tabs.List` without `aria-label` → add one.
+- Lifting a panel's data or form draft to the parent only so it survives a tab switch → `keepMounted` on that `Tabs.Panel`.
 - Tabs inside `Drawer.Body` / `Modal.Body` under the header → a floating strip under the header's hairline; wrap the header and the body in `Tabs.Root` and put `Tabs.List` into the header.
 
 ## Related

package/dist/skill/reference/components/tabs/examples/in-drawer.tsx

@@ -1,4 +1,4 @@
-/** Order details in a Drawer: the tab bar runs along the bottom of the header, the active tab is the body rising into it, and every panel is the body's own content — `Tabs.Root`, `Tabs.List`, `Tabs.Panel`. */
+/** Order details in a Drawer: the tab bar runs along the bottom of the header and scrolls sideways when the tabs outgrow the drawer, the active tab is the body rising into it, every panel is the body's own content, and the delivery form keeps its edits across tabs — `Tabs.Root`, `Tabs.List`, `Tabs.Panel`, `keepMounted`. */
 import { Badge, Button, DescriptionList, Drawer, Fieldset, Input, Tabs } from "prime-ui-kit";
 
 const ITEMS = [
@@ -7,6 +7,11 @@ const ITEMS = [
   { name: "Сборка и подъём на этаж", amount: "1 × 3 200 ₽" },
 ];
 
+const DOCUMENTS = [
+  { name: "Счёт № 1042-С", date: "3 октября" },
+  { name: "Накладная № 1042-Н", date: "4 октября" },
+];
+
 const HISTORY = [
   { time: "3 октября, 10:14", event: "Заказ оформлен" },
   { time: "3 октября, 10:20", event: "Оплата прошла" },
@@ -33,6 +38,7 @@ export default function TabsInDrawerExample() {
                 <Tabs.Count>{ITEMS.length}</Tabs.Count>
               </Tabs.Item>
               <Tabs.Item value="delivery">Доставка</Tabs.Item>
+              <Tabs.Item value="documents">Документы</Tabs.Item>
               <Tabs.Item value="history">История</Tabs.Item>
             </Tabs.List>
           </Drawer.Header>
@@ -58,7 +64,7 @@ export default function TabsInDrawerExample() {
               </DescriptionList.Root>
             </Tabs.Panel>
 
-            <Tabs.Panel value="delivery">
+            <Tabs.Panel value="delivery" keepMounted>
               <Fieldset aria-label="Доставка">
                 <Input.Root label="Адрес">
                   <Input.Wrapper>
@@ -73,6 +79,16 @@ export default function TabsInDrawerExample() {
               </Fieldset>
             </Tabs.Panel>
 
+            <Tabs.Panel value="documents">
+              <DescriptionList.Root>
+                {DOCUMENTS.map((document) => (
+                  <DescriptionList.Item key={document.name} label={document.name}>
+                    {document.date}
+                  </DescriptionList.Item>
+                ))}
+              </DescriptionList.Root>
+            </Tabs.Panel>
+
             <Tabs.Panel value="history">
               <DescriptionList.Root>
                 {HISTORY.map((entry) => (

package/dist/skill/reference/components/thumbnail/COMPONENT.md

@@ -142,6 +142,7 @@ Thumbnail.Root          frame (a <div>; the child with asChild; a <button role="
 - In a table the row grows to the thumbnail; never shrink the thumbnail to the row.
 - Card covers: `fullWidth` inside the card body, the body's gap to the title.
 - No outline by default: the fill separates the preview.
+- In a leading media slot (`Drawer.Icon`, `Modal.Icon`, `Sheet.Icon`, `Card.Icon`) the thumbnail takes the slot's size (`m`, 40px) whatever `size` it was given, also through a wrapper component of yours; the slot then draws no tile.
 
 ## Accessibility
 

package/dist/skill/reference/components/tooltip/COMPONENT.md

@@ -110,7 +110,7 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| open / closed | hover (mouse, pen) or focus after `delayDuration`; `open` / `defaultOpen` / `onOpenChange` | `data-state="open" \| "closed"` on the chip (closed during the exit) and on the trigger |
+| open / closed | hover (mouse, pen) or keyboard focus after `delayDuration` (not the focus a click causes or a dialog moves in after a click); `open` / `defaultOpen` / `onOpenChange` | `data-state="open" \| "closed"` on the chip (closed during the exit) and on the trigger |
 | closing | blur, a press on the trigger, Escape, pointer leaving (unless it moves onto the chip) | — |
 | warm group | another tooltip of the Provider was just shown | `data-instant="true"`: opens and leaves without motion |
 | side | `side` and the room around the trigger | `data-side` (resolved), `data-align` |
@@ -128,7 +128,7 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 
 | Key | Action |
 |---|---|
-| `Tab` | Focus on the trigger opens the tooltip after the delay. |
+| `Tab` | Keyboard focus on the trigger opens the tooltip after the delay; focus a click causes, or a layer moves in after a click, does not. |
 | `Escape` | Hides the tooltip; focus stays on the trigger. |
 
 ### ARIA
@@ -137,7 +137,7 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 - The chip is `role="tooltip"`; while open the trigger points at it with `aria-describedby` (appended to the child's own).
 - `Tooltip.Trigger` composes the child's `ref`, sets `data-state` and chains the child's `onPointerEnter`, `onPointerLeave`, `onPointerDown`, `onFocus` and `onBlur`.
 - The tooltip is a description, not the name: an icon-only button needs its own `aria-label`.
-- The pointer may move onto the chip without closing it (WCAG 1.4.13); a touch does not open it, focus does.
+- The pointer may move onto the chip without closing it (WCAG 1.4.13); a touch does not open it, keyboard focus does.
 - Tooltip has no `closeOnEscape` / `closeOnOutsideClick` (foundation §8): it closes on pointer-leave, blur, a press on the trigger and Escape, and Escape cannot be turned off — WCAG 1.4.13 requires the chip to be dismissable without moving the pointer or focus.
 - A `disabled` control (its own prop or a disabled `Fieldset`) is wrapped by the kit in a focusable `<span>`: the host takes hover and Tab, the focus ring is drawn on the control. Around a button the host is that button for assistive tech — `role="button"`, `aria-disabled`, named by the control through `aria-labelledby` — and the control itself leaves the tree.
 - A trigger that is no tab stop (Badge, Avatar, ProgressCircle, `Icon` with `label`) gets `tabIndex={0}` and the focus ring; its name comes from `aria-label` or the icon `label`.

package/dist/skill/reference/foundation.md

@@ -51,11 +51,14 @@ The design contract for every component. Tokens live in `tokens/` and are genera
    perfectly in a row (Button, Input, Select, Datepicker trigger, SegmentedControl, Tabs).
 5. **Nested radius = outer radius − padding.** Panel 12 with padding 4 → items 8.
 6. **Air is hierarchy.** Important content gets more space; secondary content is grouped tighter.
-7. **State changes are continuous.** Nothing on screen flips from one state to another. Controls move
-   into their new state (§7 Motion, rule 8); a region that changes what it shows — loading → data →
+7. **State changes are continuous; loading never unfolds.** Nothing on screen flips from one state to
+   another. Controls move into their new state (§7 Motion, rule 8). Whatever loads is a `Skeleton` in
+   the data's geometry from the first paint — never nothing, never a region that grows from zero —
+   and the data then replaces it in place: no height glide, no reveal, no slide, at most a short
+   cross-fade, the layout settled in one frame. A region swapping between settled states — data →
    empty → error, one record → another — cross-fades and glides to its new height (`Crossfade`). A
-   loading region holds the shape of what is coming (`Skeleton` with the data's geometry), so the
-   swap moves nothing. This holds for every region of every screen, not only for prominent ones.
+   region that mounts in its state shows it still. This holds for every region of every screen, not
+   only for prominent ones.
 
 ## 2. Token layers and naming
 
@@ -339,8 +342,8 @@ Every component is designed with its micro-animations, not only its static state
    `padding`, `top/left`; never `transition: all` — list the properties. Where size must animate, prefer
    `transform` / `scale` (progress fills). The exceptions are a closed list, each with one engine,
    and `src/styles/motion-perf.test.ts` allows nothing else:
-   - **height glide** — a region that swaps its content glides to the new height (`Crossfade`, the
-     Notification stack);
+   - **height glide** — a region that swaps its content between settled states glides to the new
+     height (`Crossfade`, the Notification stack); a swap into or out of loading never glides;
    - **row fold** — a part that folds open or closed animates `grid-template-rows` 0fr ↔ 1fr
      (`Disclosure`: Accordion, DataTable expanded rows);
    - **text width** — a label that morphs into another text glides its `width` (`MorphText`).
@@ -353,8 +356,11 @@ Every component is designed with its micro-animations, not only its static state
 8. **State moves, it does not swap.** Checkmark draws/scales in, switch thumb slides, selection indicator
    (tabs, segmented control) glides to the new item, chevrons rotate, progress fills, counters and fills
    ease. Two states cross-fade rather than flip when they replace each other in place: a region
-   swapping its content uses `Crossfade` (inside a component: `RegionSwap`), and its
-   loading state is a `Skeleton` of the coming content (principle 7).
+   swapping its content uses `Crossfade` (inside a component: `RegionSwap`). Its loading state is
+   the state `"loading"`: a `Skeleton` of the coming content, drawn from the first paint, which the
+   data replaces in place — the height settles in one frame and the fade takes `fast`; only a swap
+   between settled states fades on `base` and glides its height (principle 7). Nothing moves on the
+   first render of a region.
 9. **Interruptible.** Toggled state uses CSS transitions (retarget mid-flight), not keyframes. Keyframes only
    for one-shot enter/exit (overlay presence, spinner, skeleton) and one-shot gestures (icons, rule 13;
    a field's error shake, rule 14).
@@ -394,7 +400,7 @@ should stay still, and say so in a CSS comment only when the omission is non-obv
 | selected | `accent-soft` bg + `accent-text`, or check icon in `accent-text` |
 | disabled | `fill-muted`/`field-bg-disabled` bg, `text-disabled` color, no shadow, `cursor: not-allowed` |
 | loading (control) | spinner replaces leading icon, label stays, width does not change, `aria-busy` |
-| loading (region) | `Skeleton` in the data's geometry inside `Crossfade`, `aria-busy` on the region; data already shown stays during a refresh |
+| loading (region) | `Skeleton` in the data's geometry from the first paint, as the `"loading"` state of `Crossfade` (the data replaces it in place, no height glide), `aria-busy` on the region; data already shown stays during a refresh |
 | error | `danger-border` inset ring + `danger-text` message; layout does not shift (support row reserves height when the component asks for it) |
 | empty | centered muted text in `body-s`, optional action; reached through `Crossfade` like every region state |
 

package/dist/skill/reference/layout/page/COMPONENT.md

@@ -292,6 +292,7 @@ A wide cell (`span` 7–11) written next to a narrow one (`span` 4–5) is a pai
 - The edge air comes from the host: `AppShell.Main` sets `--page-gutter` (the page gutter, 16 → 24 → 32) and `--page-top` (24 → 32 from 1024px); `Page.Root` pads itself with them. Outside a host the page brings no air. The page resets both for what it holds, so a page nested in it starts clean.
 - `Page.TopBar` steps out of the gutter to the panel's edges and keeps the gutter inside; padding 12 above (or the top safe-area inset) and below; what follows starts 24 under its controls (header → body; the bar's own 12 counts in). The first line is as high as the Sidebar brand row (control m + 8), so the two read as one line. Groups 16 apart on a line, lines 12 apart; tools 8 apart; buttons 8 apart.
 - `Page.Tools` and `Page.Chips` are the kit's one tool row and chips line (`ToolRow`), the same as the DataTable `toolbar` and `toolbarChips`: the bar only places them. On the first line every tool keeps its natural width; on a line of their own they take the line and lay out from its width (container `prime-tool-row`), never from the window.
+- The tool row lays out the elements it is given, each in a cell: pass the tools as direct children of `Page.Tools` or a fragment. A wrapper component that returns several controls is one cell — no gaps between them, no growing search.
 - In the bar only the heading's column gives (`minmax(0, 1fr)`): the tools and the actions keep their width. The heading keeps its natural width until every button step is taken; then a heading with a path stacks (the path over the title, the title and the description wrapping), so no level is cut to a fragment; a heading without a path truncates its title.
 - The plan is measured, never chosen by breakpoints: the bar lays itself out from its own width.
 - Header (flow) → Body 24; blocks inside Body 24; a `Page.Section` 40 from its neighbours (the body's 24 + 16); tile → tile in a Grid 16 on both axes; section heading → content 16, heading → description 4; flow Title → Description 8; heading → Actions 24 side by side, 16 once they wrap below.

package/dist/skill/reference/layout/sidebar/COMPONENT.md

@@ -70,7 +70,7 @@ Sidebar.Root                       rail wrapper; renders <nav> inside; size tier
 │        ├─ Sidebar.SubTrigger     disclosure row, chevron at the end
 │        └─ Sidebar.SubContent     child Items on a guide line (a flyout on the compact rail)
 └─ Sidebar.Footer                  bottom items, the item Toggle, the account
-   └─ Sidebar.Account              avatar + name + muted line; a Dropdown.Trigger child
+   └─ Sidebar.Account              avatar + name + muted line; a ↕ chevron as a Dropdown.Trigger child
 useSidebar()                       state hook for custom parts inside Root (useAppShellNav outside it, in a shell)
 ```
 
@@ -220,7 +220,7 @@ useSidebar()                       state hook for custom parts inside Root (useA
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `children` (Items), `className` (on the list) and the other div attributes. |
 
 ### Sidebar.Account
-`ref` → `HTMLButtonElement`. The signed-in person at the bottom of `Sidebar.Footer`: avatar, name, a muted line and a ↕ chevron. A button, so it is a `Dropdown.Trigger` child; in compact mode only the avatar stays, with the name as a tooltip.
+`ref` → `HTMLButtonElement`. The signed-in person at the bottom of `Sidebar.Footer`: avatar, name, a muted line; a ↕ chevron only as a `Dropdown.Trigger` child. In compact mode only the avatar stays, with the name as a tooltip.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -311,6 +311,7 @@ Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header,
 | flyout | hover / click / keyboard on a SubTrigger, or on the `…` row of a folded group, in compact mode | the row `aria-haspopup="dialog"`, `aria-expanded`; a Popover `role="dialog"` |
 | attention dot | a coloured `Sidebar.ItemCount` inside a folded Sub (always on the rail) or a folded Group | `Badge.Dot` with `data-attention="shown" \| "hidden"` on the parent row / heading / `…` row |
 | persisted | `persistKey` on Root | the mode and the open state of collapsible groups and sub-lists are read from and written to `localStorage` |
+| account menu | `Sidebar.Account` inside a `Dropdown.Trigger` (`aria-haspopup="menu"`) | the ↕ chevron at the end of the row; without a menu (a plain `onClick`, a `Drawer.Trigger`) no chevron |
 | disabled | `disabled` | Item `disabled` / `aria-disabled`, `data-disabled` |
 
 `persistKey` stores collapsible groups and sub-lists by their `id`, else by their label text — give an `id` when labels are translated or change. The stored state wins over `defaultMode` / `defaultOpen`; controlled `mode` / `open` are not stored, and unavailable storage is ignored. A hidden rail is stored as the mode it left, so a reload never strands a person on a hidden rail.
@@ -388,6 +389,7 @@ Leaving the narrow viewport closes the off-canvas panel; activating an item (a l
 | [collapsible-groups.tsx](examples/collapsible-groups.tsx) | Group headings that fold their items away, one group open at a time, with a chevron at the end of the heading; on the compact rail a folded group becomes one row whose items open in a flyout — `collapsible`, `open`, `onOpenChange`. |
 | [nested-items.tsx](examples/nested-items.tsx) | A parent item with child items on a guide line: a current child opens it and marks the parent; on the compact rail the children open in a flyout — `Sidebar.Sub`, `Sidebar.SubTrigger`, `Sidebar.SubContent`. |
 | [account.tsx](examples/account.tsx) | Footer items and the collapse row above the signed-in person: avatar, name and email open the account menu; collapse the rail from that row and only the avatar stays, on the icon axis — `Sidebar.Footer`, `Sidebar.Account`, `description`, `Sidebar.Toggle`. |
+| [account-profile.tsx](examples/account-profile.tsx) | The signed-in person opens a profile panel, not a menu, so the row draws no chevron — `Sidebar.Account`, `description`. |
 | [router.tsx](examples/router.tsx) | Router links as the brand and the items: the router marks the current link and the item shows it as current; render it inside a router — `asChild`. |
 | [persist.tsx](examples/persist.tsx) | The first visit opens on the icon rail; the mode and the folded groups are remembered and come back after a reload — `persistKey`, `defaultMode`. |
 | [custom-part.tsx](examples/custom-part.tsx) | A part of your own in the footer reads the rail state: the storage meter shows on the full rail and in the off-canvas panel and steps aside on the icon rail — `useSidebar`. |

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.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

@@ -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