prime-ui-kit 0.2.5 → 0.3.2

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/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/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/button/COMPONENT.md

@@ -0,0 +1,101 @@
+# 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.
+
+### Example files in `examples/`
+
+| File | Scenario |
+|------|----------|
+| `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` + `fullWidth` |
+
+### 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" 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/marketing-cta.tsx

@@ -0,0 +1,26 @@
+import { Button, Icon } from "prime-ui-kit";
+
+/**
+ * Marketing CTA stack: strong primary (`fancy` + `xl`), secondary outline with trailing icon.
+ */
+export default function MarketingCtaExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+      }}
+    >
+      <Button.Root variant="primary" mode="fancy" size="xl" fullWidth>
+        Start free trial
+      </Button.Root>
+      <Button.Root variant="neutral" mode="stroke" size="l" fullWidth>
+        Compare plans
+        <Button.Icon>
+          <Icon name="nav.chevronRight" size="s" tone="subtle" />
+        </Button.Icon>
+      </Button.Root>
+    </div>
+  );
+}

package/src/components/button/examples/toolbar.tsx

@@ -0,0 +1,38 @@
+import { Button, Icon } from "prime-ui-kit";
+
+/**
+ * Dense toolbar: ghost neutrals for secondary actions, primary action with icon + label.
+ */
+export default function ToolbarExample() {
+  return (
+    <div
+      role="toolbar"
+      aria-label="Document actions"
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-s)",
+        alignItems: "center",
+      }}
+    >
+      <Button.Root variant="neutral" mode="ghost" size="m">
+        Bold
+      </Button.Root>
+      <Button.Root variant="neutral" mode="ghost" size="m">
+        Italic
+      </Button.Root>
+      <Button.Root variant="neutral" mode="ghost" size="m" aria-label="Insert link">
+        <Button.Icon>
+          <Icon name="field.email" size="s" tone="subtle" />
+        </Button.Icon>
+      </Button.Root>
+      <span style={{ flex: 1, minWidth: "var(--prime-sys-spacing-m)" }} aria-hidden />
+      <Button.Root variant="primary" mode="filled" size="m">
+        <Button.Icon>
+          <Icon name="action.upload" size="s" />
+        </Button.Icon>
+        Publish
+      </Button.Root>
+    </div>
+  );
+}

package/src/components/button-group/COMPONENT.md

@@ -0,0 +1,131 @@
+# ButtonGroup
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## Canonical
+
+- **What:** `ButtonGroup` groups native **`<button>`** segments that share one outline, inner dividers, and corner radius only on the outer shell; **`Root`** sets **`size`** and optional **`orientation`**, wraps **`ControlSizeProvider`**.
+- **Pieces:** namespace **`ButtonGroup.Root`**, **`ButtonGroup.Item`**, **`ButtonGroup.Icon`** (decorative wrapper, **`aria-hidden`**); **`Item`** must live inside **`Root`**.
+- **Selection look:** optional **`pressed`** on **`Item`** → **`data-state="on"`** and **`aria-pressed`** when boolean; mutual exclusivity is **parent state**, not enforced by the component.
+- **Forms:** **`Item`** supports **`type="button" | "submit" | "reset"`** (default **`"button"`**).
+- **Defaults:** **`size="m"`**, **`orientation="horizontal"`**; no **`variant`** or built-in **`fullWidth`** — widen via layout/`className` on **`Root`** and items if needed.
+- **Prefer something else:** true **one-of-N** field with radio semantics → [Radio](../radio/COMPONENT.md); kit segmented control API → [SegmentedControl](../segmented-control/COMPONENT.md); single CTA → [Button](../button/COMPONENT.md).
+
+## Extended
+
+### About
+
+A row or column of native buttons that share one bordered outline: one size tier for the whole group, internal dividers, and rounded corners only on the outer edges.
+
+- **Use** for toolbars, filters, and view switches where segments should read as one control but keep separate button semantics (`type`, `disabled`, per-item handlers).
+- **Use** for compact action pairs such as submit and reset inside a form.
+- **Use** when you control which segment looks active with `pressed` and parent state (toggle or single-choice UX).
+- **Do not use** when you need a true “one of N” form field with radio semantics and native submission — prefer [Radio](../radio/COMPONENT.md) or native radios.
+- **Do not use** when the kit’s segmented switcher API fits better — see [SegmentedControl](../segmented-control/COMPONENT.md).
+- **Do not use** for a single standalone call to action — use [Button](../button/COMPONENT.md) instead.
+
+### Scenarios (examples)
+
+Copy-ready demos live under **`examples/`** (same folder as this file):
+
+| Scenario | File | Idea |
+|----------|------|------|
+| Editor toolbar | [`examples/editor-toolbar.tsx`](examples/editor-toolbar.tsx) | Icon segments + optional **`pressed`** for active format; **`aria-label`** on icon-only **`Item`**. |
+| Form footer | [`examples/form-footer.tsx`](examples/form-footer.tsx) | **`type="submit"`** / **`type="reset"`** (or **`button`**) in one group; name **`Root`** with **`aria-label`**. |
+| View switcher | [`examples/view-switcher.tsx`](examples/view-switcher.tsx) | Single choice in React state; exactly one **`pressed={true}`** at a time. |
+| Wizard actions | [`examples/wizard-actions.tsx`](examples/wizard-actions.tsx) | Step **Back** / **Next** as a horizontal group; **`disabled`** on **Back** for the first step. |
+
+Playground demos (sizes, orientation, states, composition, full-width layout) live in **`playground/snippets/button-group/`**.
+
+### Composition
+
+- **`ButtonGroup`** is a namespace object: **`Root`**, **`Item`**, **`Icon`**.
+- **`ButtonGroup.Root`** — wrapper `div` with `data-size={size}`; for `orientation="vertical"` it sets `data-orientation="vertical"`. It provides group context and **`ControlSizeProvider`**, so nested controls inherit the same size tier.
+- Place one or more **`ButtonGroup.Item`** elements inside **`Root`** (they call the group context; using **`Item`** outside **`Root`** throws).
+- Optionally put **`ButtonGroup.Icon`** inside an **`Item`** to wrap an SVG: it renders a **`span`** with **`aria-hidden="true"`**.
+
+### Minimal example
+
+```tsx
+import { ButtonGroup } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <ButtonGroup.Root aria-label="Options" size="m">
+      <ButtonGroup.Item type="button">One</ButtonGroup.Item>
+      <ButtonGroup.Item type="button">Two</ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}
+```
+
+### Rules
+
+- There is no `variant` prop: appearance is always the shared-outline segment style; vary **`size`**, **`orientation`**, **`pressed`**, and **`disabled`** instead.
+- **`pressed`**: when `true`, the segment gets `data-state="on"` and `aria-pressed="true"`; when `false`, you get `aria-pressed="false"`; when omitted, `aria-pressed` is not set.
+- The component does not enforce a single selected segment: for mutually exclusive choice, keep state in the parent and set **`pressed`** (and handlers) accordingly; avoid multiple **`pressed`** items unless that is intentional.
+- Give **`Root`** an accessible name with **`aria-label`** or **`aria-labelledby`** when the group is not labeled by visible text.
+- For icon-only segments, set **`aria-label`** on **`ButtonGroup.Item`**; do not rely on **`ButtonGroup.Icon`** for a name (it is hidden from assistive tech).
+- Segments always render as **`<button>`** (no `asChild`); there is no built-in **`fullWidth`** — widen the group with layout on the root and items if needed.
+- **`ButtonGroup.Item`** supports **`type="button" | "submit" | "reset"`** (default **`"button"`**) for correct form behavior.
+
+### API
+
+#### ButtonGroup.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | no | Layout direction of segments. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Size tier for the group (height, radius, typography, icon scale). |
+| children | `React.ReactNode` | — | yes | Usually several `ButtonGroup.Item` nodes. |
+| className | `string` | — | no | Additional class on the root element. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | no | Other div attributes (e.g. `aria-label`, `role`, event handlers). |
+
+#### ButtonGroup.Item
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| pressed | `boolean` | — | no | Selected look: `data-state="on"` when `true`; `aria-pressed` mirrors the prop when it is a boolean. |
+| type | `"button" \| "submit" \| "reset"` | `"button"` | no | Native button type inside forms. |
+| disabled | `boolean` | — | no | Disables the segment. |
+| children | `React.ReactNode` | — | no | Label content; optional `ButtonGroup.Icon` for icons. |
+| className | `string` | — | no | Additional class on the button. |
+| …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | no | Other native button attributes. |
+
+#### ButtonGroup.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Typically an SVG icon. |
+| className | `string` | — | no | Additional class on the wrapper span. |
+| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | no | Other span attributes (not `children`). |
+
+### Related
+
+- [Button](../button/COMPONENT.md) — single actions, variants, loading.
+- [SegmentedControl](../segmented-control/COMPONENT.md) — alternative segmented switcher API.
+- [Radio](../radio/COMPONENT.md) — form “one of N” with radio semantics.
+
+## LLM note
+
+```yaml
+component: ButtonGroup
+exports: [ButtonGroup.Root, ButtonGroup.Item, ButtonGroup.Icon]
+defaults: { size: m, orientation: horizontal }
+behavior:
+  items_are: native button elements
+  pressed: optional boolean per Item; parent owns mutual exclusion for single-choice UX
+  no_variant: true
+  no_fullWidth_prop: true  # use layout / className on Root and Items
+forms:
+  Item_type: [button, submit, reset]
+a11y:
+  name_Root: aria-label or aria-labelledby when no visible label
+  icon_only_Item: aria-label on Item (not on Icon)
+anti_patterns:
+  - Using as native radio group for form submit semantics → Radio
+  - Single CTA → Button
+  - Prefer SegmentedControl when that composable API is a better fit
+doc_examples_dir: src/components/button-group/examples/
+playground_snippets: playground/snippets/button-group/
+```

package/src/components/button-group/examples/editor-toolbar.tsx

@@ -0,0 +1,46 @@
+import { Bold, Italic, Underline } from "lucide-react";
+import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Editor toolbar: icon segments share one outline; active format uses `pressed`.
+ * Meaning for assistive tech: `aria-label` on each icon-only `Item`.
+ */
+export default function EditorToolbarExample() {
+  const [marks, setMarks] = React.useState({ bold: true, italic: false, underline: false });
+
+  return (
+    <ButtonGroup.Root aria-label="Text formatting" size="m">
+      <ButtonGroup.Item
+        aria-label="Bold"
+        pressed={marks.bold}
+        type="button"
+        onClick={() => setMarks((m) => ({ ...m, bold: !m.bold }))}
+      >
+        <ButtonGroup.Icon>
+          <Bold />
+        </ButtonGroup.Icon>
+      </ButtonGroup.Item>
+      <ButtonGroup.Item
+        aria-label="Italic"
+        pressed={marks.italic}
+        type="button"
+        onClick={() => setMarks((m) => ({ ...m, italic: !m.italic }))}
+      >
+        <ButtonGroup.Icon>
+          <Italic />
+        </ButtonGroup.Icon>
+      </ButtonGroup.Item>
+      <ButtonGroup.Item
+        aria-label="Underline"
+        pressed={marks.underline}
+        type="button"
+        onClick={() => setMarks((m) => ({ ...m, underline: !m.underline }))}
+      >
+        <ButtonGroup.Icon>
+          <Underline />
+        </ButtonGroup.Icon>
+      </ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}

package/src/components/button-group/examples/form-footer.tsx

@@ -0,0 +1,19 @@
+import { ButtonGroup } from "prime-ui-kit";
+
+/**
+ * Form footer: native submit + reset in one segmented control.
+ */
+export default function FormFooterExample() {
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+      }}
+    >
+      <ButtonGroup.Root aria-label="Save or reset draft" size="m">
+        <ButtonGroup.Item type="submit">Save</ButtonGroup.Item>
+        <ButtonGroup.Item type="reset">Reset</ButtonGroup.Item>
+      </ButtonGroup.Root>
+    </form>
+  );
+}

package/src/components/button-group/examples/view-switcher.tsx

@@ -0,0 +1,25 @@
+import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+type ViewMode = "list" | "grid" | "board";
+
+/**
+ * View switcher: one active segment; state lives in the parent.
+ */
+export default function ViewSwitcherExample() {
+  const [mode, setMode] = React.useState<ViewMode>("list");
+
+  return (
+    <ButtonGroup.Root aria-label="View layout" size="m">
+      <ButtonGroup.Item pressed={mode === "list"} type="button" onClick={() => setMode("list")}>
+        List
+      </ButtonGroup.Item>
+      <ButtonGroup.Item pressed={mode === "grid"} type="button" onClick={() => setMode("grid")}>
+        Grid
+      </ButtonGroup.Item>
+      <ButtonGroup.Item pressed={mode === "board"} type="button" onClick={() => setMode("board")}>
+        Board
+      </ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}

package/src/components/button-group/examples/wizard-actions.tsx

@@ -0,0 +1,30 @@
+import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+const STEP_LAST = 2;
+
+/**
+ * Wizard step actions: Back disabled on first step; Next advances (demo stops at last step).
+ */
+export default function WizardActionsExample() {
+  const [step, setStep] = React.useState(0);
+
+  return (
+    <ButtonGroup.Root aria-label="Wizard navigation" size="m">
+      <ButtonGroup.Item
+        disabled={step === 0}
+        type="button"
+        onClick={() => setStep((s) => Math.max(0, s - 1))}
+      >
+        Back
+      </ButtonGroup.Item>
+      <ButtonGroup.Item
+        disabled={step >= STEP_LAST}
+        type="button"
+        onClick={() => setStep((s) => Math.min(STEP_LAST, s + 1))}
+      >
+        Next
+      </ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}