prime-ui-kit 0.10.0 → 0.11.1

package/dist/internal/transcript.d.ts

@@ -0,0 +1,73 @@
+import * as React from "react";
+import type { SurfaceDepth } from "./surfaceDepth";
+/**
+ * The transcript of a voice or video message (VoicePlayer, VideoNote): a button that
+ * opens the text under the media, the text itself, and its request when the text is not known yet.
+ */
+export type TranscriptProps = {
+    /** The text of the recording, when it is known. With it or `onTranscribe` the button shows. */
+    transcript?: string;
+    /**
+     * Asks for the text when `transcript` is not known yet, on the first open. Return a Promise of the
+     * text: only the button spins and the area stays closed until it resolves, then it opens with the
+     * text; a rejection announces `transcribeFailed`. Returning nothing keeps the button spinning
+     * until the owner passes `transcript`.
+     */
+    onTranscribe?: () => Promise<string> | void;
+    /** The transcript is open (controlled). */
+    transcriptExpanded?: boolean;
+    /** Initially open (uncontrolled). Default `false`. */
+    defaultTranscriptExpanded?: boolean;
+    onTranscriptExpandedChange?: (expanded: boolean) => void;
+};
+export type TranscriptLabels = {
+    /** Name of the transcript button while the text is closed. */
+    transcribe: string;
+    /** Name of the transcript button while the text is open. */
+    hideTranscript: string;
+    /** Announced when `onTranscribe` rejects. */
+    transcribeFailed: string;
+};
+export declare const TRANSCRIPT_LABELS: TranscriptLabels;
+type RegionOptions = {
+    /** The message meta's spacer, at the end of the text's last line. */
+    spacer?: React.ReactNode;
+    /** The block that holds the text (a fill and padding under a video circle). */
+    className?: string;
+    /** The block is a surface of its own (under a video circle). */
+    depth?: SurfaceDepth;
+};
+export type Transcript = {
+    expanded: boolean;
+    /** Asked to open, the text is not there yet: the button spins, the area stays closed. */
+    pending: boolean;
+    toggle: () => void;
+    /** Props of the toggle button: its name and its relation to the text. */
+    buttonProps: {
+        "aria-expanded": boolean;
+        "aria-controls": string;
+        "aria-label": string;
+    };
+    /** The disclosure of the text and the announcement of a failed request. */
+    region: (options?: RegionOptions) => React.ReactNode;
+};
+/**
+ * The transcript's state: the expanded triad, the text (`transcript`, or what `onTranscribe`
+ * resolved), the request and its rollback. `null` when there is nothing to transcribe.
+ *
+ * The text always sits in a collapsed `Disclosure` under the media: opening and closing are one
+ * instant layout (the height and the text together) after `holdPosition` asks the chat to keep the
+ * view still. No JS measures or animates anything. Asked to open before the text is known, the
+ * area stays closed and only the button spins; the text opens once it is there — no placeholder
+ * that would change the bubble twice.
+ */
+export declare function useTranscript({ transcript, onTranscribe, transcriptExpanded, defaultTranscriptExpanded, onTranscriptExpandedChange, }: TranscriptProps, labels: TranscriptLabels): Transcript | null;
+/**
+ * The button's glyph: the transcript mark («→A») while closed, a chevron up while open; they
+ * cross-fade. The request's spinner is the Button's own `loading` (`internal/mediaPlayer`
+ * `TranscriptButton`).
+ */
+export declare function TranscriptGlyph({ expanded }: {
+    expanded: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/transfer.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Where a transfer of a file or a recording is, in either direction: `remote` — not fetched yet
+ * (the download arrow fetches it); `queued` — waiting its turn; `loading` — in flight; `failed` —
+ * stopped by an error (a retry sends or fetches it again); `done` — through. The values of
+ * `UploadItem.status` (without `remote`), so an upload queue item maps onto a message part as is.
+ */
+export type TransferState = "remote" | "queued" | "loading" | "failed" | "done";
+/**
+ * Which way it goes: `upload` — sending it, `download` — receiving it. It changes only the words
+ * (labels and announcements), never the look.
+ */
+export type TransferDirection = "upload" | "download";
+/** A cancel, a retry or a download: a returned promise keeps the disk pending until it settles. */
+export type TransferHandler = () => void | Promise<void>;
+/**
+ * The transfer props of every part that sends or receives its content (VoicePlayer, VideoNote,
+ * Message.File; Message.Media per item, its handlers per index).
+ */
+export type TransferProps = {
+    /** Where the transfer is; without it the content is simply there. */
+    transfer?: TransferState;
+    /** Share transferred, 0…1; without it a transfer in flight turns an indeterminate arc. */
+    transferProgress?: number;
+    /** Which way it goes: the words only. Default `upload`. */
+    transferDirection?: TransferDirection;
+    /** Cancel the transfer in flight (the disk's cross). */
+    onCancel?: TransferHandler;
+    /** Transfer it again after a failure (the danger disk). */
+    onRetry?: TransferHandler;
+    /** Fetch a `remote` content (the download arrow). */
+    onDownload?: TransferHandler;
+};
+/** The strings of a transfer, one shape for every part that transfers its content. */
+export type TransferLabels = {
+    /** The cross while sending. */
+    cancelUpload: string;
+    /** The cross while receiving. */
+    cancelDownload: string;
+    /** The retry after a failed send. */
+    retryUpload: string;
+    /** The retry after a failed receive. */
+    retryDownload: string;
+    /** The ring while sending: `{percent}`. */
+    uploadProgress: string;
+    /** The ring while receiving: `{percent}`. */
+    downloadProgress: string;
+    /** Why a send failed: the retry's description. */
+    notSent: string;
+    /** Why a receive failed: the retry's description. */
+    notReceived: string;
+    /** The download arrow of a `remote` content. */
+    download: string;
+    /** Announced when `onCancel` rejected. */
+    cancelFailed: string;
+    /** Announced when `onRetry` rejected. */
+    retryFailed: string;
+    /** Announced when `onDownload` rejected. */
+    downloadFailed: string;
+};
+export declare const TRANSFER_LABELS: TransferLabels;
+/** A transfer still in flight. */
+export declare const inFlight: (state: TransferState | undefined) => state is "loading" | "queued";
+/** The content is not there to use: in flight, failed or not fetched yet. */
+export declare const transferCovers: (state: TransferState | undefined) => state is "loading" | "remote" | "queued" | "failed";
+/** The strings the transfer disk reads, already resolved for one direction. */
+export type TransferDiskLabels = {
+    cancel?: string;
+    retry?: string;
+    download?: string;
+    /** The ring's name («Отправка 45%»). */
+    progress?: string | null;
+    /** On a failure: the reason, the retry's description. */
+    failed?: string | null;
+    cancelFailed?: string;
+    retryFailed?: string;
+    downloadFailed?: string;
+};
+/** The disk's strings from a part's transfer labels, for its direction and share. */
+export declare function transferDiskLabels(labels: TransferLabels, direction: TransferDirection, progress: number | undefined, tokens?: Record<string, string>): TransferDiskLabels;

package/dist/internal/transferDisk.d.ts

@@ -0,0 +1,76 @@
+import * as React from "react";
+import { type TransferDiskLabels, type TransferHandler, type TransferState } from "./transfer";
+export type TransferDiskProps = {
+    state: TransferState;
+    /** Share transferred, 0…1. Without it a transfer in flight turns an indeterminate arc. */
+    progress?: number;
+    /**
+     * `shade` (default) — Button `variant="shade"`: the media shade with a blur, over a picture, a
+     * video circle or a file's tile; `solid` — the accent disk of a voice message (recoloured by an
+     * outgoing bubble).
+     */
+    look?: "shade" | "solid";
+    /**
+     * `l` (default) — the control `l` disk (over media, the voice play disk); `xl` — the control
+     * `xl` round tile of a file in a bubble.
+     */
+    size?: "l" | "xl";
+    labels: TransferDiskLabels;
+    /** The cross while in flight; without it the disk carries only the ring. */
+    onCancel?: TransferHandler;
+    /** The retry after a failure; without it the failed disk only marks the failure. */
+    onRetry?: TransferHandler;
+    /** The download arrow of a `remote` content; without it the disk only marks it. */
+    onDownload?: TransferHandler;
+    /** The host saves the cancel itself (a tile's pending delete): the disk spins. */
+    cancelPending?: boolean;
+    /** The host is disabled: its action is off. */
+    disabled?: boolean;
+    className?: string;
+};
+type Action = "cancel" | "retry" | "download";
+export type TransferDiskModel = {
+    /** What a press does now, or `null` when the disk only shows the state. */
+    action: Action | null;
+    /** The handler of `action` was given. */
+    pressable: boolean;
+    /** A handler's promise (or the host's pending cancel) is in flight. */
+    busy: boolean;
+    /** The glyph in the disk: ×, the retry or download arrow, the failure mark, or a Spinner. */
+    glyph: React.ReactNode;
+    /** The disk's name. */
+    name: string | undefined;
+    /** For Button `progress`: the share in flight (`null` unknown), full when done, else none. */
+    progress: number | null | undefined;
+    failed: boolean;
+    /** The id of the disk's description (the share in flight, the reason of a failure). */
+    describedBy: string | undefined;
+    /** Hidden texts the disk refers to: its description and the live region of refusals. */
+    texts: React.ReactNode;
+    run: () => void;
+};
+/**
+ * The logic of a transfer disk, shared by `TransferDisk` and the play disk of the players (which
+ * draw it as one `Button shape="circle"`): what a press does in each state, a pending promise (no
+ * second press, `aria-busy`), the announcement of a refusal, the names and the description (the
+ * share in flight — «Отправка 45%» — or the reason of a failure).
+ */
+export declare function useTransferDisk({ state, progress, labels, onCancel, onRetry, onDownload, cancelPending, disabled, }: Omit<TransferDiskProps, "look" | "size" | "className">): TransferDiskModel;
+/**
+ * The transfer disk — the one look of a transfer in the kit, both ways: a `Button
+ * shape="circle"` whose `progress` ring runs along its inner edge in the glyph's color (the kit
+ * ring at the line weight, turning). In flight it is the cancel (×), described by the share;
+ * `remote` — the download arrow; a failure turns it danger with a retry arrow, described by the
+ * reason; done, the ring fills, then the disk fades and shrinks to 0.9 and leaves the focus order
+ * (`inert`). Without the handler of its state it is no button: a still disk with the ring, a
+ * named `progressbar` while in flight.
+ */
+export declare function TransferDisk({ look, size, className, ...props }: TransferDiskProps): import("react/jsx-runtime").JSX.Element;
+export type TransferOverlayProps = TransferDiskProps;
+/**
+ * The transfer disk centred over a box (an attachment tile, a picture in a chat message, a video
+ * circle). The host positions it (`position: absolute; inset: 0`) and dims its content while the
+ * transfer is not done; only the disk takes the pointer.
+ */
+export declare function TransferOverlay({ className, ...props }: TransferOverlayProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/useNearView.d.ts

@@ -0,0 +1,7 @@
+import * as React from "react";
+/**
+ * `true` once the element has come near the view of its scroller (half a viewport ahead) and from
+ * then on: heavy media (a video's first frame) mounts only then. Without IntersectionObserver it is
+ * `true` at once.
+ */
+export declare function useNearView(ref: React.RefObject<Element | null>): boolean;

package/dist/internal/usePendingChanges.d.ts

@@ -0,0 +1,18 @@
+/** Whether an event handler answered with a promise: the change it made is pending until it settles. */
+export declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;
+/**
+ * The changes an async event is still saving, drawn ahead of the owner's answer (the kit's
+ * async-event contract): `shown` is `value` with every pending change applied in order.
+ * `track(change, promise)` holds a change until its promise settles; on resolve `onResolve` runs in
+ * the same update that drops it (apply it to the stored value there, so nothing snaps back), on
+ * reject the change simply goes and `value` shows again. `apply` must be idempotent: an owner that
+ * applied the change already keeps it applied.
+ */
+export declare function usePendingChanges<T, Change>(value: T, apply: (value: T, change: Change) => T): {
+    shown: T;
+    pending: Change[];
+    track: (change: Change, promise: PromiseLike<unknown>, handlers?: {
+        onResolve?: () => void;
+        onReject?: (reason: unknown) => void;
+    }) => void;
+};

package/dist/internal/useRangeSelection.d.ts

@@ -0,0 +1,41 @@
+import * as React from "react";
+export type RangeSelectionOptions<K> = {
+    /**
+     * The items in their visual order: ranges and drags run over them. A function is read at the
+     * moment of the press (items whose order lives in the DOM).
+     */
+    keys: readonly K[] | (() => readonly K[]);
+    isSelected: (key: K) => boolean;
+    /** Set every key of `keys` to `value` (one commit per pointer step or click). */
+    apply: (keys: K[], value: boolean) => void;
+    /** The list: a drag paints only items inside it. */
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** The element under the pointer that stands for an item, with its index in `keys`. */
+    hit: (element: Element) => number | null;
+    /** A finger sliding from the pressed item paints too (its start sets `touch-action: none`). */
+    touch?: boolean;
+    /** The list's scroller follows a drag held at its top or bottom edge. */
+    autoScroll?: boolean;
+};
+export type RangeSelectionHandlers = {
+    /** A press on an item: starts a drag that sets every item it passes to the first one's new state. */
+    onPointerDown: (index: number, event: React.PointerEvent<HTMLElement>) => void;
+    /**
+     * A click on an item: toggles it, Shift sets the range from the anchor (the last clicked or
+     * dragged-over item) to it. A click that ends a drag is no toggle (the drag applied it).
+     */
+    onClick: (index: number, event: {
+        shiftKey: boolean;
+        detail: number;
+    }) => void;
+};
+/**
+ * Selection of a list like a file manager's (DataTable rows, chat messages in selection mode):
+ * click toggles, Shift+click selects the range from the anchor, press-and-drag (mouse, pen, a
+ * sliding finger when `touch`) paints every item it passes with the first item's new state, and a
+ * drag held at the scroller's edge scrolls it. The handlers are stable across renders.
+ */
+export declare function useRangeSelection<K>(options: RangeSelectionOptions<K>): {
+    handlers: RangeSelectionHandlers;
+    dragging: boolean;
+};

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

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { type DividerProps } from "@/components/divider/Divider";
+import { type DividerProps } from "../../components/divider/Divider";
 export type AppHeaderLabels = {
     /** Name of the menu button that opens the off-canvas Sidebar. */
     menu: string;
@@ -28,12 +28,18 @@ declare function AppHeaderStart({ className, ...rest }: AppHeaderStartProps): im
 declare namespace AppHeaderStart {
     var displayName: string;
 }
-export type AppHeaderTitleProps = DivProps;
+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";
+};
 /**
  * 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.
  */
-declare function AppHeaderTitle({ className, children, ...rest }: AppHeaderTitleProps): import("react/jsx-runtime").JSX.Element;
+declare function AppHeaderTitle({ as: NameTag, className, children, ...rest }: AppHeaderTitleProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppHeaderTitle {
     var displayName: string;
 }
@@ -77,6 +83,17 @@ declare function AppHeaderSearch({ children, shortcut, className, ...rest }: App
 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
+ * action): the header's second row, the full width under the title row, so the toolbar lays
+ * itself out from that width (one row when wide, two when narrow). Root moves it there wherever
+ * it is written.
+ */
+declare function AppHeaderTools({ className, ...rest }: AppHeaderToolsProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderTools {
+    var displayName: string;
+}
 export type AppHeaderActionsProps = DivProps;
 /** Buttons at the end: one primary action, notifications, the account. Never wraps. */
 declare function AppHeaderActions({ className, ...rest }: AppHeaderActionsProps): import("react/jsx-runtime").JSX.Element;
@@ -104,6 +121,7 @@ export declare const AppHeader: {
     Description: typeof AppHeaderDescription;
     Separator: typeof AppHeaderSeparator;
     Search: typeof AppHeaderSearch;
+    Tools: typeof AppHeaderTools;
     Actions: typeof AppHeaderActions;
     MenuButton: typeof AppHeaderMenuButton;
 };

package/dist/layout/bottom-nav/BottomNav.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-import type { PaletteColor, Variant } from "@/internal/states";
+import type { PaletteColor, Variant } from "../../internal/states";
 export type BottomNavLabels = {
     /** `aria-label` of the `<nav>` landmark. */
     nav: string;
@@ -9,22 +9,41 @@ export type BottomNavRootProps = React.HTMLAttributes<HTMLElement> & {
     iconOnly?: boolean;
     /**
      * A glass capsule floating over the content (backdrop blur, inset from the edges) instead of
-     * a flat bar at the edge. It places itself at the bottom of its positioned container
-     * (`AppShell.Footer`), so the page scrolls under it.
+     * a flat bar at the edge, with a selection capsule that glides to the current item. It places
+     * itself at the bottom of its positioned container (`AppShell.Footer`), so the page scrolls
+     * under it.
      */
     floating?: boolean;
     labels?: Partial<BottomNavLabels>;
-    /** The `<nav>` bar. */
+    /** The `<nav>`. */
     ref?: React.Ref<HTMLElement>;
 };
 /**
- * Phone navigation: a bar of 3–5 sections at the bottom of the screen. Inside `AppShell.Footer`
- * it shows only while the content panel is narrower than 640px; wider, Sidebar navigates.
+ * Phone navigation: a bar of 2–6 sections at the bottom of the screen, optionally with a round
+ * action beside it. Inside `AppShell.Footer` it shows only while the Sidebar rail is off screen;
+ * once the rail is on screen, Sidebar navigates.
  */
-declare function BottomNavRoot({ iconOnly, floating, labels, className, ...rest }: BottomNavRootProps): import("react/jsx-runtime").JSX.Element;
+declare function BottomNavRoot({ iconOnly, floating, labels, className, children, ...rest }: BottomNavRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace BottomNavRoot {
     var displayName: string;
 }
+export type BottomNavActionProps = Omit<React.ComponentPropsWithoutRef<"button">, "children"> & {
+    /** The glyph, e.g. `<Icon name="action.add" />`. */
+    children: React.ReactNode;
+    /** The action has no visible text: `aria-label` names it. */
+    "aria-label": string;
+    ref?: React.Ref<HTMLButtonElement>;
+};
+/**
+ * A round button beside the bar for the screen's main action (create, search, assistant): a
+ * `Button shape="circle"` (`l`, neutral) — in a flat bar a muted disk at its edge, in `floating` a
+ * glass disk as tall as the capsule (the capsule's own glass, set on the Button by class: Button
+ * has no glass look).
+ */
+declare function BottomNavAction({ className, children, ...rest }: BottomNavActionProps): import("react/jsx-runtime").JSX.Element;
+declare namespace BottomNavAction {
+    var displayName: string;
+}
 export type BottomNavItemIconProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
@@ -76,5 +95,6 @@ export declare const BottomNav: {
     Item: typeof BottomNavItem;
     ItemIcon: typeof BottomNavItemIcon;
     ItemCount: typeof BottomNavItemCount;
+    Action: typeof BottomNavAction;
 };
 export {};

package/dist/layout/index.d.ts

@@ -1,8 +1,8 @@
-export type { AppHeaderActionsProps, AppHeaderDescriptionProps, AppHeaderIconProps, AppHeaderLabels, AppHeaderMenuButtonProps, AppHeaderRootProps, AppHeaderSearchProps, AppHeaderSeparatorProps, AppHeaderStartProps, AppHeaderTitleProps, } from "./app-header/AppHeader";
+export type { AppHeaderActionsProps, AppHeaderDescriptionProps, AppHeaderIconProps, AppHeaderLabels, AppHeaderMenuButtonProps, AppHeaderRootProps, AppHeaderSearchProps, 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";
-export type { BottomNavItemCountProps, BottomNavItemIconProps, BottomNavItemProps, BottomNavLabels, BottomNavRootProps, } from "./bottom-nav/BottomNav";
+export type { BottomNavActionProps, BottomNavItemCountProps, BottomNavItemIconProps, BottomNavItemProps, BottomNavLabels, BottomNavRootProps, } from "./bottom-nav/BottomNav";
 export { BottomNav } from "./bottom-nav/BottomNav";
 export type { SidebarAccountProps, SidebarBrandLogoProps, SidebarBrandProps, SidebarContentProps, SidebarFooterProps, SidebarGroupProps, SidebarHeaderProps, SidebarItemActionProps, SidebarItemCountProps, SidebarItemIconProps, SidebarItemProps, SidebarItemShortcutProps, SidebarLabels, SidebarMode, SidebarRootProps, SidebarSubContentProps, SidebarSubProps, SidebarSubTriggerProps, SidebarToggleProps, } from "./sidebar/Sidebar";
 export { Sidebar, useSidebar } from "./sidebar/Sidebar";

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

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { type ControlSize, type PaletteColor, type Variant } from "@/internal/states";
+import { type ControlSize, type PaletteColor, type Variant } from "../../internal/states";
 /** Desktop rail mode: full width, icon rail, or collapsed to zero width. */
 export type SidebarMode = "expanded" | "compact" | "hidden";
 export type SidebarLabels = {

package/dist/skill/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: prime-ui-kit
+description: >
+  Build product UI with prime-ui-kit (React 19, CSS Modules, --prime-* tokens) the way its author would.
+  Use when laying out screens, forms, tables, boards, schedules, chats, dashboards, settings or
+  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.
+---
+
+# prime-ui-kit
+
+You build screens only from kit components and `--prime-*` tokens, on the kit's own page skeleton.
+Every visually repeated element is one component. The goal: a screen that looks as if the kit's author
+polished it for weeks — one rhythm, one size, one primary action, fill instead of lines, a state for
+every region, and states that flow into each other instead of flipping (`Crossfade` around every
+region, `Skeleton` while it loads).
+
+## How to use this skill
+
+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
+   that are easy to confuse.
+3. **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
+   [foundations.md](foundations.md).
+5. **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
+   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
+   `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.
+
+## Where things are
+
+Every component link in this skill opens that component's `COMPONENT.md` (API, variants, states,
+a11y, mistakes) or its `examples/` — follow the link, never guess a prop. The installed skill carries
+them under `reference/`; the same files are in the kit repository under `src/` and in a consumer
+project under `node_modules/prime-ui-kit/src/`.
+
+| What | Installed skill | Consumer project |
+|---|---|---|
+| 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` |
+
+## Files of this skill
+
+| File | Read when |
+|---|---|
+| [cheatsheet.md](cheatsheet.md) | first — the most frequent decisions and mistakes in one page |
+| [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 |
+| [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 |
+| [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 |
+
+## Setup (once per app)
+
+```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/reset.css"; // optional: minimal document reset (skip if the app has one)
+import { applyTheme } from "prime-ui-kit";
+
+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.
+
+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.
+Take a semantic `<Icon name="…" />` first, else a glyph from the full animated set
+`prime-ui-kit/icons` (`<BellIcon />`, about 500); only a glyph neither has goes through
+`createIcon` with `lucide-react`. Order, names and the full list: [api-contract.md](api-contract.md#icons).
+
+## Ten rules
+
+1. Kit component first. A `div` that looks like a Card, Badge, Divider or Kbd is a bug.
+2. Tokens only: `--prime-space-*`, `--prime-color-*`, `--prime-radius-*`, `--prime-text-*`. No raw
+   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.
+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.
+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.
+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.
+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 && …}`.
+10. No decoration: no emoji, no icons that do not carry meaning, no explanatory text nobody asked for.
+    Icons that do carry meaning come from the kit only (`<Icon name>`, `prime-ui-kit/icons`) — they
+    are animated.
+
+## Component structure
+
+Components with parts are used through them: `Button.Root` + `Button.Icon`,
+`Modal.Root > Modal.Content > Modal.Body`; the namespace itself is not a component (`<Button>` is
+invalid, `<Button.Root>` is right). Leaves without parts are single exports (`<Typography>`,
+`<Skeleton>`, `<DataTable>`, `<Sparkline>`… — the full list in [api-contract.md](api-contract.md)). Data-driven
+components take data as props: `DataTable` (`columns`, `rows`), `Gantt` (`rows`, `getRowBars`), `Kanban`
+(`columns`, `items`), `TagSelect` (`options`), `SmartFilter` (`fields`), `ProgressBar` (`segments`).