prime-ui-kit 0.2.5 → 0.3.2

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

@@ -0,0 +1,108 @@
+# SegmentedControl
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A single-choice control: a horizontal `radiogroup` whose options are segment buttons, with a floating pill indicator under the active segment.
+
+- **Use** when there are few mutually exclusive options that should stay visible (period toggles, layout mode, compact filters).
+- **Use** with **`SegmentedControl.Icon`** plus visible or visually hidden text when a segment is icon-led.
+- **Do not use** for long lists or many options—prefer [Select](../select/COMPONENT.md) or a dropdown.
+- **Do not use** when each choice should show its own panel and tab keyboard model—prefer [Tabs](../tabs/COMPONENT.md).
+- **Do not use** for independent or multi-select actions—prefer [Button group](../button-group/COMPONENT.md) or other patterns.
+- **Do not use** expecting a vertical stack or orientation prop; layout is horizontal only.
+
+## Composition
+
+- **`SegmentedControl.Root`** — outer `div` with **`role="radiogroup"`**, **`data-size`**, focus and arrow-key handling, **`ControlSizeProvider`** for descendants, and a decorative indicator layer (`aria-hidden`).
+- **`SegmentedControl.Item`** — direct children of **`Root`** (and only in that role for correct behavior). Each item is a **`button`** with **`role="radio"`**; order in the tree is the visual order of segments.
+- **`SegmentedControl.Icon`** — optional **`span`** with **`aria-hidden="true"`** inside an **`Item`**; pair with visible label text or an accessible name in **`Item`** **`children`**.
+
+### Minimal example
+
+```tsx
+import { SegmentedControl } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <SegmentedControl.Root defaultValue="a">
+      <SegmentedControl.Item value="a">A</SegmentedControl.Item>
+      <SegmentedControl.Item value="b">B</SegmentedControl.Item>
+    </SegmentedControl.Root>
+  );
+}
+```
+
+### Canonical composition (reference)
+
+For **controlled mode**, **`SegmentedControl.Icon` + text**, **icon-only segments with visually hidden labels**, and **`Typography` as an external group hint** (because **`Root` does not forward `aria-label`**), open **`examples/canonical-composition.tsx`** next to this file. Imports use **`"prime-ui-kit"`** so the same snippets work in an app after installing the package.
+
+### Example files in `examples/`
+
+| File | Scenario |
+|------|----------|
+| `canonical-composition.tsx` | Icon + text, controlled period, icon-only + visually hidden labels |
+| `view-mode.tsx` | English catalog view: List / Grid / Table |
+| `pricing-toggle.tsx` | English billing: Monthly / Annual |
+| `catalog-filters.tsx` | English compact availability filter; `size="s"` |
+
+### Note for LLMs
+
+- **Imports:** `SegmentedControl`, `Icon`, and `Typography` from **`"prime-ui-kit"`** in these examples; paths are relative to `src/components/segmented-control/examples/`.
+- **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 **`""`**).
+- **`defaultValue=""`** (and no controlled **`value`**) means **no** segment is selected; **`Root`** gets **`tabIndex={0}`** so the group can be focused until a segment is chosen.
+- Values are **strings**; mapping to app enums or unions is the consumer’s responsibility.
+- **`disabled`** on **`Root`** sets **`aria-disabled`** on the group and **`data-disabled`**; all segments are inactive.
+- **`disabled`** on an **`Item`** skips that segment for **Left/Right** arrow navigation among enabled radios.
+- **Roving tabindex:** **Tab** focuses the group (when nothing is selected) or the checked segment; **ArrowLeft** / **ArrowRight** move selection and focus across enabled items.
+- **`SegmentedControl.Icon`** is **`aria-hidden`**; the segment’s accessible name must come from **`Item`** **`children`** (visible text and/or visually hidden text). **`Item`** does not forward extra attributes—there is no **`…rest`**—so you cannot set **`aria-label`** on the segment via props.
+- **No `asChild`** and no merging **`Root`** with an arbitrary element.
+- **`Root`** does **not** forward arbitrary HTML attributes (**`aria-label`**, **`style`**, etc.); wrap **`Root`** in another element when you need extra semantics or layout hooks.
+- The indicator position follows the active segment’s layout; updates use **`ResizeObserver`** and **`MutationObserver`** on the root—avoid unpredictable segment size changes without expecting a reflow/recalc.
+
+## API
+
+### SegmentedControl.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | No | Selected value in controlled mode |
+| defaultValue | `string` | `""` | No | Initial value when uncontrolled; empty string means no segment selected |
+| onValueChange | `(value: string) => void` | — | No | Called when the selected value changes |
+| 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 |
+
+### SegmentedControl.Item
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | Yes | Segment identifier |
+| disabled | `boolean` | `false` | No | Disables this segment |
+| children | `React.ReactNode` | — | Yes | Label and/or `SegmentedControl.Icon` |
+| className | `string` | — | No | Extra class on the button |
+
+### SegmentedControl.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Icon node |
+| className | `string` | — | No | Extra class on the `span` |
+| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other `span` attributes |
+
+## Related
+
+- [Tabs](../tabs/COMPONENT.md) — separate panels and tab keyboard model.
+- [Button group](../button-group/COMPONENT.md) — grouped actions, not a single required choice.
+- [Radio](../radio/COMPONENT.md) — standalone radio field primitive.
+- [Select](../select/COMPONENT.md) — many options or list in a dropdown.

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/pricing-toggle.tsx

@@ -0,0 +1,40 @@
+import { SegmentedControl, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+type BillingCycle = "monthly" | "annual";
+
+function isBillingCycle(value: string): value is BillingCycle {
+  return value === "monthly" || value === "annual";
+}
+
+/**
+ * SaaS-style billing cycle toggle: two clear options, often paired with price copy elsewhere.
+ */
+export default function PricingToggleExample() {
+  const [cycle, setCycle] = React.useState<BillingCycle>("monthly");
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <SegmentedControl.Root
+        value={cycle}
+        onValueChange={(v) => {
+          if (isBillingCycle(v)) setCycle(v);
+        }}
+        size="m"
+      >
+        <SegmentedControl.Item value="monthly">Monthly</SegmentedControl.Item>
+        <SegmentedControl.Item value="annual">Annual</SegmentedControl.Item>
+      </SegmentedControl.Root>
+      <Typography.Root as="p" variant="body-compact" tone="muted">
+        Showing prices for <strong>{cycle === "monthly" ? "monthly" : "annual"}</strong> billing.
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/segmented-control/examples/segmented-examples.module.css

@@ -0,0 +1,12 @@
+/* Visually hidden label for icon-only segments (accessible name). */
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}

package/src/components/segmented-control/examples/view-mode.tsx

@@ -0,0 +1,53 @@
+import { SegmentedControl, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+type CatalogView = "list" | "grid" | "table";
+
+function isCatalogView(value: string): value is CatalogView {
+  return value === "list" || value === "grid" || value === "table";
+}
+
+/**
+ * Catalog or dashboard view mode: mutually exclusive layout, state owned by the parent.
+ */
+export default function ViewModeExample() {
+  const [view, setView] = React.useState<CatalogView>("list");
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-m)",
+          alignItems: "center",
+        }}
+      >
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          View
+        </Typography.Root>
+        <SegmentedControl.Root
+          value={view}
+          onValueChange={(v) => {
+            if (isCatalogView(v)) setView(v);
+          }}
+          size="m"
+        >
+          <SegmentedControl.Item value="list">List</SegmentedControl.Item>
+          <SegmentedControl.Item value="grid">Grid</SegmentedControl.Item>
+          <SegmentedControl.Item value="table">Table</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <Typography.Root as="p" variant="body-default" tone="muted">
+        Active layout: <strong>{view}</strong>
+      </Typography.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,104 @@
+# SegmentedProgressBar
+
+**Default `size`:** use **`m`** for the size axis unless the screen explicitly needs another tier.
+
+## Canonical
+
+- **`SegmentedProgressBar`** — proportional **stacked** bar: **`SegmentedProgressBar.Root`** only; one segment per category, width ∝ **`value`** (weight).
+- **`segments`:** each item has **`value`** (≥ 0, clamped), optional **`label`** (tooltip + assistive copy), optional **`tone`**: **`primary` | `success` | `warning` | `danger` | `neutral`** (default **`primary`**).
+- **`segmentGap`:** **`none`** (default, continuous bar) or **`hairline`** (1px separators via track background).
+- **`label`:** optional visible title above the track; when set, the track uses **`aria-labelledby`** + **`aria-describedby`** with a visually hidden distribution string; without **`label`**, **`aria-label`** is the distribution text.
+- **Not** a native **`<progress>`** — track is **`role="group"`**; use [ProgressBar](../progress-bar/COMPONENT.md) for a single determinate fraction.
+- **Not** for picking a segment — use [SegmentedControl](../segmented-control/COMPONENT.md); **not** for steps — use [Stepper](../stepper/COMPONENT.md).
+
+## Extended
+
+### About
+
+`SegmentedProgressBar` shows a part-to-whole breakdown: segment widths follow **`value[i] / sum(values)`** via **`flex-grow`**, so layout stays correct in shrink-to-fit parents. Percentages in the accessibility description are rounded to whole numbers.
+
+- **When to use** — status mixes (errors / pending / success), survey or poll shares, rollout phase allocation, storage or budget split by category.
+- **When to use** — **`segmentGap="none"`** for one solid bar; **`hairline`** when segments should read as separate columns.
+- **When to use** — per-segment **`label`** for tooltips and clearer **`aria-*`** distribution text.
+- **When not to use** — a single task completion percentage; use **ProgressBar**.
+- **When not to use** — interactive selection or toggles; use **SegmentedControl**.
+- **When not to use** — discrete wizard steps; use **Stepper**.
+
+### Composition
+
+- **`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/`)
+
+| 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) |
+
+### Minimal example
+
+```tsx
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <SegmentedProgressBar.Root
+      segments={[
+        { value: 30, label: "Errors", tone: "danger" },
+        { value: 25, label: "Pending", tone: "warning" },
+        { value: 35, label: "Success", tone: "success" },
+        { value: 10, label: "Other", tone: "neutral" },
+      ]}
+    />
+  );
+}
+```
+
+### Rules
+
+- **Weights** are non-negative; invalid numbers are treated as **`0`**. If the sum is **`0`**, the track shows no fills (track background only).
+- **Layout** uses **`flex-grow`** from weights, not `%` width, so proportions stay correct when the parent shrinks.
+- **`segmentGap`:** **`none`** — track background **`surface-accentSoft`**; **`hairline`** — **`gap: 1px`** on the track, background **`border-subtle`**, segments sit on top so a thin line shows between fills.
+- **`tone`** omitted → **`primary`**.
+- Segment **`label`** → native **`title`** on the segment **div**.
+
+## API
+
+### SegmentedProgressBar.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `segments` | `SegmentedProgressSegment[]` | — | Yes | Non-negative weights; layout is proportional to the sum. |
+| `label` | `string` | — | No | Text above the track; **`aria-labelledby`** + **`aria-describedby`** when set. |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Track height and label typography (aligned with ProgressBar). |
+| `segmentGap` | `"none" \| "hairline"` | `"none"` | No | Gap between segment fills. |
+| `className` | `string` | — | No | Class on the outer wrapper. |
+| `ref` | `React.Ref<HTMLDivElement>` | — | No | Ref to the **`role="group"`** track element. |
+
+### SegmentedProgressSegment
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `value` | `number` | Yes | Weight ≥ 0; contributes to proportion. |
+| `label` | `string` | No | Tooltip and assistive segment label in the distribution string. |
+| `tone` | `"primary" \| "success" \| "warning" \| "danger" \| "neutral"` | No | Default **`primary`**. |
+
+## Related
+
+- [ProgressBar](../progress-bar/COMPONENT.md) — single determinate progress on **`<progress>`**.
+- [ProgressCircle](../progress-circle/COMPONENT.md) — circular fraction.
+- [Typography](../typography/COMPONENT.md) — headings and legends beside the bar.
+
+## LLM note
+
+- 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`**.
+- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**.
+- **`segmentGap`** literals: **`none`**, **`hairline`** — default **`none`**.
+- Do not describe this as a native progress bar; it is **`role="group"`**, not **`role="progressbar"`**.
+- Do not suggest **SegmentedControl** or **Stepper** for the same job unless the UX is selection or steps, not a static breakdown.
+- For a single 0–100% task, recommend **ProgressBar** instead.

package/src/components/segmented-progress-bar/examples/distribution-breakdown.tsx

@@ -0,0 +1,16 @@
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+/** Part-to-whole job outcomes with a visible title and per-segment labels for tooltips and SR distribution. */
+export default function DistributionBreakdownExample() {
+  return (
+    <SegmentedProgressBar.Root
+      label="Pipeline results"
+      segments={[
+        { value: 30, label: "Failed", tone: "danger" },
+        { value: 25, label: "Queued", tone: "warning" },
+        { value: 35, label: "Succeeded", tone: "success" },
+        { value: 10, label: "Skipped", tone: "neutral" },
+      ]}
+    />
+  );
+}

package/src/components/segmented-progress-bar/examples/multi-phase-rollout.tsx

@@ -0,0 +1,15 @@
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+/** Rollout mix by phase: weights reflect share of accounts or environments on each tier. */
+export default function MultiPhaseRolloutExample() {
+  return (
+    <SegmentedProgressBar.Root
+      label="Feature rollout"
+      segments={[
+        { value: 15, label: "Internal", tone: "neutral" },
+        { value: 35, label: "Beta", tone: "warning" },
+        { value: 50, label: "General availability", tone: "success" },
+      ]}
+    />
+  );
+}

package/src/components/segmented-progress-bar/examples/segment-gaps.tsx

@@ -0,0 +1,23 @@
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+const segments = [
+  { value: 50, label: "Region A", tone: "primary" as const },
+  { value: 50, label: "Region B", tone: "neutral" as const },
+];
+
+/** Default continuous bar vs hairline separators — weights and tones are unchanged. */
+export default function SegmentGapsExample() {
+  return (
+    <>
+      <SegmentedProgressBar.Root
+        segments={segments}
+        label="Continuous (default, segmentGap none)"
+      />
+      <SegmentedProgressBar.Root
+        segmentGap="hairline"
+        segments={segments}
+        label="Hairline separators"
+      />
+    </>
+  );
+}

package/src/components/segmented-progress-bar/examples/size-ladder.tsx

@@ -0,0 +1,19 @@
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+const segments = [
+  { value: 40, tone: "danger" as const },
+  { value: 35, tone: "warning" as const },
+  { value: 25, tone: "success" as const },
+];
+
+/** Same weights across the control size scale (aligned with ProgressBar). */
+export default function SizeLadderExample() {
+  return (
+    <>
+      <SegmentedProgressBar.Root size="s" segments={segments} />
+      <SegmentedProgressBar.Root size="m" segments={segments} />
+      <SegmentedProgressBar.Root size="l" segments={segments} />
+      <SegmentedProgressBar.Root size="xl" segments={segments} />
+    </>
+  );
+}

package/src/components/segmented-progress-bar/examples/storage-mix.tsx

@@ -0,0 +1,16 @@
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+/** Non-status categories: tones differentiate segments without implying pass/fail. */
+export default function StorageMixExample() {
+  return (
+    <SegmentedProgressBar.Root
+      label="Disk usage by type"
+      segmentGap="hairline"
+      segments={[
+        { value: 42, label: "Documents", tone: "primary" },
+        { value: 33, label: "Media", tone: "neutral" },
+        { value: 25, label: "Applications", tone: "warning" },
+      ]}
+    />
+  );
+}