prime-ui-kit 0.0.1

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

@@ -0,0 +1,33 @@
+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.
+ * Playground: `snippets/progress/circle-a11y-label.tsx`.
+ */
+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} 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 (playground: `snippets/progress/circle-composition.tsx`). */
+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}>
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            gap: "var(--prime-sys-spacing-xs)",
+          }}
+        >
+          <IconDownload 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">
+        <IconCheck size="s" aria-hidden />
+      </ProgressCircle.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,53 @@
+import { Button, ProgressCircle, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+/** Parent-owned `value` — typical for polling, uploads, or simulations (playground: `snippets/progress/circle-controlled.tsx`). */
+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">
+        <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,31 @@
+import { Card, Icon, ProgressCircle, Typography } from "prime-ui-kit";
+
+/** KPI tile with a ring in `Card.Media` — extended pattern; no matching `circle-*` playground snippet. */
+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} 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) (playground: `snippets/progress/circle-max-scale.tsx`). */
+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}>
+          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}>
+          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}>
+          75%
+        </ProgressCircle.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,77 @@
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+/** Four ring sizes: diameter and stroke from `progressCircle` primitives (playground: `snippets/progress/circle-sizes.tsx`). */
+export default function SizesExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-xl)",
+        alignItems: "flex-end",
+        justifyContent: "center",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: "var(--prime-sys-spacing-s)",
+        }}
+      >
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          Size s
+        </Typography.Root>
+        <ProgressCircle.Root value={50} size="s">
+          50%
+        </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">
+          Size m
+        </Typography.Root>
+        <ProgressCircle.Root value={50} size="m">
+          50%
+        </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">
+          Size l
+        </Typography.Root>
+        <ProgressCircle.Root value={50} size="l">
+          50%
+        </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">
+          Size xl
+        </Typography.Root>
+        <ProgressCircle.Root value={50} size="xl">
+          50%
+        </ProgressCircle.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,87 @@
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+/**
+ * Typical fill levels and clamping: `value` is clamped to `[0, max]`; if `max <= 0`, scale falls back to `100`.
+ * Playground: `snippets/progress/circle-states.tsx`.
+ */
+export default function StatesExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-xl)",
+        alignItems: "flex-end",
+        justifyContent: "center",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: "var(--prime-sys-spacing-s)",
+        }}
+      >
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          value 0
+        </Typography.Root>
+        <ProgressCircle.Root value={0}>0%</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">
+          value 50
+        </Typography.Root>
+        <ProgressCircle.Root value={50}>50%</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">
+          value 100
+        </Typography.Root>
+        <ProgressCircle.Root value={100}>100%</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">
+          value −20 → 0
+        </Typography.Root>
+        <ProgressCircle.Root value={-20}>clamp</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">
+          value 140, max 100
+        </Typography.Root>
+        <ProgressCircle.Root value={140} max={100}>
+          full
+        </ProgressCircle.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/radio/COMPONENT.md

@@ -0,0 +1,137 @@
+# 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 `.field`, `data-size`, `data-variant`, `data-disabled`, `data-invalid`), **`Radio.Label`** (native `input type="radio"` + marker + optional text), optional **`Radio.Hint`** and **`Radio.Error`** (wired into `aria-describedby` and invalid styling).
+- **`variant`:** **`default`** or **`error`** on **`Radio.Root`**; mounting **`Radio.Error`** also drives invalid / `aria-invalid` for that instance.
+- **`size`:** **`s` | `m` | `l` | `xl`** on **`Radio.Root`** — marker, label, and hint/error scale via context (`ControlSizeProvider`).
+- **Groups:** several **`Radio.Root`** nodes share the same **`name`** (and optionally **`value` / `checked` / `onChange`**) — there is **no** separate **`RadioGroup`**; behavior is native HTML or your controlled state.
+- **`Radio.Root` `ref`** is forwarded to the **native `<input type="radio">`**.
+- **DOM `type`** is always **`radio`**; the design-system **`size`** prop is **not** the HTML `size` attribute (that key is omitted from input props).
+
+## Extended
+
+### About
+
+A compound radio field: wrapper, label row with a native radio and decorative rings, plus optional hint and error text aligned under the label column.
+
+- **When to use** — exactly one choice from mutually exclusive options that submit with the form (`name`, `value`, `required`); native group semantics with the same **`name`** on each **`Radio.Root`**; short helper or validation copy per option via **`Radio.Hint`** / **`Radio.Error`**.
+- **When not to use** — multiple independent toggles or “select many” (prefer [Checkbox](../checkbox/COMPONENT.md)).
+- **When not to use** — a single binary on/off where a switch fits the product language (prefer [Switch](../switch/COMPONENT.md)).
+- **When not to use** — a compact segmented bar of modes in one control (prefer [Segmented control](../segmented-control/COMPONENT.md)).
+- **When not to use** — fully custom markup or `asChild`; the marker and label row are fixed by the implementation.
+
+### Playground snippets
+
+Demos match **`playground/sections/RadioSection.tsx`** (order and intent). Sources use `@/` imports under **`playground/snippets/radio/`**:
+
+| Block | File | What it shows |
+|-------|------|----------------|
+| **Sizes** | [`sizes.tsx`](../../../playground/snippets/radio/sizes.tsx) | **`size`** **`s`**, **`m`**, **`l`**, **`xl`** at **`variant="default"`**; separate **`name`** per row so previews do not clash. |
+| **Variants** | [`variants.tsx`](../../../playground/snippets/radio/variants.tsx) | **`variant="default"`** with **`Radio.Hint`** vs **`variant="error"`** with **`Radio.Error`** and **`aria-invalid`**. |
+| **States** | [`states.tsx`](../../../playground/snippets/radio/states.tsx) | Unchecked, selected, **`disabled`** (off/on), row with **`Radio.Hint`** and **`aria-describedby`**. |
+| **Controlled** | [`controlled.tsx`](../../../playground/snippets/radio/controlled.tsx) (+ [`radio-snippets.module.css`](../../../playground/snippets/radio/radio-snippets.module.css)) | Same **`name`**, **`checked`** + **`onChange`** with **`e.currentTarget.checked`**; summary line. |
+| **Composition** | [`composition.tsx`](../../../playground/snippets/radio/composition.tsx) | Two options, shared **`name`**, **`Radio.Hint`** under each (payment-style block). |
+| **Full width** | [`full-width.tsx`](../../../playground/snippets/radio/full-width.tsx) (+ [`radio-snippets.module.css`](../../../playground/snippets/radio/radio-snippets.module.css)) | Narrow column (`previewBannerNarrowColumn` in playground): root stretches **`width: 100%`**, label uses remaining space. |
+| **Specific** | [`form-group.tsx`](../../../playground/snippets/radio/form-group.tsx) (+ [`radio-snippets.module.css`](../../../playground/snippets/radio/radio-snippets.module.css)) | **`fieldset`** / **`legend`**, **`required`**, **`FormData`** on submit. |
+
+### Scenarios (recipes)
+
+| Scenario | Approach |
+|----------|----------|
+| Shipping method | **`fieldset`** + **`legend`**; shared **`name`**; **`Radio.Hint`** for delivery copy per option. → [`examples/shipping-method.tsx`](examples/shipping-method.tsx) |
+| Plan picker | Controlled group: **`checked`** + **`onChange`**, same **`name`**, optional summary line. → [`examples/plan-picker.tsx`](examples/plan-picker.tsx) |
+| Settings group | Themed or preference block; **`disabled`** on tier-gated options. → [`examples/settings-group.tsx`](examples/settings-group.tsx) |
+| Single primary channel | One-notice policy (email vs SMS vs app); still radios, not checkboxes. → [`examples/notification-channel.tsx`](examples/notification-channel.tsx) |
+
+Runnable recipe examples use **`prime-ui-kit`** imports under **`examples/`**. Snippet-level demos (internal `@/` imports) are listed in **Playground snippets** above.
+
+### Composition
+
+- **`Radio.Root`** — provides context (`inputId`, hint/error ids, `describedBy`, hint/error registration) and wraps children in a **`div`** with class **`field`**.
+- **`Radio.Label`** — [Label](../label/COMPONENT.md) with **`htmlFor`** tied to the input; contains the **`input`**, SVG marker, and optional **`children`** text.
+- **`Radio.Hint`** — optional; registers so its id is merged into **`aria-describedby`**; uses the disabled hint variant when the root is **`disabled`**.
+- **`Radio.Error`** — optional; error-styled **`Hint.Root`** and registers invalid state (same effect as **`variant="error"`** on the root for styling).
+- **Order:** **`Radio.Root`** → **`Radio.Label`** → **`Radio.Hint`** and/or **`Radio.Error`** when needed. Public API: **`Radio.Root`**, **`Radio.Label`**, **`Radio.Hint`**, **`Radio.Error`**.
+
+### Minimal example
+
+```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 from one control token tier. |
+| id | `string` | auto (`useId`) | no | Input id; paired with `Radio.Label` via `htmlFor`. |
+| className | `string` | — | no | Class on the field wrapper (`.field` around Label, Hint, Error slots). |
+| disabled | `boolean` | — | no | Disables the input and label row; stays in sync with label visuals. |
+| aria-describedby | `string` | — | no | Combined with hint and error ids when `Radio.Hint` / `Radio.Error` mount. |
+| children | `React.ReactNode` | — | no | Typically `Label`, optional `Hint` / `Error`. |
+| ref | `React.Ref<HTMLInputElement>` | — | no | Ref to the native radio input. |
+| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | — | no | Other native attributes on the `input` (e.g. `name`, `value`, `checked`, `defaultChecked`, `onChange`, `required`, `readOnly`, `form`). `type` is always `radio`. |
+
+### 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 (`Label.Root`). |
+| …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 (offset under the marker column). |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally for `aria-describedby`. |
+
+### Radio.Error
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Error message text; registers invalid context (`aria-invalid` on input). |
+| className | `string` | — | no | Additional class on the error slot. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally for `aria-describedby`. |
+
+## 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.
+- **Playground demos** live under **`playground/snippets/radio/`** and are wired from **`playground/sections/RadioSection.tsx`**. **Recipes** under **`src/components/radio/examples/`** import **`prime-ui-kit`** for copy-paste after **`npm install prime-ui-kit`**.

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

@@ -0,0 +1,29 @@
+import { Radio } from "prime-ui-kit";
+
+import styles from "./radio-examples.module.css";
+
+/** Product alerts: mutually exclusive delivery channel (not multi-select — use Checkbox for that). */
+export default function NotificationChannelExample() {
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Security alerts</legend>
+      <p className={styles.helperBelowLegend}>
+        Choose one primary channel for account and login notices.
+      </p>
+      <div className={styles.columnTight}>
+        <Radio.Root name="security-alert-example" value="email" defaultChecked>
+          <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">
+          <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">
+          <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,50 @@
+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"
+          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"
+          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"
+          checked={plan === "scale"}
+          onChange={(e) => {
+            if (e.currentTarget.checked) setPlan("scale");
+          }}
+        >
+          <Radio.Label>Scale</Radio.Label>
+          <Radio.Hint>Dedicated support and regional data residency.</Radio.Hint>
+        </Radio.Root>
+      </div>
+      <p className={styles.selectionMeta}>Selected plan: {plan}</p>
+    </>
+  );
+}

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

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