prime-ui-kit 0.0.1

package/src/components/banner/examples/controlled-visibility.tsx

@@ -0,0 +1,42 @@
+import { Info } from "lucide-react";
+import { Banner, Button } from "prime-ui-kit";
+import { useState } from "react";
+
+/** Show and hide by mounting the root; external control restores the strip (no `open` prop). */
+export default function BannerControlledVisibilityExample() {
+  const [visible, setVisible] = useState(true);
+
+  return (
+    <>
+      {!visible ? (
+        <Button.Root size="s" type="button" variant="neutral" onClick={() => setVisible(true)}>
+          Show announcement
+        </Button.Root>
+      ) : null}
+      {visible ? (
+        <Banner.Root status="feature" variant="lighter">
+          <Banner.Content>
+            <Banner.Icon as={Info} aria-hidden />
+            <Banner.Title>Controlled visibility</Banner.Title>
+            <Banner.Description>
+              Removing the node from the tree hides the banner; use parent state to show it again.
+            </Banner.Description>
+            <Banner.Actions>
+              <Button.Root mode="ghost" size="s" type="button" variant="neutral">
+                Learn more
+              </Button.Root>
+              <Button.Root
+                size="s"
+                type="button"
+                variant="primary"
+                onClick={() => setVisible(false)}
+              >
+                Hide
+              </Button.Root>
+            </Banner.Actions>
+          </Banner.Content>
+        </Banner.Root>
+      ) : null}
+    </>
+  );
+}

package/src/components/banner/examples/cookie-consent-row.tsx

@@ -0,0 +1,35 @@
+import { Cookie } from "lucide-react";
+
+import { Banner, Button, LinkButton } from "prime-ui-kit";
+
+/** Inline consent row: actions for accept / preferences; optional dismiss defers to product policy. */
+export default function CookieConsentRowExample() {
+  return (
+    <Banner.Root
+      aria-labelledby="cookie-banner-title"
+      role="region"
+      status="information"
+      variant="lighter"
+      onDismiss={() => {
+        /* product: defer / snooze — follow local privacy rules */
+      }}
+    >
+      <Banner.Content>
+        <Banner.Icon as={Cookie} aria-hidden />
+        <Banner.Title id="cookie-banner-title">Cookies and similar technologies</Banner.Title>
+        <Banner.Description>
+          We use cookies to run the site, remember preferences, and measure usage. See our policy
+          for details.
+        </Banner.Description>
+        <Banner.Actions>
+          <Button.Root size="s" type="button" variant="primary">
+            Accept essential
+          </Button.Root>
+          <LinkButton.Root href="/settings/cookies" size="s">
+            Manage preferences
+          </LinkButton.Root>
+        </Banner.Actions>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}

package/src/components/banner/examples/dismiss-close-button.tsx

@@ -0,0 +1,26 @@
+import { CheckCircle2 } from "lucide-react";
+
+import { Banner } from "prime-ui-kit";
+
+/**
+ * Explicit `Banner.CloseButton` as a direct child of `Banner.Root` (sibling of `Banner.Content`).
+ * No `onDismiss` on the root — the kit does not inject a second close control.
+ */
+export default function BannerDismissCloseButtonExample() {
+  return (
+    <Banner.Root status="success" variant="lighter">
+      <Banner.Content>
+        <Banner.Icon as={CheckCircle2} aria-hidden />
+        <Banner.Title>Changes saved</Banner.Title>
+        <Banner.Description>Your profile was updated successfully.</Banner.Description>
+      </Banner.Content>
+      <Banner.CloseButton
+        aria-label="Dismiss confirmation"
+        type="button"
+        onClick={() => {
+          /* product: hide banner */
+        }}
+      />
+    </Banner.Root>
+  );
+}

package/src/components/banner/examples/feature-promo.tsx

@@ -0,0 +1,35 @@
+import { Sparkles } from "lucide-react";
+
+import { Banner, Button } from "prime-ui-kit";
+
+/** Product promo: feature palette, lighter fill, compact actions. */
+export default function FeaturePromoExample() {
+  return (
+    <Banner.Root
+      aria-labelledby="feature-banner-title"
+      role="region"
+      status="feature"
+      variant="lighter"
+      onDismiss={() => {
+        /* product: persist dismissal (localStorage / profile flag) */
+      }}
+    >
+      <Banner.Content>
+        <Banner.Icon as={Sparkles} aria-hidden />
+        <Banner.Title id="feature-banner-title">New: shared workspaces</Banner.Title>
+        <Banner.Description>
+          Invite teammates, assign roles, and keep projects in one place. Available on Pro and
+          Enterprise.
+        </Banner.Description>
+        <Banner.Actions>
+          <Button.Root size="s" type="button" variant="primary">
+            Try workspaces
+          </Button.Root>
+          <Button.Root mode="ghost" size="s" type="button" variant="neutral">
+            What&apos;s new
+          </Button.Root>
+        </Banner.Actions>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}

package/src/components/banner/examples/maintenance.tsx

@@ -0,0 +1,23 @@
+import { Wrench } from "lucide-react";
+
+import { Banner, LinkButton } from "prime-ui-kit";
+
+/** Scheduled downtime: visible but non-blocking; stroke keeps the bar calm on neutral chrome. */
+export default function MaintenanceBannerExample() {
+  return (
+    <Banner.Root aria-label="Scheduled maintenance" role="region" status="warning" variant="stroke">
+      <Banner.Content>
+        <Banner.Icon as={Wrench} aria-hidden />
+        <Banner.Title>Scheduled maintenance</Banner.Title>
+        <Banner.Description>
+          Brief downtime tonight, 02:00–03:00 UTC. APIs and the dashboard may be unavailable.
+        </Banner.Description>
+        <Banner.Actions>
+          <LinkButton.Root href="/status" size="s">
+            Status page
+          </LinkButton.Root>
+        </Banner.Actions>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}

package/src/components/breadcrumb/COMPONENT.md

@@ -0,0 +1,139 @@
+# Breadcrumb
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## Canonical
+
+**What it is:** A `nav` with an ordered list (`ol`) of trail segments. **`Breadcrumb.Item`** with **`href`** uses **`LinkButton`**; without **`href`** it is plain text. **`Breadcrumb.Separator`** defaults to a subtle chevron icon; **`Breadcrumb.Ellipsis`** renders a static middle collapse marker (`…`). **`Breadcrumb.Root`** sets **`size`** (`s` | `m` | `l` | `xl`) for links, current text, ellipsis, and the default separator icon via context and **`ControlSizeProvider`**.
+
+**When to use**
+
+- Hierarchical URLs (docs, catalog, admin) where jumping to a parent beats reopening the main nav.
+- Deep screens (orders, settings leaf pages) to answer “where am I”.
+- Long trails where you manually keep root, near parent, and leaf and insert **`Ellipsis`** for skipped middle levels.
+
+**When not to use**
+
+- Primary IA — sidebars and top nav own top-level structure; breadcrumbs are supplemental.
+- Flat or two-level apps — a title or back control may be enough.
+- Need to pick hidden levels — **`Ellipsis`** is not interactive; use a dropdown or popover separately.
+- As the only page heading — keep a real **`h1`** (or [Typography](../typography/COMPONENT.md)); breadcrumbs do not replace it.
+
+**Minimal pattern**
+
+```tsx
+import { Breadcrumb } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Breadcrumb.Root>
+      <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item current>Current page</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}
+```
+
+**Non‑negotiables**
+
+- **Current page:** omit **`href`** on the active segment and set **`current`**. With **`href`**, the segment is always a link and does **not** get **`aria-current="page"`**.
+- **List semantics:** only **`Item`**, **`Separator`**, and **`Ellipsis`** as **direct** children of **`Root`** (each renders an **`li`**). Do not inject arbitrary wrappers inside the list.
+- **No routing API:** URLs and navigation are app-owned; there is no `asChild`, no controlled “value”, and **no built‑in auto-collapse** — you place **`Ellipsis`** where you want it.
+
+**Runnable examples (package import)**
+
+| Scenario | File |
+|----------|------|
+| Minimal trail | [`examples/canonical.tsx`](./examples/canonical.tsx) |
+| Four `size` rows (`s`–`xl` on `Root`) | [`examples/sizes.tsx`](./examples/sizes.tsx) |
+| Links + `current`; middle segment without `href` | [`examples/states.tsx`](./examples/states.tsx) |
+| Icon-only first `Item` (`aria-label`) + custom `Separator` | [`examples/composition.tsx`](./examples/composition.tsx) |
+| Narrow container; trail wraps (`flex-wrap`) | [`examples/full-width.tsx`](./examples/full-width.tsx) |
+| Long path + `Ellipsis` | [`examples/long-path-ellipsis.tsx`](./examples/long-path-ellipsis.tsx) |
+| Deep docs path | [`examples/deep-documentation.tsx`](./examples/deep-documentation.tsx) |
+| E‑commerce PDP | [`examples/ecommerce-product.tsx`](./examples/ecommerce-product.tsx) |
+| SaaS settings hierarchy | [`examples/saas-settings.tsx`](./examples/saas-settings.tsx) |
+
+**Playground snippets** (app alias `@/…`, same scenarios as the rows above where noted)
+
+| File | Coverage |
+|------|----------|
+| [`playground/snippets/breadcrumb/sizes.tsx`](../../../playground/snippets/breadcrumb/sizes.tsx) | `size` `s`–`xl` |
+| [`playground/snippets/breadcrumb/states.tsx`](../../../playground/snippets/breadcrumb/states.tsx) | Links + `current`; `Item` without `href` |
+| [`playground/snippets/breadcrumb/composition.tsx`](../../../playground/snippets/breadcrumb/composition.tsx) | Home icon + `/` separators |
+| [`playground/snippets/breadcrumb/full-width.tsx`](../../../playground/snippets/breadcrumb/full-width.tsx) | Narrow box; long labels wrap |
+| [`playground/snippets/breadcrumb/long-ellipsis.tsx`](../../../playground/snippets/breadcrumb/long-ellipsis.tsx) | Same trail shape as `long-path-ellipsis.tsx` (Russian copy in playground) |
+
+---
+
+## Extended
+
+### Composition
+
+- **`Breadcrumb.Root`** — `nav` with default **`aria-label="Breadcrumb"`**; spread **`…rest`** for overrides (e.g. localized label). Inner structure is a single **`ol`**.
+- **Typical sequence:** `[Item] [Separator] [Item] [Separator] … [Item]`; for a collapsed middle, use **`[Item] [Separator] … [Ellipsis] [Separator] … [Item]`** as in [`long-path-ellipsis.tsx`](./examples/long-path-ellipsis.tsx).
+- **`Separator`** — **`aria-hidden="true"`**; override **`children`** for `/`, `>`, or other glyphs.
+- **Icon-only first item** — set **`aria-label`** on **`Item`** when **`href`** is set and there is no visible text.
+
+### Scenarios (extended)
+
+1. **Deep documentation path** — mirror the doc tree so each segment links to its index page; last segment is current text ([`deep-documentation.tsx`](./examples/deep-documentation.tsx)).
+2. **E‑commerce** — storefront → category → subcategory → … → SKU name; every ancestor is a link, PDP title is **`current`** ([`ecommerce-product.tsx`](./examples/ecommerce-product.tsx)).
+3. **SaaS settings hierarchy** — org → settings area → section → leaf (e.g. invoices); matches how admins mental-model nested admin URLs ([`saas-settings.tsx`](./examples/saas-settings.tsx)).
+4. **Long trail + ellipsis** — show first levels and the tail; **`Ellipsis`** stands in for omitted middle **only visually** — screen readers still read the visible segments in order ([`long-path-ellipsis.tsx`](./examples/long-path-ellipsis.tsx)). On very narrow viewports the row may **wrap** (flex wrap in styles); do not rely on breadcrumbs alone for mobile orientation if the path is long.
+
+### Rules
+
+- **`Item` props are not an escape hatch** — only **`href`**, **`current`**, **`children`**, **`className`**, and **`aria-label`**; extra **`li`** attributes are not forwarded.
+- **No disabled, loading, or error props** on **`Item`**.
+- **Separators** are decorative; meaning lives in **`Item`** labels and route targets.
+
+### API
+
+#### Breadcrumb.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | `Item`, `Separator`, and `Ellipsis` as direct children of the inner `ol` |
+| className | `string` | — | no | Extra class on the `nav` |
+| size | `BreadcrumbSize` | `"m"` | no | Scale for links, current text, ellipsis, default separator icon (`"s"` \| `"m"` \| `"l"` \| `"xl"`) |
+| …rest | `React.HTMLAttributes<HTMLElement>` | — | no | Additional attributes on the `nav` |
+
+#### Breadcrumb.Item
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| href | `string` | — | no | If set, renders `LinkButton`; otherwise renders a `span` |
+| current | `boolean` | — | no | Current-page styling and `aria-current="page"` on the `span` when there is no `href` |
+| children | `React.ReactNode` | — | no | Label or custom content (e.g. icon) |
+| className | `string` | — | no | Class on the `li` |
+| aria-label | `string` | — | no | For link items without visible text (e.g. icon-only home) |
+
+#### Breadcrumb.Separator
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | `Icon` `nav.chevronRight` (`tone="subtle"`) | no | Custom separator content |
+| className | `string` | — | no | Class on the `li` |
+
+#### Breadcrumb.Ellipsis
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | no | Class on the `li` that displays the ellipsis character |
+
+### Related
+
+- [LinkButton](../link-button/COMPONENT.md) — used inside `Item` when `href` is set.
+- [Typography](../typography/COMPONENT.md) — page titles and captions beside the trail.
+
+---
+
+## Note for LLM and codegen
+
+- Import **`Breadcrumb`** from **`prime-ui-kit`**; compose **`Root` → `Item` / `Separator` / `Ellipsis`** only — no hidden slots or `asChild`.
+- Mark the active route with **`current`** and **no `href`** on that **`Item`**; otherwise **`aria-current="page"`** will not apply.
+- Collapsing the path is **manual**: insert **`Breadcrumb.Ellipsis`** between **`Separator`** nodes; it is **not** a menu and does not expose hidden links to assistive tech.
+- Icon-only links require **`aria-label`** on **`Item`**.
+- For copy-paste recipes, prefer the files under **`src/components/breadcrumb/examples/`** (including **`sizes`**, **`states`**, **`composition`**, **`full-width`** aligned with playground); for interactive kit demos see **`playground/snippets/breadcrumb/`**.

package/src/components/breadcrumb/examples/canonical.tsx

@@ -0,0 +1,12 @@
+import { Breadcrumb } from "prime-ui-kit";
+
+/** Smallest valid trail: previous level as link, current page as text with `current`. */
+export default function BreadcrumbCanonicalExample() {
+  return (
+    <Breadcrumb.Root>
+      <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item current>Current page</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}

package/src/components/breadcrumb/examples/composition.tsx

@@ -0,0 +1,25 @@
+import { Breadcrumb, Icon } from "prime-ui-kit";
+
+/** Icon-only first item (`aria-label`) and custom `Separator` children. Matches playground `snippets/breadcrumb/composition.tsx`. */
+export default function BreadcrumbCompositionExample() {
+  return (
+    <Breadcrumb.Root>
+      <Breadcrumb.Item href="/help" aria-label="Help home">
+        <span
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            justifyContent: "center",
+            lineHeight: 0,
+          }}
+        >
+          <Icon name="nav.home" tone="default" />
+        </span>
+      </Breadcrumb.Item>
+      <Breadcrumb.Separator>/</Breadcrumb.Separator>
+      <Breadcrumb.Item href="/help/billing">Billing</Breadcrumb.Item>
+      <Breadcrumb.Separator>/</Breadcrumb.Separator>
+      <Breadcrumb.Item current>Refunds</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}

package/src/components/breadcrumb/examples/deep-documentation.tsx

@@ -0,0 +1,16 @@
+import { Breadcrumb } from "prime-ui-kit";
+
+/** Docs IA: section → subsection → article (no ellipsis). */
+export default function BreadcrumbDeepDocumentationExample() {
+  return (
+    <Breadcrumb.Root>
+      <Breadcrumb.Item href="/docs">Documentation</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item href="/docs/guides">Guides</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item href="/docs/guides/accessibility">Accessibility</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item current>Focus order</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}

package/src/components/breadcrumb/examples/ecommerce-product.tsx

@@ -0,0 +1,18 @@
+import { Breadcrumb } from "prime-ui-kit";
+
+/** Storefront hierarchy down to a product detail page. */
+export default function BreadcrumbEcommerceProductExample() {
+  return (
+    <Breadcrumb.Root>
+      <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item href="/catalog">Catalog</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item href="/catalog/furniture">Furniture</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item href="/catalog/furniture/chairs">Chairs</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item current>Ergo Mesh Pro</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}

package/src/components/breadcrumb/examples/full-width.tsx

@@ -0,0 +1,24 @@
+import { Breadcrumb } from "prime-ui-kit";
+
+/**
+ * Narrow container so the inner `ol` wraps (`flex-wrap` in component styles). Matches playground `snippets/breadcrumb/full-width.tsx`.
+ */
+export default function BreadcrumbFullWidthExample() {
+  return (
+    <div
+      style={{
+        maxWidth: 200,
+        padding: "8px",
+        border: "1px dashed var(--prime-sys-color-border-default)",
+      }}
+    >
+      <Breadcrumb.Root>
+        <Breadcrumb.Item href="/org">Transit LLC</Breadcrumb.Item>
+        <Breadcrumb.Separator />
+        <Breadcrumb.Item href="/org/hubs">Hubs</Breadcrumb.Item>
+        <Breadcrumb.Separator />
+        <Breadcrumb.Item current>East terminal</Breadcrumb.Item>
+      </Breadcrumb.Root>
+    </div>
+  );
+}

package/src/components/breadcrumb/examples/long-path-ellipsis.tsx

@@ -0,0 +1,21 @@
+import { Breadcrumb } from "prime-ui-kit";
+
+/**
+ * Collapsed middle: you choose which segments stay visible; `Ellipsis` is static text, not a menu.
+ * Pair each part with `Separator` between items (including around the ellipsis).
+ */
+export default function BreadcrumbLongPathEllipsisExample() {
+  return (
+    <Breadcrumb.Root>
+      <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item href="/catalog">Catalog</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Ellipsis />
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item href="/catalog/furniture/chairs/office">Office chairs</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item current>Model X</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}

package/src/components/breadcrumb/examples/saas-settings.tsx

@@ -0,0 +1,16 @@
+import { Breadcrumb } from "prime-ui-kit";
+
+/** Org → area → section → leaf screen in admin / settings. */
+export default function BreadcrumbSaasSettingsExample() {
+  return (
+    <Breadcrumb.Root>
+      <Breadcrumb.Item href="/orgs/acme">Acme Inc</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item href="/orgs/acme/settings">Workspace settings</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item href="/orgs/acme/settings/billing">Billing</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item current>Invoices</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}

package/src/components/breadcrumb/examples/sizes.tsx

@@ -0,0 +1,25 @@
+import { Breadcrumb, type BreadcrumbSize } from "prime-ui-kit";
+
+function BreadcrumbSizeRow({ size }: { size: BreadcrumbSize }) {
+  return (
+    <Breadcrumb.Root size={size}>
+      <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item href="/catalog">Catalog</Breadcrumb.Item>
+      <Breadcrumb.Separator />
+      <Breadcrumb.Item current>Page</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}
+
+/** Four stacked trails: `size` `s` → `xl` on `Breadcrumb.Root` (matches playground `snippets/breadcrumb/sizes.tsx`). */
+export default function BreadcrumbSizesExample() {
+  return (
+    <>
+      <BreadcrumbSizeRow size="s" />
+      <BreadcrumbSizeRow size="m" />
+      <BreadcrumbSizeRow size="l" />
+      <BreadcrumbSizeRow size="xl" />
+    </>
+  );
+}

package/src/components/breadcrumb/examples/states.tsx

@@ -0,0 +1,26 @@
+import { Breadcrumb } from "prime-ui-kit";
+
+/**
+ * Top: ancestors as links, leaf with `current`. Bottom: middle segment without `href` renders as plain text (`span`).
+ * Matches playground `snippets/breadcrumb/states.tsx`.
+ */
+export default function BreadcrumbStatesExample() {
+  return (
+    <>
+      <Breadcrumb.Root>
+        <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
+        <Breadcrumb.Separator />
+        <Breadcrumb.Item href="/orders">Orders</Breadcrumb.Item>
+        <Breadcrumb.Separator />
+        <Breadcrumb.Item current>Order #1042</Breadcrumb.Item>
+      </Breadcrumb.Root>
+      <Breadcrumb.Root>
+        <Breadcrumb.Item href="/courses">Courses</Breadcrumb.Item>
+        <Breadcrumb.Separator />
+        <Breadcrumb.Item>Module 3</Breadcrumb.Item>
+        <Breadcrumb.Separator />
+        <Breadcrumb.Item current>Lesson: introduction</Breadcrumb.Item>
+      </Breadcrumb.Root>
+    </>
+  );
+}

package/src/components/button/COMPONENT.md

@@ -0,0 +1,106 @@
+# Button
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Compound control for actions: a root that renders a native `<button>` (or merges props into one child with `asChild`), plus optional icon and loading indicator parts that share size via context.
+
+- **Use** for primary, secondary, or destructive actions in forms, toolbars, dialogs, and empty states; submit/reset in forms; triggers that must look like a button.
+- **Use** for async actions where you set `loading` on `Button.Root` and optionally render `Button.Spinner` next to the label.
+- **Use** for full-width actions in narrow layouts via `fullWidth`.
+- **Do not use** for navigation that should be a plain link semantically (consider [Link button](../link-button/COMPONENT.md) or `asChild` with a link).
+- **Do not use** for binary on/off or multi-option selection (use [Switch](../switch/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Segmented control](../segmented-control/COMPONENT.md), etc.).
+- **Do not use** when several related buttons need shared chrome and spacing (see [Button group](../button-group/COMPONENT.md)).
+
+## Composition
+
+- **`Button.Root`** — required wrapper. Provides size to descendants via `ControlSizeProvider` (including in `asChild` mode). Place all other parts inside it.
+- **`Button.Icon`** — optional; wraps the icon in a `span` with `aria-hidden="true"`. Use for decorative icons next to text.
+- **`Button.Spinner`** — optional; renders nothing unless the nearest `Button.Root` has `loading={true}`. Place it inside `Button.Root` with visible text or a clear `aria-label`; order relative to the label is up to you.
+
+### Minimal example
+
+```tsx
+import { Button } from "prime-ui-kit";
+
+export function Example() {
+  return <Button.Root>Save</Button.Root>;
+}
+```
+
+### Canonical composition (reference)
+
+For **icon + label**, **several `variant` / `mode` pairs**, and **`loading` with `Button.Spinner`**, open **`examples/canonical-composition.tsx`** next to this file. Imports use **`"prime-ui-kit"`** so the same snippets work in an app after installing the package.
+
+The playground Button section (`playground/sections/ButtonSection.tsx`) renders snippets from `playground/snippets/button/*.tsx`. The examples **`sizes-ladder`**, **`icon-composition`**, and **`full-width-stack`** mirror the **Размеры**, **Композиция**, and **Full width** demos there (same structure and labels; app-ready imports).
+
+### Example files in `examples/`
+
+| File | Scenario |
+|------|----------|
+| `sizes-ladder.tsx` | `size` `s`–`xl` at `variant="primary"` `mode="filled"` (playground: `snippets/button/sizes.tsx`) |
+| `icon-composition.tsx` | `Button.Icon` left/right and icon-only with `aria-label`; primary filled + neutral stroke rows (`snippets/button/composition.tsx`) |
+| `full-width-stack.tsx` | `fullWidth` primary filled and neutral stroke at `m` (`snippets/button/full-width.tsx`) |
+| `canonical-composition.tsx` | Icon + text, variant/mode mix, loading + spinner |
+| `form-submit-row.tsx` | English form footer: cancel vs submit, async loading |
+| `destructive-confirm.tsx` | English confirm dialog: `error` + `Modal` |
+| `toolbar.tsx` | English editor-style toolbar: ghost row + primary action |
+| `marketing-cta.tsx` | English CTA column: `fancy` + `xl` / `l` with `fullWidth` (marketing emphasis; see also `full-width-stack.tsx`) |
+
+### Note for LLMs
+
+- **Imports:** `Button` (and `Icon`, `Modal` where needed) from **`"prime-ui-kit"`** in these examples; paths are relative to `src/components/button/examples/`.
+- **`loading`** is **controlled** on `Button.Root` only; there is no internal async state. When `loading` or `disabled` is true, the native `<button>` is disabled.
+- **`Button.Spinner`** only appears when `loading` is true; keep button text or `aria-label` meaningful while loading (`aria-busy` is set on the root).
+- **Forms:** default `type` is **`"button"`**; use **`"submit"`** / **`"reset"`** explicitly when the control lives in a `<form>`.
+- **Destructive actions:** use **`variant="error"`**; pair **filled** confirm with **stroke/lighter** or neutral cancel for hierarchy.
+- **`asChild`:** exactly one element child; `disabled`/`loading` map to `aria-disabled` and blocked clicks, not native `disabled` on non-button hosts.
+
+## Rules
+
+- `loading` is controlled only by the `loading` prop on `Button.Root`; there is no internal async state. When `loading` or `disabled` is true, the native `<button>` is disabled and `onClick` does not run.
+- With `asChild`, pass exactly one React element child. `type` is not forwarded; `disabled`/`loading` become `aria-disabled`, blocked `onClick`, and styles—native `disabled` is not set on non-button elements.
+- The `asChild` child must accept `className`, `aria-*`, `data-*`, and event props merged from the root.
+- For icon-only buttons, set a clear `aria-label` or `aria-labelledby` on `Button.Root`.
+- `variant` sets color role (`primary`, `neutral`, `error`); `mode` sets visual weight (`filled`, `stroke`, `lighter`, `ghost`, `fancy`).
+
+## API
+
+### Button.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| variant | `"primary" \| "neutral" \| "error"` | `"primary"` | No | Color semantics. |
+| mode | `"filled" \| "stroke" \| "lighter" \| "ghost" \| "fancy"` | `"filled"` | No | Visual weight / style. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Height, radius, text, and icon scale. |
+| fullWidth | `boolean` | — | No | Full-width layout (`data-full-width`). |
+| loading | `boolean` | `false` | No | Disables interaction, sets `aria-busy`, exposes loading to `Button.Spinner`. |
+| asChild | `boolean` | `false` | No | Merge props into the single child instead of rendering `<button>`. |
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Native button type; not forwarded when `asChild` is true. |
+| disabled | `boolean` | — | No | Inactive state; combined with `loading` for effective disabled behavior. |
+| className | `string` | — | No | Additional class on the root. |
+| children | `React.ReactNode` | — | No | Label, `Button.Icon`, `Button.Spinner`, etc. |
+| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "size">` | — | No | Other button attributes (`onClick`, `aria-*`, `data-*`, etc.); `size` is the component size prop, not the HTML attribute. |
+
+### Button.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Icon node. |
+| className | `string` | — | No | Additional class on the `span`. |
+| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other `span` attributes; root sets `aria-hidden="true"`. |
+
+### Button.Spinner
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the indicator. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes; not rendered when root `loading` is false. |
+
+## Related
+
+- [Link button](../link-button/COMPONENT.md) — link-styled control when the action is navigation.
+- [Button group](../button-group/COMPONENT.md) — grouped actions with shared sizing and dividers.
+- [Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md) — common hosts for triggers and dialog footers.
+- [Input](../input/COMPONENT.md), [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — form fields alongside submit/reset buttons.

package/src/components/button/examples/canonical-composition.tsx

@@ -0,0 +1,46 @@
+import { Button, Icon } from "prime-ui-kit";
+
+/**
+ * Canonical composition: icon + label, multiple variants/modes, and controlled loading with Button.Spinner.
+ */
+export default function CanonicalCompositionExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-l)",
+        alignItems: "flex-start",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-m)",
+          alignItems: "center",
+        }}
+      >
+        <Button.Root variant="primary" mode="filled">
+          <Button.Icon>
+            <Icon name="action.copy" size="s" />
+          </Button.Icon>
+          Copy link
+        </Button.Root>
+        <Button.Root variant="neutral" mode="stroke">
+          <Button.Icon>
+            <Icon name="field.email" size="s" tone="subtle" />
+          </Button.Icon>
+          Contact sales
+        </Button.Root>
+        <Button.Root variant="error" mode="lighter">
+          Remove from list
+        </Button.Root>
+      </div>
+      <Button.Root variant="primary" mode="filled" loading>
+        <Button.Spinner />
+        Saving…
+      </Button.Root>
+    </div>
+  );
+}