prime-ui-kit 0.15.0 → 0.17.0

package/dist/layout/sidebar/Sidebar.d.ts

@@ -9,9 +9,10 @@ export type SidebarLabels = {
     collapse: string;
     /** Toggle label while the rail is compact or hidden. */
     expand: string;
-    /** Toggle label inside the off-canvas panel, and the scrim's label. */
+    /** Toggle label while the off-canvas panel is open. */
     close: string;
 };
+export declare const SIDEBAR_LABELS: SidebarLabels;
 type SidebarContextValue = {
     /** Stored open state of groups and sub-lists (`persistKey`), or `null`. */
     persist: SidebarPersist | null;
@@ -28,55 +29,108 @@ type SidebarContextValue = {
     navId: string;
     labels: SidebarLabels;
 };
-declare const useSidebar: () => SidebarContextValue;
+declare const useSidebar: (part?: string) => SidebarContextValue;
 type SidebarPersist = {
     read: (id: string) => boolean | undefined;
     write: (id: string, open: boolean) => void;
 };
 export { useSidebar };
 export type SidebarRootProps = React.ComponentPropsWithoutRef<"div"> & {
-    /** Item tier: height, icon and text of `--prime-control-<size>-*`. */
+    /**
+     * Item tier: height 28 · 32 · 36 · 40 · 48, text, icon; coloured counts and row actions one tier down, plain counts keep the item size. The rail width does not change. Without it the tier of its host, else `m`.
+     */
     size?: ControlSize;
+    /**
+     * Desktop mode (controlled): full rail, icon rail with tooltips and flyouts, or hidden.
+     */
     mode?: SidebarMode;
+    /**
+     * Initial mode (uncontrolled).
+     */
     defaultMode?: SidebarMode;
+    /**
+     * Called with the new mode (Toggle, `useSidebar().setMode`).
+     */
     onModeChange?: (mode: SidebarMode) => void;
-    /** The off-canvas panel (while the sidebar is off-canvas, see `offCanvas`). */
+    /**
+     * Off-canvas panel on narrow viewports (controlled).
+     */
     open?: boolean;
+    /**
+     * Initial off-canvas state (uncontrolled).
+     */
     defaultOpen?: boolean;
+    /**
+     * Off-canvas open / close: Toggle, the menu button of `Page.TopBar`, scrim, Escape, an activated item, leaving the narrow viewport.
+     */
     onOpenChange?: (open: boolean) => void;
     /**
-     * When the rail becomes an off-canvas panel with a scrim and a focus trap, opened by `open`:
-     * `auto` below 768px, `always` at any width (navigation behind a menu button), `never`.
+     * When the rail becomes an off-canvas panel opened by `open`: `auto` — below 768px (viewport); `always` — at any width; `never` — always a rail.
      */
     offCanvas?: "auto" | "always" | "never";
     /**
-     * Remembers the state across reloads in `localStorage` under this key: the mode and which
-     * collapsible groups and sub-lists are open (by their `id`, else their label text). Controlled
-     * `mode` / `open` are not stored.
+     * A press on the scrim (outside the off-canvas panel) closes the panel.
+     */
+    closeOnOutsideClick?: boolean;
+    /**
+     * Escape closes the off-canvas panel.
+     */
+    closeOnEscape?: boolean;
+    /**
+     * `localStorage` key that keeps the mode (never `hidden`: the mode it left) and the open groups and sub-lists (by `id`, else label text) across reloads. Wins over `defaultMode` / `defaultOpen`.
      */
     persistKey?: string;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<SidebarLabels>;
+    ref?: React.Ref<HTMLDivElement>;
 };
+declare function SidebarRoot({ children, className, size: sizeProp, mode: modeProp, defaultMode, onModeChange, open: openProp, defaultOpen, onOpenChange, offCanvas: offCanvasProp, closeOnOutsideClick, closeOnEscape, persistKey, labels: labelsProp, ref, ...rest }: SidebarRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SidebarRoot {
+    var displayName: string;
+}
 export type SidebarHeaderProps = React.ComponentProps<"div">;
 declare function SidebarHeader({ className, ...rest }: SidebarHeaderProps): import("react/jsx-runtime").JSX.Element;
 declare namespace SidebarHeader {
     var displayName: string;
 }
-export type SidebarContentProps = React.HTMLAttributes<HTMLElement>;
+export type SidebarContentProps = React.HTMLAttributes<HTMLElement> & {
+    ref?: React.Ref<HTMLElement>;
+};
+/**
+ * Scrolling middle region: a ScrollContainer with edge fades and no scrollbar (a classic bar
+ * would take width and move the icons; the rail scrolls by wheel, touch and focus).
+ */
+declare function SidebarContent({ className, ...rest }: SidebarContentProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SidebarContent {
+    var displayName: string;
+}
 export type SidebarFooterProps = React.ComponentProps<"div">;
 declare function SidebarFooter({ className, ...rest }: SidebarFooterProps): import("react/jsx-runtime").JSX.Element;
 declare namespace SidebarFooter {
     var displayName: string;
 }
 export type SidebarGroupProps = Omit<React.ComponentProps<"div">, "role"> & {
-    /** Group heading. In compact mode it folds away. */
+    /**
+     * Group heading (`aria-labelledby`). Keep it to one short word: on the compact rail only its first letters show.
+     */
     label?: React.ReactNode;
-    /** The heading becomes a disclosure button that shows and hides the items. Needs `label`. */
+    /**
+     * The heading shows and hides the items. Needs `label`.
+     */
     collapsible?: boolean;
-    /** Items shown (controlled; `collapsible` only). */
+    /**
+     * Items shown (controlled).
+     */
     open?: boolean;
-    /** Initial open state (uncontrolled). */
+    /**
+     * Initial state (uncontrolled). Off the compact rail a closed group opens by itself when the current page moves into it; on the rail it stays folded and its `…` row marks the page.
+     */
     defaultOpen?: boolean;
+    /**
+     * Called with the new open state (click, keyboard, a current page moving inside).
+     */
     onOpenChange?: (open: boolean) => void;
 };
 declare function SidebarGroup({ className, label, collapsible, open: openProp, defaultOpen, onOpenChange, children, ...rest }: SidebarGroupProps): import("react/jsx-runtime").JSX.Element;
@@ -84,6 +138,9 @@ declare namespace SidebarGroup {
     var displayName: string;
 }
 export type SidebarItemIconProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
+    /**
+     * The icon, e.g. `<Icon name="nav.home" />`; takes the item tier.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };
@@ -96,11 +153,17 @@ declare namespace SidebarItemIcon {
     var displayName: string;
 }
 export type SidebarItemCountProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children" | "color"> & {
-    /** The number (or a short status). */
+    /**
+     * The number (or a short status such as «!»).
+     */
     children: React.ReactNode;
-    /** Badge hue: the count needs attention. Without `color` and `variant` it is a plain number. */
+    /**
+     * Badge hue: the count needs attention.
+     */
     color?: PaletteColor;
-    /** Badge treatment (default `soft` once `color` is set). */
+    /**
+     * Badge treatment; `soft` once `color` is set.
+     */
     variant?: Exclude<Variant, "ghost">;
     /** The number `<span>` (the Badge when it has a hue). */
     ref?: React.Ref<HTMLSpanElement>;
@@ -115,7 +178,9 @@ declare namespace SidebarItemCount {
     var displayName: string;
 }
 export type SidebarItemShortcutProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
-    /** A key hint, e.g. `<Kbd>⌘K</Kbd>`. */
+    /**
+     * A key hint, e.g. `<Kbd>⌘K</Kbd>`.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };
@@ -124,46 +189,108 @@ declare function SidebarItemShortcut({ children, className, ...rest }: SidebarIt
 declare namespace SidebarItemShortcut {
     var displayName: string;
 }
-export type SidebarItemActionProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onClick" | "aria-label"> & {
-    /** Accessible name and tooltip of the action («Создать задачу»). */
+type SidebarItemActionBaseProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onClick" | "aria-label"> & {
+    /**
+     * Accessible name and tooltip («Создать задачу»).
+     */
     label: string;
-    onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * Not available.
+     */
     disabled?: boolean;
-    /** The glyph; a plus by default. */
-    children?: React.ReactNode;
     ref?: React.Ref<HTMLButtonElement>;
 };
+/** A button that runs `onClick`, or with `asChild` the one link it renders as (a page, `mailto:`). */
+export type SidebarItemActionProps = SidebarItemActionBaseProps & ({
+    /**
+     * Renders the single child (a link: another page, `mailto:`) as the action; its children are the glyph.
+     */
+    asChild?: false;
+    /**
+     * The action; required without `asChild`.
+     */
+    onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * The glyph (`<Icon name="action.add" />` by default), or with `asChild` the link around it.
+     */
+    children?: React.ReactNode;
+} | {
+    /**
+     * Renders the single child (a link: another page, `mailto:`) as the action; its children are the glyph.
+     */
+    asChild: true;
+    /**
+     * The action; required without `asChild`.
+     */
+    onClick?: never;
+    /**
+     * The glyph (`<Icon name="action.add" />` by default), or with `asChild` the link around it.
+     */
+    children: React.ReactElement;
+});
 /**
- * A small action at the end of the row (create, add): a ghost icon Button one tier down, shown on
- * hover and focus of the row. It sits next to the item element, never inside it.
+ * A small action at the end of the row (create, add): the kit row action (`internal/RowAction`, a
+ * ghost icon Button one tier down), shown on hover and focus of the row. It sits next to the item
+ * element, never inside it. With `asChild` it is a link with the same look.
  */
-declare function SidebarItemAction({ label, onClick, disabled, children, className, ...rest }: SidebarItemActionProps): import("react/jsx-runtime").JSX.Element;
+declare function SidebarItemAction({ label, children, className, ...rest }: SidebarItemActionProps): import("react/jsx-runtime").JSX.Element;
 declare namespace SidebarItemAction {
     var displayName: string;
 }
 type SidebarItemOwnProps = {
-    /** Current page: `aria-current="page"`. Links rendered by a router may set it themselves. */
+    /**
+     * Current page: `aria-current="page"`, `data-state="active"`; a muted fill and primary text and icon colour.
+     */
     current?: boolean;
+    /**
+     * Not interactive: `disabled` / `aria-disabled`, `data-disabled`; a link loses its `href`.
+     */
     disabled?: boolean;
-    /** Render the single child element (e.g. a router link) as the item; its children are the content. */
+    /**
+     * Renders the single child (e.g. a router `NavLink`) as the item; its children are the label and parts.
+     */
     asChild?: boolean;
     /**
-     * Label and parts: `Sidebar.ItemIcon` (leading, or trailing after the label),
-     * `Sidebar.ItemCount`, `Sidebar.ItemShortcut`, `Sidebar.ItemAction`.
+     * Label (also the compact tooltip) and parts: `Sidebar.ItemIcon` (before the label — leading, after it — trailing), `Sidebar.ItemCount`, `Sidebar.ItemShortcut`, `Sidebar.ItemAction`.
      */
     children?: React.ReactNode;
 };
-export type SidebarItemProps = SidebarItemOwnProps & Omit<React.ComponentPropsWithoutRef<"button">, keyof SidebarItemOwnProps> & {
-    /** Renders an `<a>` instead of a `<button>`. */
+export type SidebarItemProps = SidebarItemOwnProps & Omit<React.HTMLAttributes<HTMLElement>, keyof SidebarItemOwnProps> & {
+    /**
+     * Renders an `<a>` (with `target`, `rel`).
+     */
     href?: string;
+    /**
+     * Where the `<a>` opens (`href` only).
+     */
     target?: string;
+    /**
+     * Relationship of the `<a>` (`href` only).
+     */
     rel?: string;
+    ref?: React.Ref<HTMLElement>;
 };
+/**
+ * A row of the navigation: a link (`href`), a button, or the consumer's element (`asChild`, a
+ * router link) — the kit's interactive element with its disabled guard. Activating it closes the
+ * compact flyout and the off-canvas panel, unless `onClick` prevents the default.
+ */
+declare function SidebarItem({ current, disabled, asChild, href, target, rel, className, children, onClick, ...rest }: SidebarItemProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SidebarItem {
+    var displayName: string;
+}
 export type SidebarSubProps = React.ComponentProps<"div"> & {
-    /** Children shown (controlled). */
+    /**
+     * Children shown (controlled).
+     */
     open?: boolean;
-    /** Initial open state (uncontrolled). A sub-list also opens by itself when a child becomes current. */
+    /**
+     * Initial state (uncontrolled). Opens by itself when a child becomes the current page.
+     */
     defaultOpen?: boolean;
+    /**
+     * Called with the new open state (click, keyboard, a current page moving inside).
+     */
     onOpenChange?: (open: boolean) => void;
 };
 /**
@@ -175,9 +302,20 @@ declare namespace SidebarSub {
     var displayName: string;
 }
 export type SidebarSubTriggerProps = Omit<React.ComponentPropsWithoutRef<"button">, "aria-expanded" | "aria-controls"> & {
-    /** Label and parts, as in `Sidebar.Item`: `Sidebar.ItemIcon`, `Sidebar.ItemCount`. */
+    /**
+     * Label (it also names the flyout) and parts as in `Sidebar.Item`: `Sidebar.ItemIcon`, `Sidebar.ItemCount`.
+     */
     children?: React.ReactNode;
+    ref?: React.Ref<HTMLButtonElement>;
 };
+/**
+ * The parent row: a disclosure button with a chevron at the end. Expanded it shows / hides the
+ * children; on the rail it opens the flyout (hover, click, `Enter` · `Space` · `→`).
+ */
+declare function SidebarSubTrigger({ className, children, disabled, onClick, onKeyDown, onPointerEnter, onPointerLeave, ref, ...rest }: SidebarSubTriggerProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SidebarSubTrigger {
+    var displayName: string;
+}
 export type SidebarSubContentProps = Omit<React.ComponentProps<"div">, "role">;
 /** The children of a `Sidebar.Sub`: `Sidebar.Item`s on a faint guide line under the parent icon. */
 declare function SidebarSubContent({ className, children, ref, ...rest }: SidebarSubContentProps): import("react/jsx-runtime").JSX.Element;
@@ -185,7 +323,9 @@ declare namespace SidebarSubContent {
     var displayName: string;
 }
 export type SidebarBrandLogoProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
-    /** The product mark (`<img>`, `<svg>`); it fills a square on the icon axis. */
+    /**
+     * The mark: `<img>`, `<svg>` or a styled element.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };
@@ -195,94 +335,85 @@ declare namespace SidebarBrandLogo {
     var displayName: string;
 }
 export type SidebarBrandProps = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
-    /** Muted second line under the name (workspace, plan). */
+    /**
+     * Muted second line under the name (workspace, plan).
+     */
     description?: React.ReactNode;
-    /** Renders an `<a>` (usually home). */
+    /**
+     * Renders an `<a>` (usually home); navigating closes the off-canvas panel.
+     */
     href?: string;
-    /** Render the single child element (e.g. a router link) as the brand; its children are the content. */
+    /**
+     * Renders the single child (e.g. a router `Link`) as the brand; its children are the logo and the name.
+     */
     asChild?: boolean;
-    /** `Sidebar.BrandLogo` and the product name. */
+    /**
+     * `Sidebar.BrandLogo` and the product name.
+     */
     children?: React.ReactNode;
+    ref?: React.Ref<HTMLElement>;
 };
+/**
+ * Product block in `Sidebar.Header`: logo, name and a muted line; in compact only the logo stays.
+ * A link with `href`, the consumer's element with `asChild`, a button with only `onClick` (one way
+ * to reach it from the keyboard), else a static block. Activating it closes the off-canvas panel.
+ */
+declare function SidebarBrand({ description, href, asChild, className, children, onClick, ...rest }: SidebarBrandProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SidebarBrand {
+    var displayName: string;
+}
 export type SidebarAccountProps = Omit<React.ComponentPropsWithoutRef<"button">, "children"> & {
-    /** Muted second line under the name (email, role). */
+    /**
+     * Muted second line under the name (email, role).
+     */
     description?: React.ReactNode;
-    /** An `Avatar.Root` (sized to the tier by the slot) and the person's name. */
+    /**
+     * An `Avatar.Root` (sized to the tier by the slot, hidden from screen readers) and the person's name.
+     */
     children?: React.ReactNode;
+    ref?: React.Ref<HTMLButtonElement>;
 };
+/**
+ * The signed-in person at the bottom of the rail: avatar, name, a muted line and a chevron. A
+ * button, so it can be a `Dropdown.Trigger` child; in compact mode only the avatar stays.
+ */
+declare function SidebarAccount({ description, className, children, type, ...rest }: SidebarAccountProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SidebarAccount {
+    var displayName: string;
+}
 export type SidebarToggleProps = Omit<React.ComponentPropsWithoutRef<"button">, "children" | "aria-label" | "aria-expanded" | "aria-controls"> & {
     /**
-     * `item` — a row in the rail. `header` — a small icon button at the end of `Sidebar.Header`
-     * while expanded that moves onto the rail's outer edge as a round button in compact mode.
+     * In the rail: `item` — a row; `header` — a round icon button «‹‹» at the end of `Sidebar.Header` that moves onto the rail edge in compact mode.
      */
     variant?: "item" | "header";
+    ref?: React.Ref<HTMLButtonElement>;
 };
+/**
+ * Toggles expanded ↔ compact on desktop (hidden → expanded) and opens / closes the panel
+ * off-canvas. Inside the rail it reads the Sidebar; anywhere else in an `AppShell` (a header, a
+ * page toolbar) it reads the navigation the shell relays — the way back to a hidden rail. Its
+ * label comes from the Sidebar `labels`.
+ */
+declare function SidebarToggle(props: SidebarToggleProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SidebarToggle {
+    var displayName: string;
+}
 export declare const Sidebar: {
-    Root: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
-        /** Item tier: height, icon and text of `--prime-control-<size>-*`. */
-        size?: ControlSize;
-        mode?: SidebarMode;
-        defaultMode?: SidebarMode;
-        onModeChange?: (mode: SidebarMode) => void;
-        /** The off-canvas panel (while the sidebar is off-canvas, see `offCanvas`). */
-        open?: boolean;
-        defaultOpen?: boolean;
-        onOpenChange?: (open: boolean) => void;
-        /**
-         * When the rail becomes an off-canvas panel with a scrim and a focus trap, opened by `open`:
-         * `auto` below 768px, `always` at any width (navigation behind a menu button), `never`.
-         */
-        offCanvas?: "auto" | "always" | "never";
-        /**
-         * Remembers the state across reloads in `localStorage` under this key: the mode and which
-         * collapsible groups and sub-lists are open (by their `id`, else their label text). Controlled
-         * `mode` / `open` are not stored.
-         */
-        persistKey?: string;
-        labels?: Partial<SidebarLabels>;
-    } & React.RefAttributes<HTMLDivElement>>;
+    Root: typeof SidebarRoot;
     Header: typeof SidebarHeader;
-    Brand: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
-        /** Muted second line under the name (workspace, plan). */
-        description?: React.ReactNode;
-        /** Renders an `<a>` (usually home). */
-        href?: string;
-        /** Render the single child element (e.g. a router link) as the brand; its children are the content. */
-        asChild?: boolean;
-        /** `Sidebar.BrandLogo` and the product name. */
-        children?: React.ReactNode;
-    } & React.RefAttributes<HTMLElement>>;
+    Brand: typeof SidebarBrand;
     BrandLogo: typeof SidebarBrandLogo;
-    Content: React.ForwardRefExoticComponent<SidebarContentProps & React.RefAttributes<HTMLElement>>;
+    Content: typeof SidebarContent;
     Footer: typeof SidebarFooter;
     Group: typeof SidebarGroup;
-    Item: React.ForwardRefExoticComponent<SidebarItemOwnProps & Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">, keyof SidebarItemOwnProps> & {
-        /** Renders an `<a>` instead of a `<button>`. */
-        href?: string;
-        target?: string;
-        rel?: string;
-    } & React.RefAttributes<HTMLElement>>;
+    Item: typeof SidebarItem;
     ItemIcon: typeof SidebarItemIcon;
     ItemCount: typeof SidebarItemCount;
     ItemShortcut: typeof SidebarItemShortcut;
     ItemAction: typeof SidebarItemAction;
     Sub: typeof SidebarSub;
-    SubTrigger: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">, "aria-controls" | "aria-expanded"> & {
-        /** Label and parts, as in `Sidebar.Item`: `Sidebar.ItemIcon`, `Sidebar.ItemCount`. */
-        children?: React.ReactNode;
-    } & React.RefAttributes<HTMLButtonElement>>;
+    SubTrigger: typeof SidebarSubTrigger;
     SubContent: typeof SidebarSubContent;
-    Account: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">, "children"> & {
-        /** Muted second line under the name (email, role). */
-        description?: React.ReactNode;
-        /** An `Avatar.Root` (sized to the tier by the slot) and the person's name. */
-        children?: React.ReactNode;
-    } & React.RefAttributes<HTMLButtonElement>>;
-    Toggle: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">, "children" | "aria-controls" | "aria-expanded" | "aria-label"> & {
-        /**
-         * `item` — a row in the rail. `header` — a small icon button at the end of `Sidebar.Header`
-         * while expanded that moves onto the rail's outer edge as a round button in compact mode.
-         */
-        variant?: "item" | "header";
-    } & React.RefAttributes<HTMLButtonElement>>;
+    Account: typeof SidebarAccount;
+    Toggle: typeof SidebarToggle;
 };

package/dist/skill/SKILL.md

@@ -32,8 +32,8 @@ region, `Skeleton` while it loads).
    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.
+   with the `Sidebar`, page wrappers, auth screens. A screen you deliver renders its page: one
+   `Page.Root` with its top bar (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.
 4. **Read the component** — [components.md](components.md) links each `COMPONENT.md` (API, variants,
@@ -48,11 +48,11 @@ region, `Skeleton` while it loads).
    icon names.
 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.
-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. **Narrow screens** — [responsive.md](responsive.md): every screen works from 320px, the page's top bar
+   gives way by width itself, nothing is hidden on phones, touch follows `(hover)` / `(pointer)`.
 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.
+   in a browser ([ux.md](ux.md#9-look-at-it-before-handing-it-over)). Fix every «no», then hand
+   over.
 
 ## Where things are
 
@@ -65,7 +65,7 @@ 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>/…` |
+| AppShell, Sidebar, BottomNav, Page | `reference/layout/<dir>/…` | `node_modules/prime-ui-kit/src/layout/<dir>/…` |
 | Whole screens | `reference/<base>/<dir>/examples/screen.tsx` | `node_modules/prime-ui-kit/src/<base>/<dir>/examples/screen.tsx` |
 
 ## Files of this skill
@@ -81,7 +81,7 @@ project under `node_modules/prime-ui-kit/src/`.
 | [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 |
-| [responsive.md](responsive.md) | every screen — 320px and up, the page panel (`PageToolbar`), touch |
+| [responsive.md](responsive.md) | every screen — 320px and up, the page's top bar (`Page.TopBar`), touch |
 | [anti-slop.md](anti-slop.md) | before and after writing — what makes a screen look generated |
 | [checklist.md](checklist.md) | before handing the screen over |
 
@@ -89,7 +89,7 @@ project under `node_modules/prime-ui-kit/src/`.
 
 ```tsx
 import "prime-ui-kit/bundle.css"; // tokens, light + dark themes, component styles
-import "prime-ui-kit/fonts.css"; // optional: Golos Text + JetBrains Mono from Google Fonts
+import "prime-ui-kit/fonts.css"; // optional: Golos Text + JetBrains Mono, metric-matched fallbacks
 import "prime-ui-kit/reset.css"; // optional: minimal document reset (skip if the app has one)
 import { applyTheme } from "prime-ui-kit";
 
@@ -97,10 +97,10 @@ applyTheme("light"); // sets data-theme on <html>; "dark" for the dark theme
 ```
 
 Wrap the app in `NotificationProvider` if it shows toasts. Styles, `applyTheme`, `NotificationProvider`
-and `AppShell` belong to the app root, once. A screen component you deliver renders only its page
-(`PageContent…`) and assumes the root exists. If the project has no app frame yet, also deliver it as
-a separate `AppLayout` from [layouts.md](layouts.md#app-frame-once-per-app) — never inline the frame
-into a page.
+and `AppShell` belong to the app root, once. A screen component you deliver renders its page — one
+`Page.Root` with its `Page.TopBar` and its `Page.Body` — and assumes the root exists. If the project has no app
+frame yet, also deliver it as a separate root layout from
+[layouts.md](layouts.md#app-frame-once-per-app) — never inline the frame into a page.
 
 Icons: every glyph comes from the kit, and every kit icon is animated — its gesture plays when its
 button, link, tab, menu item or row is hovered or pressed, which gives the screen life with no code.
@@ -115,7 +115,7 @@ Take a semantic `<Icon name="…" />` first, else a glyph from the full animated
    lengths or hex (a raw length only in `@media` / `@container` conditions), no `--prime-ref-*`, no
    inline `style`.
 3. Depth from fill, not lines: Card on the panel, field inside the Card. No borders to separate blocks,
-   no card around a table, no card in a card.
+   no card around a table ([surfaces](foundations.md#4-fill-not-lines)).
 4. One size per row. Default `m` everywhere (omit `size`); change the tier for a whole region.
 5. Air is hierarchy: tighter inside a group, wider between groups, widest between sections — spacing via
    `gap` on the parent, never margins.
@@ -123,8 +123,8 @@ Take a semantic `<Icon name="…" />` first, else a glyph from the full animated
 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 `AppHeader.Title` in the page's header, `PageContent.Title` only on a
-   document page). No custom font sizes.
+   the page title is `Page.Title`, one per page: in the `Page.Heading` of `Page.TopBar` on a work screen, in the flow
+   on a document page or an overview). 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 && …}`.