prime-ui-kit 0.3.1 → 0.4.0

package/src/components/breadcrumb/COMPONENT.md

@@ -2,32 +2,24 @@
 
 **Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
 
-## About
+## Canonical
 
-A composite breadcrumb: a `nav` with an ordered list (`ol`) of segments—links via `LinkButton`, plain text, optional custom separators, and an optional ellipsis for collapsed middle segments. `Root` sets type scale and control size for links, the current segment, the ellipsis, and the default separator icon.
+**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 paths** — storefront, catalog, or docs where users jump to a parent level without opening the main menu.
-- **Deep screens** — account, orders, or admin flows where the trail clarifies “where am I” (e.g. orders → order detail).
-- **Long trails** — show root, near parent, and leaf while collapsing the middle with `Ellipsis`.
+- 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 navigation** — use the main nav or sidebar for top-level IA; breadcrumbs are supplemental.
-- **Flat IA** — a single section or two levels rarely needs a trail; a page title or back control may be enough.
-- **Interactive “collapsed path”** — `Ellipsis` is static text, not a menu; build a dropdown or popover separately if users must pick hidden levels.
-- **Replacing a page title** — breadcrumbs orient; they do not substitute a clear `h1` or heading for the page.
+- 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.
 
-## Composition
-
-- **`Breadcrumb.Root`** renders `nav` (default `aria-label="Breadcrumb"`) and a single **`ol`**. Put **`Breadcrumb.Item`**, **`Breadcrumb.Separator`**, and **`Breadcrumb.Ellipsis`** only as **direct children** of that list (each part renders an `li`).
-- **Typical pattern:** `[Item] [Separator] [Item] [Separator] … [Item]`; use **`Ellipsis`** between separators when the path is long. Order is flexible, but stray non-`li` children would break list semantics—stick to these parts.
-- **`Item` with `href`** renders a **`LinkButton`**; **`Item` without `href`** renders a **`span`** (use **`current`** on the last segment for current-page styling and `aria-current="page"`).
-- **`Separator`** defaults to a chevron **`Icon`** (`nav.chevronRight`, `tone="subtle"`). Override with **`children`** (e.g. `/`) for a custom glyph or text.
-- **`Root`** provides breadcrumb **`size`** to nested parts via context and **`ControlSizeProvider`**.
-
-### Minimal example
+**Minimal pattern**
 
 ```tsx
 import { Breadcrumb } from "prime-ui-kit";
@@ -43,52 +35,105 @@ export function Example() {
 }
 ```
 
-## Rules
+**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
 
-- **Current page:** set **`current`** on the segment that represents the active page. **`aria-current="page"`** is applied only on the **non-link** branch (`span`); if **`href`** is set, the item is always a link and does **not** receive **`aria-current`**—for a proper current-page marker, omit **`href`** on that item and use **`current`**.
-- **No controlled “value” API** — markup is presentational; URLs and navigation are app-owned. There is no **`asChild`** on these parts.
-- **`Item` props are not an escape hatch** — only **`href`**, **`current`**, **`children`**, **`className`**, and **`aria-label`** are supported; extra **`li`** attributes are not forwarded.
-- **Icon-only first item** — set a meaningful **`aria-label`** on **`Item`** when **`href`** is set and **`children`** has no visible text.
-- **Override root label** — pass your own **`aria-label`** (or other **`nav`** attributes) via **`Root`** **`...rest`** after the documented props; defaults can be overridden per HTML merging rules.
-- **Separators** — **`aria-hidden="true"`** on **`Separator`** so assistive tech ignores decorative dividers; keep meaningful order in **`Item`** text instead.
-- **List layout** — items use flex with wrap in styles; very narrow layouts may wrap segments; do not rely on breadcrumbs as the only orientation cue on mobile if the path is long.
-- **No disabled, loading, or error props** — not part of this API.
+### Composition
 
-## API
+- **`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.
 
-### Breadcrumb.Root
+### 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` nodes as direct children of the inner `ol` |
+| 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 | Type scale for links, current text, ellipsis, and default separator icon (`"s"` \| `"m"` \| `"l"` \| `"xl"`) |
-| …rest | `React.HTMLAttributes<HTMLElement>` | — | no | Additional attributes on the `nav` (e.g. custom `aria-label`) |
+| 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
+#### 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` |
+| 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
+#### 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
+#### Breadcrumb.Ellipsis
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | className | `string` | — | no | Class on the `li` that displays the ellipsis character |
 
-## Related
+### Related
 
 - [LinkButton](../link-button/COMPONENT.md) — used inside `Item` when `href` is set.
-- [Typography](../typography/COMPONENT.md) — for page titles or captions next to the trail.
+- [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

@@ -6,18 +6,18 @@
 
 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.
 
-- **When to use** — primary, secondary, or destructive actions in forms, toolbars, dialogs, and empty states; submit/reset in forms; triggers that must look like a button.
-- **When to use** — async actions where you control `loading` and optionally show `Button.Spinner` next to the label.
-- **When to use** — full-width actions in narrow layouts via `fullWidth`.
-- **When not to use** — navigation that should be a plain link semantically (consider [Link button](../link-button/COMPONENT.md) or `asChild` with a link).
-- **When not to use** — binary on/off or multi-option selection (use [Switch](../switch/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Segmented control](../segmented-control/COMPONENT.md), etc.).
-- **When not to use** — grouping several related buttons without shared chrome (see [Button group](../button-group/COMPONENT.md) for layout).
+- **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 children via `ControlSizeProvider` (including in `asChild` mode). Place all other parts inside it.
+- **`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` alongside label text (order is up to you; keep a visible name for assistive tech).
+- **`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
 
@@ -29,15 +29,41 @@ export function Example() {
 }
 ```
 
+### 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 clicks do not run.
+- `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.
-- `Button.Spinner` reads context from the closest `Button.Root`; if `loading` is false, it renders nothing. It uses `aria-hidden="true"`—do not rely on it alone for a progress announcement; keep button text or `aria-label` meaningful while loading.
 - 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`).
-- Native `type` defaults to `"button"`; use `"submit"` / `"reset"` explicitly in forms when needed.
 
 ## API
 
@@ -76,5 +102,5 @@ export function Example() {
 
 - [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 consumers for open/close triggers.
+- [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" size="m">
+          <Button.Icon>
+            <Icon name="action.copy" size="s" />
+          </Button.Icon>
+          Copy link
+        </Button.Root>
+        <Button.Root variant="neutral" mode="stroke" size="m">
+          <Button.Icon>
+            <Icon name="field.email" size="s" tone="subtle" />
+          </Button.Icon>
+          Contact sales
+        </Button.Root>
+        <Button.Root variant="error" mode="lighter" size="m">
+          Remove from list
+        </Button.Root>
+      </div>
+      <Button.Root variant="primary" mode="filled" size="m" loading>
+        <Button.Spinner />
+        Saving…
+      </Button.Root>
+    </div>
+  );
+}

package/src/components/button/examples/destructive-confirm.tsx

@@ -0,0 +1,36 @@
+import { Button, Modal } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Destructive flow: `variant="error"` on the trigger and on the confirming action; neutral cancel.
+ */
+export default function DestructiveConfirmExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Modal.Root open={open} onOpenChange={setOpen}>
+      <Modal.Trigger>
+        <Button.Root variant="error" mode="stroke" size="m">
+          Delete project
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel
+        title="Delete this project?"
+        footer={
+          <>
+            <Modal.Close>
+              <Button.Root variant="neutral" mode="stroke" size="m">
+                Cancel
+              </Button.Root>
+            </Modal.Close>
+            <Button.Root variant="error" mode="filled" size="m" onClick={() => setOpen(false)}>
+              Delete
+            </Button.Root>
+          </>
+        }
+      >
+        <p style={{ margin: 0 }}>This permanently removes the project and its data.</p>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}

package/src/components/button/examples/form-submit-row.tsx

@@ -0,0 +1,33 @@
+import { Button } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Form footer: explicit `type="button"` vs `type="submit"`, plus async submit with `loading` and Spinner.
+ */
+export default function FormSubmitRowExample() {
+  const [loading, setLoading] = React.useState(false);
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        setLoading(true);
+        window.setTimeout(() => setLoading(false), 1200);
+      }}
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-m)",
+        justifyContent: "flex-end",
+      }}
+    >
+      <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+        Cancel
+      </Button.Root>
+      <Button.Root type="submit" variant="primary" mode="filled" size="m" loading={loading}>
+        <Button.Spinner />
+        Save changes
+      </Button.Root>
+    </form>
+  );
+}

package/src/components/button/examples/full-width-stack.tsx

@@ -0,0 +1,23 @@
+import { Button } from "prime-ui-kit";
+
+/**
+ * `fullWidth` primary filled and neutral stroke at `size="m"` (parity with `playground/snippets/button/full-width.tsx`).
+ */
+export default function FullWidthStackExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+      }}
+    >
+      <Button.Root variant="primary" mode="filled" size="m" fullWidth>
+        Button full width primary
+      </Button.Root>
+      <Button.Root variant="neutral" mode="stroke" size="m" fullWidth>
+        Button full width neutral stroke
+      </Button.Root>
+    </div>
+  );
+}