prime-ui-kit 0.14.0 → 0.16.0

package/dist/skill/foundations.md

@@ -1,6 +1,6 @@
 # Foundations — do it this way
 
-Condensed from the kit's design contract (`docs/foundation.md` in the kit repository). Use semantic
+Condensed from the kit's design contract, [foundation.md](reference/foundation.md). Use semantic
 tokens `--prime-*` only.
 
 ## 1. 4px grid
@@ -29,7 +29,7 @@ Things that belong together sit closer than things that do not.
 |---|---|---|
 | label → field | 4–8 | built into fields (`label` prop) — do not add |
 | field → hint/error | 4 | built into fields — do not add |
-| a hand-built field (your own control + `Label.Root` + `Hint.Root`) | label 4–8, hint 4 | `--prime-control-<size>-label-gap`, `--prime-control-<size>-hint-gap` |
+| a hand-built field (your own control + `Label.Root` + `Hint.Root`) | label 4–8, hint 4 | [the recipe](api-contract.md#your-own-control-without-a-frame) |
 | group heading → its fields | 16 | `--prime-space-4` |
 | field → field in a form | 20 | `--prime-space-5` |
 | inline controls in a row (buttons, filters) | 8 | `--prime-space-2` |
@@ -69,12 +69,19 @@ gutters — do not add your own outer padding.
   nest components, never set backgrounds yourself.
 - Separate blocks by fill and air. Hairlines (`Divider`) only inside a block: list rows, table rows,
   between a form and its footer.
-- A card inside a card becomes the next layer automatically — use it sparingly; usually a section
-  heading inside one card is better. The ladder stops at layer 4.
-- Your own bounded block is a `Card` (it takes the right layer wherever it lands). A plain tile with
-  no controls inside may use `background: var(--prime-color-layer-nested)` and
-  `border-radius: var(--prime-card-radius)`; never a transparent box with a border, never a
-  hard-coded `--prime-color-layer-2-bg`.
+
+### Card in a card
+
+Allowed — a card inside a card becomes the next layer by itself — but avoided by default: a section
+heading inside one card usually reads better. Never a card around a `DataTable` (it already is a
+filled block), a single field or a whole page. The ladder stops at layer 4.
+
+### Your own bounded block
+
+A `Card` (it takes the right layer wherever it lands). The one background you may set yourself: a
+plain tile with no controls inside on `background: var(--prime-color-layer-nested)` with
+`border-radius: var(--prime-card-radius)`. Never a transparent box with a border, never a
+hard-coded `--prime-color-layer-<n>-*`.
 
 ## 5. Nested radius
 
@@ -87,8 +94,10 @@ Inner radius = outer radius − padding. Panel 12 with padding 4 → items 8. Us
 - `color` is decoration from the palette: `gray · blue · green · orange · red · yellow · purple · sky ·
   pink · teal` — Badge, Avatar, Thumbnail, SegmentedControl dots, count badges of Tabs,
   SegmentedControl, Sidebar and BottomNav, FileUpload format badges, Timeline dots, TagSelect tags,
-  Kanban column counts, Gantt bars, the author hue of a chat (`Message.Author`). Use one hue per meaning
-  across the product (e.g. «Оплачен» is always green): keep one `Record<Status, PaletteColor>` map.
+  Kanban column counts, Gantt bars, the author hue of a chat (`Message.Author`). A category keeps one
+  hue across the product: keep one `Record<Category, PaletteColor>` map.
+- A status wears a `tone` (a Badge `tone`: «Оплачен» is `success` everywhere), never a palette hue;
+  keep one status → tone map.
 - Never convey meaning by color alone: a status badge has text.
 
 ### Charts and categorical colors
@@ -109,8 +118,8 @@ A chart color does one job, and the job picks the colors:
   `green` → `chart-6`, `purple` → `chart-7`, `red` → `chart-8`, `gray` → `chart-other`), so a
   ProgressBar share and a line in a chart library match. `sky` has no chart step (it sits too close to
   blue).
-- The palette is validated in both themes (OKLCH lightness band, chroma, colour-blind and
-  normal-vision separation of neighbours, ≥ 3:1 on the layer grounds). In scatter-like charts, where
+- The tokens and their contrast guarantee are in
+  [foundation.md → Chart palette](reference/foundation.md#chart-palette). In scatter-like charts, where
   any two marks can meet, keep to the first three series or facet.
 - A chart library takes the colors as strings: `chartColors.series[i]`, `chartColors.grid`,
   `chartColors.axis`, `chartColors.scale[i]` (each a `var(--prime-color-chart-*)`, so the theme
@@ -137,7 +146,7 @@ A chart color does one job, and the job picks the colors:
 | `title-m` | 16/24 600 | page section heading (`PageContent.Section` draws it), modal title |
 | `title-l` | 18/24 600 | large block title |
 | `heading-s` | 20/28 600 | page sub-heading |
-| `heading-m` | 24/32 600 | page title (`PageContent.Title`) |
+| `heading-m` | 24/32 600 | the title of a document page (`PageContent.Title`); an app page titles itself in `AppHeader.Title` (`title-s`) |
 | `heading-l` | 30/36 600 | marketing / auth title |
 | `display-*` | 36–60 | hero numbers only |
 | `code` | 13/20 mono | identifiers, inline code |
@@ -145,8 +154,13 @@ A chart color does one job, and the job picks the colors:
 `variant` is required on `Typography`. Weights only 400/500/600. Numbers in tables, prices, dates:
 tabular (the kit does it in DataTable `numeric` columns and `Card.Value`; your own amounts take
 `font-variant-numeric: tabular-nums`). Reading text max width `--prime-layout-reading-max-width`
-(`PageContent.Root maxWidth="readable"`). Secondary text uses `tone="secondary"`/`"muted"` on
-`Typography`, not a lighter custom color.
+(`PageContent.Root maxWidth="readable"`).
+
+### Text colour
+
+Text takes its colour from `Typography tone` (`secondary`, `muted`, `accent`, `success`, `warning`,
+`danger`) or from the kit part it sits in — never `color` in your CSS. A `--prime-color-*` token in
+your CSS colours only what is not text: a fill, a tile, a line.
 
 ## 8. Hierarchy through air
 
@@ -156,17 +170,10 @@ level of air: a page with uniform 16px gaps everywhere reads as a list of unrela
 ## 9. Responsive
 
 - Flexbox for rows/stacks, Grid for two-dimensional layouts; spacing via `gap`.
-- Must work from 320px and at 400% zoom; the full rules are in [responsive.md](responsive.md).
-- Viewport breakpoints 640 · 768 · 1024 · 1280 (`max-width: 639px` for "below 640"), only for the app
-  frame. Components adapt to their own container — do not re-implement that.
-- Touch follows input, not width: your `:hover` styles only inside `@media (hover: hover)`; nothing is
-  hover-only; the kit keeps field text at 16px and gives small controls a 44px hit area on coarse
-  pointers — do not wrap kit fields to change that.
+- Every screen works from 320px and at 400% zoom: [responsive.md](responsive.md) holds the rules —
+  the [breakpoints and their scope](responsive.md#breakpoints), the
+  [intrinsic grids](responsive.md#intrinsic-grids), what the kit adapts by itself and touch.
 - Flex children with text: `min-width: 0` + ellipsis or `overflow-wrap: anywhere`.
-- Wide tables on phones: they scroll inside themselves with edge shadows; `stickyFirstColumn`, a column
-  chooser through `hiddenColumns`; never let the page scroll sideways.
-- Card grids on a page: `PageContent.Grid` + `PageContent.Cell span` (folds by its own width); inside one block: `repeat(auto-fill, minmax(min(100%, …), 1fr))`.
-- A page panel with sections, filter and search, view and the primary action is `PageToolbar`.
 - Sticky parts come from the kit: `AppHeader` (with the `PageToolbar` in `AppHeader.Tools`), the
   DataTable head and `stickyFirstColumn`, the Gantt header and first column — each sticks inside its
   own scroller, and the top ones let go on screens lower than 480px. Never a `position: sticky` bar of your own.

package/dist/skill/layouts.md

@@ -1,39 +1,46 @@
 # Layouts — app frame, page wrappers, auth
 
-Every screen sits in one frame: `AppShell.Root` with Nav / `AppHeader` / Main (the content panel is the page,
-the nav rail one layer above it) → `PageContent` (header + body). `AppShell.Main` carries the page gutters
-and `PageContent` spaces the page — blocks 24, a titled `PageContent.Section` 40, tiles in a
-`PageContent.Grid` 16 on both axes — so your code adds **no outer padding and no margins**. Your CSS only lays out the inside of a block (grids, rows) with `gap` on `--prime-space-*`.
-Main's top space under the header is part of the frame — 24, then 32 from 1024px: a page header starts
-there; never cancel it with a negative margin or a padding override.
-
-The page recipes are whole, working screens in [patterns/](patterns/) — start from the closest one
-([the list](composition.md#patterns)) and keep its skeleton. The rules behind them are in [composition.md](composition.md).
+Every screen sits in one frame: `AppShell.Root` with the Sidebar in `AppShell.Nav`, a header row and
+`AppShell.Main` (the content panel is the page, the nav rail one layer above it). The frame is the
+app's; the header row and the body are the page's — a screen renders its own `AppHeader.Root` (the
+page title and the page's tools, [composition.md](composition.md#1-page-skeleton)) and its body in
+`PageContent`.
+`AppShell.Main` carries the page gutters and `PageContent` spaces the page — blocks 24, a titled
+`PageContent.Section` 40, tiles in a `PageContent.Grid` 16 on both axes — so your code adds **no outer padding and no margins**. Your CSS only lays out the inside of a block (grids, rows) with `gap` on `--prime-space-*`.
+Main's top air under the header is part of the frame — 24, then 32 from 1024px: the page's first block
+starts there; never cancel it with a negative margin or a padding override.
+
+The page recipes are whole, working screens — the `screen.tsx` example of their main component
+([the list](composition.md#screens)): start from the closest one and keep its skeleton. The rules behind them are in [composition.md](composition.md).
 
 ## App frame (once per app)
 
-Every `Sidebar.Item` gets a `Sidebar.ItemIcon` (in compact mode only icons remain) and is a link:
-`href`, or `asChild` with the router's `NavLink`; `current` marks the current page (`aria-current`), a
-router link sets it itself. Counters go in `Sidebar.ItemCount`. Below 768px the Sidebar becomes an
-off-canvas panel — the app must render a menu button that opens it, otherwise navigation is unreachable
-on phones. `AppHeader` is the top bar of the panel on every width: `AppHeader.MenuButton` shows itself
-below 768px (the Sidebar's own breakpoint), the title says where you are, `AppHeader.Search` opens the
-CommandMenu and folds into an icon on a narrow header. Its row is as high as the Sidebar brand row, so
-the brand and the title read as one line.
+The frame is the root layout and nothing else: the providers, `AppShell.Root`, the Sidebar in
+`AppShell.Nav` and `AppShell.Main` around the page. It holds no header content and no menu state:
+
+- **The header row belongs to the page.** An `AppHeader.Root` anywhere inside the shell — the page's
+  own one, rendered at the top of its body — shows in the shell's header row; the latest one on
+  screen wins, so every page brings its own. Its row is as high as the Sidebar brand row, so the brand
+  and the title read as one line. Nothing app-wide goes into it — no global search, no notifications.
+- **The phone menu comes with the frame.** Below 768px the Sidebar becomes an off-canvas panel
+  (`offCanvas="auto"`) and the AppHeader leads with the menu button that opens it by itself — never a
+  menu state or a menu button wired by hand. A trigger outside the rail (a BottomNav «Ещё», your own
+  button) reads the shell's navigation with `useAppShellNav()` (`open`, `setOpen`, `navId`; see
+  [the app frame screen](reference/layout/app-shell/examples/screen.tsx)).
+- **Every Sidebar item is a link** (`href`, or `asChild` with the router's `NavLink`); `current`
+  marks the current page (`aria-current`), a router link sets it itself. Icons and counts follow the
+  [navigation structure](#navigation-structure-the-sidebars-content).
 
 ```tsx
-import { AppHeader, AppShell, Icon, NotificationProvider, Sidebar } from "prime-ui-kit";
-import { type ReactNode, useState } from "react";
-
-type AppLayoutProps = { title: string; onSearch: () => void; children: ReactNode };
+import { AppShell, Icon, NotificationProvider, Sidebar } from "prime-ui-kit";
+import type { ReactNode } from "react";
 
-export function AppLayout({ title, onSearch, children }: AppLayoutProps) {
-  const [menuOpen, setMenuOpen] = useState(false);
+export function AppFrame({ children }: { children: ReactNode }) {
   return (
     <NotificationProvider>
       <AppShell.Root fillViewport>
         <AppShell.Nav>
-          <Sidebar.Root open={menuOpen} onOpenChange={setMenuOpen}>
+          <Sidebar.Root>
             <Sidebar.Header>
               <Sidebar.Brand href="/" description="Интернет-магазин">
                 <Sidebar.BrandLogo>
@@ -44,7 +51,7 @@ export function AppLayout({ title, onSearch, children }: AppLayoutProps) {
               <Sidebar.Toggle variant="header" />
             </Sidebar.Header>
             <Sidebar.Content>
-              <Sidebar.Group label="Продажи">
+              <Sidebar.Group>
                 <Sidebar.Item href="/" current>
                   <Sidebar.ItemIcon>
                     <Icon name="nav.dashboard" />
@@ -76,14 +83,6 @@ export function AppLayout({ title, onSearch, children }: AppLayoutProps) {
             </Sidebar.Footer>
           </Sidebar.Root>
         </AppShell.Nav>
-        <AppHeader.Root>
-          <AppHeader.Start>
-            <AppHeader.MenuButton aria-expanded={menuOpen} onClick={() => setMenuOpen(true)} />
-            <AppHeader.Title>{title}</AppHeader.Title>
-          </AppHeader.Start>
-          {/* Opens the app's CommandMenu; bind ⌘K to the same handler. */}
-          <AppHeader.Search onClick={onSearch}>Поиск заказов и клиентов</AppHeader.Search>
-        </AppHeader.Root>
         <AppShell.Main>{children}</AppShell.Main>
       </AppShell.Root>
     </NotificationProvider>
@@ -91,31 +90,60 @@ export function AppLayout({ title, onSearch, children }: AppLayoutProps) {
 }
 ```
 
+Every page renders its header and its body; the header shows in the frame's header row:
+
+```tsx
+import { AppHeader, PageContent } from "prime-ui-kit";
+
+export function OrdersPage() {
+  return (
+    <>
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <AppHeader.Title>
+            Заказы
+            <AppHeader.Description>128 в работе · 6 ждут оплаты</AppHeader.Description>
+          </AppHeader.Title>
+        </AppHeader.Start>
+      </AppHeader.Root>
+      <PageContent.Root as="section">
+        <PageContent.Body>{/* the page's blocks */}</PageContent.Body>
+      </PageContent.Root>
+    </>
+  );
+}
+```
+
+A document page (settings, a long form, help) renders an `AppHeader.Root` without a title — only
+its own buttons, and on a phone the menu button the header draws — and opens its body with
+`PageContent.Header`.
+
+With React Router the frame's `children` is `<Outlet />` and every item is `Sidebar.Item asChild`
+around a `NavLink` ([the router example](reference/layout/sidebar/examples/router.tsx)). The same frame
+as one component is `AppShell.Template` (`nav`, `footer`, the page as children); give it the
+pathname as `scrollResetKey`, so a new page opens at the top.
+
 Phone navigation for 2–6 main sections is a `BottomNav.Root` in `AppShell.Footer` (the last child of
 `AppShell.Root`, or the Template `footer` prop) — never in Main, never `position: fixed`, never behind
 your own media query. The shell hides the footer while the Sidebar rail is on screen and shows it
 while the Sidebar is off-canvas, so the bar and the rail never appear together.
 
 Next.js App Router: the package is marked `"use client"`, but a server component cannot dot into it
-(`<Button.Root>`) or pass it callbacks. Put `AppLayout` and every screen in a file that starts with
+(`<Button.Root>`) or pass it callbacks. Put the frame and every screen in a file that starts with
 `"use client"` and render them from `app/layout.tsx` and the pages; import `bundle.css` in the root
 layout and put `data-theme` on `<html>` there.
 
-A nested record page keeps its `Breadcrumb` at the top of `PageContent.Header`, above the title
-([patterns/detail-page.tsx](patterns/detail-page.tsx)) — not in `AppHeader`. `AppHeader.Actions` holds at most notifications, the account and one primary action; page
-actions stay in `PageContent.Actions`. With `offCanvas="always"` pass `show="always"` to the menu button.
+A nested record page puts the path up before its title in the header — `Breadcrumb` (the list it
+belongs to), `AppHeader.Separator`, `AppHeader.Title` with the record's name and its status as
+the description ([the detail page](reference/components/description-list/examples/screen.tsx)).
 
-### The page title in the header
+### The page's tools in the header
 
-A page that wants all its height for the work (a board, a chat, a dense register) may drop the
-heading row in main and let the header carry the page — one or the other, never both:
-
-- `AppHeader.Title as="h1"` is the page's only `<h1>` (the description stays outside its name);
-  main then has no `PageContent.Header`.
-- The page's tools — sections, the period, filters, the page's primary action — go into
-  `AppHeader.Tools` as a `PageToolbar.Root`: the header's second row, full width, sticky with it. The
-  toolbar lays itself out from that width (one row when wide, two on a phone), so the tools wrap
-  under the title instead of squeezing it. `AppHeader.Actions` keeps notifications and the account.
+The page's tools — its own search and filters, sections, the period or view, the primary action —
+go into `AppHeader.Tools` as a `PageToolbar.Root`: the header's second row, full width, sticky with
+it. The toolbar lays itself out from that width ([the page panel](responsive.md#page-panel--pagetoolbar)),
+so the tools wrap under the title instead of squeezing it. `AppHeader.Actions` keeps the page's
+other buttons (export, a more menu) in the title row.
 
 ```tsx
 import { AppHeader, Button, Icon, PageToolbar, SegmentedControl } from "prime-ui-kit";
@@ -126,7 +154,10 @@ export function DealsHeader({ view, onViewChange }: DealsHeaderProps) {
   return (
     <AppHeader.Root>
       <AppHeader.Start>
-        <AppHeader.Title as="h1">Сделки</AppHeader.Title>
+        <AppHeader.Title>
+          Сделки
+          <AppHeader.Description>7 сделок в работе · 6 461 750 ₽</AppHeader.Description>
+        </AppHeader.Title>
       </AppHeader.Start>
       <AppHeader.Tools>
         <PageToolbar.Root aria-label="Сделки">
@@ -156,49 +187,49 @@ export function DealsHeader({ view, onViewChange }: DealsHeaderProps) {
 }
 ```
 
-With React Router put `<Outlet />` as the child and pass `NavLink` through `Sidebar.Item asChild`
-(see `src/layout/sidebar/examples/router.tsx`).
-
 ## Navigation structure (the sidebar's content)
 
 The sidebar is the product's map: people scan it, remember where things are and come back. Build it
-from what people do, not from how the backend is split. The full guide with the reasoning is in
+from what people do, not from how the backend is split. The criteria — how many items, what folds,
+when a count gets a colour — are in
 [Sidebar COMPONENT.md → Building the navigation](reference/layout/sidebar/COMPONENT.md#building-the-navigation).
 
-| Level | Kit part | Rule |
-|---|---|---|
-| Everyday places | `Sidebar.Group` without `label` at the top | 2–4 items (Обзор, Входящие); never folded |
-| Category of work | `Sidebar.Group label collapsible` | 3–7 items by frequency; label is one short word with a distinct start (the rail shows its first letters); fold only long or rarely used groups |
-| Views of one section | `Sidebar.Sub` | 2–6 children; the parent only discloses (overview page = first child); one level only |
-| Meta | `Sidebar.Footer` | help, settings, then `Sidebar.Account` with its menu last |
+| Level | Kit part |
+|---|---|
+| Everyday places | `Sidebar.Group` without `label` at the top, never folded |
+| Category of work | `Sidebar.Group label collapsible` |
+| Views of one section | `Sidebar.Sub`, one level only |
+| Meta | `Sidebar.Footer`: help, settings, then `Sidebar.Account` with its menu last |
+
+### Sidebar icons
 
-- Icons on every top-level item and sub-list parent, distinct shapes; none on sub-list children.
-- `Sidebar.ItemCount` plain for information (12 new); `color` only when it asks for action (3
-  unanswered, 2 overdue) — it becomes a dot on the rail and on every folded parent, so keep it rare:
-  red for blocked or overdue, blue for new or unread.
-- `persistKey` on `Sidebar.Root` keeps the rail mode and folded groups across reloads; give groups an
-  `id` when labels are translated.
+An icon on every top-level item and every sub-list parent, each a distinct shape (the compact rail
+shows only icons); none on the children of a sub-list.
 
 ## Page wrapper
 
-- App pages with actions (dashboard, list, detail): `PageContent.Page` — the full width of the panel.
-- Settings and long forms: `PageContent.Root maxWidth="wide"` with a `PageContent.Section layout="aside"`
-  (heading column + panel) per section ([patterns/settings-page.tsx](patterns/settings-page.tsx)), or `maxWidth="readable"` for a single
+- App pages (dashboard, list, detail, a board): `PageContent.Root as="section"` — the full width of
+  the panel; the page's title and tools are in its `AppHeader`, its blocks go into
+  `PageContent.Body` ([the page skeleton](composition.md#1-page-skeleton)).
+- Document pages — settings and long forms: `PageContent.Root maxWidth="wide"` with `PageContent.Header`
+  (the page's h1) and a `PageContent.Section layout="aside"`
+  (heading column + panel) per section ([the settings page](reference/components/page-content/examples/screen.tsx)), or `maxWidth="readable"` for a single
   narrow column of fields.
-- Long reading text (terms, help): `PageContent.Root maxWidth="readable"`.
+- Long reading text (terms, help): `PageContent.Root maxWidth="readable"` with `PageContent.Header`.
 - A page as high as the panel (a log, a board, a chat): `AppShell.Root fillViewport` +
   `PageContent.Root fill`; the body passes its free height to a filling child — DataTable
   `scrollHeight="fill"`, Crossfade `fill`, `PageContent.Split`. Never compute heights from `100vh`.
-- List + detail (mail, a messenger, a ticket queue): `PageContent.Split` with `PageContent.List` and
-  `PageContent.Detail` in a filling page. Side by side from 48rem of the split's own width, one pane
+- List + detail (mail, a messenger, a ticket queue): `PageContent.Split` with `PageContent.Panel kind="list"` and
+  `PageContent.Panel kind="detail"` in a filling page. Side by side from 48rem of the split's own width, one pane
   at a time below it with `PageContent.BackButton` first in the detail's header; `open` is «a record
   is chosen». Each pane gives its last child the free height: a Card with its own `ScrollContainer`
   (`anchor="end"` for a thread). The records in the list pane are a `List` (`current` on the open
-  one). Details that open over a table and close again are a Drawer instead.
+  one), the conversations of a messenger a `ChatList`. Details that open over a table and close
+  again are a Drawer instead.
 
-## Which pattern to start from
+## Which screen to start from
 
-The table of screens and their patterns lives in [composition.md](composition.md#patterns).
+The table of screens lives in [composition.md](composition.md#screens).
 
 A short form (≤ 4 fields: rename, invite, confirm with a reason) belongs in a `Modal` with the same
 form rules: `Modal.Body` holds the `<form id>`, `Modal.Footer` holds Cancel + submit with `form={id}`

package/dist/skill/motion.md

@@ -5,8 +5,8 @@ the kit's author would make it move: every state change is continuous, every pre
 flips — and nothing moves without a reason. Most of it is already inside the components; your job is
 to use them so it can happen, and to add motion only where the kit leaves the choice to you.
 
-The full design contract lives in the kit repository (`docs/foundation.md`, «Motion»); this file is how
-to apply it on a screen and is enough on its own.
+The full design contract is [foundation.md → Motion and micro-animation](reference/foundation.md#motion-and-micro-animation);
+this file is how to apply it on a screen.
 
 ## 1. What the kit already animates — do not rebuild it
 
@@ -23,8 +23,8 @@ Use the component and the motion comes with it. Never re-animate these with your
 | Check / uncheck | the check draws in with a stroke, leaves fast | `Checkbox`, `Checkbox.Indicator`, `ColorSwatches` |
 | Toggle | the thumb slides | `Switch` |
 | One of a few | the indicator glides to the choice | `SegmentedControl`, `Tabs` |
-| Disclosure | height through `grid-template-rows`, the chevron turns | `Accordion` |
-| A chat message changes size (a reaction comes or goes, a transcript opens, an edit, an upload state) | one stroke: the new layout is there at once and the bubble's box glides from the old size to the new one — width and height together, its parts gliding, fading in or out where they stand on the same clock (`--prime-message-morph-duration`); the time and the tail stay, and nothing travels across text (the time dips while text passes through its place, and cross-fades when it changes line): a reaction grows the message upward, the chat scrolling by the change while the rows above glide as one block (the rows below never move); a transcript grows it downward under a still player | `Message.Root` (built in) |
+| A part that folds open or closed | it opens on the enter clock and closes faster, the content fading as the height glides; the chevron turns | `Accordion`, `Sidebar.Group collapsible`, `Sidebar.Sub`, DataTable expanded rows |
+| A chat message changes size (a reaction, a transcript, an edit, an upload state) | one stroke: the bubble glides to its new size with its parts, the time and the tail still ([Message → States](reference/components/message/COMPONENT.md#states)) | `Message.Root` (built in) |
 | A counter or a count | digits roll like an odometer | `Badge` with a number child, the `counter` of `Input` / `Textarea` |
 | A field with an error | the control shakes once, sharply, when the error arrives or changes; the label stays, the message drops in | `error` (or `invalid`) on any field, `Checkbox.Root`, `Switch.Root`, `Radio.Group` — not for an error the field mounts with |
 | Password strength | stepped bar fills cell by cell, the level word flows in | `Input.Root strength` |
@@ -36,11 +36,11 @@ Use the component and the motion comes with it. Never re-animate these with your
 | Tooltips along a toolbar | the first waits, the next ones show at once | `Tooltip` (shared warm window) |
 | Toast stack | depth stack, expands on hover | `NotificationProvider` + `useNotifications` |
 | Loading → data → empty → error | the region cross-fades and glides its height; loading is a skeleton of the data | `Crossfade` around the region, `Skeleton` in the data's geometry |
-| Drag | the carried piece lifts, its neighbours glide apart, the drop glides into place; while its save runs the piece quiets under a spinner, and a refused save glides it back — across columns too | `Dnd`, `Kanban` cards and columns, DataTable `onReorder`, `FileUpload` tiles |
+| Drag | the carried piece lifts, its neighbours glide apart, the drop glides into place; while its save runs the piece stays still and its grip turns busy, and a refused save glides it back — across columns too | `Dnd`, `Kanban` cards and columns, DataTable and `List` `onReorder`, `FileUpload` tiles |
 | A setting saved on the server | the thumb moves at once and a spinner turns inside it (a slider thumb dims); a refused save glides it back | `Switch` (`onCheckedChange` returns a Promise, or `loading`), `Slider` (`onCommit`) |
 | A chip or a file row removed | it waits dimmed with a spinner on its ×; once gone it fades and closes up, the next ones glide into its place; refused, it stays | `Badge` `onRemove`, `FileUpload` `onValueChange`, TagSelect chips |
 | A schedule bar moved, stretched or drawn | the bar lifts and steps by whole days under the pointer with a dates tooltip; a drawn bar is a ghost that turns into a pulsing Skeleton while `onBarCreate` runs; a refused change glides back, a refused bar fades out; the zoom cross-fades around the day in the middle | `Gantt` (`onBarChange`, `onBarCreate`, `scale`) |
-| Messages | a message new at the end enters by itself — mine and theirs alike float up a little from below and fade in (`fast`), while the list is only pushed by layout and stays pinned to the end; nothing else moves, and nothing is ever moved by a transform computed from page geometry; the first render, history loaded above, rows the list renders as they scroll into view and a status change never move; «печатает…» is an incoming bubble of three dots rising in turn on the loading loop, opening its height as it comes and closing it as it goes — or gone at once when the reply takes its place; a jumped-to message (a reply, a search result, a pinned one) comes to the middle of the chat's own scroller and stays at full strength while the others step back and forth three times (opacity only, `base` each; a search keeps them back while the match is current) — nothing is drawn on it; the «к последним» button rises in while the reader is away from the end; delivery ticks cross-fade into the next status; a reaction new on the message fades and scales in from 0.9 once (never on the first render or a history load); a new chip takes its room at once and fades and scales in, a removed one fades out where it stood while the chips after it glide into its place; the first and the last reaction open and close the row as the message's one stroke, the message growing upward with the time and the tail still and the rows above gliding as one block; a count change rolls its digits only; the reaction bar grows from the bubble, its emoji pop in one after another, the picked one pops while the bar leaves on the same clock it opened with; in selection mode the checks enter at the start of the rows and the unselected messages step back (opacity and a slight desaturation, `fast`) while the selected stay as they are; a transcript opens and closes as one stroke, the player row still and the text fading over the whole stroke as the box opens or closes over it; the transcript button's glyph cross-fades into a chevron | `Chat` (`selected`, `search`, `typing`, `current`, `Chat.Pinned`), `Message` (`onReactionToggle`, `Message.Typing`, `Message.Reply target`) |
+| Messages | a message new at the end floats up a little and fades in; the first render, history loaded above and rows scrolled into view never move; a jumped-to message stays bright while the others step back; «печатает…», reactions, selection and the ticks move by themselves ([Chat → States](reference/components/chat/COMPONENT.md#states), [Message → States](reference/components/message/COMPONENT.md#states)) | `Chat` (`selected`, `search`, `typing`, `jumpTo`, `Chat.Pinned`), `Message` (`onReactionToggle`, `Message.Typing`, `Message.Reply target`) |
 | Writing a message | the send glyph turns into place as text appears; the reply / edit bar enters; a paused recording stills its dot into a pause glyph and freezes the timer and the waveform; the recording bar cross-fades over the field inside the row's height, the hint slides and fades with the finger, the dot breathes and the live waveform follows the voice; the formatting toolbar fades in over a selection | `Composer` |
 | Playing a voice message | the waveform fills as it plays and is the seek slider; play and pause cross-fade; the speed label flows into the next rate | `VoicePlayer` |
 | A rare milestone | a short confetti burst | `celebrate({ origin })` |
@@ -66,24 +66,18 @@ under it. Easing starts when the hand lets go.
 
 ## 3. Tokens — the only durations and curves
 
-| Token | Value | Use |
-|---|---|---|
-| `--prime-motion-duration-xfast` | 150 ms | hover fill on dense rows |
-| `--prime-motion-duration-fast` | 230 ms | press, hover, small panels (in and out), the exit of a dialog |
-| `--prime-motion-duration-base` | 380 ms | dialogs, toggles, content swaps, things gliding into place |
-| `--prime-motion-duration-slow` | 570 ms | drawers, sheets, long fills |
-| `--prime-motion-easing-enter` | strong ease-out | appearing, responding |
-| `--prime-motion-easing-exit` | strong ease-out | leaving (with a shorter duration than enter) |
-| `--prime-motion-easing-standard` | ease-in-out | moving on screen, color and fill |
-| `--prime-motion-easing-emphasized` | decisive start, soft landing | a thumb, an indicator, a check gliding into place |
-| `--prime-motion-stagger` | 80 ms | step of a staggered first render |
-| `--prime-motion-loop` | 570 ms | period unit of a loading loop (Spinner); kept under reduced motion |
-| `--prime-motion-blur` | 2 px | hiding a change of shape while two states swap |
-| `--prime-motion-press-scale` / `-compact` | 0.98 / 0.96 | `:active` scale |
-
-Under `prefers-reduced-motion` the durations and stagger go to 0 and the press scale to 1 globally —
-token-based CSS honours it for free. `--prime-motion-loop` stays: a loading loop is information and
-keeps running, slower. Anything you drive from JS checks the media query itself.
+Every duration, curve and scale is a `--prime-motion-*` token; the table with values and uses is
+[foundation.md → Motion and micro-animation](reference/foundation.md#motion-and-micro-animation). In
+short: movement runs on `--prime-motion-duration-xfast · fast · base · slow` with the `enter`, `exit`,
+`standard` or `emphasized` easing; opacity and color changes run on the
+`--prime-motion-fade-xfast · fast · base · slow` group; sizes you start from or pass through come
+from the `--prime-motion-scale-*` ladder.
+
+Under `prefers-reduced-motion` the movement durations and stagger go to 0 and the press scale to 1
+globally — token-based CSS honours it for free. Fades stay: a transition on the
+`--prime-motion-fade-*` group still eases a state in instead of flipping it, and a loading loop
+(`--prime-motion-loop`) keeps running, slower. Anything you drive from JS checks the media query
+itself.
 
 ## 4. Rules for your own motion
 
@@ -95,8 +89,9 @@ keeps running, slower. Anything you drive from JS checks the media query itself.
 - Never from nothing: appear from `opacity: 0` plus a small offset (`--prime-space-1`/`-2`) or
   `scale(0.96)`, never `scale(0)`.
 - State moves, it does not swap: a selection travels, a check draws, a counter rolls, two contents
-  cross-fade. A toggled state uses transitions (they retarget mid-flight); keyframes only for one-shot
-  appearance.
+  cross-fade. Foundation §7 rule 9: «Toggled state uses CSS transitions (retarget mid-flight), not
+  keyframes. Keyframes only for one-shot enter/exit … and one-shot gestures»; rule 3: «Durations and
+  easings come from `--prime-motion-*`; never a raw `ms` or `cubic-bezier`».
 - Hover movement only inside `@media (hover: hover)`; nothing is hover-only.
 - Stagger only the first render of a short group (≤ 6 items) and never block interaction with it.
 - A gesture clock (a hold, a countdown) is information, not motion: it keeps running under reduced
@@ -129,10 +124,8 @@ export function ExportButton({ progress, ready }: { progress?: number; ready: bo
 **Save → saved.** `loading` while the request runs, then change the label; the kit morphs it. Return
 to the idle label after about two seconds.
 
-**Delete without a dialog.** One destructive action that is not a row in a list and is easy to redo
-by hand (clear a draft, revoke a token) → `holdToConfirm` instead of a confirm dialog. A row in a list →
-the undo recipe below. Irreversible loss of work → a `ConfirmDialog`. (The rule:
-[choosing.md](choosing.md), «ConfirmDialog / Modal / `holdToConfirm` / undo».)
+**Delete without a dialog.** When [friction](ux.md#5-friction-matches-the-cost-of-a-mistake) asks for
+a held press, `holdToConfirm` with the action in `onConfirm`:
 
 ```tsx
 import { Button, Icon } from "prime-ui-kit";
@@ -165,7 +158,9 @@ hint that states the rule in words.
 **Removing a row with undo.** Remove the row from the data, show a notification with an «Отменить»
 action, put the row back on undo — undo beats a confirm dialog for reversible deletes. When the delete
 reaches the server only after the chance to undo has passed, send it from the notification's
-`onDismiss`.
+`onDismiss(reason)`: every reason but `"action"` (the toast timed out, was closed, swiped or pushed
+out of the stack) means the person let it go; the «Отменить» action closes its toast by itself with
+`"action"` ([the undo example](reference/components/notification/examples/undo.tsx)).
 
 **A rare achievement.** Say it in words (a `Banner`, the progress label turning success), then call
 `celebrate({ origin: element })` once. Only for something that happens rarely — a quarter closed, the

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

@@ -26,10 +26,10 @@ import { Accordion } from "prime-ui-kit";
 ```
 Accordion.Root                frame (grouped) or column of cards (separate)
 └─ Accordion.Item             one section; data-state open / closed
-   ├─ Accordion.Header        <h3> around the trigger
+   ├─ Accordion.Header        heading around the trigger (<h3>, or the level of `as`)
    │  └─ Accordion.Trigger    <button>: children, then the chevron (Icon nav.chevronDown)
    │     └─ Accordion.Icon    optional leading icon
-   └─ Accordion.Content       <section> region; clip <div> → padded body <div>
+   └─ Accordion.Content       <section> region (the kit fold); clip <div> → padded body <div>
 ```
 
 ## API
@@ -46,7 +46,7 @@ Accordion.Root                frame (grouped) or column of cards (separate)
 | `defaultValue` | `string \| string[]` | — | Initially open item(s) (uncontrolled). |
 | `onValueChange` | `(value: string) => void \| (value: string[]) => void` | — | Called with the new open item, or the new list with `multiple`. |
 | `collapsible` | `boolean` | `true` | Without `multiple`: `false` keeps the open item open on a second click. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of trigger height, text, icon and padding. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of trigger height, text, icon and padding. Without it the tier of its host, else `m`. |
 | `layout` | `"grouped" \| "separate"` | `"grouped"` | `grouped` — one surface with hairlines between items; `separate` — every item is its own card. |
 | `children` | `ReactNode` | — | `Accordion.Item`s. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange">` | — | `className` and the other div attributes. |
@@ -61,10 +61,11 @@ Accordion.Root                frame (grouped) or column of cards (separate)
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
 
 ### Accordion.Header
-`ref` → `HTMLHeadingElement`. The `<h3>` around the trigger.
+`ref` → `HTMLHeadingElement`. The heading around the trigger (`<h3>` unless `as` says otherwise).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `as` | `"h2" \| "h3" \| "h4" \| "h5" \| "h6"` | `"h3"` | Heading level in the page outline: one below the heading of the section that holds the accordion. |
 | `…rest` | `HTMLAttributes<HTMLHeadingElement>` | — | `className` and the other heading attributes. |
 
 ### Accordion.Trigger
@@ -125,24 +126,29 @@ Accordion.Root                frame (grouped) or column of cards (separate)
 | hover / active | pointer | trigger `fill-muted-hover` (two ladder steps off the accordion's layer, so it never lands on the host's color at the edges) / `fill-strong` |
 | focus-visible | keyboard | inset focus ring inside the trigger |
 
-Root: `data-size`, `data-layout`. The panel height transitions through `grid-template-rows: 0fr → 1fr` (no JS measuring, follows content that resizes while open) and the body fades in while settling by `--prime-space-1`; open uses `base` + `enter`, close `fast` + `exit`. The chevron rotates over `base`. Instant under `prefers-reduced-motion`.
+Root: `data-size`, `data-layout`. The panel is the kit fold (`Disclosure`): its height glides (no JS measuring, follows content that resizes while open) and the body fades in while settling by one space step; open uses `base` + `enter`, close `fast` + `exit`. The chevron rotates over `base`. Instant under `prefers-reduced-motion`.
 
 ## Layout & spacing
 - Takes the full width of its parent (`width: 100%`); the parent sets the measure.
-- Panel content is a flex column with `--prime-space-3` gap; it reserves `--prime-focus-space` at the top so focus rings of fields inside are not clipped.
+- Panel content is a flex column with `--prime-space-3` gap; its padding (`--acc-pad-y` above and below, `--acc-pad-x` at the sides) keeps it clear of the trigger's hover fill and leaves room for the focus rings of fields inside.
 - The root is a layer of the surface ladder (`data-depth`): fields inside panels take that layer's fill automatically.
-- Stack several accordions or an accordion and other blocks with the page gap (`--prime-space-8` between groups).
+- Stack several accordions or an accordion and other blocks with the page gap between groups.
+- On a coarse pointer a trigger is at least the touch target high.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus between triggers; a disabled one is skipped. |
 | `Enter` · `Space` | Opens or closes the section. |
 
 ### ARIA
-- The trigger is a native `<button>` inside an `<h3>` with `aria-expanded` and `aria-controls`.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- The trigger is a native `<button>` inside a heading (`<h3>`, or the level of `as`) with `aria-expanded` and `aria-controls`.
 - The panel is a `<section>` with `aria-labelledby`; closed content is `inert`, so it leaves the tab order and the accessibility tree.
 - The chevron and `Accordion.Icon` are `aria-hidden`.
 
@@ -154,7 +160,7 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | A FAQ where one answer is open at a time — `defaultValue`. |
+| [overview.tsx](examples/overview.tsx) | A FAQ where one answer is open at a time and every question heads its section — `defaultValue`, `as`. |
 | [variants.tsx](examples/variants.tsx) | One surface with hairlines between items, or every item as its own card — `layout`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: trigger height, text, icon and padding grow together — `size`. |
 | [states.tsx](examples/states.tsx) | A disabled section that cannot be opened, next to regular ones — `disabled`. |
@@ -165,6 +171,7 @@ No `labels`.
 
 ## Mistakes
 - Trigger without `Accordion.Header` → wrap it so the section has a heading.
+- A heading level that skips the outline (an `<h3>` under a page `<h1>`) → set `as` one level below the heading above the accordion.
 - `value={["a"]}` without `multiple` → arrays only with `multiple`.
 - Adding a chevron icon to the trigger → the trigger draws one itself.
 - Expecting `className` on Content to style the `<section>` → it styles the inner padded block.

package/dist/skill/reference/components/accordion/examples/overview.tsx

@@ -1,4 +1,4 @@
-/** A FAQ where one answer is open at a time — `defaultValue`. */
+/** A FAQ where one answer is open at a time and every question heads its section — `defaultValue`, `as`. */
 import { Accordion } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -27,7 +27,7 @@ export default function AccordionOverviewExample() {
       <Accordion.Root defaultValue="delivery">
         {FAQ.map((item) => (
           <Accordion.Item key={item.value} value={item.value}>
-            <Accordion.Header>
+            <Accordion.Header as="h2">
               <Accordion.Trigger>{item.question}</Accordion.Trigger>
             </Accordion.Header>
             <Accordion.Content>{item.answer}</Accordion.Content>