prime-ui-kit 0.13.1 → 0.15.0

package/dist/index.js

@@ -27,6 +27,7 @@ import {
   Drawer,
   Dropdown,
   ExampleFrame,
+  FieldList,
   Fieldset,
   FileUpload,
   Gallery,
@@ -85,7 +86,7 @@ import {
   useSidebar,
   useTokenValue,
   useUploadQueue
-} from "./chunks/chunk-JV2KB5JZ.js";
+} from "./chunks/chunk-THFZIHKU.js";
 import {
   Avatar,
   Badge,
@@ -117,7 +118,7 @@ import {
   textTones,
   tones,
   variants
-} from "./chunks/chunk-PK2GC77E.js";
+} from "./chunks/chunk-XJAVS6FH.js";
 import {
   ControlSizeProvider,
   useOptionalControlSize
@@ -158,6 +159,7 @@ export {
   Dropdown,
   EmptyPage,
   ExampleFrame,
+  FieldList,
   Fieldset,
   FileUpload,
   Gallery,

package/dist/internal/ChartTooltip.d.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+import type { AnchorPoint } from "../hooks/usePosition";
+export type { AnchorPoint };
+export type ChartTooltipProps = React.HTMLAttributes<HTMLDivElement> & {
+    /** The point the content belongs to («8 окт», «Неделя 41»), over the content. */
+    label?: React.ReactNode;
+    /**
+     * Floats the tooltip beside a point of `anchorRef` (px from its top-left corner) — the pointer
+     * over the plot, or the point the arrow keys reached; `null` hides it. Without `anchorRef` the
+     * body renders in place (a chart library positions it).
+     */
+    point?: AnchorPoint | null;
+    /** The plot the point lies in: its scroll and size changes move the tooltip with it. */
+    anchorRef?: React.RefObject<HTMLElement | null>;
+    /** Escape hid the floating tooltip (it stays hidden until the point moves). */
+    onDismiss?: () => void;
+    ref?: React.Ref<HTMLDivElement>;
+};
+/**
+ * The one chart tooltip of the kit (ChartFrame.Tooltip, Sparkline): its look, and — with
+ * `anchorRef` — its place. A floating tooltip is an anchored layer like every other
+ * (`useFloatingLayer` + `usePosition` with `anchorPoint`): right of the point, vertically centred,
+ * flipped to the left only where the right has no room, kept inside the viewport, passive (no
+ * focus, no presses) and aria-hidden — the chart speaks its points itself.
+ */
+export declare function ChartTooltip({ anchorRef, ...props }: ChartTooltipProps): import("react/jsx-runtime").JSX.Element;

package/dist/internal/FieldAction.d.ts

@@ -1,10 +1,4 @@
 import * as React from "react";
-/**
- * A button segment at a field's edge (Input, Textarea): full field height, the icon centred with the
- * field padding on both sides, a hover wash over the whole segment, the touch hit area. The field
- * hosts style it through `data-field-action`.
- */
-export declare const fieldActionClass: string;
 export type FieldActionButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" | "children"> & {
     /** Accessible name and tooltip («Позвонить», «Открыть профиль»). */
     label: string;
@@ -14,8 +8,13 @@ export type FieldActionButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonE
     children: React.ReactNode;
     ref?: React.Ref<HTMLButtonElement>;
 };
+/**
+ * A segment without a tooltip, for a kit control whose glyph says it all (Input's clear and
+ * reveal): the name stays accessible, nothing floats over the field.
+ */
+export declare function FieldActionSegment(props: FieldActionButtonProps): import("react/jsx-runtime").JSX.Element;
 /** A named icon action at the field's edge with a tooltip. */
-export declare function FieldActionButton({ label, asChild, className, disabled, type, children, ref, ...rest }: FieldActionButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function FieldActionButton(props: FieldActionButtonProps): import("react/jsx-runtime").JSX.Element;
 export type CopyState = "idle" | "copied" | "error";
 export type FieldCopyLabels = {
     /** Name and tooltip of the copy button. */

package/dist/internal/fieldCell.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+/**
+ * The contract between `FieldList` and the fields in its cells. A cell provides its column heading;
+ * a framed field without a `label` of its own takes it as its label (and keeps its own `label`, if
+ * any), so every field in a row has a name without a visible label per row. The column heading
+ * shows the name once above the rows; the field's label is read, not shown, until the list stacks
+ * its rows into blocks in a narrow container (`FIELD_LIST_CONTAINER`), where each field shows it.
+ */
+export type FieldCell = {
+    /** The column heading: the name of the field in this cell. */
+    label: string;
+    /**
+     * `wide` — hidden while the column heading is on screen, shown when the rows stack; `always` —
+     * a one-column list, named by the list's own label, shows none in either layout.
+     */
+    hidden: "wide" | "always";
+};
+export declare const FieldCellContext: React.Context<FieldCell | null>;
+/** Name of the size container `FieldList` sets; FieldFrame shows a cell label under its query. */
+export declare const FIELD_LIST_CONTAINER = "prime-field-list";
+export declare function useFieldCell(): FieldCell | null;

package/dist/internal/messageList.d.ts

@@ -43,8 +43,8 @@ export type MessageListContextValue = {
     /** A message was new at the end in this commit. */
     arrivedNow: () => boolean;
     /**
-     * Brings a message into view and points at it (unless `flash` is `false`: the others blink
-     * around it); `focus` moves the focus to it too.
+     * Brings a message into view and blinks it (unless `flash` is `false`); `focus`
+     * moves the focus to it too.
      */
     reveal: (value: string, focus?: boolean, flash?: boolean) => boolean;
     /** The selection; read it through `useMessageSelection` / `useListSelection`. */

package/dist/internal/palette.d.ts

@@ -1,4 +1,11 @@
 import { type PaletteColor } from "./states";
+/**
+ * A palette hue as a data mark: its step of the categorical chart palette, so a category has one
+ * color in charts and in shares. The one source of `--hue-chart` in `palette.module.css` (kept equal
+ * by `palette.test.ts`); as strings here, because a chart library takes its colors in JS. Gray is
+ * `chart-other`; sky has no chart step (it sits too close to blue) and keeps its solid.
+ */
+export declare const HUE_CHART: Record<PaletteColor, string>;
 /**
  * A palette hue for a person, stable per `id`: the same id always gets the same hue, on every
  * render and every device (a string hash, no state). For names in a group chat and initials of

package/dist/internal/swatch.d.ts

@@ -11,11 +11,15 @@ export type ColorPreset = {
  * Take `COLOR_PRESETS.slice(0, 8)` for a single row of eight.
  */
 export declare const COLOR_PRESETS: readonly ColorPreset[];
-/** One selectable swatch: `null` is «no color». */
+/**
+ * One selectable swatch: `null` is «no color». `contrast` picks the check mark: `light` / `dark`
+ * by the color's luminance; `surface` (the «no color» checkerboard, drawn from the surface's own
+ * fills) follows the theme with the primary text color.
+ */
 export type SwatchOption = {
     value: string | null;
     label: string;
-    contrast: "light" | "dark";
+    contrast: "light" | "dark" | "surface";
 };
 /** The presets as swatch options, plus the «no color» option at the end when `allowEmpty`. */
 export declare function useSwatchOptions(presets: readonly ColorPreset[], allowEmpty: boolean, emptyLabel: string): SwatchOption[];

package/dist/layout/app-header/AppHeader.d.ts

@@ -14,9 +14,10 @@ export type AppHeaderRootProps = HeaderProps & {
     labels?: Partial<AppHeaderLabels>;
 };
 /**
- * The bar at the very top of the content panel: where you are, global search, a few actions.
- * One row as high as the Sidebar brand row, so the two read as one line; sticky; lays itself out
- * from its own width (narrow: the search folds into an icon, the title truncates).
+ * The page's bar at the very top of the content panel: its row holds only what the current page
+ * needs — the page title, the page's tools, per-page buttons. One row as high as the Sidebar brand
+ * row, so the two read as one line; sticky; lays itself out from its own width (narrow: the
+ * description goes, the title truncates).
  */
 declare function AppHeaderRoot({ labels, className, children, ...rest }: AppHeaderRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppHeaderRoot {
@@ -28,18 +29,14 @@ declare function AppHeaderStart({ className, ...rest }: AppHeaderStartProps): im
 declare namespace AppHeaderStart {
     var displayName: string;
 }
-export type AppHeaderTitleProps = DivProps & {
-    /**
-     * Tag of the name: `h1` when the header carries the page title (no `PageContent.Header` in
-     * main) — the description stays outside the heading's name. Default `span`.
-     */
-    as?: "span" | "h1";
-};
+export type AppHeaderTitleProps = DivProps;
 /**
  * Where you are: an optional `AppHeader.Icon`, the name and an optional `AppHeader.Description`
- * under it — the same anatomy as the Sidebar brand. The name truncates.
+ * under it — the same anatomy as the Sidebar brand. The name is the page's `<h1>` (an app page
+ * titles itself in the header); the description stays outside the heading's name. The name
+ * truncates.
  */
-declare function AppHeaderTitle({ as: NameTag, className, children, ...rest }: AppHeaderTitleProps): import("react/jsx-runtime").JSX.Element;
+declare function AppHeaderTitle({ className, children, ...rest }: AppHeaderTitleProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppHeaderTitle {
     var displayName: string;
 }
@@ -68,21 +65,6 @@ declare function AppHeaderSeparator({ className, ...rest }: AppHeaderSeparatorPr
 declare namespace AppHeaderSeparator {
     var displayName: string;
 }
-export type AppHeaderSearchProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> & {
-    /** Placeholder text; also the button's name when the header is narrow and the field folds. */
-    children: React.ReactNode;
-    /** Key hint at the end. Default `⌘K`; `null` hides it. */
-    shortcut?: React.ReactNode;
-    ref?: React.Ref<HTMLButtonElement>;
-};
-/**
- * Global search entry: looks like a field, works as a button that opens your CommandMenu (wire
- * `onClick` and the shortcut). On a narrow header it folds into a square search button.
- */
-declare function AppHeaderSearch({ children, shortcut, className, ...rest }: AppHeaderSearchProps): import("react/jsx-runtime").JSX.Element;
-declare namespace AppHeaderSearch {
-    var displayName: string;
-}
 export type AppHeaderToolsProps = DivProps;
 /**
  * The page's tools in the header — a `PageToolbar.Root` (sections, period, filters, the primary
@@ -120,7 +102,6 @@ export declare const AppHeader: {
     Icon: typeof AppHeaderIcon;
     Description: typeof AppHeaderDescription;
     Separator: typeof AppHeaderSeparator;
-    Search: typeof AppHeaderSearch;
     Tools: typeof AppHeaderTools;
     Actions: typeof AppHeaderActions;
     MenuButton: typeof AppHeaderMenuButton;

package/dist/layout/index.d.ts

@@ -1,4 +1,4 @@
-export type { AppHeaderActionsProps, AppHeaderDescriptionProps, AppHeaderIconProps, AppHeaderLabels, AppHeaderMenuButtonProps, AppHeaderRootProps, AppHeaderSearchProps, AppHeaderSeparatorProps, AppHeaderStartProps, AppHeaderTitleProps, AppHeaderToolsProps, } from "./app-header/AppHeader";
+export type { AppHeaderActionsProps, AppHeaderDescriptionProps, AppHeaderIconProps, AppHeaderLabels, AppHeaderMenuButtonProps, AppHeaderRootProps, AppHeaderSeparatorProps, AppHeaderStartProps, AppHeaderTitleProps, AppHeaderToolsProps, } from "./app-header/AppHeader";
 export { AppHeader } from "./app-header/AppHeader";
 export type { AppShellContentWidth, AppShellFooterProps, AppShellMainProps, AppShellNavProps, AppShellRootProps, AppShellTemplateProps, } from "./app-shell/AppShell";
 export { AppShell } from "./app-shell/AppShell";

package/dist/skill/SKILL.md

@@ -6,10 +6,12 @@ description: >
   navigation on prime-ui-kit; when
   choosing which kit component fits a task; when a needed component is missing and must be composed from
   the kit; when adding loading, empty and error states, feedback, motion or micro-animation to a screen;
-  and when reviewing a screen for design-system compliance (spacing rhythm, sizes, tokens, states,
-  motion, a11y, narrow screens). Triggers: build a screen, page, form, table, board, schedule, chat,
-  uploads, settings, dashboard, navigation; which component to use; animate, transition, loading state; prime-ui-kit; review a screen
-  against the design system — in any language.
+  when changing or redesigning a screen that exists; and when reviewing a screen for design-system and
+  UX compliance (data shape and layout, repeated or redundant labels, copy, friction, spacing rhythm,
+  sizes, tokens, states, motion, a11y, narrow screens). Triggers: build a screen, page, form, table,
+  board, schedule, chat, uploads, settings, dashboard, navigation; repeating fields, add another row;
+  which component to use; animate, transition, loading state; prime-ui-kit; improve, fix or review a
+  screen against the design system — in any language.
 ---
 
 # prime-ui-kit
@@ -24,25 +26,33 @@ region, `Skeleton` while it loads).
 
 0. **First** — [cheatsheet.md](cheatsheet.md): one page of the decisions agents most often get wrong,
    each as «do this, not that» with the exact API. Then follow the steps in order; each names its file.
-1. **The app frame, once per app** — [layouts.md](layouts.md): styles, theme, providers, `AppShell`
-   with `Sidebar` and `AppHeader`, page wrappers, auth screens. A screen you deliver renders only its page.
-2. **Choose** — [choosing.md](choosing.md): the category by task, then the component, then the pairs
+   Changing a screen that exists: audit it first ([ux.md](ux.md#8-changing-a-screen-someone-built)),
+   then make the change.
+1. **Brief** — [ux.md](ux.md): five lines before any JSX (who and what for, the data and its shape,
+   the main action, the states, the narrow screen); the shape of the data decides the layout, every
+   label must carry something new, friction matches the cost of a mistake.
+2. **The app frame, once per app** — [layouts.md](layouts.md): styles, theme, providers, `AppShell`
+   with `Sidebar` and `AppHeader`, page wrappers, auth screens. A screen you deliver renders only its
+   page: its header content (title, a line of data, its tools) and its body.
+3. **Choose** — [choosing.md](choosing.md): the category by task, then the component, then the pairs
    that are easy to confuse.
-3. **Read the component** — [components.md](components.md) links each `COMPONENT.md` (API, variants,
+4. **Read the component** — [components.md](components.md) links each `COMPONENT.md` (API, variants,
    states, a11y, mistakes) and its `examples/`. Never guess a prop; copy structure from an example.
-4. **Compose the screen** — [composition.md](composition.md): start from the closest working screen in
-   [patterns/](patterns/) and keep its skeleton; rhythm, hierarchy, surfaces and type in
+5. **Compose the screen** — [composition.md](composition.md): start from the closest working screen (the
+   [screens index](composition.md#screens): the `examples/screen.tsx` of its main component) and keep
+   its skeleton; rhythm, hierarchy, surfaces and type in
    [foundations.md](foundations.md).
-5. **Write the JSX** — [api-contract.md](api-contract.md): prop names, controlled state, events (async
+6. **Write the JSX** — [api-contract.md](api-contract.md): prop names, controlled state, events (async
    events return the request's Promise), forms and their submit flow (`Fieldset disabled`), uploads
    (`useUploadQueue`), destructive actions (`ConfirmDialog`), helpers (`groupMessages` for chat rows you build yourself),
    icon names.
-6. **States and motion** — [motion.md](motion.md): every region loads, empties and fails without
+7. **States and motion** — [motion.md](motion.md): every region loads, empties and fails without
    flipping; what the kit animates by itself and when to move your own elements.
-7. **Narrow screens** — [responsive.md](responsive.md): every screen works from 320px, the page panel is
+8. **Narrow screens** — [responsive.md](responsive.md): every screen works from 320px, the page panel is
    `PageToolbar`, nothing is hidden on phones, touch follows `(hover)` / `(pointer)`.
-8. **Check** — [checklist.md](checklist.md) and [anti-slop.md](anti-slop.md). Fix every «no», then hand
-   over.
+9. **Check** — [checklist.md](checklist.md) and [anti-slop.md](anti-slop.md), then look at the screen
+   in a browser: both themes, 1280 and 375 px ([ux.md](ux.md#9-look-at-it-before-handing-it-over)). Fix
+   every «no», then hand over.
 
 ## Where things are
 
@@ -56,18 +66,18 @@ project under `node_modules/prime-ui-kit/src/`.
 | Component reference | `reference/components/<dir>/COMPONENT.md` | `node_modules/prime-ui-kit/src/components/<dir>/COMPONENT.md` |
 | Copyable scenarios | `reference/components/<dir>/examples/*.tsx` | `node_modules/prime-ui-kit/src/components/<dir>/examples/*.tsx` |
 | AppShell, Sidebar, AppHeader, BottomNav | `reference/layout/<dir>/…` | `node_modules/prime-ui-kit/src/layout/<dir>/…` |
-| Whole screens | `patterns/*.tsx` | `node_modules/prime-ui-kit/dist/skill/patterns/*.tsx` |
+| Whole screens | `reference/<base>/<dir>/examples/screen.tsx` | `node_modules/prime-ui-kit/src/<base>/<dir>/examples/screen.tsx` |
 
 ## Files of this skill
 
 | File | Read when |
 |---|---|
 | [cheatsheet.md](cheatsheet.md) | first — the most frequent decisions and mistakes in one page |
+| [ux.md](ux.md) | before the layout of every screen and before changing one — the brief, data shape → layout, label economy, copy, friction, defaults, the visual check |
 | [layouts.md](layouts.md) | once per app — the app frame, page wrappers, auth screens |
 | [choosing.md](choosing.md) | unsure which component fits (Gantt / Timeline / Kanban / DataTable, Message / Composer, FileUpload list / grid / gallery / strip, ColorField / ColorPicker…); how to confirm a destructive action |
 | [components.md](components.md) | finding a component and its `COMPONENT.md` / `examples/` |
-| [composition.md](composition.md) | building any screen — the patterns table, the rules of assembly, what to do when the kit lacks a component |
-| [patterns/](patterns/) | starting a screen — list, detail, settings, form in a Drawer, dashboard, states, messenger |
+| [composition.md](composition.md) | building any screen — the screens index (list, detail, settings, form in a Drawer, dashboard, states, messenger, board, app frame, media library, schedule, record editor) and what each one teaches, the rules of assembly, what to do when the kit lacks a component |
 | [foundations.md](foundations.md) | grid, proximity scale, sizes, surfaces, type, tone and color |
 | [api-contract.md](api-contract.md) | writing JSX — prop names, sizes and host tiers, controlled state, forms, helpers, icons |
 | [motion.md](motion.md) | every screen — loading / empty / error that flow, what the kit animates, when to move, recipes |
@@ -110,9 +120,11 @@ Take a semantic `<Icon name="…" />` first, else a glyph from the full animated
 5. Air is hierarchy: tighter inside a group, wider between groups, widest between sections — spacing via
    `gap` on the parent, never margins.
 6. One primary action per area. The rest are `soft`/`ghost`/`outline` with `tone="neutral"`.
-7. Labels above fields, always. Placeholder is an example value, never the label.
+7. Labels above fields, always — once per column for records in rows (`FieldList`), never numbered
+   («Пункт 1»), never repeating their heading. Placeholder is an example value, never the label.
 8. Text through `Typography` roles (`title-m` section, `title-s` group, `body-m` text, `caption` meta;
-   the page title is `PageContent.Title`). No custom font sizes.
+   the page title is `AppHeader.Title` in the page's header, `PageContent.Title` only on a
+   document page). No custom font sizes.
 9. Overlays (Modal, ConfirmDialog, Drawer, Sheet, Popover, Dropdown, Tooltip, CommandMenu, Select,
    MediaViewer) come from the kit — never hand-made — and stay mounted: drive them with `open`,
    never `{open && …}`.

package/dist/skill/anti-slop.md

@@ -48,9 +48,10 @@ Text color goes through `Typography tone="secondary"`, not CSS.
 // bad — a card around a card around a table
 <Card.Root><Card.Root><DataTable columns={columns} rows={rows} /></Card.Root></Card.Root>
 
-// good — DataTable already is a filled block; a section heading is enough
-<Typography as="h2" variant="title-m">Последние оплаты</Typography>
-<DataTable columns={columns} rows={rows} />
+// good — DataTable already is a filled block; a titled section is enough
+<PageContent.Section label="Последние оплаты">
+  <DataTable columns={columns} rows={rows} />
+</PageContent.Section>
 ```
 
 ## 3a. Hover that merges with the neighbour
@@ -106,6 +107,78 @@ and inside a card, in both themes: rest, hover and the neighbour must be three d
 
 A search field in a toolbar may go without a visible label, but then it needs `aria-label`.
 
+## 5a. A label in every row, a record split over lines
+
+The most common shape bug of generated forms: rules for one field applied to a list of records.
+
+```tsx partial
+// bad — «Иконка · Параметр · Значение · Цвет» repeated in every record, a record on two lines,
+// numbered labels, a hint that explains the lock
+{specs.map((spec, index) => (
+  <div key={spec.id} className={styles.grid}>
+    <Select.Root label="Иконка">…</Select.Root>
+    <Input.Root label={`Параметр ${index + 1}`}>…</Input.Root>
+    <Input.Root label="Значение">…</Input.Root>
+    <ColorField label="Цвет иконки" />
+  </div>
+))}
+<Typography variant="body-s">Первые три всегда первыми. Остальные можно перетаскивать.</Typography>
+
+// good — one row per record, the headings once, compact columns for the small attributes
+<FieldList
+  label="Характеристики"
+  columns={[
+    { label: "Иконка", width: "compact" },
+    { label: "Параметр" },
+    { label: "Значение" },
+    { label: "Цвет", width: "compact" },
+  ]}
+  reorderable
+  getLocked={(spec) => spec.pinned}
+  value={specs}
+  onValueChange={setSpecs}
+  getId={(spec) => spec.id}
+  getLabel={(spec) => spec.name}
+  createItem={newSpec}
+  addLabel="Добавить характеристику"
+  renderItem={(spec, row) => (
+    <>
+      <Select.Root value={spec.icon} onValueChange={(icon) => row.update({ icon })}>
+        <Select.Trigger>
+          <Select.TriggerIcon><Icon name={spec.icon} /></Select.TriggerIcon>
+        </Select.Trigger>
+        <Select.Content>…</Select.Content>
+      </Select.Root>
+      <Input.Root>…</Input.Root>
+      <Input.Root>…</Input.Root>
+      <ColorPresets.Root value={spec.color} onValueChange={…}>…</ColorPresets.Root>
+    </>
+  )}
+/>
+```
+
+The same for one value in several units — one heading, the fields in a row, the unit inside:
+
+```tsx partial
+// bad — three labels, the currency in the label and again in the field, one field on a line of its own
+<Input.Root label="Депозит, $" optional>…<Input.InlineAffix side="end">$</Input.InlineAffix>…</Input.Root>
+<Input.Root label="Депозит, ฿" optional>…</Input.Root>
+<Input.Root label="Депозит, ₽" optional>…</Input.Root>
+
+// good — a group heading, three fields in one row, each named for assistive tech
+<Fieldset label="Депозит">
+  <div className={styles.row}>
+    <Input.Root>
+      <Input.Wrapper>
+        <Input.Field aria-label="Депозит в долларах" inputMode="decimal" />
+        <Input.InlineAffix side="end">$</Input.InlineAffix>
+      </Input.Wrapper>
+    </Input.Root>
+    {/* ฿ and ₽ the same */}
+  </div>
+</Fieldset>
+```
+
 ## 6. Everything on one level of air
 
 ```css
@@ -115,7 +188,7 @@ A search field in a toolbar may go without a visible label, but then it needs `a
 /* good — proximity scale */
 .form { display: grid; gap: var(--prime-space-8); }   /* group → group 32 */
 .group { display: grid; gap: var(--prime-space-5); }  /* field → field 20 */
-/* section → section 40 comes from PageContent.Body */
+/* block → block 24 and section → section 40 come from PageContent.Body / PageContent.Section */
 ```
 
 ## 7. `div` instead of a ready component

package/dist/skill/api-contract.md

@@ -157,7 +157,7 @@ export function InviteForm() {
 ```
 
 (`.form { display: grid; gap: var(--prime-space-5); }`.) A full create form with groups, validation,
-loading and a toast: [patterns/form-drawer.tsx](patterns/form-drawer.tsx).
+loading and a toast: [the Drawer screen](reference/components/drawer/examples/screen.tsx).
 
 ## Loading without DataTable
 
@@ -167,7 +167,7 @@ any other card or region that loads: wrap its content in `Crossfade state={statu
 (same rows, gaps and heights). A `Spinner` only where there is no shape to hold. Show the error in
 place (a `Banner` for the page, `EmptyPage` with `EmptyPage.Icon tone="danger"` and a retry for a
 region). Never draw your own spinners or shimmer blocks. See
-[patterns/screen-states.tsx](patterns/screen-states.tsx) and [motion.md](motion.md).
+[the screen states](reference/components/crossfade/examples/screen.tsx) and [motion.md](motion.md).
 
 ## Secondary actions
 

package/dist/skill/cheatsheet.md

@@ -39,6 +39,10 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - A record card that saves each field: `<Input.Root onCommit={save}>` (save returns a Promise) — not hand-written blur / Enter / Escape handlers or a field disabled while saving.
 - Markdown text outside a chat (an announcement, a task description) is `<Textarea.Root formatting>`: the Composer's toolbar, hotkeys and subset (`**`, `_`, `~~`, `` ` ``, `||spoiler||`, links, `> `) — not a hand-made toolbar over a textarea. Turn it on only where the text is shown with its Markdown.
 - Copy or call next to a value: `Input.CopyButton`, `Input.Action` inside `Input.Wrapper` — not a Button beside the field; a password: `Input.RevealButton`.
+- Records of one shape a person adds and removes (invoice lines, contacts, specs, prices by period): `<FieldList columns={[{ label: "Услуга" }, { label: "Цена", width: "m" }]} value onValueChange getId createItem addLabel renderItem={(item, row) => <>…fields without label…</>} />` — the headings stand once, every field takes its column heading as its label; not a `.map()` of fields with a `label` in every row, not «Позиция 1», «Позиция 2».
+- Small attributes in a row of fields: an icon-only `Select` (`<Select.Trigger><Select.TriggerIcon>…</Select.TriggerIcon></Select.Trigger>`, no `Select.Value`) and a `ColorPresets` swatch in `width: "compact"` columns — not a full-width Select and a ColorField on a line of their own.
+- A base value with overrides (a price and its changes by month): one `FieldList`, the base as the first row pinned by `getLocked` — not a separate field above a list in another geometry.
+- One value in several units (a deposit in ₽, $, ฿): the fields side by side in one row under one heading, each unit in `Input.InlineAffix` — not a label per field, not the unit in the label and in the field.
 
 ## State
 
@@ -72,11 +76,19 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - Busy action: `<Button.Root loading>` — not a hand-made spinner or «Загрузка…» text.
 - An action on a coloured host (a solid Banner, an accent strip): `<Button.Root variant="ghost" tone="inherit">` — it takes the host's text colour; never recolour a Button with a CSS override.
 
+## Page title and header
+
+- An app page titles itself in its header: `<AppHeader.Title>` + `<AppHeader.Description>` with a line of data («128 в работе · 6 ждут оплаты») — not a `PageContent.Header` in main and not a sentence about the page.
+- The page's tools — its own search and filter, sections, the view, the primary action — are a `<PageToolbar.Root>` in `<AppHeader.Tools>`; the page's other buttons in `<AppHeader.Actions>` — not a global search, notifications or app-wide buttons: the header row is per page.
+- A nested record: `Breadcrumb` + `<AppHeader.Separator />` + `<AppHeader.Title>` with the record's name — not a breadcrumb in main.
+- A document page (settings, a long form, help) is the only one with `<PageContent.Header>` + `PageContent.Title` in main, and then its header has no title — never two titles, never no `<h1>`.
+
 ## Cards and surfaces
 
 - `Card.Root` only for a bounded block with its own title: a KPI tile (`variant="stat-trend"`), a settings panel (`variant="panel"`), side facts — not around a whole section, a form field or a page.
 - Never a card in a card, and never a `DataTable` inside a Card — the table is already a filled block.
-- Section without a card: `<Typography as="h2" variant="title-m">` + the content.
+- Section without a card: `<PageContent.Section label="…">` + the content (a link or button beside the heading in `PageContent.Actions`) — not a hand-made `<section>` + `Typography as="h2"` + own gap.
+- The tiles of a screen (KPI cards, charts, panels): one `<PageContent.Grid>` with a `<PageContent.Cell span>` per tile — not an `auto-fit` grid per row (the rows would stand 24 apart instead of 16).
 - Depth from fill, not lines: no borders around blocks; `<Divider />` only inside a block.
 - Every scroll region is a `ScrollContainer` — never `overflow: auto` on a `div`: its hidden edges fade by themselves (`edges="shadow"` on a filled surface, `"none"` only for a page column), `scrollbar="hidden"` on strips, `snap` on strips of cards, `lock` to hold a list still, `anchor="end"` for a log. Kit components already scroll through it; do not wrap them again.
 - Tabs are a bar, not a container: `Tabs.Root` stands in the host's padding and the panel content goes straight into `Tabs.Panel` — never a Card or a padded `div` around the tabs or inside a panel. In a Modal / Drawer, `Tabs.Root` wraps `X.Header` + `X.Body` and `Tabs.List` goes last into the header — not a tab strip at the top of the body.
@@ -90,13 +102,14 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - Data the server sorts and pages (thousands of records): `source="server"` + `rowCount`, controlled `sort` / `page` as the request, `page` back to 1 on a new search or filter, old rows kept with `loading` while the next page loads — not a server page passed to the default client mode, and not `rows={[]}` between pages.
 - Categories (sources, platforms, regions) get `color` and the same order of `chartColors` in charts; statuses and meanings get `tone` — never paint categories with tones.
 - A chart with axes or several series: `<ChartFrame.Root series state>` around the library (or your SVG) with `ChartFrame.Plot renderPlot`, `Legend`, `Table` — not a hand-made Card with a grey box while loading and a legend of colored dots.
+- A tooltip on your own SVG chart: `<ChartFrame.Tooltip point={{ x, y }} items>` with the pointer in plot coordinates — not a `foreignObject` or a div placed and clamped by hand; it flips only when out of room.
 - Amounts, counts and dates are `numeric` columns; statuses are `Badge.Root color` from one status → color map.
 - Rows people order by hand: `onReorder(id, beforeId)` (apply it with `moveBefore`, return the save's Promise) — not a Dnd list rebuilt next to the table.
 - A short list of records people order by hand (stages, priorities) is `<List.Root onReorder>` with `List.Item value` — not up / down buttons or a hand-made `Dnd.Sortable`.
 - Groups that fold: pass `defaultCollapsedGroups={[]}` (or the controlled `collapsedGroups` + `onCollapsedGroupsChange`) — not your own button in `renderGroupHeader` or filtering `rows`. One heatmap over several columns: the same `scale: { min, max }` on each.
-- A trend in a table row is `<Sparkline layout="compact">` in the column's `cell` (a column `width`, series built once, not inline); the number itself goes in its own column.
+- A trend in a table row is `<Sparkline layout="compact">` in the column's `cell` (a column `width`, series built once, not inline, the same `min` / `max` on every row when rows compare by size); the number itself goes in its own column. A missing day is `value: null`, never `0`.
 - Properties of one record: `<DescriptionList.Root>` of `DescriptionList.Item` — not a hand-made grid of label / value text, not a one-row DataTable.
-- Who is busy when, a plan with dates: `Gantt` with `onBarChange` / `onBarCreate` — not bars drawn by hand or a DataTable of start and end dates. Statuses moved by hand: `Kanban`.
+- Who is busy when, a plan with dates: `Gantt` with `onBarChange` / `onBarCreate` — not bars drawn by hand or a DataTable of start and end dates. Statuses moved by hand: `Kanban` — `plain` (default, a header plate) or `line` (a header over a line) for a board that is the page's main region, `variant="well"` only when columns must read as bounded queues (WIP limits, sparse columns); never a Card or a filled box around a column.
 - Open a board card with `Kanban.Root onItemClick` (click, Enter, Space, never after a drag) or `getItemHref`; a Gantt row with `onRowClick` / `getRowHref` (the DataTable contract), a bar with `onSelect`; more facts in a bar tooltip with `renderBarTooltip` (it adds lines under the dates). A legend of hues is a row of `Badge.Root color` + `Badge.Dot` in the host's `toolbar`, the category also in text. Hour slots (bookings, appointments) are not Gantt — its unit is a calendar day.
 
 ## Chat
@@ -113,7 +126,7 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - «печатает…» on the other side: `Composer onActivityChange` (`typing` / `voice` / `video` / `null`, on a change only) → your socket; on the receiving side `<Chat.Root typing={activity === "typing"}>` (the header's status and the list's typing bubble together). Never send it from `onValueChange`.
 - Appearance: messages that are new at the end enter by themselves — mine and theirs float up a little from below and fade in; the first render, history loaded above and rows scrolled into view never animate. Do not add your own enter animation or `scrollTop = scrollHeight`.
 - `Chat.Messages` scrolls to my message, stays at the end for theirs while the reader is there, and otherwise shows the «N новых» button; `onNewMessage(value, { direction })` is for a sound or a counter, `onRead(values)` for read receipts (only what was really seen). The first unread is `unread={key}`; older history is `hasOlder` + `onLoadOlder`.
-- Jump to a message: `Message.Reply target={id}`, a press on `Chat.Pinned`, or `Chat.Root current={id}` (the chat scrolls to it and the other messages blink back around it); search: `Chat.SearchButton` + `Chat.Search` mark, count and step through the matches in texts and transcripts, keeping the others stepped back. Never an outline or a wash of your own on the target or on selected messages. Never `scrollIntoView` or your own transforms on rows.
+- Jump to a message: `Message.Reply target={id}`, a press on `Chat.Pinned`, or `Chat.Root current={id}` (the chat scrolls to it and the message blinks); search: `Chat.SearchButton` + `Chat.Search` mark, count and step through the matches in texts and transcripts, keeping the others stepped back. Never an outline or a wash of your own on the target or on selected messages. Never `scrollIntoView` or your own transforms on rows.
 - A long history (thousands of messages): nothing to switch on — `Chat.Messages` renders only the rows around the view and keeps the reader's place. With children, every top-level child is one row (a `Message.Root`, or a fragment / your own row component keyed by the message `value`); give pictures their `width` / `height` so a row's size is final before load; jumps, search, selection and the keyboard still reach every message. Not a hand-rolled window, `content-visibility` on rows or a measured bubble.
 - A message's layout is CSS: the bubble fits its content and the time sits at the end of the last line (or of the reactions row). Every size change of a message (reactions, a transcript, an edit, an upload) plays as one built-in stroke, width and height together; a reaction grows the message upward with the time still, the rows above gliding as one block. Never size, measure or animate a bubble yourself; an own content part declares itself with the kit's part contract instead of a wrapper.
 - One sound at a time is built in: a voice message, a video message and a chat video pause each other; `playing` / `onPlayingChange` on `VoicePlayer` or `VideoNote` when the app needs to know. A round video never plays or loops before a press. A recorded voice message without levels gets them from `getWaveform(blob)` once, stored with the message.
@@ -170,7 +183,7 @@ State change is continuous in the whole kit: every region that changes what it s
 
 Full rules: [responsive.md](responsive.md).
 
-- The page panel is `<PageToolbar.Root>` with, in this order, `Tools` (`SmartFilter.Toolbar`: search, then filter), `Sections` (a `fullWidth` SegmentedControl), `View`, `Actions`, `Chips` — the active filters always sit right under the search, never under the sections; not a hand-made flex row of tabs, search and buttons.
+- The page panel is `<PageToolbar.Root>` with, in this order, `Tools` (`SmartFilter.Toolbar`: search, then filter), `Sections` (a `fullWidth` SegmentedControl), `View`, `Actions`, `Chips` — the active filters sit under the top row, never under the sections; on a phone the primary action takes its own row by itself when the search would be squeezed; not a hand-made flex row of tabs, search and buttons.
 - Rearrange, never hide: every desktop function is on the phone, in another place or a menu — not `display: none` below a breakpoint.
 - Breakpoints 640 · 768 · 1024 · 1280 only for the app frame; inside a page — intrinsic grids (`auto-fill, minmax`) and container queries.
 - A wide table scrolls inside itself; offer `DataTable.ColumnsMenu` in its `toolbar` — never drop columns by breakpoint, never hand-build the chooser.
@@ -183,10 +196,23 @@ Full rules: [responsive.md](responsive.md).
 
 ## Spacing and values
 
-- Gaps are `gap` on the parent with `--prime-space-N` (N × 4px): 8 in a row of buttons, 20 field → field, 32 group → group; `PageContent.Body` already spaces blocks 40 — not margins, not outer padding.
+- Gaps are `gap` on the parent with `--prime-space-N` (N × 4px): 8 in a row of buttons, 16 tile → tile, 20 field → field, 32 group → group; `PageContent` already spaces blocks 24 and sections 40 — not margins, not outer padding.
 - Tokens only: `var(--prime-space-4)`, `var(--prime-color-text-secondary)`, `var(--prime-radius-m)` — never raw `px` / `rem` / hex, never `--prime-ref-*`, never inline `style`.
 - Text through `Typography` roles (`title-m`, `title-s`, `body-m`, `caption`) and `tone="secondary" | "muted"` — not `font-size` or `color` in CSS.
 
+## UX — what goes on the screen
+
+- Five lines of brief before the JSX: who and what for, the data and its shape, the main action, the states, the narrow screen ([ux.md](ux.md)) — not a layout picked by habit.
+- The shape of the data picks the layout: one record → a form or a `DescriptionList`; records a person edits → `FieldList`; records a person reads → `DataTable` ([the table](ux.md#2-the-shape-of-the-data-decides-the-layout)).
+- Every label carries something new: once per column, never numbered, never repeating its heading; no hint that explains what the layout shows (a lock already says «закреплено»).
+- Buttons say the verb and the object («Выставить счёт»), errors say how to fix it («Формат: +7 912 404-18-20»), empty states offer the next step — not «ОК», «Ошибка», «Нет данных».
+- Money, numbers and dates through `Intl` (`ru-RU`); «ёлочки», `…`, a non-breaking space before a unit — not `toFixed` and string glue.
+- Friction matches the cost: a reversible action at once with «Отменить» in a `Notification`; `ConfirmDialog` only for irreversible or weighty ones, naming the thing and the loss — not «Вы уверены?» on every delete.
+- A disabled control says why when the reason is not on screen; an action without permission is hidden.
+- Tabs, filters, search, page and the open record live in the URL.
+- Changing a screen that exists: audit it against [ux.md](ux.md), [checklist.md](checklist.md) and [anti-slop.md](anti-slop.md) first, fix the shape, then make the change.
+- Before handing over, look at it in a browser: both themes, 1280 and 375 px, every text read aloud.
+
 ## Anti-slop
 
 The whole list, bad → good: [anti-slop.md](anti-slop.md). Before handing over: [checklist.md](checklist.md).
@@ -205,7 +231,7 @@ applyTheme("light");
 The frame itself (providers, `AppShell` with `Sidebar` and the phone menu button) is built once too:
 copy it from [layouts.md](layouts.md#app-frame-once-per-app).
 
-A page with one primary action and a field frame:
+A document page (a form) — its title is in main, its header carries none:
 
 ```tsx
 import { Button, Icon, Input, PageContent } from "prime-ui-kit";