prime-ui-kit 0.3.2 → 0.4.0

package/src/components/segmented-progress-bar/COMPONENT.md

@@ -28,15 +28,29 @@
 
 - **`SegmentedProgressBar.Root`** — outer wrapper with **`data-size`**, **`data-segment-gap`**, optional visible **`label`**, optional visually hidden distribution **`span`** (when **`label`** is set), and a **`role="group"`** track with one **`div`** per segment (presentational fills).
 
-### Scenarios (see `examples/`)
+### Playground (`playground/sections/SegmentedProgressBarSection.tsx`)
 
-| Scenario | Approach |
-|----------|----------|
-| Multi-phase rollout | Weight segments by cohort or phase (e.g. internal / beta / GA); use **`tone`** to distinguish states. → [`examples/multi-phase-rollout.tsx`](examples/multi-phase-rollout.tsx) |
-| Distribution / breakdown | **`label`** for the chart title; **`label`** on each segment for tooltips and the spoken distribution string. → [`examples/distribution-breakdown.tsx`](examples/distribution-breakdown.tsx) |
-| Gaps between segments | Default **`segmentGap="none"`**; **`hairline`** for visible separators without changing weights. → [`examples/segment-gaps.tsx`](examples/segment-gaps.tsx) |
-| Size ladder | **`size="s" | "m" | "l" | "xl"`** — same tokens scale as ProgressBar. → [`examples/size-ladder.tsx`](examples/size-ladder.tsx) |
-| Category mix (storage-style) | Multiple **`tone`** values for categories that are not “good/bad”, e.g. content types. → [`examples/storage-mix.tsx`](examples/storage-mix.tsx) |
+The section renders snippets from **`playground/snippets/progress/`** (segmented bar demos only):
+
+| Demo (section) | Snippet | What it shows |
+|----------------|---------|----------------|
+| Распределение | [`segmented-distribution.tsx`](../../../playground/snippets/progress/segmented-distribution.tsx) | Weights as shares of the sum (like percentages when the total is 100); visible **`label`** and per-segment **`label`** / **`tone`** (Russian copy in the snippet; **`previewLayout="stack"`**). |
+| Размеры | [`segmented-sizes.tsx`](../../../playground/snippets/progress/segmented-sizes.tsx) | **`size`** **`s`**, **`m`**, **`l`**, **`xl`** with the same weights (**`previewLayout="stack-center"`**). |
+| Зазор между сегментами | [`segmented-gap.tsx`](../../../playground/snippets/progress/segmented-gap.tsx) | Default **`segmentGap="none"`** vs **`hairline`** (1px separators); **`previewLayout="stack"`**. |
+
+`playground/snippets/segmented/*` is for **SegmentedControl**, not this component.
+
+### Example files in `examples/`
+
+Imports use **`"prime-ui-kit"`** so the same patterns work in an app. **`distribution-breakdown`**, **`size-ladder`**, and **`segment-gaps`** mirror the three playground frames above (same structure; English labels and copy where the snippets use Russian).
+
+| File | Scenario |
+|------|----------|
+| [`distribution-breakdown.tsx`](examples/distribution-breakdown.tsx) | **`label`** + weighted segments + **`tone`** (`snippets/progress/segmented-distribution.tsx`). |
+| [`size-ladder.tsx`](examples/size-ladder.tsx) | **`size`** ladder **`s`–`xl`** (`snippets/progress/segmented-sizes.tsx`; snippet wraps rows in **`stack`** + **`examplePreviewBleed`** for the playground). |
+| [`segment-gaps.tsx`](examples/segment-gaps.tsx) | **`segmentGap`** **`none`** vs **`hairline`** (`snippets/progress/segmented-gap.tsx`). |
+| [`multi-phase-rollout.tsx`](examples/multi-phase-rollout.tsx) | Phase mix (internal / beta / GA) with distinct **`tone`** values — not mounted in the section; extra recipe. |
+| [`storage-mix.tsx`](examples/storage-mix.tsx) | Category-style breakdown with **`hairline`** — not mounted in the section; extra recipe. |
 
 ### Minimal example
 
@@ -94,6 +108,7 @@ export function Example() {
 
 ## LLM note
 
+- Playground source of truth for live demos: **`playground/sections/SegmentedProgressBarSection.tsx`** → **`playground/snippets/progress/segmented-{distribution,sizes,gap}.tsx`** (not **`snippets/segmented/`**, which is SegmentedControl).
 - Export: **`import { SegmentedProgressBar } from "prime-ui-kit"`** — public surface is **`SegmentedProgressBar.Root`** only (namespace object).
 - **`SegmentedProgressBarRootProps`:** **`segments`** (required), **`label?`**, **`size?`**, **`segmentGap?`**, **`className?`**; **`ref`** → track **`div`** (**`role="group"`**).
 - **`SegmentedProgressSegment`:** **`value`** (number), **`label?`**, **`tone?`** — **`tone`** literals: **`primary`**, **`success`**, **`warning`**, **`danger`**, **`neutral`**.

package/src/components/select/COMPONENT.md

@@ -23,7 +23,7 @@ A single-select field: by default (**`native`** `false`) it is a combobox — a
 - **`Select.Root`** — owns value (controlled or uncontrolled), `size`, `hasError`, `disabled`, **`placeholder`**, and **`native`**. When **`native`** is `false`, it also owns open state and highlight. Wrap everything else.
 - **`Select.Trigger`** — (non-**`native`** only) the combobox `button` (fixed chevron on the right). Put **`Select.Value`** inside; optionally **`Select.TriggerIcon`** before **`Select.Value`**. The implementation sets the trigger **`id`**; you cannot override it — associate an external [Label](../label/COMPONENT.md) with **`aria-labelledby`** pointing at the label’s **`id`**.
 - **`Select.Value`** — (non-**`native`** only) displays the selected item label, otherwise falls back to the raw value or **`placeholder`** (hint styling when empty).
-- **`Select.Content`** — when **`native`** is `false`: portaled **`role="listbox"`**; rendered in the tree always but hidden when closed. Place **`Select.Item`** rows (and optional groups/separators) inside. Must come after the trigger in the document for a predictable structure. When **`native`** is `true`, **`Select.Content`** is optional as a structural wrapper; only **`Select.Item`** (and groups) contribute to the DOM **`<select>`**.
+- **`Select.Content`** — when **`native`** is `false`: portaled **`role="listbox"`** with **`display: none`** while closed (nodes stay mounted). Place **`Select.Item`** rows (and optional groups/separators) inside. Must come after the trigger in the document for a predictable structure. When **`native`** is `true`, **`Select.Content`** is optional as a structural wrapper; only **`Select.Item`** (and groups) contribute to the DOM **`<select>`**.
 - **`Select.Item`** — one option per row; optional **`Select.ItemIcon`** children are recognized by component type and rendered before the text. Use **`label`** when the trigger should show different text than the row content.
 - **`Select.Group`** / **`Select.GroupLabel`** / **`Select.Separator`** — optional structure inside **`Select.Content`**.
 
@@ -76,14 +76,44 @@ export function NativeExample() {
 
 You can wrap items in **`Select.Content`** for parity with the composable tree; behavior is the same.
 
-### Extended examples
+### Playground snippets (live demos)
 
-- [`./examples/01-country.tsx`](./examples/01-country.tsx) — Country or region field with **`Label.Root`**, combobox, and helper copy (**`Typography.Root`**).
-- [`./examples/02-controlled.tsx`](./examples/02-controlled.tsx) — Controlled **`value`** / **`onChange`** with subscription tier options.
-- [`./examples/03-groups.tsx`](./examples/03-groups.tsx) — **`Select.Group`**, **`Select.GroupLabel`**, and **`Select.Separator`** for regional time zones.
-- [`./examples/04-full-width-form.tsx`](./examples/04-full-width-form.tsx) — Form column where the trigger spans the track (**`width: 100%`** via kit styles on the trigger; width the parent column).
+These files power **`playground/sections/SelectSection.tsx`** (Russian copy in the playground UI). Order matches the section.
 
-**LLM note:** Prefer reading the runnable files under `./examples/*.tsx` for full scenarios, prop combinations, and composition patterns; this page keeps the contract (rules + API tables) authoritative.
+| File | Intent |
+|------|--------|
+| `playground/snippets/select/sizes.tsx` | Four **`size`** values **`s`–`xl`** in one column |
+| `playground/snippets/select/states.tsx` | Placeholder only, **`defaultValue`**, root **`disabled`**, **`hasError`** |
+| `playground/snippets/select/controlled.tsx` | **`value`** / **`onChange`** with caption showing parent state |
+| `playground/snippets/select/composition.tsx` | **`Select.TriggerIcon`**, **`Select.ItemIcon`**, item **`label`** vs short row text |
+| `playground/snippets/select/full-width.tsx` | Trigger fills a narrow shell (**`width: 100%`** from kit styles) |
+| `playground/snippets/select/native.tsx` | **`Select.Root`** **`native`** with optional **`Select.Content`** wrapper |
+| `playground/snippets/select/features.tsx` | **`Group`** / **`GroupLabel`** / **`Separator`**, disabled item, long list + scroll |
+
+### Examples next to this file
+
+Runnable examples use **`@/`** in the workspace; published consumers import **`prime-ui-kit`**. **`pattern-*`** files mirror the playground snippets above in English (same APIs).
+
+| File | Intent |
+|------|--------|
+| `examples/pattern-sizes.tsx` | **`sizes.tsx`** snippet |
+| `examples/pattern-states.tsx` | **`states.tsx`** snippet |
+| `examples/pattern-controlled.tsx` | **`controlled.tsx`** snippet |
+| `examples/pattern-composition.tsx` | **`composition.tsx`** snippet |
+| `examples/pattern-full-width.tsx` | **`full-width.tsx`** snippet |
+| `examples/pattern-native.tsx` | **`native.tsx`** snippet |
+| `examples/pattern-features.tsx` | **`features.tsx`** snippet |
+
+### Additional scenarios
+
+| File | Intent |
+|------|--------|
+| [`./examples/01-country.tsx`](./examples/01-country.tsx) | Visible **`Label.Root`** + **`aria-labelledby`** on **`Select.Trigger`** and helper copy |
+| [`./examples/02-controlled.tsx`](./examples/02-controlled.tsx) | Controlled **`value`** / **`onChange`** with **`Label.Root`** (same tier options as **`pattern-controlled.tsx`**) |
+| [`./examples/03-groups.tsx`](./examples/03-groups.tsx) | Time zones with **`Select.Group`**, **`Select.GroupLabel`**, **`Select.Separator`** |
+| [`./examples/04-full-width-form.tsx`](./examples/04-full-width-form.tsx) | Multi-field form column; triggers span the track |
+
+**LLM note:** Prefer **`pattern-*`** and `playground/snippets/select/*.tsx` for parity with live demos; use **`01`–`04`** for labeled forms and richer scenarios. This page keeps the contract (rules + API tables) authoritative.
 
 ## Rules
 
@@ -106,7 +136,7 @@ You can wrap items in **`Select.Content`** for parity with the composable tree;
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Trigger and list sizing tokens |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Token tier: trigger height, type scale, padding, icon sizes in trigger and list |
 | value | `string` | — | No | Controlled selected value |
 | defaultValue | `string` | — | No | Initial value when uncontrolled |
 | onChange | `(value: string) => void` | — | No | Fires after a new value is selected |
@@ -147,7 +177,7 @@ You can wrap items in **`Select.Content`** for parity with the composable tree;
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | className | `string` | — | No | Class on the portaled listbox container |
-| children | `React.ReactNode` | — | Yes | Items, groups, and separators |
+| children | `React.ReactNode` | — | Yes | Items, groups, and separators (listbox portal stays mounted; hidden while closed) |
 
 ### Select.Item
 

package/src/components/select/examples/examples.module.css

@@ -4,6 +4,17 @@
   gap: var(--prime-sys-spacing-s);
 }
 
+.stackNarrow {
+  width: 100%;
+  max-width: calc(var(--prime-sys-unit-1rem) * 22);
+}
+
+.fullWidthShell {
+  box-sizing: border-box;
+  width: 100%;
+  max-width: calc(var(--prime-sys-unit-1rem) * 20);
+}
+
 .field {
   display: flex;
   flex-direction: column;

package/src/components/select/examples/pattern-composition.tsx

@@ -0,0 +1,40 @@
+import { Select } from "@/components/select/Select";
+import { Icon } from "@/icons";
+
+import styles from "./examples.module.css";
+
+/** `TriggerIcon`, `ItemIcon`, and item `label` for trigger vs row text; mirrors `playground/snippets/select/composition.tsx`. */
+export default function SelectPatternCompositionExample() {
+  return (
+    <div className={`${styles.stack} ${styles.stackNarrow}`}>
+      <Select.Root size="m" defaultValue="eur" placeholder="Report currency">
+        <Select.Trigger>
+          <Select.TriggerIcon>
+            <Icon name="nav.layoutGrid" size="s" tone="subtle" />
+          </Select.TriggerIcon>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="rub" label="RUB — Russian ruble">
+            <Select.ItemIcon>
+              <Icon name="nav.layoutGrid" size="s" tone="subtle" />
+            </Select.ItemIcon>
+            ₽ RUB
+          </Select.Item>
+          <Select.Item value="eur" label="EUR — Euro">
+            <Select.ItemIcon>
+              <Icon name="nav.layoutGrid" size="s" tone="subtle" />
+            </Select.ItemIcon>
+            € EUR
+          </Select.Item>
+          <Select.Item value="usd" label="USD — US dollar">
+            <Select.ItemIcon>
+              <Icon name="nav.layoutGrid" size="s" tone="subtle" />
+            </Select.ItemIcon>
+            $ USD
+          </Select.Item>
+        </Select.Content>
+      </Select.Root>
+    </div>
+  );
+}

package/src/components/select/examples/pattern-controlled.tsx

@@ -0,0 +1,29 @@
+import * as React from "react";
+
+import { Select } from "@/components/select/Select";
+import { Typography } from "@/components/typography/Typography";
+
+import styles from "./examples.module.css";
+
+/** Controlled `value` / `onChange`; mirrors `playground/snippets/select/controlled.tsx`. */
+export default function SelectPatternControlledExample() {
+  const [tier, setTier] = React.useState("pro");
+
+  return (
+    <div className={`${styles.stack} ${styles.stackNarrow}`}>
+      <Select.Root size="m" value={tier} onChange={setTier} placeholder="Tier">
+        <Select.Trigger aria-label="Subscription tier">
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="free">Free</Select.Item>
+          <Select.Item value="pro">Pro</Select.Item>
+          <Select.Item value="team">Team</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Typography.Root as="p" variant="caption" tone="muted" className={styles.caption}>
+        Current value in parent state: <code>{tier}</code>
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/select/examples/pattern-features.tsx

@@ -0,0 +1,33 @@
+import { Select } from "@/components/select/Select";
+
+const ZONES = ["A", "B", "C", "D", "E", "F", "G", "H", "I", "K"] as const;
+
+/** Groups, labels, separator, disabled item, long scrollable list; mirrors `playground/snippets/select/features.tsx`. */
+export default function SelectPatternFeaturesExample() {
+  return (
+    <Select.Root size="m" placeholder="Zones and groups">
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        <Select.Group>
+          <Select.GroupLabel>Available now</Select.GroupLabel>
+          <Select.Item value="east-1">East — node 1</Select.Item>
+          <Select.Item value="east-2">East — node 2</Select.Item>
+        </Select.Group>
+        <Select.Separator />
+        <Select.Group>
+          <Select.GroupLabel>Planned</Select.GroupLabel>
+          <Select.Item value="west-1" disabled>
+            West — node 1 (reserved)
+          </Select.Item>
+          {ZONES.map((z, i) => (
+            <Select.Item key={z} value={`zone-${i}`}>
+              Reserve {z}
+            </Select.Item>
+          ))}
+        </Select.Group>
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/src/components/select/examples/pattern-full-width.tsx

@@ -0,0 +1,21 @@
+import { Select } from "@/components/select/Select";
+
+import styles from "./examples.module.css";
+
+/** Narrow column shows trigger `width: 100%`; mirrors `playground/snippets/select/full-width.tsx`. */
+export default function SelectPatternFullWidthExample() {
+  return (
+    <div className={styles.fullWidthShell}>
+      <Select.Root size="m" defaultValue="ship" placeholder="Shipping method">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="pickup">Pickup</Select.Item>
+          <Select.Item value="ship">Courier</Select.Item>
+          <Select.Item value="post">Post</Select.Item>
+        </Select.Content>
+      </Select.Root>
+    </div>
+  );
+}

package/src/components/select/examples/pattern-native.tsx

@@ -0,0 +1,14 @@
+import { Select } from "@/components/select/Select";
+
+/** Native `<select>` via `native`; optional `Select.Content` wrapper; mirrors `playground/snippets/select/native.tsx`. */
+export default function SelectPatternNativeExample() {
+  return (
+    <Select.Root native size="m" placeholder="Mode">
+      <Select.Content>
+        <Select.Item value="auto">Auto</Select.Item>
+        <Select.Item value="light">Light</Select.Item>
+        <Select.Item value="dark">Dark</Select.Item>
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/src/components/select/examples/pattern-sizes.tsx

@@ -0,0 +1,51 @@
+import { Select } from "@/components/select/Select";
+
+import styles from "./examples.module.css";
+
+/** `size` ladder `s`–`xl`; mirrors `playground/snippets/select/sizes.tsx`. */
+export default function SelectPatternSizesExample() {
+  return (
+    <div className={`${styles.stack} ${styles.stackNarrow}`}>
+      <Select.Root size="s" placeholder="Size s">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="a">A</Select.Item>
+          <Select.Item value="b">B</Select.Item>
+          <Select.Item value="c">C</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Select.Root size="m" placeholder="Size m">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="a">A</Select.Item>
+          <Select.Item value="b">B</Select.Item>
+          <Select.Item value="c">C</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Select.Root size="l" placeholder="Size l">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="a">A</Select.Item>
+          <Select.Item value="b">B</Select.Item>
+          <Select.Item value="c">C</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Select.Root size="xl" placeholder="Size xl">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="a">A</Select.Item>
+          <Select.Item value="b">B</Select.Item>
+          <Select.Item value="c">C</Select.Item>
+        </Select.Content>
+      </Select.Root>
+    </div>
+  );
+}

package/src/components/select/examples/pattern-states.tsx

@@ -0,0 +1,47 @@
+import { Select } from "@/components/select/Select";
+
+import styles from "./examples.module.css";
+
+/** Placeholder, `defaultValue`, root `disabled`, `hasError`; mirrors `playground/snippets/select/states.tsx`. */
+export default function SelectPatternStatesExample() {
+  return (
+    <div className={`${styles.stack} ${styles.stackNarrow}`}>
+      <Select.Root size="m" placeholder="Placeholder only">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="a">Option A</Select.Item>
+          <Select.Item value="b">Option B</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Select.Root size="m" defaultValue="b" placeholder="With default value">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="a">Option A</Select.Item>
+          <Select.Item value="b">Option B</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Select.Root size="m" defaultValue="on" disabled placeholder="Disabled">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="off">Off</Select.Item>
+          <Select.Item value="on">On</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Select.Root size="m" hasError placeholder="Validation error">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="1">Item 1</Select.Item>
+          <Select.Item value="2">Item 2</Select.Item>
+        </Select.Content>
+      </Select.Root>
+    </div>
+  );
+}

package/src/components/slider/COMPONENT.md

@@ -35,14 +35,22 @@ export function Example() {
 }
 ```
 
-### Extended examples
+### Playground-aligned examples
 
-- [`./examples/01-volume.tsx`](./examples/01-volume.tsx) — Volume on a 0–100 scale with helper copy under the track.
-- [`./examples/02-price-range.tsx`](./examples/02-price-range.tsx) — Stepped “maximum price” filter with a `Hint` for how results update.
-- [`./examples/03-controlled.tsx`](./examples/03-controlled.tsx) — Controlled `value` / `onChange` with a live numeric readout.
-- [`./examples/04-disabled.tsx`](./examples/04-disabled.tsx) — Disabled preset until a parent feature is available.
+**`playground/sections/SliderSection.tsx`** and **`playground/snippets/slider/`** define the demo order and code shown in the playground (Russian UI copy in snippets). Matching runnable package examples (imports from **`"prime-ui-kit"`**) live next to this file:
 
-**LLM note:** Prefer reading the runnable files under `./examples/*.tsx` for full scenarios, prop combinations, and composition with `Typography` / `Hint`; this page keeps the contract (rules + API tables) authoritative.
+| Playground block | Snippet | Example file |
+|------------------|---------|--------------|
+| Sizes | `sizes.tsx` | `sizes.tsx` |
+| States | `states.tsx` | `states.tsx` |
+| Controlled | `controlled.tsx` | `controlled.tsx` |
+| Composition | `composition.tsx` | `composition.tsx` |
+| Full width | `full-width.tsx` | `full-width.tsx` |
+| Features (range / step) | `features.tsx` | `features.tsx` |
+
+Shared layout for controlled and full-width demos: **`examples/examples.module.css`**.
+
+**LLM note:** Prefer reading the runnable files under `./examples/*.tsx` for full scenarios and prop combinations; this page keeps the contract (rules + API tables) authoritative.
 
 ## Rules
 
@@ -59,17 +67,17 @@ export function Example() {
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| value | `number` | — | No | Controlled value |
-| defaultValue | `number` | — | No | Initial value when uncontrolled; if omitted, the internal initial value is `min` (clamped to `[min, max]`) |
-| min | `number` | `0` | No | Minimum value |
-| max | `number` | `100` | No | Maximum value |
+| value | `number` | — | No | Controlled value; use with **`onChange`** for external state |
+| defaultValue | `number` | — | No | Initial value when uncontrolled; clamped to **`[min, max]`**; if omitted, the internal initial value is **`min`** |
+| min | `number` | `0` | No | Minimum for the native `type="range"` |
+| max | `number` | `100` | No | Maximum for the native `type="range"` |
 | step | `number` | `1` | No | Step increment (may be fractional) |
-| disabled | `boolean` | — | No | Disables the range input |
-| onChange | `(value: number) => void` | — | No | Called when the value updates |
-| label | `string` | — | No | Visible label above the track; wires `htmlFor` / `id` on the input |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Track, thumb, and label scale |
-| className | `string` | — | No | Class on the root `div` |
-| aria-label | `string` | — | No | Accessible name when there is no `label` |
+| disabled | `boolean` | — | No | Blocks input and lowers track opacity |
+| onChange | `(value: number) => void` | — | No | Fires when the value changes after user input (pointer, touch, or native range keys) |
+| label | `string` | — | No | Text above the track; creates an associated **`label`** with **`htmlFor`** on the input |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Track height, thumb, and label type scale from one control token tier |
+| className | `string` | — | No | Extra class on the root container |
+| aria-label | `string` | — | No | Accessible name when there is no visible **`label`** |
 
 ## Related
 

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

@@ -0,0 +1,14 @@
+import { Slider } from "prime-ui-kit";
+
+/**
+ * Visible `label` (linked `label` / `htmlFor` to the input) vs no visible label — then set `aria-label`
+ * for screen readers (fractional step for “layer opacity”).
+ */
+export default function SliderCompositionExample() {
+  return (
+    <>
+      <Slider.Root label="Screen brightness" defaultValue={55} />
+      <Slider.Root defaultValue={20} min={0} max={1} step={0.05} aria-label="Layer opacity" />
+    </>
+  );
+}

package/src/components/slider/examples/controlled.tsx

@@ -0,0 +1,23 @@
+import { Slider } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** Controlled pair `value` + `onChange`; mirror the current value in adjacent copy. */
+export default function SliderControlledExample() {
+  const [level, setLevel] = React.useState(62);
+
+  return (
+    <div className={styles.controlledColumn}>
+      <Slider.Root
+        label="Reserve level"
+        value={level}
+        onChange={setLevel}
+        min={0}
+        max={100}
+        step={1}
+      />
+      <span className={styles.valueHint}>Current value: {level}%</span>
+    </div>
+  );
+}

package/src/components/slider/examples/examples.module.css

@@ -15,3 +15,23 @@
   margin: 0;
   color: var(--prime-sys-color-content-secondary);
 }
+
+.controlledColumn {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x2);
+  width: 100%;
+  max-width: 20rem;
+  box-sizing: border-box;
+}
+
+.valueHint {
+  margin: 0;
+  font-size: var(--prime-sys-typography-sizeScale-xs);
+  line-height: var(--prime-sys-typography-lineHeightScale-xs);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.narrowColumn {
+  width: min(12rem, 100%);
+}

package/src/components/slider/examples/features.tsx

@@ -0,0 +1,17 @@
+import { Slider } from "prime-ui-kit";
+
+/** Custom range and stepping: `min` / `max` / `step` — e.g. whole degrees or coarse percentage stops. */
+export default function SliderFeaturesExample() {
+  return (
+    <>
+      <Slider.Root label="Temperature, °C" min={16} max={30} step={1} defaultValue={22} />
+      <Slider.Root
+        label="Position by quarters (step 25)"
+        min={0}
+        max={100}
+        step={25}
+        defaultValue={50}
+      />
+    </>
+  );
+}

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

@@ -0,0 +1,12 @@
+import { Slider } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Root stretches to the parent width — in a narrow column the track grows with the column. */
+export default function SliderFullWidthExample() {
+  return (
+    <div className={styles.narrowColumn}>
+      <Slider.Root label="Width inside a narrow column" defaultValue={40} />
+    </div>
+  );
+}

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

@@ -0,0 +1,15 @@
+import { Slider } from "prime-ui-kit";
+
+/**
+ * Four `size` values (`s`–`xl`): track height, thumb, and label type ramp stay on one control token tier.
+ */
+export default function SliderSizesExample() {
+  return (
+    <>
+      <Slider.Root size="s" label="Size s" defaultValue={30} />
+      <Slider.Root size="m" label="Size m" defaultValue={40} />
+      <Slider.Root size="l" label="Size l" defaultValue={50} />
+      <Slider.Root size="xl" label="Size xl" defaultValue={60} />
+    </>
+  );
+}

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

@@ -0,0 +1,11 @@
+import { Slider } from "prime-ui-kit";
+
+/** Default interaction vs `disabled`: lower opacity and no pointer/keyboard input on the range control. */
+export default function SliderStatesExample() {
+  return (
+    <>
+      <Slider.Root label="Volume" defaultValue={45} />
+      <Slider.Root label="Disabled example" defaultValue={35} disabled />
+    </>
+  );
+}

package/src/components/stepper/COMPONENT.md

@@ -29,6 +29,26 @@ Multi-step progress UI on a semantic ordered list (`<ol>` / `<li>`) for **`Stepp
 - **`HorizontalStepper.Root`** — non-semantic **`div`** rail; children: **`SeparatorIcon`** and **`Item`** buttons, each with **`ItemIndicator`** inside.
 - **`VerticalStepper.Root`** — non-semantic **`div`** column; children: **`Item`** rows with **`ItemIndicator`**, label text, and optional **`Arrow`**.
 
+### Scenarios (playground + `examples/`)
+
+Live demos use **`playground/snippets/stepper/*.tsx`** (see **`playground/sections/StepperSection.tsx`**). The table lists the same scenarios with package-oriented copies under **`examples/`** (aligned 1:1 with those snippets; order matches the playground section).
+
+| Scenario | What it shows | `examples/` |
+|----------|---------------|-------------|
+| Sizes | Four **`size`** values on **`Stepper.Root`** (`s`–`xl`), same three steps per row. | [`examples/sizes.tsx`](examples/sizes.tsx) |
+| Low-level API | **`HorizontalStepper`** and **`VerticalStepper`** with explicit per-row **`state`** (no **`currentStep`** / semantic **`<ol>`**). | [`examples/low-level-api.tsx`](examples/low-level-api.tsx) |
+| States | **`disabled`** step and **`status="error"`** with custom **`Indicator`** content. | [`examples/states.tsx`](examples/states.tsx) |
+| Orientation | **`orientation="horizontal"`** with **`SeparatorIcon`**; vertical default with **`Stepper.Arrow`** on steps. | [`examples/orientation.tsx`](examples/orientation.tsx) |
+| Controlled | Parent **`currentStep`** plus **Back** / **Next** **`Button`** actions. | [`examples/controlled.tsx`](examples/controlled.tsx) |
+| Composition | Custom **`Indicator`**, **`Content`**, and an extra icon beside the label (**`IconMail`**). | [`examples/composition.tsx`](examples/composition.tsx) |
+| Full width | Horizontal rail spanning a wide card; root **`className`** spreads steps (**`width: 100%`**, **`justify-content: space-between`**). | [`examples/full-width.tsx`](examples/full-width.tsx) |
+| Polymorphic **`as`** | **`HorizontalStepper.SeparatorIcon`** and **`VerticalStepper.Arrow`** with **`as={IconHouse}`** / **`as={IconMail}`**. | [`examples/polymorphic-as.tsx`](examples/polymorphic-as.tsx) |
+| Features | **`Stepper.Item`** / **`ItemIndicator`** aliases, explicit **`index`**, **`SeparatorIcon`** as separate list items. | [`examples/features.tsx`](examples/features.tsx) |
+
+**Additional narrative examples** (not duplicated as snippet files): checkout horizontal rail → [`examples/01-checkout-horizontal.tsx`](examples/01-checkout-horizontal.tsx); onboarding + back/next → [`examples/02-onboarding-vertical.tsx`](examples/02-onboarding-vertical.tsx); vertical primitive rail → [`examples/03-vertical-primitive-rail.tsx`](examples/03-vertical-primitive-rail.tsx); error step + **`currentStep`** on payment → [`examples/04-checkout-step-error.tsx`](examples/04-checkout-step-error.tsx); horizontal primitive only → [`examples/05-horizontal-primitive.tsx`](examples/05-horizontal-primitive.tsx).
+
+**LLM note:** Prefer `./examples/*.tsx` for runnable scenarios; this page keeps rules and API tables authoritative.
+
 ### Canonical example
 
 ```tsx
@@ -56,16 +76,6 @@ export function Example() {
 }
 ```
 
-### Extended examples
-
-- [`./examples/01-checkout-horizontal.tsx`](./examples/01-checkout-horizontal.tsx) — Checkout: **`orientation="horizontal"`**, **`Stepper.SeparatorIcon`** between steps, controlled index on click.
-- [`./examples/02-onboarding-vertical.tsx`](./examples/02-onboarding-vertical.tsx) — Onboarding: vertical semantic **`Stepper`**, **`Stepper.Arrow`**, external **Back** / **Next** buttons.
-- [`./examples/03-vertical-primitive-rail.tsx`](./examples/03-vertical-primitive-rail.tsx) — Vertical rail: **`VerticalStepper`** with app-owned **`state`** per row.
-- [`./examples/04-checkout-step-error.tsx`](./examples/04-checkout-step-error.tsx) — Checkout: **`status="error"`** on a middle step while **`currentStep`** points at payment.
-- [`./examples/05-horizontal-primitive.tsx`](./examples/05-horizontal-primitive.tsx) — Horizontal primitive: **`HorizontalStepper`** + **`SeparatorIcon`**, explicit **`state`**.
-
-**LLM note:** Prefer reading the runnable files under `./examples/*.tsx` for full scenarios, prop combinations, and composition patterns; this page keeps the contract (rules + API tables) authoritative.
-
 ## Rules
 
 - **`Stepper.Root`**: **`currentStep`** defaults to **`0`**; indices before it are **`completed`**, the equal index is **`active`**, after are **`pending`**. Override any step with **`status`** on **`Stepper.Step`** (e.g. **`error`**).
@@ -88,7 +98,7 @@ Exported types include **`StepStatus`**, **`StepperOrientation`**, **`StepperSiz
 | currentStep | `number` | `0` | No | Active step index for default statuses |
 | size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control tier for the subtree |
 | children | `React.ReactNode` | — | Yes | Steps and optional **`SeparatorIcon`** |
-| className | `string` | — | No | Class on **`<ol>`** |
+| className | `string` | — | No | Class on **`<ol>`** (e.g. full-width horizontal rail: **`width: 100%`** and **`justify-content: space-between`** to override the default centered flex layout) |
 
 ### Stepper.Step (Stepper.Item)