prime-ui-kit 0.3.1 → 0.4.0

package/src/components/radio/COMPONENT.md

@@ -1,26 +1,60 @@
 # Radio
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default `size`:** use **`m`** for the size axis unless the screen or field explicitly needs another tier.
 
-## About
+## Canonical
 
-A compound radio control: a field wrapper, a [Label](../label/COMPONENT.md) row with a native `input type="radio"` and decorative marker, plus optional [Hint](../hint/COMPONENT.md) and error text wired to `aria-describedby` and invalid state.
+- **`Radio`** — compound choice control: **`Radio.Root`** (field wrapper `.field`, `data-size`, `data-variant`, `data-disabled`, `data-invalid`), **`Radio.Label`** (native `input type="radio"` + marker + optional text), optional **`Radio.Hint`** and **`Radio.Error`** (wired into `aria-describedby` and invalid styling).
+- **`variant`:** **`default`** or **`error`** on **`Radio.Root`**; mounting **`Radio.Error`** also drives invalid / `aria-invalid` for that instance.
+- **`size`:** **`s` | `m` | `l` | `xl`** on **`Radio.Root`** — marker, label, and hint/error scale via context (`ControlSizeProvider`).
+- **Groups:** several **`Radio.Root`** nodes share the same **`name`** (and optionally **`value` / `checked` / `onChange`**) — there is **no** separate **`RadioGroup`**; behavior is native HTML or your controlled state.
+- **`Radio.Root` `ref`** is forwarded to the **native `<input type="radio">`**.
+- **DOM `type`** is always **`radio`**; the design-system **`size`** prop is **not** the HTML `size` attribute (that key is omitted from input props).
 
-- **When to use** — exactly one choice from a set of mutually exclusive options that submit with the form (`name`, `value`, `required`).
-- **When to use** — grouped options that should behave as a single native radio group (same `name` on each `Radio.Root`).
-- **When to use** — hint or inline validation aligned under the label column.
-- **When not to use** — multiple independent toggles or “select many” lists (prefer [Checkbox](../checkbox/COMPONENT.md)).
-- **When not to use** — a single binary on/off setting where a switch matches the product language (prefer [Switch](../switch/COMPONENT.md)).
+## Extended
+
+### About
+
+A compound radio field: wrapper, label row with a native radio and decorative rings, plus optional hint and error text aligned under the label column.
+
+- **When to use** — exactly one choice from mutually exclusive options that submit with the form (`name`, `value`, `required`); native group semantics with the same **`name`** on each **`Radio.Root`**; short helper or validation copy per option via **`Radio.Hint`** / **`Radio.Error`**.
+- **When not to use** — multiple independent toggles or “select many” (prefer [Checkbox](../checkbox/COMPONENT.md)).
+- **When not to use** — a single binary on/off where a switch fits the product language (prefer [Switch](../switch/COMPONENT.md)).
 - **When not to use** — a compact segmented bar of modes in one control (prefer [Segmented control](../segmented-control/COMPONENT.md)).
-- **When not to use** — you need `asChild` or fully custom markup; the marker and label row are fixed by the implementation.
+- **When not to use** — fully custom markup or `asChild`; the marker and label row are fixed by the implementation.
+
+### Playground snippets
+
+Demos match **`playground/sections/RadioSection.tsx`** (order and intent). Sources use `@/` imports under **`playground/snippets/radio/`**:
+
+| Block | File | What it shows |
+|-------|------|----------------|
+| **Sizes** | [`sizes.tsx`](../../../playground/snippets/radio/sizes.tsx) | **`size`** **`s`**, **`m`**, **`l`**, **`xl`** at **`variant="default"`**; separate **`name`** per row so previews do not clash. |
+| **Variants** | [`variants.tsx`](../../../playground/snippets/radio/variants.tsx) | **`variant="default"`** with **`Radio.Hint`** vs **`variant="error"`** with **`Radio.Error`** and **`aria-invalid`**. |
+| **States** | [`states.tsx`](../../../playground/snippets/radio/states.tsx) | Unchecked, selected, **`disabled`** (off/on), row with **`Radio.Hint`** and **`aria-describedby`**. |
+| **Controlled** | [`controlled.tsx`](../../../playground/snippets/radio/controlled.tsx) (+ [`radio-snippets.module.css`](../../../playground/snippets/radio/radio-snippets.module.css)) | Same **`name`**, **`checked`** + **`onChange`** with **`e.currentTarget.checked`**; summary line. |
+| **Composition** | [`composition.tsx`](../../../playground/snippets/radio/composition.tsx) | Two options, shared **`name`**, **`Radio.Hint`** under each (payment-style block). |
+| **Full width** | [`full-width.tsx`](../../../playground/snippets/radio/full-width.tsx) (+ [`radio-snippets.module.css`](../../../playground/snippets/radio/radio-snippets.module.css)) | Narrow column (`previewBannerNarrowColumn` in playground): root stretches **`width: 100%`**, label uses remaining space. |
+| **Specific** | [`form-group.tsx`](../../../playground/snippets/radio/form-group.tsx) (+ [`radio-snippets.module.css`](../../../playground/snippets/radio/radio-snippets.module.css)) | **`fieldset`** / **`legend`**, **`required`**, **`FormData`** on submit. |
 
-## Composition
+### Scenarios (recipes)
 
-- **`Radio.Root`** — `div` with `data-size`, `data-variant`, `data-disabled`, `data-invalid`; provides context and `ControlSizeProvider` for child parts (`inputId`, hint/error ids, `describedBy`, registration for hint/error slots).
-- **`Radio.Label`** — [Label](../label/COMPONENT.md) with `htmlFor` tied to the input id; contains the native `input[type=radio]`, decorative SVG rings, and optional text in a trailing column.
-- **`Radio.Hint`** — optional; registers presence so its id is merged into the input’s `aria-describedby`; uses disabled hint variant when the root is `disabled`.
-- **`Radio.Error`** — optional; error-styled message and registers invalid state (same as `variant="error"` on the root for styling).
-- **Order:** `Root` → `Label` → `Hint` and/or `Error` when needed. Public API: `Radio` with `Root`, `Label`, `Hint`, `Error`.
+| Scenario | Approach |
+|----------|----------|
+| Shipping method | **`fieldset`** + **`legend`**; shared **`name`**; **`Radio.Hint`** for delivery copy per option. → [`examples/shipping-method.tsx`](examples/shipping-method.tsx) |
+| Plan picker | Controlled group: **`checked`** + **`onChange`**, same **`name`**, optional summary line. → [`examples/plan-picker.tsx`](examples/plan-picker.tsx) |
+| Settings group | Themed or preference block; **`disabled`** on tier-gated options. → [`examples/settings-group.tsx`](examples/settings-group.tsx) |
+| Single primary channel | One-notice policy (email vs SMS vs app); still radios, not checkboxes. → [`examples/notification-channel.tsx`](examples/notification-channel.tsx) |
+
+Runnable recipe examples use **`prime-ui-kit`** imports under **`examples/`**. Snippet-level demos (internal `@/` imports) are listed in **Playground snippets** above.
+
+### Composition
+
+- **`Radio.Root`** — provides context (`inputId`, hint/error ids, `describedBy`, hint/error registration) and wraps children in a **`div`** with class **`field`**.
+- **`Radio.Label`** — [Label](../label/COMPONENT.md) with **`htmlFor`** tied to the input; contains the **`input`**, SVG marker, and optional **`children`** text.
+- **`Radio.Hint`** — optional; registers so its id is merged into **`aria-describedby`**; uses the disabled hint variant when the root is **`disabled`**.
+- **`Radio.Error`** — optional; error-styled **`Hint.Root`** and registers invalid state (same effect as **`variant="error"`** on the root for styling).
+- **Order:** **`Radio.Root`** → **`Radio.Label`** → **`Radio.Hint`** and/or **`Radio.Error`** when needed. Public API: **`Radio.Root`**, **`Radio.Label`**, **`Radio.Hint`**, **`Radio.Error`**.
 
 ### Minimal example
 
@@ -36,16 +70,13 @@ export function Example() {
 }
 ```
 
-## Rules
+### Rules
 
-- Support **controlled** (`checked` + `onChange`) and **uncontrolled** (`defaultChecked`); forward standard input change semantics from the native radio.
+- Support **controlled** (`checked` + `onChange`) and **uncontrolled** (`defaultChecked`); use standard input change semantics from the native radio.
 - Build a **group** with multiple **`Radio.Root`** instances sharing the same **`name`**; wrap in **`fieldset`** / **`legend`** when the group needs a visible or programmatic heading.
-- There is **no** separate `RadioGroup` component—selection is native HTML behavior or your own controlled state.
-- **`variant="error"`** or a mounted **`Radio.Error`** sets **`aria-invalid`** on the input and error styling on the root; **`disabled`** disables the input and dims the label/hint treatment.
-- **`aria-describedby`** on the root is merged with hint and error ids when those slots mount.
+- **`variant="error"`** or a mounted **`Radio.Error`** sets **`aria-invalid`** on the input and error styling on that root; **`disabled`** disables the input and dims the label/hint treatment.
+- **`aria-describedby`** on **`Radio.Root`** is merged with hint and error ids when those slots mount.
 - Set **`aria-label`** or ensure visible label text when **`Radio.Label`** has no readable children (icon-only or empty label).
-- **`Radio.Root`** **`ref`** is forwarded to the **native `input`** element.
-- DOM **`type`** is always **`radio`**; the design-system **`size`** prop lives on **`Radio.Root`** and does not map to the HTML `size` attribute (that key is omitted from input props).
 
 ## API
 
@@ -54,11 +85,11 @@ export function Example() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | variant | `"default" \| "error"` | `"default"` | no | Error styling and `data-invalid` when `error` or when `Radio.Error` is mounted. |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Marker, typography, and hint/error scale. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Marker, typography, and hint/error scale from one control token tier. |
 | id | `string` | auto (`useId`) | no | Input id; paired with `Radio.Label` via `htmlFor`. |
-| className | `string` | — | no | Class on the field wrapper `div`. |
-| disabled | `boolean` | — | no | Disables the input and label row. |
-| aria-describedby | `string` | — | no | Combined with hint and error ids when those slots exist. |
+| className | `string` | — | no | Class on the field wrapper (`.field` around Label, Hint, Error slots). |
+| disabled | `boolean` | — | no | Disables the input and label row; stays in sync with label visuals. |
+| aria-describedby | `string` | — | no | Combined with hint and error ids when `Radio.Hint` / `Radio.Error` mount. |
 | children | `React.ReactNode` | — | no | Typically `Label`, optional `Hint` / `Error`. |
 | ref | `React.Ref<HTMLInputElement>` | — | no | Ref to the native radio input. |
 | …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | — | no | Other native attributes on the `input` (e.g. `name`, `value`, `checked`, `defaultChecked`, `onChange`, `required`, `readOnly`, `form`). `type` is always `radio`. |
@@ -68,7 +99,7 @@ export function Example() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | children | `React.ReactNode` | — | no | Label text beside the marker; omit only if an accessible name is set on the root input via remaining root props (e.g. `aria-label`). |
-| className | `string` | — | no | Class on the label row. |
+| className | `string` | — | no | Class on the label row (`Label.Root`). |
 | …rest | `Omit<React.HTMLAttributes<HTMLLabelElement>, "htmlFor" \| "size">` | — | no | Other label attributes; `htmlFor` and `size` come from context. |
 
 ### Radio.Hint
@@ -76,14 +107,14 @@ export function Example() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | children | `React.ReactNode` | — | yes | Supplementary text below the label. |
-| className | `string` | — | no | Additional class on the hint slot. |
-| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally. |
+| className | `string` | — | no | Additional class on the hint slot (offset under the marker column). |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally for `aria-describedby`. |
 
 ### Radio.Error
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Error message text. |
+| children | `React.ReactNode` | — | yes | Error message text; registers invalid context (`aria-invalid` on input). |
 | className | `string` | — | no | Additional class on the error slot. |
 | …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally for `aria-describedby`. |
 
@@ -93,3 +124,14 @@ export function Example() {
 - [Switch](../switch/COMPONENT.md) — binary setting with a different control pattern.
 - [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — primitives used inside Radio; pair with [Input](../input/COMPONENT.md) in larger forms.
 - [Segmented control](../segmented-control/COMPONENT.md) — compact mode switching in one bar.
+
+## LLM note
+
+- Export: **`import { Radio } from "prime-ui-kit"`** — use **`Radio.Root`**, **`Radio.Label`**, **`Radio.Hint`**, **`Radio.Error`** only; there is **no** `RadioGroup`.
+- **`RadioRootProps`**: extends **`Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size">`** plus **`variant?`**, **`size?`**, **`className?`**, **`children?`**; **`ref`** → **`<input type="radio">`**.
+- **`variant`** literals: **`default`**, **`error`** — error semantics also activate when **`Radio.Error`** mounts inside that **`Radio.Root`**.
+- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**.
+- Grouping: repeat **`Radio.Root`** with the same **`name`**; for controlled mode, set **`checked`/`onChange`** (or **`defaultChecked`**) consistently across the group.
+- Do not invent a **`Radio.Group`** wrapper — it is not part of the API.
+- Per-root context: **`Radio.Error`** / **`variant="error"`** affect **that** instance’s input **`aria-invalid`** and wrapper **`data-invalid`**; for a whole-group message, either mirror **`variant="error"`** on each root in the group or add separate page-level copy as required by your form pattern.
+- **Playground demos** live under **`playground/snippets/radio/`** and are wired from **`playground/sections/RadioSection.tsx`**. **Recipes** under **`src/components/radio/examples/`** import **`prime-ui-kit`** for copy-paste after **`npm install prime-ui-kit`**.

package/src/components/radio/examples/notification-channel.tsx

@@ -0,0 +1,29 @@
+import { Radio } from "prime-ui-kit";
+
+import styles from "./radio-examples.module.css";
+
+/** Product alerts: mutually exclusive delivery channel (not multi-select — use Checkbox for that). */
+export default function NotificationChannelExample() {
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Security alerts</legend>
+      <p className={styles.helperBelowLegend}>
+        Choose one primary channel for account and login notices.
+      </p>
+      <div className={styles.columnTight}>
+        <Radio.Root name="security-alert-example" value="email" defaultChecked size="m">
+          <Radio.Label>Email</Radio.Label>
+          <Radio.Hint>Sent to your verified address immediately.</Radio.Hint>
+        </Radio.Root>
+        <Radio.Root name="security-alert-example" value="sms" size="m">
+          <Radio.Label>SMS</Radio.Label>
+          <Radio.Hint>Requires a phone number on file.</Radio.Hint>
+        </Radio.Root>
+        <Radio.Root name="security-alert-example" value="app" size="m">
+          <Radio.Label>Mobile app only</Radio.Label>
+          <Radio.Hint>No email or SMS; push when the app is installed.</Radio.Hint>
+        </Radio.Root>
+      </div>
+    </fieldset>
+  );
+}

package/src/components/radio/examples/plan-picker.tsx

@@ -0,0 +1,53 @@
+import { Radio } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./radio-examples.module.css";
+
+/** Controlled subscription tier: one `name`, `checked` + `onChange` driven by React state. */
+export default function PlanPickerExample() {
+  const [plan, setPlan] = React.useState<"starter" | "growth" | "scale">("growth");
+
+  return (
+    <>
+      <div className={styles.columnTight}>
+        <Radio.Root
+          name="plan-example"
+          value="starter"
+          size="m"
+          checked={plan === "starter"}
+          onChange={(e) => {
+            if (e.currentTarget.checked) setPlan("starter");
+          }}
+        >
+          <Radio.Label>Starter</Radio.Label>
+          <Radio.Hint>Up to 5 seats and basic reporting.</Radio.Hint>
+        </Radio.Root>
+        <Radio.Root
+          name="plan-example"
+          value="growth"
+          size="m"
+          checked={plan === "growth"}
+          onChange={(e) => {
+            if (e.currentTarget.checked) setPlan("growth");
+          }}
+        >
+          <Radio.Label>Growth</Radio.Label>
+          <Radio.Hint>Shared pipelines, SSO, and audit log.</Radio.Hint>
+        </Radio.Root>
+        <Radio.Root
+          name="plan-example"
+          value="scale"
+          size="m"
+          checked={plan === "scale"}
+          onChange={(e) => {
+            if (e.currentTarget.checked) setPlan("scale");
+          }}
+        >
+          <Radio.Label>Scale</Radio.Label>
+          <Radio.Hint>Dedicated support and regional data residency.</Radio.Hint>
+        </Radio.Root>
+      </div>
+      <p className={styles.selectionMeta}>Selected plan: {plan}</p>
+    </>
+  );
+}

package/src/components/radio/examples/radio-examples.module.css

@@ -0,0 +1,31 @@
+.fieldsetPlain {
+  margin: 0;
+  padding: 0;
+  border: none;
+  min-width: 0;
+}
+
+.legend {
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  font-weight: 600;
+  margin-bottom: var(--prime-sys-spacing-x2);
+}
+
+.columnTight {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x2);
+}
+
+.selectionMeta {
+  margin: var(--prime-sys-spacing-x3) 0 0;
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.helperBelowLegend {
+  margin: 0 0 var(--prime-sys-spacing-x2);
+  max-width: 40rem;
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  color: var(--prime-sys-color-content-secondary);
+}

package/src/components/radio/examples/settings-group.tsx

@@ -0,0 +1,30 @@
+import { Radio } from "prime-ui-kit";
+
+import styles from "./radio-examples.module.css";
+
+/** Settings screen: `fieldset` + `legend`, theme radios, one disabled tier-gated option. */
+export default function SettingsGroupExample() {
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Appearance</legend>
+      <div className={styles.columnTight}>
+        <Radio.Root name="theme-example" value="light" defaultChecked size="m">
+          <Radio.Label>Light</Radio.Label>
+          <Radio.Hint>Best for bright environments.</Radio.Hint>
+        </Radio.Root>
+        <Radio.Root name="theme-example" value="dark" size="m">
+          <Radio.Label>Dark</Radio.Label>
+          <Radio.Hint>Reduced glare in low light.</Radio.Hint>
+        </Radio.Root>
+        <Radio.Root name="theme-example" value="system" size="m">
+          <Radio.Label>Match system</Radio.Label>
+          <Radio.Hint>Follows your OS light/dark schedule.</Radio.Hint>
+        </Radio.Root>
+        <Radio.Root name="theme-example" value="contrast" size="m" disabled>
+          <Radio.Label>High contrast</Radio.Label>
+          <Radio.Hint>Available on Enterprise; contact sales to enable.</Radio.Hint>
+        </Radio.Root>
+      </div>
+    </fieldset>
+  );
+}

package/src/components/radio/examples/shipping-method.tsx

@@ -0,0 +1,26 @@
+import { Radio } from "prime-ui-kit";
+
+import styles from "./radio-examples.module.css";
+
+/** Checkout-style carrier choice: same `name`, short hints under each option. */
+export default function ShippingMethodExample() {
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Shipping method</legend>
+      <div className={styles.columnTight}>
+        <Radio.Root name="shipping-example" value="standard" defaultChecked size="m">
+          <Radio.Label>Standard (5–7 business days)</Radio.Label>
+          <Radio.Hint>Free on orders over $50.</Radio.Hint>
+        </Radio.Root>
+        <Radio.Root name="shipping-example" value="express" size="m">
+          <Radio.Label>Express (2 business days)</Radio.Label>
+          <Radio.Hint>Flat rate; tracking included.</Radio.Hint>
+        </Radio.Root>
+        <Radio.Root name="shipping-example" value="pickup" size="m">
+          <Radio.Label>Pick up in store</Radio.Label>
+          <Radio.Hint>Ready next day at your selected location.</Radio.Hint>
+        </Radio.Root>
+      </div>
+    </fieldset>
+  );
+}

package/src/components/segmented-control/COMPONENT.md

@@ -34,6 +34,41 @@ export function Example() {
 }
 ```
 
+### Canonical composition (reference)
+
+For a **single file** that combines **controlled mode**, **`SegmentedControl.Icon` + text**, **icon-only segments with visually hidden labels**, and layout notes (remember **`Root` does not forward `aria-label`**), see **`examples/canonical-composition.tsx`**. Imports use **`"prime-ui-kit"`** so the same patterns work in an app after installing the package.
+
+The **playground** (`playground/sections/SegmentedControlSection.tsx`) renders the same scenarios as **`playground/snippets/segmented/*.tsx`** (internal `@/` imports). The **`examples/`** files below mirror those snippets with **`"prime-ui-kit"`** imports.
+
+### Example files in `examples/`
+
+| File | Scenario (aligned with `playground/snippets/segmented/`) |
+|------|----------|
+| `sizes.tsx` | All four **`size`** values `s`–`xl` with identical segment labels |
+| `states.tsx` | Default group; **`disabled`** on one **`Item`**; **`disabled`** on **`Root`** |
+| `controlled.tsx` | **`value`** + **`onValueChange`** (no **`defaultValue`**) |
+| `composition.tsx` | **`Icon`** + label text; icon-only rows with visually hidden text in **`Item`** |
+| `full-width.tsx` | Narrow container; **`className`** overrides root **`width: fit-content`** so segments share width |
+| `features.tsx` | Two, three, and four segments; keyboard (**ArrowLeft** / **ArrowRight** on the group) |
+
+Additional English product-style recipes:
+
+| File | Scenario |
+|------|----------|
+| `canonical-composition.tsx` | Combined: icons, controlled period, icon-only (superset demo) |
+| `view-mode.tsx` | Catalog view: List / Grid / Table |
+| `pricing-toggle.tsx` | Billing: Monthly / Annual |
+| `catalog-filters.tsx` | Compact availability filter; **`size="s"`** |
+
+### Note for LLMs
+
+- **Imports:** `SegmentedControl`, `Icon`, and `Typography` from **`"prime-ui-kit"`** in **`examples/`**; paths are relative to `src/components/segmented-control/examples/`. Playground snippets use **`@/…`** but should stay behavior-identical to these files.
+- **Values are strings:** map `onValueChange` to app enums with a type guard or narrow union; **`Item` does not accept `aria-label`**—accessible names come from **visible** `children` and/or **visually hidden** text inside **`Item`**.
+- **`SegmentedControl.Icon`** is **`aria-hidden`**; always pair with visible text or a visually hidden span inside the same **`Item`**.
+- **`Root`** does **not** forward **`aria-label`**, **`aria-labelledby`**, or **`style`**: use a **wrapper** and visible copy, or **`aria-labelledby`** on a wrapper that references visible page text—not on **`Root`**.
+- **Keyboard:** **ArrowLeft** / **ArrowRight** move among **enabled** items; **`disabled`** on **`Item`** is skipped; **`defaultValue=""`** leaves no selection and **`Root`** is focusable until the user picks a segment.
+- **Many options or vertical layout:** prefer [Select](../select/COMPONENT.md); **tabbed panels** → [Tabs](../tabs/COMPONENT.md).
+
 ## Rules
 
 - **Controlled:** pass **`value`** and handle changes with **`onValueChange`**. **Uncontrolled:** use **`defaultValue`** (defaults to **`""`**).
@@ -59,7 +94,7 @@ export function Example() {
 | disabled | `boolean` | `false` | No | Disables the entire group |
 | size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Segment dimensions and typography |
 | children | `React.ReactNode` | — | Yes | `Item` nodes (and their content) |
-| className | `string` | — | No | Extra class on the container |
+| className | `string` | — | No | Extra class on the container (e.g. full-width override when the default **`width: fit-content`** is too narrow—see **`examples/full-width.tsx`**) |
 
 ### SegmentedControl.Item
 

package/src/components/segmented-control/examples/canonical-composition.tsx

@@ -0,0 +1,70 @@
+import { Icon, SegmentedControl, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./segmented-examples.module.css";
+
+/**
+ * Canonical composition: controlled group, icon + text, and icon-only segments with visually hidden labels.
+ */
+export default function CanonicalCompositionExample() {
+  const [period, setPeriod] = React.useState("week");
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-l)",
+        alignItems: "flex-start",
+      }}
+    >
+      <SegmentedControl.Root defaultValue="light" size="m">
+        <SegmentedControl.Item value="light">
+          <SegmentedControl.Icon>
+            <Icon name="theme.light" size="m" />
+          </SegmentedControl.Icon>
+          Light
+        </SegmentedControl.Item>
+        <SegmentedControl.Item value="dark">
+          <SegmentedControl.Icon>
+            <Icon name="theme.dark" size="m" />
+          </SegmentedControl.Icon>
+          Dark
+        </SegmentedControl.Item>
+      </SegmentedControl.Root>
+
+      <SegmentedControl.Root value={period} onValueChange={setPeriod} size="m">
+        <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
+        <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
+        <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+      </SegmentedControl.Root>
+
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-s)",
+          alignItems: "flex-start",
+        }}
+      >
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          Layout preview
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="grid" size="m">
+          <SegmentedControl.Item value="feed">
+            <SegmentedControl.Icon>
+              <Icon name="nav.home" size="m" />
+            </SegmentedControl.Icon>
+            <span className={styles.visuallyHidden}>Feed</span>
+          </SegmentedControl.Item>
+          <SegmentedControl.Item value="grid">
+            <SegmentedControl.Icon>
+              <Icon name="nav.layoutGrid" size="m" />
+            </SegmentedControl.Icon>
+            <span className={styles.visuallyHidden}>Grid</span>
+          </SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/segmented-control/examples/catalog-filters.tsx

@@ -0,0 +1,41 @@
+import { SegmentedControl, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+type StockFilter = "all" | "in_stock" | "preorder";
+
+function isStockFilter(value: string): value is StockFilter {
+  return value === "all" || value === "in_stock" || value === "preorder";
+}
+
+/**
+ * Compact filter strip: few exclusive scopes above a product grid (pair with Select when options grow).
+ */
+export default function CatalogFiltersExample() {
+  const [stock, setStock] = React.useState<StockFilter>("all");
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-s)",
+        alignItems: "flex-start",
+      }}
+    >
+      <Typography.Root as="span" variant="caption" tone="muted">
+        Availability
+      </Typography.Root>
+      <SegmentedControl.Root
+        value={stock}
+        onValueChange={(v) => {
+          if (isStockFilter(v)) setStock(v);
+        }}
+        size="s"
+      >
+        <SegmentedControl.Item value="all">All</SegmentedControl.Item>
+        <SegmentedControl.Item value="in_stock">In stock</SegmentedControl.Item>
+        <SegmentedControl.Item value="preorder">Pre-order</SegmentedControl.Item>
+      </SegmentedControl.Root>
+    </div>
+  );
+}

package/src/components/segmented-control/examples/composition.tsx

@@ -0,0 +1,55 @@
+import { Icon, SegmentedControl, Typography } from "prime-ui-kit";
+
+import styles from "./segmented-examples.module.css";
+
+/** Icon + text and icon-only segments with visually hidden labels (mirrors playground/snippets/segmented/composition). */
+export default function SegmentedCompositionExample() {
+  return (
+    <div className={styles.demoStack}>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          Icon and label
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="light" size="m">
+          <SegmentedControl.Item value="light">
+            <SegmentedControl.Icon>
+              <Icon name="theme.light" size="m" />
+            </SegmentedControl.Icon>
+            Light
+          </SegmentedControl.Item>
+          <SegmentedControl.Item value="dark">
+            <SegmentedControl.Icon>
+              <Icon name="theme.dark" size="m" />
+            </SegmentedControl.Icon>
+            Dark
+          </SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          Icon-only + visually hidden text
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="grid" size="m">
+          <SegmentedControl.Item value="feed">
+            <SegmentedControl.Icon>
+              <Icon name="nav.home" size="m" />
+            </SegmentedControl.Icon>
+            <span className={styles.visuallyHidden}>Feed</span>
+          </SegmentedControl.Item>
+          <SegmentedControl.Item value="grid">
+            <SegmentedControl.Icon>
+              <Icon name="nav.layoutGrid" size="m" />
+            </SegmentedControl.Icon>
+            <span className={styles.visuallyHidden}>Grid</span>
+          </SegmentedControl.Item>
+          <SegmentedControl.Item value="compact">
+            <SegmentedControl.Icon>
+              <Icon name="theme.light" size="m" />
+            </SegmentedControl.Icon>
+            <span className={styles.visuallyHidden}>Compact</span>
+          </SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/segmented-control/examples/controlled.tsx

@@ -0,0 +1,23 @@
+import { SegmentedControl, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./segmented-examples.module.css";
+
+/** Controlled selection with `value` and `onValueChange` (mirrors playground/snippets/segmented/controlled). */
+export default function SegmentedControlledExample() {
+  const [controlled, setControlled] = React.useState("week");
+
+  return (
+    <div className={styles.demoStack}>
+      <SegmentedControl.Root value={controlled} onValueChange={setControlled}>
+        <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
+        <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
+        <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+      </SegmentedControl.Root>
+      <Typography.Root as="p" variant="body-compact" tone="muted" className={styles.demoCaption}>
+        Selected: <strong>{controlled}</strong> — state is held in React (<code>value</code> +{" "}
+        <code>onValueChange</code>).
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/segmented-control/examples/features.tsx

@@ -0,0 +1,45 @@
+import { SegmentedControl, Typography } from "prime-ui-kit";
+
+import styles from "./segmented-examples.module.css";
+
+/** Two, three, and four segments; arrow keys on the focused radiogroup (mirrors playground/snippets/segmented/features). */
+export default function SegmentedFeaturesExample() {
+  return (
+    <div className={styles.demoStack}>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          Two segments
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="all" size="m">
+          <SegmentedControl.Item value="all">All tasks</SegmentedControl.Item>
+          <SegmentedControl.Item value="mine">Mine</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          Three segments
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="day" size="m">
+          <SegmentedControl.Item value="day">Today</SegmentedControl.Item>
+          <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          Four segments
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="q1" size="m">
+          <SegmentedControl.Item value="q1">Q1</SegmentedControl.Item>
+          <SegmentedControl.Item value="q2">Q2</SegmentedControl.Item>
+          <SegmentedControl.Item value="q3">Q3</SegmentedControl.Item>
+          <SegmentedControl.Item value="q4">Q4</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <Typography.Root as="p" variant="body-compact" tone="muted" className={styles.demoCaption}>
+        With focus on the <code>radiogroup</code>, ArrowLeft / ArrowRight move selection (disabled
+        items are skipped).
+      </Typography.Root>
+    </div>
+  );
+}