@pnx-mixtape/mxds 0.1.0-rc.0 → 0.1.0-rc.2

package/src/Form/CheckboxCard/README.md

@@ -0,0 +1,163 @@
+# CheckboxCard
+
+A card-style checkbox — a full padded, bordered, selectable card instead of a small inline control. Use for a small set of options that benefit from a larger tap target and optional secondary hint text (e.g. a high-stakes form question), rather than a dense list of ordinary checkboxes.
+
+> **HTML/Twig users:** use native `<input type="checkbox">` with both the `.mx-checkbox` and `.mx-choice-card` wrapper classes. The react-aria wiring is React-only.
+
+`.mx-choice-card` layers on top of `.mx-checkbox` rather than replacing it — the base class still supplies input reset/sizing, disabled state, and the spacing between stacked cards in a group; `.mx-choice-card`'s higher cascade layer (`design-system.components` vs. `.mx-checkbox`'s `design-system.atoms`) overrides only what the card treatment needs to change (position, padding, border).
+
+`.mx-choice-card` is shared with `RadioCard` — it lives in `src/Form/form.css` alongside the base `.mx-checkbox`/`.mx-radio` rules, not in a per-component CSS file, since the two components' card treatments were identical enough to not warrant separate copies.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Form/form.css";
+```
+
+---
+
+## Twig
+
+```twig
+{# Single card #}
+{% include '@mixtape/Form/CheckboxCard/checkbox-card.twig' with {
+  id: 'pay-carer',
+  name: 'payments',
+  value: 'Carer Payment or Allowance',
+  label: 'Carer Payment or Carer Allowance',
+} %}
+
+{# With a secondary hint line under the label #}
+{% include '@mixtape/Form/CheckboxCard/checkbox-card.twig' with {
+  id: 'pay-other',
+  name: 'payments',
+  value: 'Another income support payment',
+  label: 'Another income support payment',
+  hint: 'You will be asked which one before you submit',
+} %}
+```
+
+**checkbox-card.twig props:**
+
+| Prop             | Type              | Required | Description                                                                                                           |
+| ---------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `id`             | `string`          | Yes      | Input id — also used to derive the `aria-describedby` ids (`help-{id}`, `status-{id}`)                                |
+| `name`           | `string`          | Yes      | `name` attribute on the input                                                                                         |
+| `value`          | `string`          | Yes      | `value` attribute on the input                                                                                        |
+| `label`          | `string`          | Yes      | Label text rendered inside `<label for="{id}">`                                                                       |
+| `hint`           | `string`          | No       | Secondary line rendered under the label, inside the card                                                              |
+| `checked`        | `boolean`         | No       | Adds `checked="checked"` to the input                                                                                 |
+| `required`       | `boolean`         | No       | Adds the `required` attribute                                                                                         |
+| `status`         | `FormStatusTypes` | No       | `invalid` adds the `error` class and `aria-invalid="true"`; `valid` adds the `success` class. Defaults to `default`   |
+| `hasDescription` | `boolean`         | No       | When `true`, `aria-describedby` is wired up to `help-{id}` (and `status-{id}` when `status` is set)                   |
+| `attributes`     | `Attribute`       | No       | Optional Drupal-style attributes object — `mx-checkbox mx-choice-card` (and the status class) is always merged on top |
+
+For a group of cards, compose several `checkbox-card.twig` includes inside a plain `<fieldset>`, same as `Checkbox` — see HTML below.
+
+---
+
+## HTML
+
+```html
+<fieldset class="mx-form-item mx-fieldset mx-fieldset--plain">
+  <legend class="mx-legend">Which payments do you currently receive?</legend>
+
+  <div class="mx-checkbox mx-choice-card">
+    <input type="checkbox" id="pay-age" name="payments" value="Age Pension" />
+    <label for="pay-age">Age Pension</label>
+  </div>
+
+  <div class="mx-checkbox mx-choice-card">
+    <input type="checkbox" id="pay-other" name="payments" value="Another income support payment" />
+    <label for="pay-other">
+      Another income support payment
+      <span class="mx-choice-card__hint">You will be asked which one before you submit</span>
+    </label>
+  </div>
+</fieldset>
+```
+
+### "Or" divider between two option groups
+
+`.mx-choice-divider` renders a horizontal rule with centred text — useful for splitting a set of card choices into "pick one of these — or — pick this other option" (see the source mockup's card question). It's plain markup, not tied to `CheckboxCard`/`RadioCard` specifically:
+
+```html
+<div class="mx-choice-divider">or</div>
+```
+
+---
+
+## React
+
+### Standalone card
+
+```tsx
+import { SingleCheckboxCard } from "@pnx-mixtape/mxds/react"
+
+;<SingleCheckboxCard value="carer">Carer Payment or Carer Allowance</SingleCheckboxCard>
+```
+
+### Card group
+
+Use `FormCheckboxCard` as the group wrapper and `CheckboxCard` for each option — same pattern as `FormCheckbox`/`Checkbox`.
+
+```tsx
+import { FormCheckboxCard, CheckboxCard } from "@pnx-mixtape/mxds/react"
+
+;<FormCheckboxCard label="Which payments do you currently receive?" onChange={setSelected}>
+  <CheckboxCard value="age">Age Pension</CheckboxCard>
+  <CheckboxCard value="dsp">Disability Support Pension</CheckboxCard>
+  <CheckboxCard value="other" hint="You will be asked which one before you submit">
+    Another income support payment
+  </CheckboxCard>
+</FormCheckboxCard>
+```
+
+**`FormCheckboxCard` props:** all `CheckboxGroupProps` from react-stately + `label: string`
+
+**`CheckboxCard` props:** all `AriaCheckboxGroupItemProps` + `hint?: string`, `status?: FormStatus`, `className?: string`
+
+**`SingleCheckboxCard` props:** all `AriaCheckboxProps` + `hint?: string`, `status?: FormStatus`, `className?: string`
+
+---
+
+### React ⇄ Twig parity
+
+The prop shapes intentionally diverge, same as `Checkbox`/`Radio`:
+
+- Twig's `label` becomes React `children` — react-aria composes the accessible name from rendered content, not a string prop.
+- Twig's `id`/`name`/`checked`/`required`/`value` are handled by the react-aria hooks (`useCheckboxGroupItem`/`useCheckbox`) via prop spread — they aren't declared as explicit props because react-aria owns generating/wiring them (e.g. `id` comes from `useId()`).
+- Twig's `hasDescription` manually wires `aria-describedby` to a `help-{id}` node; React doesn't need it because react-aria's hooks generate and wire that association themselves when a description is passed through their own props.
+
+---
+
+## Modifiers
+
+No BEM modifier classes — `error`/`success` are applied as plain (unprefixed) status classes, matching `Checkbox`'s convention, driven by the `status` prop/Twig var.
+
+---
+
+## Accessibility
+
+- The input stays a real, focusable `<input type="checkbox">` — only its default appearance is replaced (`appearance: none` plus a custom checked-state image), so it keeps native checkbox semantics, keyboard support (<kbd>Space</kbd> to toggle), and form submission behaviour.
+- The whole card is clickable because the `<label>` fills it — the input itself only needs to be as large as `--control-size` dictates, not the full card.
+- The focus ring (`:focus-visible`) renders on the input itself, inside the card, rather than around the whole card — keeps the indicator anchored to the actual interactive control.
+- `hint` text is inside the same `<label>` as the primary text, so both are announced together when the control receives focus — don't rely on `hint` to convey anything the primary `label` text doesn't already establish.
+
+---
+
+## Customisation
+
+| Custom property           | Applies to                                                        | Default                                             |
+| ------------------------- | ----------------------------------------------------------------- | --------------------------------------------------- |
+| `--choice-padding-block`  | `.mx-choice-card`                                                 | `var(--spacing-s)`                                  |
+| `--choice-padding-inline` | `.mx-choice-card`                                                 | `var(--spacing-m)`                                  |
+| `--choice-colour-active`  | `.mx-choice-card`                                                 | `var(--colour-primary)`                             |
+| `--control-size`          | `.mx-choice-card input`, and `.mx-checkbox`'s own input styling   | `var(--spacing-m)` (shared with `Checkbox`/`Radio`) |
+| `--line-width`            | `.mx-choice-card`'s border, and `.mx-checkbox`'s own input border | `2px`                                               |
+
+```css
+.theme--health-services .mx-choice-card {
+  --choice-colour-active: var(--colour-primary);
+}
+```

package/src/Form/CheckboxCard/__snapshots__/CheckboxCard.stories.ts.snap

@@ -0,0 +1,63 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Checkbox Card 1`] = `
+"
+<div class="mx-checkbox mx-choice-card">
+  <input id="pay-carer" type="checkbox" name="payments" value="Carer Payment or Allowance">
+  <label for="pay-carer">
+    Carer Payment or Carer Allowance
+      </label>
+</div>
+"
+`;
+
+exports[`Checked 1`] = `
+"
+<div class="mx-checkbox mx-choice-card">
+  <input id="pay-carer" type="checkbox" name="payments" value="Carer Payment or Allowance" checked="checked">
+  <label for="pay-carer">
+    Carer Payment or Carer Allowance
+      </label>
+</div>
+"
+`;
+
+exports[`Divider 1`] = `
+"
+<div class="mx-checkbox mx-choice-card">
+  <input id="card-yes" type="checkbox" name="card" value="Yes, I hold a card">
+  <label for="card-yes">
+    Yes, I hold a card
+    <span class="mx-choice-card__hint">Pensioner Concession, Health Care or DVA card</span>  </label>
+</div>
+<div class="mx-choice-divider">or</div>
+<div class="mx-checkbox mx-choice-card">
+  <input id="card-unsure" type="checkbox" name="card" value="Not sure">
+  <label for="card-unsure">
+    I am not sure
+    <span class="mx-choice-card__hint">We will ask a few more questions to work it out</span>  </label>
+</div>
+"
+`;
+
+exports[`Invalid 1`] = `
+"  
+<div class="mx-checkbox mx-choice-card">
+  <input id="pay-carer" type="checkbox" name="unique-0" value="Carer Payment or Allowance" aria-describedby="unique-0" aria-invalid="true">
+  <label for="pay-carer">
+    Carer Payment or Carer Allowance
+      </label>
+</div>
+"
+`;
+
+exports[`With Hint 1`] = `
+"
+<div class="mx-checkbox mx-choice-card">
+  <input id="pay-other" type="checkbox" name="payments" value="Another income support payment">
+  <label for="pay-other">
+    Another income support payment
+    <span class="mx-choice-card__hint">You will be asked which one before you submit</span>  </label>
+</div>
+"
+`;

package/src/Form/CheckboxCard/__snapshots__/CheckboxCard.stories.tsx.snap

@@ -0,0 +1,7 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Group 1`] = `"<fieldset class="mx-form-item mx-fieldset" role="group" id="react-aria-_r_6_"><legend class="mx-legend">Which payments do you currently receive?</legend><div class="mx-checkbox mx-choice-card"><input id="_r_b_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="age"><label for="_r_b_">Age Pension</label></div><div class="mx-checkbox mx-choice-card"><input id="_r_e_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="dsp"><label for="_r_e_">Disability Support Pension</label></div><div class="mx-checkbox mx-choice-card"><input id="_r_h_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="carer"><label for="_r_h_">Carer Payment or Carer Allowance</label></div><div class="mx-checkbox mx-choice-card"><input id="_r_k_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="other"><label for="_r_k_">Another income support payment<span class="mx-choice-card__hint">You will be asked which one before you submit</span></label></div></fieldset>"`;
+
+exports[`Single 1`] = `"<div class="mx-checkbox mx-choice-card"><input id="_r_0_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="carer"><label for="_r_0_">Carer Payment or Carer Allowance</label></div>"`;
+
+exports[`With Hint 1`] = `"<div class="mx-checkbox mx-choice-card"><input id="_r_3_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="other"><label for="_r_3_">Another income support payment<span class="mx-choice-card__hint">You will be asked which one before you submit</span></label></div>"`;

package/src/Form/CheckboxCard/checkbox-card.twig

@@ -0,0 +1,29 @@
+{% set classes = [
+  'mx-checkbox',
+  'mx-choice-card',
+] %}
+{% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
+{% set status = status|default("default") %}
+{% if hasDescription or status != "default" %}
+  {% set helpers = [
+    hasDescription ? "help-"~ id : null,
+    status != "default" ?  "status-"~ id : null,
+  ]|join(" ")|trim() %}
+{% endif %}
+
+<div{{ attributes }}>
+  <input
+      id="{{ id }}"
+      type="checkbox"
+      name="{{ name }}"
+      value="{{ value }}"
+      {% if checked %} checked="checked"{% endif %}
+      {% if helpers is not empty %} aria-describedby="{{ helpers }}"{% endif %}
+      {% if status == "invalid" %} aria-invalid="true"{% endif %}
+      {% if required %} required{% endif %}
+  >
+  <label for="{{ id }}">
+    {{ label }}
+    {% if hint %}<span class="mx-choice-card__hint">{{ hint }}</span>{% endif %}
+  </label>
+</div>

package/src/Form/FormItem/__snapshots__/FormItem.stories.ts.snap

@@ -31,7 +31,7 @@ exports[`Error 1`] = `
 
   
     
-<input class="mx-input__text error" id="form-item" name="unique-0" type="text" value="Musicals" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0" aria-invalid="true">
+<input class="mx-input__text" id="form-item" name="unique-0" type="text" value="Musicals" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0" aria-invalid="true">
 
   <div class="mx-description" id="help-form-item">
   Help text that provides additional information about the field.
@@ -118,7 +118,7 @@ exports[`Success 1`] = `
 
   
     
-<input class="mx-input__text success" id="form-item" name="unique-0" type="text" value="Jazz" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0">
+<input class="mx-input__text" id="form-item" name="unique-0" type="text" value="Jazz" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0">
 
   <div class="mx-description" id="help-form-item">
   Help text that provides additional information about the field.

package/src/Form/README.md

@@ -32,7 +32,7 @@ The input's `aria-describedby` is automatically wired to `help-{id}` — `FormDe
 <div class="mx-form-item">
   <label class="mx-label" for="email">Email address</label>
   <input
-    class="mx-input__text error"
+    class="mx-input__text"
     id="email"
     type="email"
     name="email"
@@ -46,12 +46,13 @@ The input's `aria-describedby` is automatically wired to `help-{id}` — `FormDe
 
 ## Input modifier classes
 
-| Class                    | Effect                                                       |
-| ------------------------ | ------------------------------------------------------------ |
-| `mx-input--wide`         | `inline-size: 100%` — fills its container                    |
-| `mx-input--small`        | Reduced border (1px), smaller chevron offset                 |
-| `mx-input--icon`         | Adds leading icon via `::before` mask                        |
-| `mx-form--inline-button` | Input + button fused into one bordered unit (used in Search) |
+| Class                    | Effect                                                        |
+| ------------------------ | ------------------------------------------------------------- |
+| `mx-input--wide`         | `inline-size: 100%` — fills its container                     |
+| `mx-input--small`        | Reduced border (1px), smaller chevron offset                  |
+| `mx-input--icon`         | Adds leading icon via `::before` mask                         |
+| `mx-form--inline-button` | Input + button fused into one bordered unit (used in Search)  |
+| `mx-validate`            | Opt in to live `:user-valid` / `:user-invalid` border colours |
 
 ## Form actions
 
@@ -186,13 +187,64 @@ import { FormStatus } from "../../enums"
 
 ---
 
-## Status states (`FormStatus` enum)
+## Validation state
 
-| Value                | Class suffix | Description                                                  |
-| -------------------- | ------------ | ------------------------------------------------------------ |
-| `FormStatus.DEFAULT` | —            | Normal state                                                 |
-| `FormStatus.VALID`   | `success`    | Green border, success icon on description                    |
-| `FormStatus.INVALID` | `error`      | Red border, error icon on description, `aria-invalid="true"` |
+There is no `error` or `success` class to apply. Two hooks drive input borders:
+
+### 1. Live native validation — opt in with `mx-validate`
+
+Add `mx-validate` to a control to let the browser colour it as the user types.
+Without the class, a control is **never** coloured automatically — so filling in
+an unmarked field doesn't turn it green.
+
+```html
+<input class="mx-input__text mx-validate" type="email" required />
+```
+
+For checkbox and radio, put it on the wrapper — that's where `className` and
+Drupal `attributes` land:
+
+```html
+<div class="mx-checkbox mx-validate"><input type="checkbox" required /><label>…</label></div>
+```
+
+| Selector        | Effect       | When it matches                                                      |
+| --------------- | ------------ | -------------------------------------------------------------------- |
+| `:user-valid`   | Green border | Field passes validation **and** the user has interacted or submitted |
+| `:user-invalid` | Red border   | Field fails validation **and** the user has interacted or submitted  |
+
+`:user-*` is used rather than `:valid`/`:invalid` so a blank `required` field
+isn't red on page load.
+
+### 2. Explicit errors — `aria-invalid`, no opt-in
+
+`[aria-invalid="true"]` always paints a red border, with or without
+`mx-validate`. This is for failures the browser can't see: server-rendered
+(Drupal) or async. The consumer has already decided the field is wrong, so
+there's nothing to opt into.
+
+Live success styling excludes `[aria-invalid="true"]`, so an explicit error
+stays red even when the field passes native validation.
+
+### `status` prop (`FormStatus` enum)
+
+`status` no longer sets border classes. It controls the ARIA state and which
+message block renders:
+
+| Value                | Effect                                                         |
+| -------------------- | -------------------------------------------------------------- |
+| `FormStatus.DEFAULT` | `aria-invalid="false"`, no message block                       |
+| `FormStatus.VALID`   | `mx-success-message` block, green icon — **no green border**   |
+| `FormStatus.INVALID` | `aria-invalid="true"` (⇒ red border), `mx-error-message` block |
+
+For a server-side error, set `status={FormStatus.INVALID}` — the border follows
+from `aria-invalid`. For client-side rules, use native attributes (`required`,
+`pattern`, `type="email"`, `min`/`max`), add `mx-validate`, and let the browser
+do it.
+
+Green borders are live-only: there is no ARIA counterpart to `aria-invalid`, so
+an explicitly-set `VALID` status renders the success message without recolouring
+the border.
 
 ---
 

package/src/Form/Radio/FormRadio.tsx

@@ -40,10 +40,7 @@ const Radio = ({
   const state = use(RadioContext)
   const { inputProps } = useRadio(props, state, ref)
 
-  const classes = classNames("mx-radio", className, {
-    error: status === FormStatus.INVALID,
-    success: status === FormStatus.VALID,
-  })
+  const classes = classNames("mx-radio", className)
 
   return (
     <div className={classes}>

package/src/Form/Radio/input-radio.twig

@@ -1,7 +1,5 @@
 {% set classes = [
   'mx-radio',
-  status == "invalid" ? "error" : null,
-  status == "valid" ? "success" : null,
 ] %}
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
 <div{{ attributes }}>

package/src/Form/RadioCard/README.md

@@ -0,0 +1,146 @@
+# RadioCard
+
+A card-style radio — a full padded, bordered, selectable card instead of a small inline control. Use for a small set of mutually-exclusive options that benefit from a larger tap target and optional secondary hint text (e.g. a high-stakes form question), rather than a dense list of ordinary radios.
+
+> **HTML/Twig users:** use native `<input type="radio">` with both the `.mx-radio` and `.mx-choice-card` wrapper classes. The react-aria wiring is React-only.
+
+`.mx-choice-card` layers on top of `.mx-radio` rather than replacing it — the base class still supplies input reset/sizing, disabled state, and the spacing between stacked cards in a group; `.mx-choice-card`'s higher cascade layer (`design-system.components` vs. `.mx-radio`'s `design-system.atoms`) overrides only what the card treatment needs to change (position, padding, border).
+
+`.mx-choice-card` is shared with `CheckboxCard` — it lives in `src/Form/form.css` alongside the base `.mx-checkbox`/`.mx-radio` rules, not in a per-component CSS file, since the two components' card treatments were identical enough to not warrant separate copies.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Form/form.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Form/RadioCard/radio-card.twig' with {
+  id: 'card-yes',
+  name: 'card',
+  value: 'yes',
+  label: 'Yes, I hold a card',
+  hint: 'Pensioner Concession, Health Care or DVA card',
+} %}
+```
+
+**radio-card.twig props:**
+
+| Prop         | Type              | Required | Description                                                                                                         |
+| ------------ | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `id`         | `string`          | Yes      | Input id                                                                                                            |
+| `name`       | `string`          | Yes      | `name` attribute on the input                                                                                       |
+| `value`      | `string`          | Yes      | `value` attribute on the input                                                                                      |
+| `label`      | `string`          | Yes      | Label text rendered inside `<label for="{id}">`                                                                     |
+| `hint`       | `string`          | No       | Secondary line rendered under the label, inside the card                                                            |
+| `checked`    | `boolean`         | No       | Adds `checked="checked"` to the input                                                                               |
+| `required`   | `boolean`         | No       | Adds the `required` attribute                                                                                       |
+| `status`     | `FormStatusTypes` | No       | `invalid` adds the `error` class and `aria-invalid="true"`; `valid` adds the `success` class. Defaults to `default` |
+| `attributes` | `Attribute`       | No       | Optional Drupal-style attributes object — `mx-radio mx-choice-card` (and the status class) is always merged on top  |
+
+For a group of cards, compose several `radio-card.twig` includes inside a `<fieldset>` — see HTML below.
+
+---
+
+## HTML
+
+```html
+<fieldset class="mx-form-item mx-fieldset mx-fieldset--plain">
+  <legend class="mx-legend">Do you hold a current concession card?</legend>
+
+  <div class="mx-radio mx-choice-card">
+    <input type="radio" id="card-yes" name="card" value="yes" />
+    <label for="card-yes">
+      Yes, I hold a card
+      <span class="mx-choice-card__hint">Pensioner Concession, Health Care or DVA card</span>
+    </label>
+  </div>
+
+  <div class="mx-radio mx-choice-card">
+    <input type="radio" id="card-no" name="card" value="no" />
+    <label for="card-no">
+      No
+      <span class="mx-choice-card__hint">You may still be eligible based on your income</span>
+    </label>
+  </div>
+
+  <div class="mx-choice-divider">or</div>
+
+  <div class="mx-radio mx-choice-card">
+    <input type="radio" id="card-unsure" name="card" value="unsure" />
+    <label for="card-unsure">I am not sure</label>
+  </div>
+</fieldset>
+```
+
+`.mx-choice-divider` is also defined in `src/Form/form.css` — plain markup used to split either card type into two groups, already available once you import `form.css`. See [`CheckboxCard`'s README](../CheckboxCard/README.md#or-divider-between-two-option-groups) for more.
+
+---
+
+## React
+
+Use `FormRadioCard` as the group wrapper and `RadioCard` for each option — same pattern as `FormRadio`/`Radio`. There's no standalone/single variant (a lone radio isn't a meaningful control on its own, same as `Radio`).
+
+```tsx
+import { FormRadioCard, RadioCard } from "@pnx-mixtape/mxds/react"
+
+;<FormRadioCard label="Do you hold a current concession card?" onChange={setSelected}>
+  <RadioCard value="yes" hint="Pensioner Concession, Health Care or DVA card">
+    Yes, I hold a card
+  </RadioCard>
+  <RadioCard value="no" hint="You may still be eligible based on your income">
+    No
+  </RadioCard>
+</FormRadioCard>
+```
+
+**`FormRadioCard` props:** all `AriaRadioGroupProps` from react-aria + `label: string`
+
+**`RadioCard` props:** all `AriaRadioProps` + `hint?: string`, `status?: FormStatus`, `className?: string`
+
+---
+
+### React ⇄ Twig parity
+
+Same intentional divergence as `Radio`/`Checkbox`/`CheckboxCard`:
+
+- Twig's `label` becomes React `children` — react-aria composes the accessible name from rendered content, not a string prop.
+- Twig's `id`/`name`/`checked`/`required`/`value` are handled by the react-aria hooks (`useRadio`/`useRadioGroup`) via prop spread rather than declared explicitly.
+
+---
+
+## Modifiers
+
+No BEM modifier classes — `error`/`success` are applied as plain (unprefixed) status classes, matching `Radio`'s convention, driven by the `status` prop/Twig var.
+
+---
+
+## Accessibility
+
+- The input stays a real, focusable `<input type="radio">` — only its default appearance is replaced (`appearance: none` plus a custom checked-state dot), so it keeps native radio semantics, keyboard support (arrow keys to move within the group, per the browser's native radio-group behaviour), and form submission behaviour.
+- The whole card is clickable because the `<label>` fills it — the input itself only needs to be as large as `--control-size` dictates, not the full card.
+- The focus ring (`:focus-visible`) renders on the input itself, inside the card, rather than around the whole card.
+- `hint` text is inside the same `<label>` as the primary text, so both are announced together when the control receives focus — don't rely on `hint` to convey anything the primary `label` text doesn't already establish.
+
+---
+
+## Customisation
+
+| Custom property           | Applies to                                                                 | Default                                             |
+| ------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------- |
+| `--choice-padding-block`  | `.mx-choice-card`                                                          | `var(--spacing-s)`                                  |
+| `--choice-padding-inline` | `.mx-choice-card`                                                          | `var(--spacing-m)`                                  |
+| `--choice-colour-active`  | `.mx-choice-card`'s border/background tint when checked                    | `var(--colour-primary)`                             |
+| `--radio-colour`          | The checked dot itself — inherited from `.mx-radio`, not `.mx-choice-card` | `var(--colour-primary)`                             |
+| `--control-size`          | `.mx-choice-card input`, and `.mx-radio`'s own input styling               | `var(--spacing-m)` (shared with `Checkbox`/`Radio`) |
+| `--line-width`            | `.mx-choice-card`'s border, and `.mx-radio`'s own input border             | `2px`                                               |
+
+```css
+.theme--health-services .mx-choice-card {
+  --choice-colour-active: var(--colour-primary);
+}
+```

package/src/Form/RadioCard/RadioCard.stories.ts

@@ -0,0 +1,95 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import Component from "../FormItem/form-item.twig"
+import InputRadioCard from "./radio-card.twig"
+import Label from "../Label/label.twig"
+import "../form.css"
+import { FormItem as FormItemType } from "@pnx-mixtape/ids-shape"
+
+type MxFormItemType = Omit<FormItemType, "fields"> & {
+  fields?: string
+}
+
+const meta: Meta<MxFormItemType> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    id: "card-set",
+    as: "fieldset",
+    label: Label({
+      title: "Do you hold a current concession card?",
+      as: "legend",
+    }),
+    fields: [
+      InputRadioCard({
+        id: "card-yes",
+        name: "card",
+        label: "Yes, I hold a card",
+        hint: "Pensioner Concession, Health Care or DVA card",
+        value: "yes",
+      }),
+      InputRadioCard({
+        id: "card-applied",
+        name: "card",
+        label: "I have applied but not received it",
+        hint: "You can continue, but we may ask for evidence later",
+        value: "applied",
+      }),
+      InputRadioCard({
+        id: "card-no",
+        name: "card",
+        label: "No",
+        hint: "You may still be eligible based on your income",
+        value: "no",
+      }),
+      '<div class="mx-choice-divider">or</div>',
+      InputRadioCard({
+        id: "card-unsure",
+        name: "card",
+        label: "I am not sure",
+        hint: "We will ask a few more questions to work it out",
+        value: "unsure",
+      }),
+    ].join(""),
+  },
+  parameters: {
+    deepControls: { enabled: true },
+    a11y: {
+      config: {
+        rules: [
+          {
+            // ID's are not unique due to test-runner.
+            id: "label",
+            enabled: false,
+          },
+        ],
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<MxFormItemType>
+
+export const RadioCard: Story = {}
+
+export const Checked: Story = {
+  args: {
+    fields: [
+      InputRadioCard({
+        id: "card-yes",
+        name: "card",
+        label: "Yes, I hold a card",
+        hint: "Pensioner Concession, Health Care or DVA card",
+        value: "yes",
+        checked: true,
+      }),
+      InputRadioCard({
+        id: "card-no",
+        name: "card",
+        label: "No",
+        hint: "You may still be eligible based on your income",
+        value: "no",
+      }),
+    ].join(""),
+  },
+}