prime-ui-kit 0.3.2 → 0.4.1

package/src/components/breadcrumb/COMPONENT.md

@@ -46,12 +46,24 @@ export function Example() {
 | 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) |
-| Long path + ellipsis | [`examples/long-path-ellipsis.tsx`](./examples/long-path-ellipsis.tsx) |
 
-Playground demos (app alias `@/…`): `playground/snippets/breadcrumb/` — sizes, states, composition (icon home + custom separator), narrow container, long ellipsis.
+**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) |
 
 ---
 
@@ -124,4 +136,4 @@ Playground demos (app alias `@/…`): `playground/snippets/breadcrumb/` — size
 - 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 five files under **`src/components/breadcrumb/examples/`**; for interactive kit demos see **`playground/snippets/breadcrumb/`**.
+- 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/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/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/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

@@ -33,15 +33,20 @@ export function Example() {
 
 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` + `fullWidth` |
+| `marketing-cta.tsx` | English CTA column: `fancy` + `xl` / `l` with `fullWidth` (marketing emphasis; see also `full-width-stack.tsx`) |
 
 ### Note for LLMs
 

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>
+  );
+}

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

@@ -0,0 +1,63 @@
+import { Button, Icon } from "prime-ui-kit";
+
+/**
+ * `Button.Icon` left, right, and icon-only with `aria-label` on root; primary filled and neutral stroke rows
+ * (parity with `playground/snippets/button/composition.tsx`).
+ */
+export default function IconCompositionExample() {
+  const rowStyle = {
+    display: "flex" as const,
+    flexWrap: "wrap" as const,
+    gap: "var(--prime-sys-spacing-m)",
+    alignItems: "center" as const,
+  };
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+      }}
+    >
+      <div style={rowStyle}>
+        <Button.Root variant="primary" mode="filled" size="m">
+          <Button.Icon>
+            <Icon name="field.email" size="s" />
+          </Button.Icon>
+          Button primary icon left
+        </Button.Root>
+        <Button.Root variant="primary" mode="filled" size="m">
+          Button primary icon right
+          <Button.Icon>
+            <Icon name="action.close" size="s" />
+          </Button.Icon>
+        </Button.Root>
+        <Button.Root variant="primary" mode="filled" size="m" aria-label="Button primary icon only">
+          <Button.Icon>
+            <Icon name="action.close" size="s" />
+          </Button.Icon>
+        </Button.Root>
+      </div>
+      <div style={rowStyle}>
+        <Button.Root variant="neutral" mode="stroke" size="m">
+          <Button.Icon>
+            <Icon name="field.email" size="s" tone="subtle" />
+          </Button.Icon>
+          Button icon left
+        </Button.Root>
+        <Button.Root variant="neutral" mode="stroke" size="m">
+          Button icon right
+          <Button.Icon>
+            <Icon name="action.close" size="s" tone="subtle" />
+          </Button.Icon>
+        </Button.Root>
+        <Button.Root variant="neutral" mode="stroke" size="m" aria-label="Button icon only">
+          <Button.Icon>
+            <Icon name="action.close" size="s" tone="subtle" />
+          </Button.Icon>
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/button/examples/sizes-ladder.tsx

@@ -0,0 +1,30 @@
+import { Button } from "prime-ui-kit";
+
+/**
+ * Size ladder: `s`–`xl` at `variant="primary"` `mode="filled"` (parity with `playground/snippets/button/sizes.tsx`).
+ */
+export default function SizesLadderExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "center",
+      }}
+    >
+      <Button.Root variant="primary" mode="filled" size="s">
+        Button s
+      </Button.Root>
+      <Button.Root variant="primary" mode="filled" size="m">
+        Button m
+      </Button.Root>
+      <Button.Root variant="primary" mode="filled" size="l">
+        Button l
+      </Button.Root>
+      <Button.Root variant="primary" mode="filled" size="xl">
+        Button xl
+      </Button.Root>
+    </div>
+  );
+}

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

@@ -34,8 +34,19 @@ Copy-ready demos live under **`examples/`** (same folder as this file):
 | 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. |
+| Full width | [`examples/full-width.tsx`](examples/full-width.tsx) | **`Root`** `className` for container width (e.g. **`w-full`**); **`flex-1`** / **`min-w-0`** on **`Item`** to split the row (no built-in **`fullWidth`** prop). |
 
-Playground demos (sizes, orientation, states, composition, full-width layout) live in **`playground/snippets/button-group/`**.
+Playground demos match `playground/sections/ButtonGroupSection.tsx` (order and `?raw` sources):
+
+| Snippet | File | Idea |
+|---------|------|------|
+| Sizes | [`playground/snippets/button-group/sizes.tsx`](../../../playground/snippets/button-group/sizes.tsx) | Four rows **`s`**, **`m`**, **`l`**, **`xl`**; each row is a real three-segment group. |
+| States | [`states.tsx`](../../../playground/snippets/button-group/states.tsx) | Default, **`pressed`**, **`disabled`** in one group. |
+| Orientation | [`orientation.tsx`](../../../playground/snippets/button-group/orientation.tsx) | Default horizontal vs **`orientation="vertical"`**. |
+| Controlled | [`controlled.tsx`](../../../playground/snippets/button-group/controlled.tsx) | Parent state; exactly one **`pressed={true}`** at a time (**day** / **week** / **month**). |
+| Composition | [`composition.tsx`](../../../playground/snippets/button-group/composition.tsx) | **`ButtonGroup.Icon`**, **`aria-label`** on icon-only **`Item`**, text + chevron, two toolbar rows. |
+| Full width | [`full-width.tsx`](../../../playground/snippets/button-group/full-width.tsx) | **`Root`** **`className="w-full"`**; items **`className="min-w-0 flex-1"`** inside a bounded container. |
+| Form features | [`form-features.tsx`](../../../playground/snippets/button-group/form-features.tsx) | Form with **`type="submit"`** and **`type="reset"`** segments. |
 
 ### Composition
 
@@ -128,4 +139,5 @@ anti_patterns:
   - Prefer SegmentedControl when that composable API is a better fit
 doc_examples_dir: src/components/button-group/examples/
 playground_snippets: playground/snippets/button-group/
+playground_snippet_files: [sizes, states, orientation, controlled, composition, full-width, form-features]
 ```

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

@@ -0,0 +1,22 @@
+import { ButtonGroup } from "prime-ui-kit";
+
+/**
+ * Full width: no dedicated prop — width on Root, equal segments via flex-1 on Items.
+ */
+export default function FullWidthExample() {
+  return (
+    <div className="w-full max-w-md">
+      <ButtonGroup.Root aria-label="Plan tier" className="w-full" size="m">
+        <ButtonGroup.Item className="min-w-0 flex-1" type="button">
+          Basic
+        </ButtonGroup.Item>
+        <ButtonGroup.Item className="min-w-0 flex-1" pressed type="button">
+          Pro
+        </ButtonGroup.Item>
+        <ButtonGroup.Item className="min-w-0 flex-1" type="button">
+          Business
+        </ButtonGroup.Item>
+      </ButtonGroup.Root>
+    </div>
+  );
+}

package/src/components/card/COMPONENT.md

@@ -50,20 +50,40 @@ export function RevenuePanelCard() {
 }
 ```
 
+## Playground snippets
+
+Live demos use these files (same order as the **Card** section in the playground):
+
+| Scenario | Snippet | Notes |
+|----------|---------|-------|
+| Mini | [`mini.tsx`](../../../playground/snippets/card/mini.tsx) | `variant="mini"`: **`IconBox`** + **`Stack`** (**`Label`**, **`Value`**) |
+| Mini + media | [`mini-media.tsx`](../../../playground/snippets/card/mini-media.tsx) | `variant="mini-media"`: same as mini + bottom **`Media`** |
+| Metric | [`metric.tsx`](../../../playground/snippets/card/metric.tsx) | `variant="metric"`: **`HeaderRow`** (**`Lead`**, **`Value`**) + **`Description`** |
+| Stat + trend | [`stat-trend.tsx`](../../../playground/snippets/card/stat-trend.tsx) | `variant="stat-trend"`: **`Value`** + **`Delta`** (`trend`) |
+| CTA | [`cta.tsx`](../../../playground/snippets/card/cta.tsx) | `variant="cta"`: **`Title`**, **`CtaBody`**, **`Actions`** |
+| List | [`list.tsx`](../../../playground/snippets/card/list.tsx) | `variant="list"`: **`ListHeader`**, **`List`** / **`ListItem`** |
+| Split | [`split.tsx`](../../../playground/snippets/card/split.tsx) | `variant="split"`: **`Split`** with two **`SplitCell`** blocks |
+| Cover | [`cover.tsx`](../../../playground/snippets/card/cover.tsx) | `variant="cover"`: **`Cover`**, **`Stack`**, **`Actions`** |
+| Panel (chart only) | [`panel.tsx`](../../../playground/snippets/card/panel.tsx) | `variant="panel"`: **`SectionHeader`** + edge-to-edge **`Chart`** |
+| Panel (body + chart) | [`panel-content-chart.tsx`](../../../playground/snippets/card/panel-content-chart.tsx) | same **`panel`**: **`Body`** + **`Chart`** |
+| Flat surface | [`flat.tsx`](../../../playground/snippets/card/flat.tsx) | **`flat`** prop: shadow vs no shadow on **`mini`** |
+| KPI grid | [`row.tsx`](../../../playground/snippets/card/row.tsx) | several mini cards in playground `introFeatureGrid` |
+
+Supporting CSS modules in that folder: `flat.module.css`, `mini-media.module.css`, `variants-stack.module.css`.
+
 ## Extended examples
 
-Copy-oriented scenarios (English copy) live next to this file:
+Copy-oriented scenarios (English copy, `prime-ui-kit` imports) live next to this file. For single-variant demos, see **Playground snippets** above.
 
 | File | Scenario |
 |------|----------|
+| [examples/mini-kpi.tsx](./examples/mini-kpi.tsx) | **`mini`**: компактный KPI с иконкой |
 | [examples/metric-dashboard.tsx](./examples/metric-dashboard.tsx) | KPI row: **`stat-trend`**, **`metric`**, **`mini-media`** |
 | [examples/list-card.tsx](./examples/list-card.tsx) | Activity list with header link |
 | [examples/media-mini.tsx](./examples/media-mini.tsx) | **`mini-media`**: sparkline and **`ProgressBar`** |
 | [examples/split-layout.tsx](./examples/split-layout.tsx) | **`split`**: two metrics in one tile |
 | [examples/cta-cover.tsx](./examples/cta-cover.tsx) | **`cta`** tile and **`cover`** with gradient banner |
 
-Playground: more live variants under `playground/snippets/card/` (e.g. **`flat`**, **`row`**, **`stat-trend`**, chart-only panel).
-
 ## Composition
 
 - **`Card.Root`** — required **`variant`**: `"mini"` \| `"mini-media"` \| `"metric"` \| `"panel"` \| `"stat-trend"` \| `"cta"` \| `"list"` \| `"split"` \| `"cover"`. Optional **`flat`** removes the default surface shadow. Sets `data-variant` / `data-flat` for styling.

package/src/components/card/examples/mini-kpi.tsx

@@ -0,0 +1,16 @@
+import { Card, Icon } from "prime-ui-kit";
+
+/** Compact KPI: icon + label/value (`variant="mini"`). */
+export function MiniKpiExample() {
+  return (
+    <Card.Root variant="mini">
+      <Card.IconBox aria-hidden>
+        <Icon name="field.email" aria-hidden />
+      </Card.IconBox>
+      <Card.Stack>
+        <Card.Label>Active sessions</Card.Label>
+        <Card.Value>1,248</Card.Value>
+      </Card.Stack>
+    </Card.Root>
+  );
+}

package/src/components/checkbox/COMPONENT.md

@@ -19,24 +19,34 @@
 
 A compound checkbox: a visually hidden native `input type="checkbox"`, a decorative box with check or indeterminate mark, and optional label, hint, and error text wired to `aria-describedby` and invalid state.
 
-- **When to use** — explicit consent, terms, or other “yes/no” fields that submit with the form (`name`, `value`, `required`).
-- **When to use** — row or “select all” patterns where the parent shows **indeterminate** when only some children are checked.
-- **When to use** — independent toggles (feature flags, optional features, settings) rather than one-of-many choices.
-- **When to use** — hint text or inline validation aligned under the label column.
-- **When not to use** — exactly one option from a set of alternatives (prefer [Radio](../radio/COMPONENT.md)).
-- **When not to use** — a single binary setting where a switch fits the product language (prefer [Switch](../switch/COMPONENT.md)).
-- **When not to use** — you need `asChild` or fully custom markup; the control is a fixed [Label](../label/COMPONENT.md) row with a hidden input and SVG.
+- **When to use** — explicit consent, terms, or other “yes/no” fields that submit with the form (`name`, `value`, `required`); row or “select all” patterns where the parent shows **indeterminate** when only some children are checked; independent toggles (feature flags, optional features, settings) rather than one-of-many choices; hint text or inline validation aligned under the label column.
+- **When not to use** — exactly one option from a set of alternatives (prefer [Radio](../radio/COMPONENT.md)); a single binary setting where a switch fits the product language (prefer [Switch](../switch/COMPONENT.md)); you need `asChild` or fully custom markup; the control is a fixed [Label](../label/COMPONENT.md) row with a hidden input and SVG.
+
+### Playground snippets
+
+Demos match **`playground/sections/CheckboxSection.tsx`** (order and intent). Sources use `@/` imports under **`playground/snippets/checkbox/`**:
+
+| Block | File | What it shows |
+|-------|------|----------------|
+| **Sizes** | [`sizes.tsx`](../../../playground/snippets/checkbox/sizes.tsx) | **`size`** **`s`**, **`m`**, **`l`**, **`xl`** — box, gap, and label scale from control tokens. |
+| **Variants** | [`variants.tsx`](../../../playground/snippets/checkbox/variants.tsx) | **`variant="default"`** vs **`variant="error"`**; mounting **`Checkbox.Error`** also drives invalid (see **Composition** + recipes). |
+| **States** | [`states.tsx`](../../../playground/snippets/checkbox/states.tsx) | Unchecked, **`defaultChecked`**, **`indeterminate`**, native **`required`**, **`disabled`** (off and on). |
+| **Controlled** | [`controlled.tsx`](../../../playground/snippets/checkbox/controlled.tsx) | **`checked`** + **`onChange`**; **`indeterminate`** from parent state cleared on user change (table “select all” pattern). |
+| **Composition** | [`composition.tsx`](../../../playground/snippets/checkbox/composition.tsx) | **`Hint`** only; **`Error`** without **`variant="error"`** on root; full **`Hint`** + **`Error`** with **`variant="error"`**. |
+| **Full width** | [`full-width.tsx`](../../../playground/snippets/checkbox/full-width.tsx) (+ [`full-width.module.css`](../../../playground/snippets/checkbox/full-width.module.css)) | Narrow container: field root is **`width: 100%`**; long label wraps in the text column; hint aligned under label. |
+| **Specific** | [`specific.tsx`](../../../playground/snippets/checkbox/specific.tsx) | Empty **`Checkbox.Label`** with **`aria-label`** on **`Root`**; **`name`** / **`value`** / **`defaultChecked`** for form submit. |
 
 ### Scenarios (recipes)
 
 | Scenario | Approach |
 |----------|----------|
-| **Terms acceptance** | **`required`** on **`Root`**; optional **`Checkbox.Hint`** for legal context; show **`Checkbox.Error`** or **`variant="error"`** after validation when unchecked. |
-| **Feature flags list** | One **`Checkbox.Root` per flag**; independent **controlled** booleans or a small state map; no indeterminate unless a parent “enable all” exists. |
-| **Bulk select (row / table)** | **Header** checkbox: **`checked`** when all rows selected, **`indeterminate`** when some; **`onChange`** selects or clears all row ids. **Row** checkboxes toggle one id each. |
-| **Settings panel** | Stack of **`Root` → `Label` → optional `Hint`** rows; same **`size`** across the panel for rhythm; **`disabled`** for plan-gated options. |
+| **Terms acceptance** | **`required`** on **`Root`**; optional **`Checkbox.Hint`** for legal context; show **`Checkbox.Error`** or **`variant="error"`** after validation when unchecked. → [`examples/terms-acceptance.tsx`](examples/terms-acceptance.tsx) |
+| **Feature flags list** | One **`Checkbox.Root` per flag**; independent **controlled** booleans or a small state map; no indeterminate unless a parent “enable all” exists. → [`examples/feature-flags-list.tsx`](examples/feature-flags-list.tsx) |
+| **Bulk select (row / table)** | **Header** checkbox: **`checked`** when all rows selected, **`indeterminate`** when some; **`onChange`** selects or clears all row ids. **Row** checkboxes toggle one id each. → [`examples/bulk-select-rows.tsx`](examples/bulk-select-rows.tsx) |
+| **Settings panel** | Stack of **`Root` → `Label` → optional `Hint`** rows; same **`size`** across the panel for rhythm; **`disabled`** for plan-gated options. → [`examples/settings-panel.tsx`](examples/settings-panel.tsx) |
+| **Empty label + form attrs** | Icon-only / compact cell: **`aria-label`** (or **`aria-labelledby`**) on **`Root`**; optional **`name`** / **`value`** for submission. → [`examples/empty-label-form.tsx`](examples/empty-label-form.tsx) |
 
-Runnable TSX for these patterns lives under **`examples/`** in this folder (`terms-acceptance.tsx`, `feature-flags-list.tsx`, `bulk-select-rows.tsx`, `settings-panel.tsx`).
+Runnable recipe examples use **`prime-ui-kit`** imports under **`examples/`**. Snippet-level demos (internal imports) are listed in **Playground snippets** above.
 
 ### Composition
 

package/src/components/checkbox/examples/empty-label-form.tsx

@@ -0,0 +1,24 @@
+import { Checkbox } from "prime-ui-kit";
+
+/**
+ * Matches playground `snippets/checkbox/specific.tsx`: no visible label text — set an accessible name on
+ * Root; optional name/value for form submission.
+ */
+export function EmptyLabelFormExample() {
+  return (
+    <>
+      <Checkbox.Root size="m" aria-label="Receive digest by email (no visible label)">
+        <Checkbox.Label />
+      </Checkbox.Root>
+      <Checkbox.Root
+        size="m"
+        name="newsletter"
+        value="weekly"
+        defaultChecked
+        aria-label="Subscribe to weekly newsletter"
+      >
+        <Checkbox.Label />
+      </Checkbox.Root>
+    </>
+  );
+}

package/src/components/code-block/COMPONENT.md

@@ -27,17 +27,31 @@
 - **`Root`** renders a **`pre`**; highlighted markup is a single inner **`code`** (do not supply **`children`**).
 - Pass source as **`code`**. Optional **`colorScheme`** sets highlighting palette / **`data-theme`** on **`pre`**.
 
-### Scenarios (examples)
+### Scenarios (playground)
 
-| Scenario | Example file |
-|----------|----------------|
-| Minimal usage | [`examples/minimal.tsx`](./examples/minimal.tsx) |
-| API response preview (JSON body) | [`examples/api-response-preview.tsx`](./examples/api-response-preview.tsx) |
-| Config snippet (TS config) | [`examples/config-snippet.tsx`](./examples/config-snippet.tsx) |
-| Error stack / log | [`examples/error-stack.tsx`](./examples/error-stack.tsx) |
-| Tutorial step (copy + snippet) | [`examples/tutorial-step.tsx`](./examples/tutorial-step.tsx) |
+Same order as `playground/sections/CodeBlockSection.tsx`. Snippets use the `@/` alias and may use `usePlaygroundTheme` for `colorScheme`.
 
-Playground demos (variants, sizes, composition, etc.): `playground/snippets/code-block/`.
+| Scenario | Snippet |
+|----------|---------|
+| Sizes — wrapper `font-size` / `line-height`; no `size` prop | [`sizes.tsx`](../../../playground/snippets/code-block/sizes.tsx) |
+| Variants — `colorScheme` light and dark side by side | [`variants.tsx`](../../../playground/snippets/code-block/variants.tsx) |
+| Controlled — `code` from parent state; switch between snippets | [`controlled.tsx`](../../../playground/snippets/code-block/controlled.tsx) |
+| Composition — documentation-style card (Typography + code) | [`composition.tsx`](../../../playground/snippets/code-block/composition.tsx) |
+| Full width — narrow column, `codeBlockFullBleed`, horizontal scroll | [`full-width.tsx`](../../../playground/snippets/code-block/full-width.tsx) |
+| Features — `id`, `aria-label`, `data-*`, trailing spaces + `trimEnd` | [`features.tsx`](../../../playground/snippets/code-block/features.tsx) |
+
+### Package examples (`examples/`)
+
+Recipes import **`prime-ui-kit`** (no playground path alias).
+
+| Scenario | File |
+|----------|------|
+| Minimal usage | [`minimal.tsx`](./examples/minimal.tsx) |
+| Controlled — `code` из состояния (рецепт на `ButtonGroup`) | [`controlled.tsx`](./examples/controlled.tsx) |
+| API response preview (JSON body) | [`api-response-preview.tsx`](./examples/api-response-preview.tsx) |
+| Config snippet (TS config) | [`config-snippet.tsx`](./examples/config-snippet.tsx) |
+| Error stack / log | [`error-stack.tsx`](./examples/error-stack.tsx) |
+| Tutorial step (copy + snippet) | [`tutorial-step.tsx`](./examples/tutorial-step.tsx) |
 
 ### Minimal example
 
@@ -74,8 +88,9 @@ The package also exports **`CodeBlockColorScheme`** and **`CodeBlockRootProps`**
 ### Related
 
 - [Typography](../typography/COMPONENT.md) — headings and body around snippets.
-- [Button](../button/COMPONENT.md) — switching samples from parent state.
-- [Segmented control](../segmented-control/COMPONENT.md) — compact sample switching.
+- [Button](../button/COMPONENT.md) — switching the active snippet from parent state (playground `controlled.tsx`).
+- [ButtonGroup](../button-group/COMPONENT.md) — segmented control for switching `code` ([`examples/controlled.tsx`](./examples/controlled.tsx)).
+- [Segmented control](../segmented-control/COMPONENT.md) — compact scenario switching.
 - [Kbd](../kbd/COMPONENT.md) — shortcut hints beside prose.
 
 ## Note for LLM assistants

package/src/components/code-block/examples/controlled.tsx

@@ -0,0 +1,43 @@
+import { ButtonGroup, CodeBlock, Typography } from "prime-ui-kit";
+import { useState } from "react";
+
+const SNIPPETS: [string, string][] = [
+  [
+    "Утилита",
+    `export function clamp(n: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, n));
+}
+`,
+  ],
+  [
+    "React",
+    `import { useMemo } from "react";
+
+export function useStableId(prefix: string) {
+  return useMemo(() => \`\${prefix}-\${Math.random().toString(36).slice(2)}\`, [prefix]);
+}
+`,
+  ],
+];
+
+/** Проп `code` из состояния родителя: сегменты переключают два разных фрагмента (как в playground `controlled.tsx`). */
+export default function CodeBlockControlledExample() {
+  const [index, setIndex] = useState(0);
+  const [label, code] = SNIPPETS[index] ?? SNIPPETS[0];
+
+  return (
+    <div>
+      <Typography.Root variant="body-compact" tone="muted" as="p">
+        Активный фрагмент: <strong>{label}</strong> (проп <code>code</code> из состояния).
+      </Typography.Root>
+      <ButtonGroup.Root size="s" aria-label="Выбор фрагмента кода">
+        {SNIPPETS.map(([title], i) => (
+          <ButtonGroup.Item key={title} pressed={i === index} onClick={() => setIndex(i)}>
+            {title}
+          </ButtonGroup.Item>
+        ))}
+      </ButtonGroup.Root>
+      <CodeBlock.Root code={code} colorScheme="light" />
+    </div>
+  );
+}