prime-ui-kit 0.2.5 → 0.3.2

package/src/components/progress-bar/examples/progress-bar-examples.module.css

@@ -0,0 +1,22 @@
+/* Examples: layout only; colors/spacing from semantic tokens. */
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+  min-width: 0;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+  max-width: 28rem;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-x2);
+  margin-top: var(--prime-sys-spacing-s);
+}

package/src/components/progress-bar/examples/step-progress.tsx

@@ -0,0 +1,23 @@
+import { ProgressBar, Typography } from "prime-ui-kit";
+
+import s from "./progress-bar-examples.module.css";
+
+/** Map the current step index and total steps to `value` / `max` so the bar matches “step k of n”. */
+export default function ProgressBarStepProgressExample() {
+  const currentStep = 2;
+  const totalSteps = 5;
+
+  return (
+    <div className={s.stack}>
+      <Typography.Root variant="body-large" weight="semibold">
+        Account setup
+      </Typography.Root>
+      <ProgressBar.Root
+        value={currentStep}
+        max={totalSteps}
+        label={`Step ${currentStep} of ${totalSteps}`}
+        size="m"
+      />
+    </div>
+  );
+}

package/src/components/progress-bar/examples/upload-progress.tsx

@@ -0,0 +1,27 @@
+import { ProgressBar, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import s from "./progress-bar-examples.module.css";
+
+/** Determinate upload: drive `value` from bytes transferred; keep filename and percent in surrounding copy. */
+export default function ProgressBarUploadExample() {
+  const [loaded, setLoaded] = React.useState(0);
+  const total = 100;
+
+  return (
+    <div className={s.card}>
+      <Typography.Root variant="body-small" tone="muted">
+        quarterly-report.pdf
+      </Typography.Root>
+      <ProgressBar.Root value={loaded} max={total} label={`Upload progress: ${loaded}%`} size="m" />
+      <div className={s.actions}>
+        <button type="button" onClick={() => setLoaded((n) => Math.max(0, n - 20))}>
+          −20%
+        </button>
+        <button type="button" onClick={() => setLoaded((n) => Math.min(total, n + 20))}>
+          +20%
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-bar/examples/wizard-composition.tsx

@@ -0,0 +1,18 @@
+import { ProgressBar, Typography } from "prime-ui-kit";
+
+import s from "./progress-bar-examples.module.css";
+
+/** Stack heading, bar, and muted helper copy — typical block in a wizard or long-running task panel. */
+export default function ProgressBarWizardCompositionExample() {
+  return (
+    <div className={s.card}>
+      <Typography.Root variant="body-large" weight="semibold">
+        Generating report
+      </Typography.Root>
+      <ProgressBar.Root value={72} max={100} label="Collecting data" size="m" />
+      <Typography.Root variant="body-small" tone="muted">
+        Usually under five minutes; you can return to the task list.
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/progress-circle/COMPONENT.md

@@ -0,0 +1,93 @@
+# ProgressCircle
+
+**Default `size`:** use **`m`** for the size axis unless the layout explicitly needs another tier.
+
+## Canonical
+
+- **`ProgressCircle`** — circular fraction of a known maximum: **`ProgressCircle.Root`** only (`inline-flex` root, SVG ring + optional centered **`children`**).
+- **Semantics:** SVG has **`role="progressbar"`** with **`aria-valuenow`**, **`aria-valuemin={0}`**, **`aria-valuemax`** (effective max after clamping / safe fallback).
+- **`value`** (required) and **`max`** (default **`100`**) — progress is **fully controlled**; **`value`** is clamped to **`[0, max]`**; if **`max <= 0`**, the scale falls back to **`100`** internally.
+- **`label`** — optional accessible name on the SVG (**`aria-label`**); use when the center has no text or the visible center text does not describe the bar.
+- **`size`:** **`s` | `m` | `l` | `xl`** — diameter and stroke from **`progressCircle`** primitives.
+- **`children`** — optional centered slot (short number, percent, icon); omit for a ring-only indicator (then set **`label`** for a11y).
+- **No indeterminate mode**, no **`disabled` / `loading` / `error`** props — reflect those in surrounding UI or by freezing **`value`**.
+- **Not** a focusable control; **not** polymorphic (**no `asChild`**).
+
+## Extended
+
+### About
+
+Circular progress: an SVG ring showing **`value` / `max`**, with optional content inside the ring.
+
+- **When to use** — compact share of a known total (percent, steps, seats, quota) where a round indicator reads better than a bar.
+- **When to use** — with **`max`** when the scale is not 0–100 (months in a plan, steps in a wizard, large numeric caps).
+- **When to use** — **`children`** for the focal number or short label in the middle of the ring.
+- **When not to use** — indeterminate or endless spinners without a numeric fraction (no built-in indeterminate API).
+- **When not to use** — as the primary interactive target; pair with [Button](../button/COMPONENT.md) or links for actions.
+- **When not to use** — when a horizontal bar is clearer; see [ProgressBar](../progress-bar/COMPONENT.md).
+
+### Composition
+
+- **`ProgressCircle.Root`** — root **`div`** with **`data-size`**, inner size CSS variable, SVG (**`progressbar`**), then optional **`children`** wrapper centered over the ring.
+- Order: pass **`value`** / **`max`** / **`size`** / **`label`** on **`Root`**; put visual center content in **`children`** when needed.
+
+### Scenarios (see `examples/`)
+
+| Scenario | Approach |
+|----------|----------|
+| Dashboard ring | Put **`ProgressCircle.Root`** in a KPI surface (e.g. [Card](../card/COMPONENT.md) **`mini-media`** **`Card.Media`**) with **`children`** for the headline fraction. → [`examples/dashboard-ring.tsx`](examples/dashboard-ring.tsx) |
+| Accessible name | Set **`label`** when the ring has no suitable visible text in the center (compact tiles, icon-only rows). → [`examples/a11y-label.tsx`](examples/a11y-label.tsx) |
+| Composition | Use **`children`** for **`Typography`**, icons, or **`value/max`** copy; keep the center concise. → [`examples/composition.tsx`](examples/composition.tsx) |
+| Non‑100 scale | Same visual fill for different **`max`** values (percent, steps, large totals). → [`examples/max-scale.tsx`](examples/max-scale.tsx) |
+| Controlled value | Drive **`value`** from parent state (polling, upload simulation). → [`examples/controlled.tsx`](examples/controlled.tsx) |
+
+### Minimal example
+
+```tsx
+import { ProgressCircle } from "prime-ui-kit";
+
+export function Example() {
+  return <ProgressCircle.Root value={40} />;
+}
+```
+
+### Rules
+
+- Progress is **always prop-driven** — no internal stored progress.
+- **`value`** clamped to **`[0, max]`**; negatives → **`0`**, above **`max`** → **`max`**.
+- If **`max <= 0`**, internal scale uses **`100`** to avoid division by zero.
+- **`label`** maps to **`aria-label`** on the SVG; prefer visible **`children`** text that describes the bar when it fully names the task.
+- Root is **`inline-flex`** — align inside your own flex or grid row when pairing with captions.
+- One visual style; scale with **`size`** only.
+
+## API
+
+### ProgressCircle.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `number` | — | Yes | Current value; clamped to `[0, max]` |
+| max | `number` | `100` | No | Upper bound; if `max <= 0`, `100` is used |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Diameter and stroke from `progressCircle` primitives |
+| label | `string` | — | No | Accessible name for the SVG (`aria-label`) |
+| children | `React.ReactNode` | — | No | Centered content inside the ring |
+| className | `string` | — | No | Extra class on the root `div` |
+| ref | `React.Ref<HTMLDivElement>` | — | No | Ref on the root `div` |
+
+## Related
+
+- [ProgressBar](../progress-bar/COMPONENT.md) — linear fraction when a horizontal bar fits better.
+- [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md) — multiple segments on one track.
+- [Card](../card/COMPONENT.md) — KPI tiles; **`mini-media`** **`Card.Media`** for rings or thin progress.
+- [Typography](../typography/COMPONENT.md) — captions and units beside or under the ring.
+
+## LLM note
+
+- Export: **`import { ProgressCircle } from "prime-ui-kit"`** — **`ProgressCircle.Root`** only (object namespace).
+- **`ProgressCircleRootProps`**: **`value`** (required), **`max?`** (default 100), **`size?`** (default **`m`**), **`label?`**, **`children?`**, **`className?`**, **`ref`** → **`HTMLDivElement`**.
+- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`**.
+- SVG: **`role="progressbar"`**, **`aria-valuenow`**, **`aria-valuemin={0}`**, **`aria-valuemax`** = effective max; **`aria-label`** from **`label`** when provided.
+- **No** indeterminate, **no** `disabled`/`loading`/`error` props — control **`value`** and surrounding UI instead.
+- **No** `asChild` / polymorphic root — fixed **`div`** + SVG + optional inner **`div`** for **`children`**.
+- When the center is empty or non-descriptive, require **`label`** for an accessible name.
+- Prefer [ProgressBar](../progress-bar/COMPONENT.md) for linear indeterminate or strip layouts unless the design specifically needs a ring.

package/src/components/progress-circle/examples/a11y-label.tsx

@@ -0,0 +1,32 @@
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+/**
+ * No text in the ring: the accessible name comes from `label` (`aria-label` on the SVG).
+ * Pair with visible copy beside the ring when the UI needs a readable caption.
+ */
+export default function A11yLabelExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "center",
+      }}
+    >
+      <ProgressCircle.Root value={62} max={100} size="m" label="Data sync, 62 percent complete" />
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "var(--prime-sys-spacing-s)",
+        }}
+      >
+        <ProgressCircle.Root value={4} max={12} size="s" label="Subscription month 4 of 12" />
+        <Typography.Root as="span" variant="body-small">
+          Subscription · month 4 of 12
+        </Typography.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-circle/examples/composition.tsx

@@ -0,0 +1,66 @@
+import { IconCheck, IconCircleDot, IconDownload, ProgressCircle, Typography } from "prime-ui-kit";
+
+/** Center slot: icon, short label, and numeric breakdowns. */
+export default function CompositionExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "center",
+      }}
+    >
+      <ProgressCircle.Root value={72} max={100} size="xl">
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            gap: "var(--prime-sys-spacing-xs)",
+          }}
+        >
+          <IconCircleDot size="l" aria-hidden />
+          <Typography.Root as="span" variant="body-small" weight="medium">
+            On track
+          </Typography.Root>
+        </div>
+      </ProgressCircle.Root>
+      <ProgressCircle.Root value={33} max={80} size="l">
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            gap: "var(--prime-sys-spacing-xs)",
+          }}
+        >
+          <Typography.Root as="span" variant="body-large" weight="semibold">
+            33
+          </Typography.Root>
+          <Typography.Root as="span" variant="body-compact" tone="muted">
+            of 80
+          </Typography.Root>
+        </div>
+      </ProgressCircle.Root>
+      <ProgressCircle.Root value={65} max={100} size="m">
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            gap: "var(--prime-sys-spacing-xs)",
+          }}
+        >
+          <IconDownload size="m" aria-hidden />
+          <Typography.Root as="span" variant="body-compact" weight="medium">
+            65%
+          </Typography.Root>
+        </div>
+      </ProgressCircle.Root>
+      <ProgressCircle.Root value={100} max={100} size="s" label="Task complete">
+        <IconCheck size="s" aria-hidden />
+      </ProgressCircle.Root>
+    </div>
+  );
+}

package/src/components/progress-circle/examples/controlled.tsx

@@ -0,0 +1,58 @@
+import { Button, ProgressCircle, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+/** Parent-owned `value` — typical for polling, uploads, or simulations. */
+export default function ControlledExample() {
+  const [value, setValue] = React.useState(35);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: "var(--prime-sys-spacing-l)",
+      }}
+    >
+      <ProgressCircle.Root
+        value={value}
+        max={100}
+        size="l"
+        label={`Upload progress, ${value} percent`}
+      >
+        <Typography.Root as="span" variant="body-small" weight="medium">
+          {value}%
+        </Typography.Root>
+      </ProgressCircle.Root>
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-s)",
+          alignItems: "center",
+          justifyContent: "center",
+        }}
+      >
+        <Button.Root
+          mode="stroke"
+          size="s"
+          type="button"
+          onClick={() => setValue((v) => Math.max(0, v - 10))}
+        >
+          −10
+        </Button.Root>
+        <Button.Root
+          mode="stroke"
+          size="s"
+          type="button"
+          onClick={() => setValue((v) => Math.min(100, v + 10))}
+        >
+          +10
+        </Button.Root>
+        <Button.Root mode="lighter" size="s" type="button" onClick={() => setValue(0)}>
+          Reset
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-circle/examples/dashboard-ring.tsx

@@ -0,0 +1,36 @@
+import { Card, Icon, ProgressCircle, Typography } from "prime-ui-kit";
+
+/** KPI tile with a ring in `Card.Media` — typical dashboard density. */
+export default function DashboardRingExample() {
+  return (
+    <Card.Root variant="mini-media">
+      <Card.IconBox aria-hidden>
+        <Icon name="nav.layoutGrid" aria-hidden />
+      </Card.IconBox>
+      <Card.Stack>
+        <Card.Label>Quarter target</Card.Label>
+        <Card.Value>68%</Card.Value>
+      </Card.Stack>
+      <Card.Media>
+        <div
+          style={{
+            display: "flex",
+            justifyContent: "center",
+            paddingBlock: "var(--prime-sys-spacing-s)",
+          }}
+        >
+          <ProgressCircle.Root
+            value={68}
+            max={100}
+            size="m"
+            label="Quarter target, 68 percent complete"
+          >
+            <Typography.Root as="span" variant="body-small" weight="medium">
+              68%
+            </Typography.Root>
+          </ProgressCircle.Root>
+        </div>
+      </Card.Media>
+    </Card.Root>
+  );
+}

package/src/components/progress-circle/examples/max-scale.tsx

@@ -0,0 +1,61 @@
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+/** Same fill ratio with different `max` scales (percent, steps, large quotas). */
+export default function MaxScaleExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-xl)",
+        alignItems: "flex-end",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: "var(--prime-sys-spacing-s)",
+        }}
+      >
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          45 of 100
+        </Typography.Root>
+        <ProgressCircle.Root value={45} max={100} size="m">
+          45%
+        </ProgressCircle.Root>
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: "var(--prime-sys-spacing-s)",
+        }}
+      >
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          3 of 5 steps
+        </Typography.Root>
+        <ProgressCircle.Root value={3} max={5} size="m">
+          3/5
+        </ProgressCircle.Root>
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: "var(--prime-sys-spacing-s)",
+        }}
+      >
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          750 of 1000
+        </Typography.Root>
+        <ProgressCircle.Root value={750} max={1000} size="m">
+          75%
+        </ProgressCircle.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/radio/COMPONENT.md

@@ -0,0 +1,123 @@
+# Radio
+
+**Default `size`:** use **`m`** for the size axis unless the screen or field explicitly needs another tier.
+
+## Canonical
+
+- **`Radio`** — compound choice control: **`Radio.Root`** (field wrapper, `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).
+
+## 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 a set of mutually exclusive options that submit with the form (`name`, `value`, `required`).
+- **When to use** — options that should behave as one native radio group (same **`name`** on each **`Radio.Root`**).
+- **When to use** — short helper or validation copy tied to a single 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** — fully custom markup or `asChild`; the marker and label row are fixed by the implementation.
+
+### Composition
+
+- **`Radio.Root`** — provides context (`inputId`, hint/error ids, `describedBy`, hint/error registration) and wraps children in a **`div`**.
+- **`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`**.
+
+### Scenarios (see `examples/`)
+
+| 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) |
+
+### Minimal example
+
+```tsx
+import { Radio } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Radio.Root name="option" value="a">
+      <Radio.Label>Option</Radio.Label>
+    </Radio.Root>
+  );
+}
+```
+
+### Rules
+
+- 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.
+- **`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).
+
+## API
+
+### Radio.Root
+
+| 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. |
+| 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. |
+| 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`. |
+
+### Radio.Label
+
+| 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. |
+| …rest | `Omit<React.HTMLAttributes<HTMLLabelElement>, "htmlFor" \| "size">` | — | no | Other label attributes; `htmlFor` and `size` come from context. |
+
+### Radio.Hint
+
+| 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. |
+
+### Radio.Error
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Error message text. |
+| 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`. |
+
+## Related
+
+- [Checkbox](../checkbox/COMPONENT.md) — independent or multi-select toggles.
+- [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.
+- Examples under **`src/components/radio/examples/`** import **`"prime-ui-kit"`** so they match consumer apps 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>
+    </>
+  );
+}