From a8d54b6697e77c54e5f4a43d00b7275b806494c7 Mon Sep 17 00:00:00 2001
From: David Gracia <david.gracia@code-sherpas.rocks>
Date: Wed, 15 Jul 2026 10:28:40 -0600
Subject: [PATCH] feat(RadioGroup): add single-choice control (17th atom, D22)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

RadioGroup + RadioGroupItem is the shadcn "RadioGroup" contract over Base UI's
RadioGroup + Radio — role="radiogroup"/role="radio", arrow-key navigation,
single selection, hidden form input, shared Button/Input/Checkbox/Switch focus
ring. Completes the boolean/choice form-control family: Checkbox -> Switch ->
Radio.

- Compound (group + item), unlike the self-contained Checkbox/Switch: the
  selection semantics (single choice, arrow nav, submitted value, name) live on
  the group, matching shadcn + ARIA APG. shadcn naming (RadioGroupItem, not
  Radio); data-pharos-slot radio-group / radio-group-item.
- Shared form-control conventions: label-less (Escuela 1, D11), no size axis.
  Error is a group concern -> aria-invalid on the group, every item shows the
  ring (.group[aria-invalid] .item), not per-control.
- Ring-with-dot look, token-derived: circular 20px (spacing-5) control, ring
  darkens to neutral-900 on select (family "active" color) + inner dot
  (spacing-2). Dot is a span (Base UI mounts Indicator only when checked),
  no icon dep.
- Stories (Default + WithDisabledItem + Disabled + Invalid), unit tests (9),
  NAMING-decisions D22, changeset minor.
- Harness (rule #8): Settings form gains a "Theme" radio group
  (light/dark/system); settings.spec picks + enforces single selection + arrow
  nav -- 26 e2e specs.

Verified: build + dist-types, typecheck, lint, unit (RadioGroup 9/9, 214
total), test:storybook a11y (106 stories, +4), build-storybook, e2e 26/26.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AgnovjGivnndpV7Yzt6AmY
---
 .changeset/radio-group-atom.md            |  13 +++
 NAMING-decisions.md                       |  53 ++++++++++
 examples/saas-demo/e2e/settings.spec.ts   |  22 ++++
 examples/saas-demo/src/pages/Settings.tsx |  37 +++++++
 src/components/RadioGroup.module.css      |  81 +++++++++++++++
 src/components/RadioGroup.stories.tsx     |  94 +++++++++++++++++
 src/components/RadioGroup.tsx             |  68 +++++++++++++
 src/index.ts                              |   2 +
 tests/RadioGroup.test.tsx                 | 119 ++++++++++++++++++++++
 9 files changed, 489 insertions(+)
 create mode 100644 .changeset/radio-group-atom.md
 create mode 100644 src/components/RadioGroup.module.css
 create mode 100644 src/components/RadioGroup.stories.tsx
 create mode 100644 src/components/RadioGroup.tsx
 create mode 100644 tests/RadioGroup.test.tsx

diff --git a/.changeset/radio-group-atom.md b/.changeset/radio-group-atom.md
new file mode 100644
index 0000000..b48fa2f
--- /dev/null
+++ b/.changeset/radio-group-atom.md
@@ -0,0 +1,13 @@
+---
+'@code-sherpas/pharos-react': minor
+---
+
+Add `RadioGroup` + `RadioGroupItem`, a set of mutually exclusive options (the
+shadcn RadioGroup contract) over Base UI's `RadioGroup` + `Radio` —
+`role="radiogroup"` / `role="radio"`, arrow-key navigation, single selection,
+and the shared Button / Input / Checkbox / Switch focus ring. Completes the
+boolean/choice form-control family (Checkbox → Switch → Radio). Compound
+(group + item) because the selection semantics live on the group. Label-less by
+design (D11): pair the group with a `<label>` / `aria-labelledby` and each item
+with a `<label htmlFor>`; error via `aria-invalid` on the group. The selected
+dot is a CSS `<span>` — no icon dependency.
diff --git a/NAMING-decisions.md b/NAMING-decisions.md
index 545025c..e4659a5 100644
--- a/NAMING-decisions.md
+++ b/NAMING-decisions.md
@@ -1718,3 +1718,56 @@ Maps to the various boolean toggles / on-off settings across Alexandria's
 forms. Like the other form atoms, a like-for-like swap (prop remap +
 `<label>` wiring) is incremental; toggles wired into complex local state are
 case-by-case (Fase 6).
+
+## RadioGroup (D22, 2026-07-15)
+
+A set of mutually exclusive options. Wraps Base UI's `RadioGroup` + `Radio` —
+a `role="radiogroup"` container plus `role="radio"` buttons with a hidden form
+input, single selection, roving-tabindex arrow-key navigation, and the shared
+focus ring. The **third and final** boolean/choice control, completing the
+family opened by Checkbox (D20): Checkbox → Switch → **Radio**.
+
+### Compound, unlike Checkbox / Switch
+
+Checkbox and Switch are single self-contained atoms. RadioGroup is **compound**
+(`RadioGroup` + `RadioGroupItem`) because a radio is meaningless alone — the
+selection semantics (single choice, arrow navigation, the submitted value, the
+`name`) live on the **group**, not the individual control. Splitting them
+matches shadcn and the ARIA APG radiogroup pattern; forcing a flat single-atom
+API here would break the contract (Rule #0). This is the same reasoning that
+made Select / Combobox / DropdownMenu compound.
+
+### Canonical naming (`RadioGroup` + `RadioGroupItem`)
+
+Canonical order shadcn > Base UI > ARIA APG. shadcn names the parts
+`RadioGroup` and `RadioGroupItem`; Base UI names them `RadioGroup` and `Radio`.
+We take shadcn's names (the item is `RadioGroupItem`, not `Radio`) so the
+public contract reads like the rest of the ecosystem, and re-author the styles
+as CSS Modules over the Base UI primitive. `data-pharos-slot` is `radio-group`
+/ `radio-group-item`, mirroring the shadcn `data-slot` values.
+
+### Shared API, error at the group
+
+Inherits the form-control conventions: **label-less** (Escuela 1, D11) — the
+consumer pairs the group with a `<label>` / `aria-labelledby` and each item
+with a `<label htmlFor>`; **no `size` axis** in v1 (shadcn ships none). The one
+structural difference from Checkbox / Switch: **error is a group concern**, so
+`aria-invalid` goes on the `RadioGroup` and every item shows the error ring
+(`.group[aria-invalid] .item`), rather than per-control.
+
+### Ring-with-dot, token-derived, no icon
+
+The item mirrors the Checkbox's 20 px (`spacing-5`) control on the token grid,
+but circular (`radius-full`): the ring stays visible and an inner dot
+(`spacing-2`, `neutral-900`) appears on selection — the state-of-the-art radio
+look, deliberately distinct from the Checkbox's filled square. The ring
+darkens to `neutral-900` when selected, keeping one "active control" color
+across the family. The dot is a plain `<span>` (Base UI mounts the Indicator
+only while selected, `keepMounted={false}`) — no icon dependency.
+
+### Mapping from Alexandria
+
+Maps to the various native/`@headlessui` radio groups across Alexandria's forms
+(single-choice settings, filters). Like the other form atoms, a like-for-like
+swap (prop remap + `<label>` wiring) is incremental; groups wired into complex
+local state are case-by-case (Fase 6).
diff --git a/examples/saas-demo/e2e/settings.spec.ts b/examples/saas-demo/e2e/settings.spec.ts
index 7761dec..0cd53ea 100644
--- a/examples/saas-demo/e2e/settings.spec.ts
+++ b/examples/saas-demo/e2e/settings.spec.ts
@@ -79,4 +79,26 @@ test.describe('Settings form', () => {
     await page.getByText('Send me a weekly digest').click();
     await expect(toggle).toHaveAttribute('aria-checked', 'false');
   });
+
+  test('picks a single theme in the radio group', async ({ page }) => {
+    const group = page.getByRole('radiogroup', { name: 'Theme' });
+    const system = group.getByRole('radio', { name: 'Match system' });
+    const light = group.getByRole('radio', { name: 'Light' });
+    // Seeded selection is "system".
+    await expect(system).toHaveAttribute('aria-checked', 'true');
+    await expect(light).toHaveAttribute('aria-checked', 'false');
+
+    // Selecting another option enforces single selection.
+    await light.click();
+    await expect(light).toHaveAttribute('aria-checked', 'true');
+    await expect(system).toHaveAttribute('aria-checked', 'false');
+
+    // Arrow keys move the selection (roving radiogroup semantics).
+    await light.press('ArrowDown');
+    await expect(group.getByRole('radio', { name: 'Dark' })).toHaveAttribute(
+      'aria-checked',
+      'true',
+    );
+    await expect(light).toHaveAttribute('aria-checked', 'false');
+  });
 });
diff --git a/examples/saas-demo/src/pages/Settings.tsx b/examples/saas-demo/src/pages/Settings.tsx
index 4c19869..1ed9aac 100644
--- a/examples/saas-demo/src/pages/Settings.tsx
+++ b/examples/saas-demo/src/pages/Settings.tsx
@@ -15,6 +15,8 @@ import {
   ComboboxList,
   ComboboxTrigger,
   Input,
+  RadioGroup,
+  RadioGroupItem,
   Select,
   SelectContent,
   SelectItem,
@@ -40,6 +42,7 @@ export function SettingsPage() {
   const [skills, setSkills] = useState<string[]>(['React']);
   const [notify, setNotify] = useState(true);
   const [weeklyDigest, setWeeklyDigest] = useState(false);
+  const [theme, setTheme] = useState('system');
   const [nameError, setNameError] = useState(false);
   const [saved, setSaved] = useState(false);
 
@@ -197,6 +200,40 @@ export function SettingsPage() {
           </label>
         </div>
 
+        <div className="field">
+          <label id="theme-label">Theme</label>
+          <RadioGroup
+            aria-labelledby="theme-label"
+            value={theme}
+            onValueChange={(value) => {
+              setTheme(value as string);
+              touch();
+            }}
+          >
+            <label
+              htmlFor="theme-light"
+              style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
+            >
+              <RadioGroupItem id="theme-light" value="light" />
+              Light
+            </label>
+            <label
+              htmlFor="theme-dark"
+              style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
+            >
+              <RadioGroupItem id="theme-dark" value="dark" />
+              Dark
+            </label>
+            <label
+              htmlFor="theme-system"
+              style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
+            >
+              <RadioGroupItem id="theme-system" value="system" />
+              Match system
+            </label>
+          </RadioGroup>
+        </div>
+
         <Separator />
         <div className="settings-actions">
           <Button type="submit">Save changes</Button>
diff --git a/src/components/RadioGroup.module.css b/src/components/RadioGroup.module.css
new file mode 100644
index 0000000..c231808
--- /dev/null
+++ b/src/components/RadioGroup.module.css
@@ -0,0 +1,81 @@
+/* RadioGroup.module.css
+ *
+ * Per-component CSS Modules definition (Decision D9). Hashed into
+ * `dist/styles.css`. Styles the shadcn "RadioGroup" contract over Base UI's
+ * `RadioGroup` + `Radio`. Item state is driven by Base UI's `data-checked` /
+ * `data-disabled` attributes.
+ *
+ * The atom owns no labels (Escuela 1, D11): the consumer pairs the group with a
+ * `<label>` / `aria-labelledby` and each item with a `<label htmlFor>`. Error
+ * state is conveyed with `aria-invalid` on the group. The selected dot is a
+ * plain `<span>` — no icon dependency (Base UI mounts it only when checked).
+ *
+ * The item mirrors Checkbox's 20px (spacing-5) control on the token grid, but
+ * circular: a ring that stays visible with an inner dot on selection, the
+ * state-of-the-art radio look (distinct from Checkbox's filled square).
+ */
+
+.group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--pharos-spacing-2);
+}
+
+.item {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: var(--pharos-spacing-5);
+  height: var(--pharos-spacing-5);
+  padding: 0;
+
+  border: 1px solid var(--pharos-color-neutral-500);
+  border-radius: var(--pharos-radius-full);
+  background-color: var(--pharos-color-base-white);
+
+  cursor: pointer;
+  transition-property: background-color, border-color, box-shadow;
+  transition-duration: var(--pharos-duration-fast);
+  transition-timing-function: var(--pharos-easing-out);
+}
+
+.item:hover:not([data-disabled]):not([data-checked]) {
+  border-color: var(--pharos-color-neutral-700);
+}
+
+/* Selected — the ring darkens to match the Checkbox / Switch "active" color and
+ * the inner dot appears. */
+.item[data-checked] {
+  border-color: var(--pharos-color-neutral-900);
+}
+
+/* Error state via aria-invalid on the group (radio error is a group concern,
+ * D11) — every item shows the error ring. */
+.group[aria-invalid='true'] .item {
+  border-color: var(--pharos-color-semantic-error-fg);
+}
+
+.item:focus-visible {
+  outline: none;
+  /* Same two-stop ring as Button / Input / Checkbox / Switch so the system has
+   * one focus look. */
+  box-shadow:
+    0 0 0 2px var(--pharos-color-base-white),
+    0 0 0 4px var(--pharos-color-primary-600);
+}
+
+.item[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+/* The inner dot — Base UI mounts the Indicator only while selected. */
+.indicator {
+  display: inline-flex;
+  width: var(--pharos-spacing-2);
+  height: var(--pharos-spacing-2);
+  border-radius: var(--pharos-radius-full);
+  background-color: var(--pharos-color-neutral-900);
+}
diff --git a/src/components/RadioGroup.stories.tsx b/src/components/RadioGroup.stories.tsx
new file mode 100644
index 0000000..b6565ef
--- /dev/null
+++ b/src/components/RadioGroup.stories.tsx
@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { RadioGroup, RadioGroupItem } from './RadioGroup';
+
+/**
+ * `RadioGroup` is a set of mutually exclusive options (Decision D22). It wraps
+ * Base UI's `RadioGroup` + `Radio` — `role="radiogroup"` / `role="radio"`,
+ * arrow-key navigation, focus ring shared with Button / Input / Checkbox /
+ * Switch. Compound (group + item) because the selection semantics live on the
+ * group. The atom owns no labels (Escuela 1, D11): pair the group with a
+ * `<label>` / `aria-labelledby` and each item with a `<label htmlFor>`. Error
+ * state via `aria-invalid` on the group.
+ */
+const meta: Meta<typeof RadioGroup> = {
+  title: 'Components/RadioGroup',
+  component: RadioGroup,
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const row: React.CSSProperties = { display: 'inline-flex', alignItems: 'center', gap: 8 };
+
+/** The label pattern: a labelled group with a `<label htmlFor>` per item. */
+export const Default: Story = {
+  render: () => (
+    <RadioGroup defaultValue="card" aria-labelledby="pay-label">
+      <span id="pay-label">Payment method</span>
+      <label style={row} htmlFor="pay-card">
+        <RadioGroupItem id="pay-card" value="card" />
+        Credit card
+      </label>
+      <label style={row} htmlFor="pay-cash">
+        <RadioGroupItem id="pay-cash" value="cash" />
+        Cash
+      </label>
+      <label style={row} htmlFor="pay-transfer">
+        <RadioGroupItem id="pay-transfer" value="transfer" />
+        Bank transfer
+      </label>
+    </RadioGroup>
+  ),
+};
+
+/** A disabled individual item sits next to selectable ones. */
+export const WithDisabledItem: Story = {
+  render: () => (
+    <RadioGroup defaultValue="standard" aria-label="Shipping speed">
+      <label style={row} htmlFor="ship-standard">
+        <RadioGroupItem id="ship-standard" value="standard" />
+        Standard
+      </label>
+      <label style={row} htmlFor="ship-express">
+        <RadioGroupItem id="ship-express" value="express" />
+        Express
+      </label>
+      <label style={row} htmlFor="ship-overnight">
+        <RadioGroupItem id="ship-overnight" value="overnight" disabled />
+        Overnight (unavailable)
+      </label>
+    </RadioGroup>
+  ),
+};
+
+/** The whole group disabled. */
+export const Disabled: Story = {
+  render: () => (
+    <RadioGroup defaultValue="a" disabled aria-label="Disabled group">
+      <label style={row} htmlFor="dis-a">
+        <RadioGroupItem id="dis-a" value="a" />
+        Option A
+      </label>
+      <label style={row} htmlFor="dis-b">
+        <RadioGroupItem id="dis-b" value="b" />
+        Option B
+      </label>
+    </RadioGroup>
+  ),
+};
+
+/** Error state via the standard `aria-invalid` attribute on the group. */
+export const Invalid: Story = {
+  render: () => (
+    <RadioGroup aria-invalid aria-label="Required choice">
+      <label style={row} htmlFor="inv-yes">
+        <RadioGroupItem id="inv-yes" value="yes" />
+        Yes
+      </label>
+      <label style={row} htmlFor="inv-no">
+        <RadioGroupItem id="inv-no" value="no" />
+        No
+      </label>
+    </RadioGroup>
+  ),
+};
diff --git a/src/components/RadioGroup.tsx b/src/components/RadioGroup.tsx
new file mode 100644
index 0000000..b009bd1
--- /dev/null
+++ b/src/components/RadioGroup.tsx
@@ -0,0 +1,68 @@
+import type { ComponentProps } from 'react';
+import { RadioGroup as BaseRadioGroup } from '@base-ui/react/radio-group';
+import { Radio as BaseRadio } from '@base-ui/react/radio';
+import { cn } from '../lib/cn';
+import styles from './RadioGroup.module.css';
+
+/**
+ * A set of mutually exclusive options (the shadcn **RadioGroup** contract).
+ * Wraps Base UI's `RadioGroup`, which renders a `role="radiogroup"` container
+ * carrying the shared value, roving-tabindex arrow-key navigation and the
+ * hidden form input.
+ *
+ * Third of the boolean/choice form-control family (Checkbox → Switch →
+ * **Radio**). Unlike Checkbox / Switch — single self-contained atoms — Radio is
+ * **compound** (`RadioGroup` + `RadioGroupItem`), because the selection
+ * semantics (single choice, arrow navigation, the submitted value) live on the
+ * group, not the individual control. This matches shadcn and ARIA APG.
+ *
+ * Like the other form atoms (Escuela 1, D11) it owns no labels: pair the group
+ * with a `<label>` / `aria-labelledby`, and each item with a `<label htmlFor>`.
+ * Error state is conveyed via `aria-invalid` on the group, not a custom prop.
+ *
+ * @example
+ * <RadioGroup defaultValue="card" aria-labelledby="pay-label">
+ *   <span id="pay-label">Payment method</span>
+ *   <label htmlFor="pay-card">
+ *     <RadioGroupItem id="pay-card" value="card" /> Card
+ *   </label>
+ *   <label htmlFor="pay-cash">
+ *     <RadioGroupItem id="pay-cash" value="cash" /> Cash
+ *   </label>
+ * </RadioGroup>
+ */
+export interface RadioGroupProps extends ComponentProps<typeof BaseRadioGroup> {}
+
+export function RadioGroup({ className, ...rest }: RadioGroupProps) {
+  return (
+    <BaseRadioGroup
+      data-pharos-slot="radio-group"
+      className={cn(styles.group, className)}
+      {...rest}
+    />
+  );
+}
+
+RadioGroup.displayName = 'RadioGroup';
+
+/**
+ * A single radio button within a `RadioGroup`. Wraps Base UI's `Radio` — a
+ * `role="radio"` button plus a hidden form input — and requires a unique
+ * `value` identifying it within the group. The selected dot is a `<span>`
+ * styled with CSS (no icon dependency).
+ */
+export interface RadioGroupItemProps extends ComponentProps<typeof BaseRadio.Root> {}
+
+export function RadioGroupItem({ className, ...rest }: RadioGroupItemProps) {
+  return (
+    <BaseRadio.Root
+      data-pharos-slot="radio-group-item"
+      className={cn(styles.item, className)}
+      {...rest}
+    >
+      <BaseRadio.Indicator className={styles.indicator} />
+    </BaseRadio.Root>
+  );
+}
+
+RadioGroupItem.displayName = 'RadioGroupItem';
diff --git a/src/index.ts b/src/index.ts
index 39be61a..fe9152a 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -175,4 +175,6 @@ export { Checkbox } from './components/Checkbox';
 export type { CheckboxProps } from './components/Checkbox';
 export { Switch } from './components/Switch';
 export type { SwitchProps } from './components/Switch';
+export { RadioGroup, RadioGroupItem } from './components/RadioGroup';
+export type { RadioGroupProps, RadioGroupItemProps } from './components/RadioGroup';
 export { cn } from './lib/cn';
diff --git a/tests/RadioGroup.test.tsx b/tests/RadioGroup.test.tsx
new file mode 100644
index 0000000..ca666f4
--- /dev/null
+++ b/tests/RadioGroup.test.tsx
@@ -0,0 +1,119 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { RadioGroup, RadioGroupItem } from '../src/components/RadioGroup';
+
+function PaymentGroup(props: React.ComponentProps<typeof RadioGroup>) {
+  return (
+    <RadioGroup aria-label="Payment method" {...props}>
+      <label htmlFor="card">
+        <RadioGroupItem id="card" value="card" />
+        Card
+      </label>
+      <label htmlFor="cash">
+        <RadioGroupItem id="cash" value="cash" />
+        Cash
+      </label>
+    </RadioGroup>
+  );
+}
+
+describe('RadioGroup', () => {
+  it('renders a radiogroup with radios, none selected by default', () => {
+    render(<PaymentGroup />);
+    expect(screen.getByRole('radiogroup', { name: 'Payment method' })).toBeInTheDocument();
+    const radios = screen.getAllByRole('radio');
+    expect(radios).toHaveLength(2);
+    radios.forEach((r) => expect(r).toHaveAttribute('aria-checked', 'false'));
+  });
+
+  it('selects an option on click', async () => {
+    const user = userEvent.setup();
+    render(<PaymentGroup />);
+    const card = screen.getByRole('radio', { name: 'Card' });
+
+    await user.click(card);
+    expect(card).toHaveAttribute('aria-checked', 'true');
+  });
+
+  it('enforces a single selection (choosing one deselects the other)', async () => {
+    const user = userEvent.setup();
+    render(<PaymentGroup />);
+    const card = screen.getByRole('radio', { name: 'Card' });
+    const cash = screen.getByRole('radio', { name: 'Cash' });
+
+    await user.click(card);
+    expect(card).toHaveAttribute('aria-checked', 'true');
+    await user.click(cash);
+    expect(cash).toHaveAttribute('aria-checked', 'true');
+    expect(card).toHaveAttribute('aria-checked', 'false');
+  });
+
+  it('moves the selection with the arrow keys', async () => {
+    const user = userEvent.setup();
+    render(<PaymentGroup defaultValue="card" />);
+    const card = screen.getByRole('radio', { name: 'Card' });
+    const cash = screen.getByRole('radio', { name: 'Cash' });
+
+    card.focus();
+    await user.keyboard('{ArrowDown}');
+    expect(cash).toHaveAttribute('aria-checked', 'true');
+    expect(card).toHaveAttribute('aria-checked', 'false');
+  });
+
+  it('calls onValueChange with the selected value', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<PaymentGroup onValueChange={onValueChange} />);
+
+    await user.click(screen.getByRole('radio', { name: 'Cash' }));
+    expect(onValueChange).toHaveBeenCalledWith('cash', expect.anything());
+  });
+
+  it('does not select when the group is disabled', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<PaymentGroup disabled onValueChange={onValueChange} />);
+
+    await user.click(screen.getByRole('radio', { name: 'Card' }));
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  it('does not select a disabled item', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <RadioGroup aria-label="Shipping" onValueChange={onValueChange}>
+        <label htmlFor="std">
+          <RadioGroupItem id="std" value="std" />
+          Standard
+        </label>
+        <label htmlFor="over">
+          <RadioGroupItem id="over" value="over" disabled />
+          Overnight
+        </label>
+      </RadioGroup>,
+    );
+
+    await user.click(screen.getByRole('radio', { name: 'Overnight' }));
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  it('associates each item with a label and selects on label click', async () => {
+    const user = userEvent.setup();
+    render(<PaymentGroup />);
+    await user.click(screen.getByText('Card'));
+    expect(screen.getByRole('radio', { name: 'Card' })).toHaveAttribute('aria-checked', 'true');
+  });
+
+  it('tags the group and items via data-pharos-slot', () => {
+    render(<PaymentGroup />);
+    expect(screen.getByRole('radiogroup', { name: 'Payment method' })).toHaveAttribute(
+      'data-pharos-slot',
+      'radio-group',
+    );
+    screen
+      .getAllByRole('radio')
+      .forEach((r) => expect(r).toHaveAttribute('data-pharos-slot', 'radio-group-item'));
+  });
+});