prime-ui-kit 0.3.1 → 0.3.2

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

@@ -0,0 +1,35 @@
+import { Label, Select, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Controlled `value` / `onChange`: parent owns the string; map enums or numbers yourself.
+ */
+export default function SelectExampleControlled() {
+  const [tier, setTier] = React.useState("pro");
+  const tierLabelId = React.useId();
+
+  return (
+    <div className={styles.stack}>
+      <div className={styles.field}>
+        <Label.Root id={tierLabelId} size="m">
+          Subscription tier
+        </Label.Root>
+        <Select.Root size="m" value={tier} onChange={setTier} placeholder="Choose a tier">
+          <Select.Trigger aria-labelledby={tierLabelId}>
+            <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>
+      </div>
+      <Typography.Root as="p" variant="caption" tone="muted" className={styles.caption}>
+        Current value in React state: <span>{tier}</span>
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/select/examples/03-groups.tsx

@@ -0,0 +1,45 @@
+import { Label, Select } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Long lists: `Select.Group`, `Select.GroupLabel`, and `Select.Separator` inside `Select.Content`.
+ */
+export default function SelectExampleGroups() {
+  const timezoneLabelId = React.useId();
+
+  return (
+    <div className={styles.field}>
+      <Label.Root id={timezoneLabelId} size="m">
+        Time zone
+      </Label.Root>
+      <Select.Root size="m" defaultValue="utc" placeholder="Select time zone">
+        <Select.Trigger aria-labelledby={timezoneLabelId}>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Group>
+            <Select.GroupLabel>Americas</Select.GroupLabel>
+            <Select.Item value="et">Eastern Time</Select.Item>
+            <Select.Item value="ct">Central Time</Select.Item>
+            <Select.Item value="pt">Pacific Time</Select.Item>
+          </Select.Group>
+          <Select.Separator />
+          <Select.Group>
+            <Select.GroupLabel>Europe</Select.GroupLabel>
+            <Select.Item value="utc">UTC</Select.Item>
+            <Select.Item value="cet">Central European Time</Select.Item>
+            <Select.Item value="gmt">GMT (London)</Select.Item>
+          </Select.Group>
+          <Select.Separator />
+          <Select.Group>
+            <Select.GroupLabel>Asia Pacific</Select.GroupLabel>
+            <Select.Item value="jst">Japan (JST)</Select.Item>
+            <Select.Item value="aest">Sydney (AEST)</Select.Item>
+          </Select.Group>
+        </Select.Content>
+      </Select.Root>
+    </div>
+  );
+}

package/src/components/select/examples/04-full-width-form.tsx

@@ -0,0 +1,51 @@
+import { Label, Select, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Trigger is `width: 100%` in kit styles — put the field in a full-width column; no `fullWidth` prop on
+ * `Select.Root`.
+ */
+export default function SelectExampleFullWidthForm() {
+  const nameLabelId = React.useId();
+  const methodLabelId = React.useId();
+
+  return (
+    <div className={styles.form}>
+      <Typography.Root as="h3" variant="heading-subsection">
+        Delivery details
+      </Typography.Root>
+      <div className={styles.fieldFullBleed}>
+        <Label.Root id={nameLabelId} size="m">
+          Full name
+        </Label.Root>
+        <Select.Root size="m" placeholder="How should we address the package?">
+          <Select.Trigger aria-labelledby={nameLabelId}>
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            <Select.Item value="home">Alex Morgan (home)</Select.Item>
+            <Select.Item value="work">Alex Morgan (office)</Select.Item>
+            <Select.Item value="gift">Gift recipient — leave at desk</Select.Item>
+          </Select.Content>
+        </Select.Root>
+      </div>
+      <div className={styles.fieldFullBleed}>
+        <Label.Root id={methodLabelId} size="m">
+          Shipping method
+        </Label.Root>
+        <Select.Root size="m" defaultValue="standard" placeholder="Choose shipping">
+          <Select.Trigger aria-labelledby={methodLabelId}>
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            <Select.Item value="standard">Standard (5–7 days)</Select.Item>
+            <Select.Item value="express">Express (2–3 days)</Select.Item>
+            <Select.Item value="overnight">Overnight</Select.Item>
+          </Select.Content>
+        </Select.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,37 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-xs);
+  width: 100%;
+  max-width: calc(var(--prime-sys-unit-1rem) * 22);
+  min-width: 0;
+}
+
+.fieldFullBleed {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-xs);
+  width: 100%;
+  min-width: 0;
+  max-width: none;
+}
+
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+  width: 100%;
+  max-width: calc(var(--prime-sys-unit-1rem) * 28);
+  min-width: 0;
+}
+
+.caption {
+  margin: 0;
+  color: var(--prime-sys-color-content-secondary);
+}

package/src/components/slider/COMPONENT.md

@@ -1,39 +1,55 @@
 # Slider
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
 
 ## About
 
-Horizontal range control built on the native `input type="range"`, with optional text label and kit sizing (`s`–`xl`).
+A horizontal range control built on the native `input type="range"`, with optional text label and kit sizing (`s`–`xl`).
 
-- **Use** when the user should pick a number along a continuous or stepped interval (volume, brightness, percentages, temperature bands) and dragging the track is appropriate.
-- **Use** when native range keyboard and pointer behavior is sufficient and you want minimal custom logic.
-- **Do not use** for vertical sliders; the implementation is horizontal only.
-- **Do not use** when you need a value thumb label, icons, or other slots on the track—compose with surrounding layout and text.
-- **Do not use** expecting built-in error, required, loading, or read-only modes; handle those with form primitives and hints around the control.
-- **Do not use** when a small set of fixed choices fits radio or segmented controls better than a continuous range.
+**When to use**
+
+- Picking a number along a continuous or stepped interval: volume, brightness, percentages, temperature bands, or filter caps (for example a maximum price).
+- When native range keyboard and pointer behavior is enough and you want minimal custom logic.
+
+**When not to use**
+
+- Vertical sliders — the implementation is horizontal only.
+- When you need thumb labels, icons, or other slots on the track — compose with surrounding layout and text.
+- Built-in error, required, loading, or read-only modes — use form primitives and hints around the control.
+- A small set of fixed choices — prefer radio or segmented controls instead of a continuous range.
 
 ## Composition
 
-- **`Slider`** is a single-part API: **`Slider.Root`** wraps **`ControlSizeProvider`**, an optional **`label`** (`label` + `htmlFor` linked to the input), and one **`input type="range"`** styled as the track.
+- **`Slider`** is a single-part API: **`Slider.Root`** wraps **`ControlSizeProvider`**, an optional **`label`** (linked to the input with `htmlFor` / `id`), and one styled **`input type="range"`**.
 - The root `div` carries **`data-size`** from **`size`**; there are no other exported subcomponents.
 
-### Minimal example
+### Canonical example
 
 ```tsx
 import { Slider } from "prime-ui-kit";
 
 export function Example() {
-  return <Slider.Root />;
+  return (
+    <Slider.Root label="Output level" min={0} max={100} step={1} defaultValue={50} size="m" />
+  );
 }
 ```
 
+### Extended 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.
+
+**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.
+
 ## Rules
 
-- **Controlled:** pass **`value`** and **`onChange`**; **uncontrolled:** pass **`defaultValue`** (or omit both value props—effective initial value is **`min`**, clamped to **`[min, max]`**).
+- **Controlled:** pass **`value`** and **`onChange`**. **Uncontrolled:** pass **`defaultValue`**, or omit both value props — the effective initial value is **`min`**, clamped to **`[min, max]`**.
 - **`min`**, **`max`**, and **`step`** default to **`0`**, **`100`**, and **`1`**; fractional **`step`** values are allowed.
-- Displayed value is **clamped** to **`[min, max]`**; if the browser emits a non-numeric value, the update is ignored.
-- With **`label`**, the visible label is associated with the input via **`id`** / **`htmlFor`**. Without **`label`**, set **`aria-label`** (or an external accessible name), or assistive technologies may not get a proper name.
+- Displayed value is **clamped** to **`[min, max]`**; non-numeric input updates are ignored.
+- With **`label`**, the visible label is associated via **`id`** / **`htmlFor`**. Without **`label`**, set **`aria-label`** (or an external accessible name) so assistive technologies get a proper name.
 - **`disabled`** sets the native **`disabled`** state on the range input.
 - There is no **`asChild`** or portal behavior; focus and **`focus-visible`** styling follow the native control and theme.
 

package/src/components/slider/examples/01-volume.tsx

@@ -0,0 +1,17 @@
+import { Slider, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Media or system volume: native range, default scale 0–100, optional readout beside the track.
+ */
+export default function SliderExampleVolume() {
+  return (
+    <div className={styles.stack}>
+      <Slider.Root label="Volume" min={0} max={100} step={1} defaultValue={72} size="m" />
+      <Typography.Root as="p" variant="body-small" className={styles.muted}>
+        Drag to adjust loudness. Arrow keys step by one unit.
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/slider/examples/02-price-range.tsx

@@ -0,0 +1,18 @@
+import { Hint, Slider } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Catalog filter: single-thumb “up to” price on a stepped currency scale (one dimension of a range UI).
+ */
+export default function SliderExamplePriceRange() {
+  return (
+    <div className={styles.stack}>
+      <Slider.Root label="Maximum price" min={0} max={500} step={5} defaultValue={250} size="m" />
+      <Hint.Root size="s" variant="default">
+        Results update when you release the thumb or finish keyboard adjustment. Pair with a second
+        control if you need an explicit minimum.
+      </Hint.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,30 @@
+import { Slider, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Controlled value: drive `value` / `onChange` from React state and mirror the number in UI copy.
+ */
+export default function SliderExampleControlled() {
+  const [brightness, setBrightness] = React.useState(48);
+
+  return (
+    <div className={styles.stack}>
+      <div className={styles.row}>
+        <Slider.Root
+          label="Brightness"
+          value={brightness}
+          onChange={setBrightness}
+          min={0}
+          max={100}
+          step={1}
+          size="m"
+        />
+        <Typography.Root as="span" variant="body-default" className={styles.muted}>
+          {brightness}%
+        </Typography.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/slider/examples/04-disabled.tsx

@@ -0,0 +1,25 @@
+import { Slider, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Disabled track: preset cannot be changed until the parent feature is unlocked or loading finishes.
+ */
+export default function SliderExampleDisabled() {
+  return (
+    <div className={styles.stack}>
+      <Slider.Root
+        label="Night mode dimming"
+        min={0}
+        max={100}
+        step={5}
+        defaultValue={40}
+        disabled
+        size="m"
+      />
+      <Typography.Root as="p" variant="body-small" className={styles.muted}>
+        Available after you enable scheduled dark mode in settings.
+      </Typography.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,17 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.row {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.muted {
+  margin: 0;
+  color: var(--prime-sys-color-content-secondary);
+}

package/src/components/stepper/COMPONENT.md

@@ -1,17 +1,22 @@
 # Stepper
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
 
 ## About
 
-Multi-step progress UI: a high-level **`Stepper`** on a semantic ordered list (`<ol>` / `<li>`), plus primitive **`HorizontalStepper`** and **`VerticalStepper`** layouts where each row owns an explicit visual **`state`**.
+Multi-step progress UI on a semantic ordered list (`<ol>` / `<li>`) for **`Stepper`**, plus **`HorizontalStepper`** and **`VerticalStepper`** layouts where each row uses an explicit visual **`state`**.
 
-- **Use** for wizards, checkout or form stages, and any flow where discrete steps should read clearly in order.
-- **Use** **`Stepper`** when **`currentStep`** (and optional per-step **`status`**) should drive numbering and completed/active/pending visuals.
-- **Use** **`HorizontalStepper`** / **`VerticalStepper`** when step logic lives in the app (store, API) and you set **`state`** on each **`Item`** yourself.
-- **Do not use** as a page hierarchy control; prefer breadcrumbs for site structure.
-- **Do not use** when a single continuous fraction matters more than discrete steps; consider a progress bar.
-- **Do not use** primitive rails alone when you need a native **ordered list** semantics for steps—wrap with appropriate roles/markup or use **`Stepper.Root`**.
+**When to use**
+
+- Wizards, checkout or form stages, and any flow where discrete ordered steps should read clearly.
+- **`Stepper`** when **`currentStep`** (and optional per-step **`status`**) should drive numbering and completed / active / pending / error visuals.
+- **`HorizontalStepper`** / **`VerticalStepper`** when step logic lives in the app (store, router, API) and you set **`state`** on each **`Item`** yourself.
+
+**When not to use**
+
+- Site hierarchy or drill-down navigation — prefer [Breadcrumb](../breadcrumb/COMPONENT.md).
+- When a single continuous fraction matters more than discrete steps — consider [Progress bar](../progress-bar/COMPONENT.md).
+- Primitive rails alone when you need native **ordered list** semantics — use **`Stepper.Root`** or add appropriate roles / markup around primitives.
 
 ## Composition
 
@@ -24,30 +29,50 @@ Multi-step progress UI: a high-level **`Stepper`** on a semantic ordered list (`
 - **`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`**.
 
-### Minimal example
+### Canonical example
 
 ```tsx
 import { Stepper } from "prime-ui-kit";
 
 export function Example() {
   return (
-    <Stepper.Root>
-      <Stepper.Step>
+    <Stepper.Root size="m" orientation="vertical">
+      <Stepper.Step type="button">
+        <Stepper.Indicator />
+        <Stepper.Content title="Account" description="Sign in or create a profile" />
+        <Stepper.Arrow />
+      </Stepper.Step>
+      <Stepper.Step type="button">
         <Stepper.Indicator />
-        <Stepper.Content title="Step one" />
+        <Stepper.Content title="Workspace" description="Name and region" />
+        <Stepper.Arrow />
+      </Stepper.Step>
+      <Stepper.Step type="button">
+        <Stepper.Indicator />
+        <Stepper.Content title="Finish" />
       </Stepper.Step>
     </Stepper.Root>
   );
 }
 ```
 
+### 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`**, equal index is **`active`**, after are **`pending`**. Override any step with **`status`** on **`Stepper.Step`** (e.g. **`error`**).
+- **`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`**).
 - **`Stepper.Step`** without **`index`** consumes the next auto index in child order; mixing explicit **`index`** and auto indices requires careful ordering.
 - **`SeparatorIcon`** is intended for **`orientation="horizontal"`**; it is not the vertical connector pattern.
 - Primitives use **`StepperAlignItemState`**: **`default`** \| **`active`** \| **`completed`** only—no built-in **`error`**; use **`Stepper`** for **`error`** or custom indicator content.
-- Active step sets **`aria-current="step"`** on the **`Stepper`** step button; indicators and separators use **`aria-hidden`** where the label carries meaning—keep titles/descriptions meaningful for assistive tech.
+- Active step sets **`aria-current="step"`** on the **`Stepper`** step button; indicators and separators use **`aria-hidden`** where the label carries meaning—keep titles and descriptions meaningful for assistive tech.
 - **`HorizontalStepper`** / **`VerticalStepper`** do not emit **`<ol>`** / **`<li>`**; add list semantics externally if required.
 - Step transitions, validation, and routing are **app-owned**; the kit handles presentation and button interactions only.
 
@@ -180,7 +205,7 @@ Exported types include **`StepStatus`**, **`StepperOrientation`**, **`StepperSiz
 
 ## Related
 
-- [Button](../button/COMPONENT.md) — next/back actions next to a controlled stepper
+- [Button](../button/COMPONENT.md) — next / back actions next to a controlled stepper
 - [Modal](../modal/COMPONENT.md) and [Drawer](../drawer/COMPONENT.md) — wizard shells
 - [Breadcrumb](../breadcrumb/COMPONENT.md) — hierarchy, not linear stages
 - [Progress bar](../progress-bar/COMPONENT.md) — continuous progress instead of discrete steps

package/src/components/stepper/examples/01-checkout-horizontal.tsx

@@ -0,0 +1,32 @@
+import { Stepper } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Checkout: horizontal ordered list with chevron separators; steps jump when clicked.
+ */
+export default function StepperExampleCheckoutHorizontal() {
+  const [step, setStep] = React.useState(1);
+
+  return (
+    <div className={styles.stack}>
+      <Stepper.Root orientation="horizontal" currentStep={step} size="m" className={styles.rail}>
+        <Stepper.Step type="button" onClick={() => setStep(0)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Cart" description="Review items" />
+        </Stepper.Step>
+        <Stepper.SeparatorIcon />
+        <Stepper.Step type="button" onClick={() => setStep(1)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Shipping" description="Address & delivery" />
+        </Stepper.Step>
+        <Stepper.SeparatorIcon />
+        <Stepper.Step type="button" onClick={() => setStep(2)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Payment" description="Card or wallet" />
+        </Stepper.Step>
+      </Stepper.Root>
+    </div>
+  );
+}

package/src/components/stepper/examples/02-onboarding-vertical.tsx

@@ -0,0 +1,51 @@
+import { Button, Stepper } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Onboarding wizard: vertical semantic stepper, controlled index, back / next actions.
+ */
+export default function StepperExampleOnboardingVertical() {
+  const [step, setStep] = React.useState(0);
+  const last = 2;
+
+  return (
+    <div className={styles.stack}>
+      <Stepper.Root currentStep={step} orientation="vertical" size="m" className={styles.rail}>
+        <Stepper.Step type="button" onClick={() => setStep(0)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Welcome" description="Product tour and goals" />
+          <Stepper.Arrow />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setStep(1)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Team" description="Invite collaborators" />
+          <Stepper.Arrow />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setStep(2)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Done" description="You are ready to build" />
+        </Stepper.Step>
+      </Stepper.Root>
+      <div className={styles.actions}>
+        <Button.Root
+          mode="stroke"
+          variant="neutral"
+          disabled={step <= 0}
+          onClick={() => setStep((s) => s - 1)}
+        >
+          Back
+        </Button.Root>
+        <Button.Root
+          mode="filled"
+          variant="primary"
+          disabled={step >= last}
+          onClick={() => setStep((s) => s + 1)}
+        >
+          Next
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/stepper/examples/03-vertical-primitive-rail.tsx

@@ -0,0 +1,36 @@
+import { VerticalStepper } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const STEPS = ["Basics", "Security", "Billing"] as const;
+
+function rowState(idx: number, active: number): "default" | "active" | "completed" {
+  if (idx < active) return "completed";
+  if (idx === active) return "active";
+  return "default";
+}
+
+/**
+ * Vertical rail without `<ol>` semantics: app-owned `state` per row (e.g. store or router).
+ */
+export default function StepperExampleVerticalPrimitiveRail() {
+  const [active, setActive] = React.useState(1);
+
+  return (
+    <VerticalStepper.Root size="m" className={styles.rail}>
+      {STEPS.map((label, idx) => (
+        <VerticalStepper.Item
+          key={label}
+          type="button"
+          state={rowState(idx, active)}
+          onClick={() => setActive(idx)}
+        >
+          <VerticalStepper.ItemIndicator>{String(idx + 1)}</VerticalStepper.ItemIndicator>
+          {label}
+          {rowState(idx, active) === "active" ? <VerticalStepper.Arrow /> : null}
+        </VerticalStepper.Item>
+      ))}
+    </VerticalStepper.Root>
+  );
+}

package/src/components/stepper/examples/04-checkout-step-error.tsx

@@ -0,0 +1,30 @@
+import { Stepper } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Checkout with a prior step flagged `error` while a later step stays active (e.g. fix shipping
+ * from the payment screen).
+ */
+export default function StepperExampleCheckoutStepError() {
+  return (
+    <div className={styles.stack}>
+      <Stepper.Root orientation="horizontal" currentStep={2} size="m" className={styles.rail}>
+        <Stepper.Step type="button">
+          <Stepper.Indicator />
+          <Stepper.Content title="Cart" />
+        </Stepper.Step>
+        <Stepper.SeparatorIcon />
+        <Stepper.Step type="button" status="error">
+          <Stepper.Indicator />
+          <Stepper.Content title="Shipping" description="Address could not be verified" />
+        </Stepper.Step>
+        <Stepper.SeparatorIcon />
+        <Stepper.Step type="button">
+          <Stepper.Indicator />
+          <Stepper.Content title="Payment" />
+        </Stepper.Step>
+      </Stepper.Root>
+    </div>
+  );
+}

package/src/components/stepper/examples/05-horizontal-primitive.tsx

@@ -0,0 +1,37 @@
+import { HorizontalStepper } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const STEPS = ["Draft", "Review", "Publish"] as const;
+
+function rowState(idx: number, active: number): "default" | "active" | "completed" {
+  if (idx < active) return "completed";
+  if (idx === active) return "active";
+  return "default";
+}
+
+/**
+ * Horizontal primitive rail: non-semantic `div` + buttons; you supply each `state`.
+ */
+export default function StepperExampleHorizontalPrimitive() {
+  const [active, setActive] = React.useState(0);
+
+  return (
+    <HorizontalStepper.Root size="m" className={styles.rail}>
+      {STEPS.map((label, idx) => (
+        <React.Fragment key={label}>
+          {idx > 0 ? <HorizontalStepper.SeparatorIcon /> : null}
+          <HorizontalStepper.Item
+            type="button"
+            state={rowState(idx, active)}
+            onClick={() => setActive(idx)}
+          >
+            <HorizontalStepper.ItemIndicator>{String(idx + 1)}</HorizontalStepper.ItemIndicator>
+            {label}
+          </HorizontalStepper.Item>
+        </React.Fragment>
+      ))}
+    </HorizontalStepper.Root>
+  );
+}