@arbor-education/design-system.components 0.15.0 → 0.16.1

package/src/components/formField/fieldset/Fieldset.stories.tsx

@@ -1,28 +1,289 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Fieldset } from './Fieldset';
-import { FormField } from '../FormField';
-import { CheckboxInput } from '../inputs/checkbox/CheckboxInput';
-import { RadioButtonInput } from '../inputs/radio/RadioButtonInput';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+
+import { CheckboxInput } from 'Components/formField/inputs/checkbox/CheckboxInput';
+import { Fieldset } from 'Components/formField/fieldset/Fieldset';
+import { RadioButtonInput } from 'Components/formField/inputs/radio/RadioButtonInput';
+import { FormField } from 'Components/formField/FormField';
+
+// ─────────────────────────────────────────────
+// Content strings
+// ─────────────────────────────────────────────
+
+const DESCRIPTION_INTRO = `
+The **Fieldset** component is the semantic wrapper for grouping related form controls in the Arbor
+design system. It renders a native HTML \`<fieldset>\` with an optional \`<legend>\`, giving a
+grouped set of inputs a shared label that assistive technology can announce before each control.
+
+Under the hood it resets all browser user-agent styles (border, margin, padding) and uses flexbox
+to stack children with consistent spacing via the design-system token
+\`--checkbox-or-radio-button-group-spacing-gap-vertical\`.
+
+Use **Fieldset** when the higher-level \`CheckboxGroup\` or \`RadioButtonGroup\` components do not
+cover your layout needs — for example, mixed control types, custom grid arrangements, or consent
+blocks that combine checkboxes with rich text.
+
+---
+
+### When to use
+
+| Scenario | Notes |
+|---|---|
+| Custom group of checkboxes | Primary use case — wrap \`CheckboxInput\` components |
+| Custom group of radio buttons | Enforces mutual exclusivity via shared \`name\` attribute |
+| Mixed control group | Combine different control types under one accessible label |
+| Section of a larger form | Groups FormField components under a shared named section |
+| Consent and permissions blocks | Parent consent forms with multiple independent options |
+
+---
+
+### When NOT to use
+
+| Scenario | Alternative |
+|---|---|
+| Single labelled input | Use \`FormField\` with \`label\` + \`labelFor\` |
+| Standard checkbox list | Consider \`CheckboxGroup\` if it covers the layout |
+| Standard radio button list | Consider \`RadioButtonGroup\` if it covers the layout |
+| Visual card grouping (non-form) | Use layout primitives — \`<fieldset>\` is for form controls only |
+| Unknown-length async option list | Compose dynamically, but always keep Fieldset + legend |
+
+---
+
+### Component API
+
+\`\`\`tsx
+import { Fieldset } from '@arbor-education/design-system.components';
+
+// With legend
+<Fieldset legend="Notification preferences">
+  <CheckboxInput id="email" name="notifications" label="Email" />
+  <CheckboxInput id="sms" name="notifications" label="SMS" />
+</Fieldset>
+
+// Without legend (requires aria-label or aria-labelledby for accessibility)
+<h2 id="prefs-heading">Notification preferences</h2>
+<Fieldset aria-labelledby="prefs-heading">
+  <CheckboxInput id="email" name="notifications" label="Email" />
+  <CheckboxInput id="sms" name="notifications" label="SMS" />
+</Fieldset>
+
+// Disable all children at once
+<Fieldset legend="Trip consent" disabled>
+  <CheckboxInput id="trip-1" name="consent" label="Year 7 Geography trip" />
+  <CheckboxInput id="trip-2" name="consent" label="Year 8 Science museum" />
+</Fieldset>
+\`\`\`
+`.trim();
+
+const USAGE_GUIDANCE = `
+### When to use
+
+Fieldset is the right choice when you need to group two or more related form controls and give that
+group an accessible label. The most common patterns in Arbor are:
+
+- **Consent blocks** — a set of independent checkboxes that each require explicit opt-in
+- **Preference groups** — a set of radio buttons where only one option is valid
+- **Form sections** — a logical sub-section of a larger form, named with a visible legend
+
+---
+
+### When NOT to use
+
+| Anti-pattern | Why it is wrong | What to do instead |
+|---|---|---|
+| Adding a visible border | The UA border is intentionally removed. Adding it back makes fieldset look like a card | Use a \`<div>\` with a border if you need a visual card |
+| Grouping non-form content | Fieldset is a form landmark — assistive technology announces it as such | Use \`<section>\` or \`<div>\` for non-form groupings |
+| Omitting legend with no ARIA fallback | Screen readers have no group label to announce | Always provide \`legend\`, \`aria-label\`, or \`aria-labelledby\` |
+| Nesting fieldsets deeply | Legal HTML but confusing for AT users | Flatten or split into separate form sections |
+
+---
+
+### The \`disabled\` prop — one prop to rule them all
+
+Setting \`disabled\` on the Fieldset element is the correct, semantic way to disable an entire group
+of controls. The browser propagates the disabled state to **all descendant form controls**
+automatically — no JavaScript, no CSS hacks, no prop-drilling needed.
+
+\`\`\`tsx
+// This ONE prop disables every checkbox/radio/input inside:
+<Fieldset legend="Trip consent" disabled>
+  <CheckboxInput id="trip-1" label="Year 7 Geography trip" />
+  <CheckboxInput id="trip-2" label="Year 8 Science museum" />
+  <CheckboxInput id="trip-3" label="Year 9 Drama workshop" />
+</Fieldset>
+\`\`\`
+
+Do **not** pass \`disabled\` to each child individually when you want to disable the whole group —
+that is more code, more error-prone, and is not semantically equivalent.
+
+---
+
+### Legend visibility
+
+The \`legend\` prop renders a \`<legend>\` element as the **first child** of the fieldset. This is
+enforced by the component. Do not try to move it via CSS positioning — the browser ignores
+\`position: absolute\` on \`<legend>\` in many layouts and the AT reading order depends on it being
+first in the DOM.
+`.trim();
+
+const DEVELOPER_NOTES = `
+### Critical usage patterns
+
+#### Always label your fieldset
+
+A fieldset without any group label fails WCAG 1.3.1 (Info and Relationships). Use one of:
+
+1. **\`legend\` prop** (preferred) — renders a visible \`<legend>\` element
+2. **\`aria-label\`** — invisible label string (use when design requires no visible heading)
+3. **\`aria-labelledby\`** — points to an existing heading element by \`id\`
+
+#### Radio button mutual exclusivity
+
+For radio buttons, share the same \`name\` attribute across all \`RadioButtonInput\` children.
+The \`<fieldset>\` provides the group semantics; the shared \`name\` enforces single-selection.
+
+\`\`\`tsx
+<Fieldset legend="Report access level">
+  <RadioButtonInput name="access" id="access-view" label="View only" value="view" />
+  <RadioButtonInput name="access" id="access-edit" label="View and edit" value="edit" />
+  <RadioButtonInput name="access" id="access-admin" label="Full admin" value="admin" />
+</Fieldset>
+\`\`\`
+
+#### Do not add extra wrapper divs around children
+
+The Fieldset already applies \`display: flex; flex-direction: column; gap: var(--checkbox-or-radio-button-group-spacing-gap-vertical)\`.
+Adding extra \`<div>\` wrappers around each child will break the spacing rhythm.
+
+---
+
+### Accessibility
+
+| Concern | How it is addressed |
+|---|---|
+| Group label | \`<legend>\` is the first child — screen readers announce it before each control in the group |
+| Disabled state | Native \`disabled\` on \`<fieldset>\` propagates to all descendants — no JS needed |
+| No visible legend | Use \`aria-label\` or \`aria-labelledby\` — never leave the group unlabelled |
+| Keyboard navigation | All standard browser keyboard behaviour is preserved — no custom handlers needed |
+| WCAG 1.3.1 | Grouping via fieldset+legend satisfies Info and Relationships at level A |
+
+---
+
+### TypeScript types
+
+\`\`\`ts
+import type { FieldsetProps } from '@arbor-education/design-system.components';
+\`\`\`
+
+| Prop | Type | Default | Description |
+|---|---|---|
+| \`legend\` | \`string\` | — | Renders a \`<legend>\` element as the first child. Omit only when using \`aria-label\` or \`aria-labelledby\` |
+| \`disabled\` | \`boolean\` | \`false\` | Disables all descendant form controls via native HTML propagation |
+| \`children\` | \`ReactNode\` | — | Form controls to group. Typically \`CheckboxInput\` or \`RadioButtonInput\` |
+| \`className\` | \`string\` | — | Additional CSS classes for the \`<fieldset>\` element |
+| \`aria-label\` | \`string\` | — | Invisible accessible label — use when there is no visible legend |
+| \`aria-labelledby\` | \`string\` | — | \`id\` of an existing heading element — alternative to \`legend\` |
+`.trim();
+
+const RELATED_COMPONENTS = `
+---
+
+### Related components
+
+| Component | Storybook link |
+|---|---|
+| FormField | [View FormField](?path=/docs/components-formfield-formfield--docs) |
+| CheckboxInput | [View CheckboxInput](?path=/docs/components-formfield-inputs-checkboxinput--docs) |
+| RadioButtonInput | [View RadioButtonInput](?path=/docs/components-formfield-inputs-radiobuttoninput--docs) |
+`.trim();
+
+const PROPS_INTRO = `
+Use the controls below to toggle \`legend\` and \`disabled\` and see how Fieldset responds in real
+time. The \`children\` prop cannot be set via the controls panel directly — the Default story
+renders \`CheckboxInput\` components as the primary use case.
+`.trim();
+
+// ─────────────────────────────────────────────
+// Custom docs page
+// ─────────────────────────────────────────────
+
+function FieldsetDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ─────────────────────────────────────────────
+// Meta
+// ─────────────────────────────────────────────
 
 const meta = {
   title: 'Components/FormField/Fieldset',
   component: Fieldset,
+  tags: ['autodocs'],
   parameters: {
     layout: 'padded',
+    docs: { page: FieldsetDocsPage },
   },
-  tags: ['autodocs'],
   argTypes: {
     legend: {
-      control: 'text',
-      description: 'The legend text for the fieldset',
+      description:
+        'Renders a `<legend>` element as the first child of the fieldset. Provides the accessible group label announced by screen readers before each control in the group. Omit only when using `aria-label` or `aria-labelledby`.',
+      control: { type: 'text' },
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: '—' },
+      },
     },
     disabled: {
-      control: 'boolean',
-      description: 'Disable all form controls within the fieldset',
+      description:
+        'Disables all descendant form controls via native HTML propagation. **One prop disables everything** — no need to pass `disabled` to each child individually.',
+      control: { type: 'boolean' },
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
     },
     children: {
+      description:
+        'Form controls to group. Typically `CheckboxInput` or `RadioButtonInput` components. Do not wrap children in extra `<div>` elements — the fieldset already applies flex + gap spacing.',
       control: false,
-      description: 'Form controls and other content to display within the fieldset',
+      table: {
+        type: { summary: 'ReactNode' },
+        defaultValue: { summary: '—' },
+      },
+    },
+    className: {
+      description:
+        'Additional CSS class(es) applied to the `<fieldset>` element. Use design-token values for any layout overrides.',
+      control: { type: 'text' },
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: '—' },
+      },
     },
   },
 } satisfies Meta<typeof Fieldset>;
@@ -30,60 +291,509 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-// Default fieldset with simple content
+// ─────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────
+
+/** Wraps a story with a consistent description below the rendered example. */
+function withDescription(description: string, story: Story): Story {
+  return {
+    ...story,
+    parameters: {
+      ...story.parameters,
+      docs: {
+        ...story.parameters?.docs,
+        description: { story: description },
+      },
+    },
+  };
+}
+
+// ─────────────────────────────────────────────
+// Stories
+// ─────────────────────────────────────────────
+
 export const Default: Story = {
   args: {
-    legend: 'Personal Information',
-    children: (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+    legend: 'Consent and Permissions',
+    disabled: false,
+  },
+  render: args => (
+    <Fieldset {...args}>
+      <CheckboxInput id="consent-trips" name="consent" label="Consent for school trips" onChange={() => {}} />
+      <CheckboxInput id="consent-photos" name="consent" label="Consent for photographs" onChange={() => {}} />
+      <CheckboxInput id="consent-data" name="consent" label="Consent for data sharing with partner schools" onChange={() => {}} />
+    </Fieldset>
+  ),
+};
+
+export const WithRadioButtons: Story = withDescription(
+  'Radio buttons inside a fieldset enforce single-selection. Share the same `name` attribute across all `RadioButtonInput` children — the fieldset provides the group semantics, the shared `name` enforces mutual exclusivity.',
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          code: `
+import { Fieldset, RadioButtonInput } from '@arbor-education/design-system.components';
+
+export default function ReportAccessFieldset() {
+  return (
+    <Fieldset legend="Report access level">
+      <RadioButtonInput
+        id="access-view"
+        name="access"
+        value="view"
+        label="View only — can read reports but not download"
+      />
+      <RadioButtonInput
+        id="access-download"
+        name="access"
+        value="download"
+        label="View and download — can export to PDF"
+      />
+      <RadioButtonInput
+        id="access-admin"
+        name="access"
+        value="admin"
+        label="Full admin — can view, download, and share with parents"
+      />
+    </Fieldset>
+  );
+}
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Fieldset legend="Report access level">
+        <RadioButtonInput
+          id="access-view"
+          name="access"
+          value="view"
+          label="View only — can read reports but not download"
+        />
+        <RadioButtonInput
+          id="access-download"
+          name="access"
+          value="download"
+          label="View and download — can export to PDF"
+        />
+        <RadioButtonInput
+          id="access-admin"
+          name="access"
+          value="admin"
+          label="Full admin — can view, download, and share with parents"
+        />
+      </Fieldset>
+    ),
+  },
+);
+
+export const WithFormFields: Story = withDescription(
+  'Fieldset can wrap `FormField` components to create a named section within a larger form. This is useful for logical groupings like an address block or emergency contact details where each field has its own label.',
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          code: `
+import { Fieldset, FormField } from '@arbor-education/design-system.components';
+
+export default function DietaryRequirementsFieldset() {
+  return (
+    <Fieldset legend="Dietary requirements">
+      <FormField
+        id="diet-primary"
+        label="Primary dietary requirement"
+        inputProps={{ placeholder: 'e.g. Halal, Vegetarian, Vegan' }}
+      />
+      <FormField
+        id="diet-allergies"
+        label="Allergies and intolerances"
+        fieldDescription="List all known allergens — this information is shared with the school kitchen"
+        inputProps={{ placeholder: 'e.g. Peanuts, Gluten, Dairy' }}
+      />
+    </Fieldset>
+  );
+}
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Fieldset legend="Dietary requirements">
         <FormField
-          id="first-name"
-          label="First Name"
-          inputProps={{
-            placeholder: 'Enter your first name',
-          }}
+          id="diet-primary"
+          label="Primary dietary requirement"
+          inputProps={{ placeholder: 'e.g. Halal, Vegetarian, Vegan' }}
         />
         <FormField
-          id="last-name"
-          label="Last Name"
-          inputProps={{
-            placeholder: 'Enter your last name',
-          }}
+          id="diet-allergies"
+          label="Allergies and intolerances"
+          fieldDescription="List all known allergens — this information is shared with the school kitchen"
+          inputProps={{ placeholder: 'e.g. Peanuts, Gluten, Dairy' }}
         />
-      </div>
+      </Fieldset>
     ),
   },
-};
-// Disabled fieldset
-export const Disabled: Story = {
-  args: {
-    legend: 'Disabled Fieldset',
-    disabled: true,
-    children: (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
-        <FormField
-          id="disabled-input"
-          label="Disabled Input"
-          inputProps={{
-            placeholder: 'This input is disabled',
-            disabled: true,
+);
+
+export const WithoutLegend: Story = withDescription(
+  'The `legend` prop is optional. When omitted the fieldset still provides semantic grouping, but you **must** supply either `aria-label` or `aria-labelledby` to satisfy WCAG 1.3.1. This is useful when the group label already exists as a visible heading in the page.',
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          code: `
+import { Fieldset, CheckboxInput } from '@arbor-education/design-system.components';
+
+export default function WithoutLegendFieldset() {
+  return (
+    // No legend prop — aria-labelledby points to the heading above
+    <div>
+      <h2 id="notif-heading">Notification preferences</h2>
+      <Fieldset aria-labelledby="notif-heading">
+        <CheckboxInput
+          id="notif-email"
+          name="notifications"
+          label="Email — weekly summary and urgent alerts"
+        />
+        <CheckboxInput
+          id="notif-sms"
+          name="notifications"
+          label="SMS — urgent alerts only"
+        />
+        <CheckboxInput
+          id="notif-app"
+          name="notifications"
+          label="In-app — all updates in the Arbor dashboard"
+        />
+      </Fieldset>
+    </div>
+  );
+}
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div>
+        <h2
+          id="notif-heading"
+          style={{
+            fontFamily: 'var(--type-body-font-family)',
+            fontWeight: 'var(--type-body-bold-weight)' as React.CSSProperties['fontWeight'],
+            color: 'var(--form-field-label-color-text)',
+            marginBottom: 'var(--form-field-spacing-vertical)',
+            marginTop: 0,
+            fontSize: '1rem',
           }}
+        >
+          Notification preferences
+        </h2>
+        <Fieldset aria-labelledby="notif-heading">
+          <CheckboxInput
+            id="notif-email"
+            name="notifications"
+            label="Email — weekly summary and urgent alerts"
+            onChange={() => {}}
+          />
+          <CheckboxInput
+            id="notif-sms"
+            name="notifications"
+            label="SMS — urgent alerts only"
+            onChange={() => {}}
+          />
+          <CheckboxInput
+            id="notif-app"
+            name="notifications"
+            label="In-app — all updates in the Arbor dashboard"
+            onChange={() => {}}
+          />
+        </Fieldset>
+      </div>
+    ),
+  },
+);
+
+export const WithAriaLabel: Story = withDescription(
+  'Use `aria-label` when no visible heading exists to reference via `aria-labelledby` and design requirements prevent showing a `<legend>`. The label is invisible to sighted users but fully accessible to screen readers.',
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          code: `
+import { Fieldset, CheckboxInput } from '@arbor-education/design-system.components';
+
+export default function AriaLabelFieldset() {
+  return (
+    <Fieldset aria-label="Trip consent options">
+      <CheckboxInput
+        id="trip-geography"
+        name="trip-consent"
+        label="Year 7 Geography field trip — 14 March"
+      />
+      <CheckboxInput
+        id="trip-science"
+        name="trip-consent"
+        label="Year 7 Science museum visit — 28 March"
+      />
+      <CheckboxInput
+        id="trip-drama"
+        name="trip-consent"
+        label="Year 7 Drama workshop — 4 April"
+      />
+    </Fieldset>
+  );
+}
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Fieldset aria-label="Trip consent options">
+        <CheckboxInput
+          id="trip-geography"
+          name="trip-consent"
+          label="Year 7 Geography field trip — 14 March"
+          onChange={() => {}}
+        />
+        <CheckboxInput
+          id="trip-science"
+          name="trip-consent"
+          label="Year 7 Science museum visit — 28 March"
+          onChange={() => {}}
         />
         <CheckboxInput
-          id="disabled-checkbox"
-          name="disabled"
-          value="disabled"
-          label="Disabled checkbox"
-          disabled={true}
+          id="trip-drama"
+          name="trip-consent"
+          label="Year 7 Drama workshop — 4 April"
+          onChange={() => {}}
         />
+      </Fieldset>
+    ),
+  },
+);
+
+export const Disabled: Story = withDescription(
+  'Setting `disabled` on the Fieldset is the correct semantic approach to disabling an entire group. The browser propagates the disabled state to **all descendant form controls** automatically — no need to pass `disabled` to each child individually.',
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          code: `
+import { Fieldset, RadioButtonInput } from '@arbor-education/design-system.components';
+
+export default function DisabledFieldset() {
+  return (
+    // ONE disabled prop disables all three radio buttons:
+    <Fieldset legend="Notification preferences" disabled>
+      <RadioButtonInput
+        id="notif-all"
+        name="notif-freq"
+        value="all"
+        label="All notifications"
+      />
+      <RadioButtonInput
+        id="notif-urgent"
+        name="notif-freq"
+        value="urgent"
+        label="Urgent alerts only"
+      />
+      <RadioButtonInput
+        id="notif-none"
+        name="notif-freq"
+        value="none"
+        label="No notifications"
+      />
+    </Fieldset>
+  );
+}
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Fieldset legend="Notification preferences" disabled>
         <RadioButtonInput
-          id="disabled-radio"
-          name="disabled"
-          value="disabled"
-          label="Disabled radio"
-          disabled={true}
+          id="notif-all"
+          name="notif-freq"
+          value="all"
+          label="All notifications"
         />
-      </div>
+        <RadioButtonInput
+          id="notif-urgent"
+          name="notif-freq"
+          value="urgent"
+          label="Urgent alerts only"
+        />
+        <RadioButtonInput
+          id="notif-none"
+          name="notif-freq"
+          value="none"
+          label="No notifications"
+        />
+      </Fieldset>
     ),
   },
-};
+);
+
+export const DisabledWithCheckboxes: Story = withDescription(
+  'The most visually compelling demonstration of the `disabled` prop — all checkboxes are greyed out and non-interactive with a single `disabled` on the fieldset. This is how Arbor locks consent forms during a pending approval workflow.',
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          code: `
+import { Fieldset, CheckboxInput } from '@arbor-education/design-system.components';
+
+export default function DisabledCheckboxesFieldset() {
+  return (
+    <Fieldset legend="Consent and permissions" disabled>
+      <CheckboxInput
+        id="consent-trips-dis"
+        name="consent"
+        label="Consent for school trips"
+        checked
+        onChange={() => {}}
+      />
+      <CheckboxInput
+        id="consent-photos-dis"
+        name="consent"
+        label="Consent for photographs"
+        checked
+        onChange={() => {}}
+      />
+      <CheckboxInput
+        id="consent-data-dis"
+        name="consent"
+        label="Consent for data sharing with partner schools"
+        onChange={() => {}}
+      />
+      <CheckboxInput
+        id="consent-medical-dis"
+        name="consent"
+        label="Consent to share medical information with trip supervisors"
+        onChange={() => {}}
+      />
+    </Fieldset>
+  );
+}
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Fieldset legend="Consent and permissions" disabled>
+        <CheckboxInput
+          id="consent-trips-dis"
+          name="consent"
+          label="Consent for school trips"
+          checked
+          onChange={() => {}}
+        />
+        <CheckboxInput
+          id="consent-photos-dis"
+          name="consent"
+          label="Consent for photographs"
+          checked
+          onChange={() => {}}
+        />
+        <CheckboxInput
+          id="consent-data-dis"
+          name="consent"
+          label="Consent for data sharing with partner schools"
+          onChange={() => {}}
+        />
+        <CheckboxInput
+          id="consent-medical-dis"
+          name="consent"
+          label="Consent to share medical information with trip supervisors"
+          onChange={() => {}}
+        />
+      </Fieldset>
+    ),
+  },
+);
+
+export const DisabledWithRadioButtons: Story = withDescription(
+  'Radio buttons inside a disabled fieldset are also non-interactive. Use this pattern when the selection has been locked — for example, after a parent has submitted a form that is now awaiting school staff approval.',
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          code: `
+import { Fieldset, RadioButtonInput } from '@arbor-education/design-system.components';
+
+export default function DisabledRadioFieldset() {
+  return (
+    <Fieldset legend="Dietary requirements" disabled>
+      <RadioButtonInput
+        id="diet-halal-dis"
+        name="diet"
+        value="halal"
+        label="Halal"
+        defaultChecked
+      />
+      <RadioButtonInput
+        id="diet-vegetarian-dis"
+        name="diet"
+        value="vegetarian"
+        label="Vegetarian"
+      />
+      <RadioButtonInput
+        id="diet-vegan-dis"
+        name="diet"
+        value="vegan"
+        label="Vegan"
+      />
+      <RadioButtonInput
+        id="diet-none-dis"
+        name="diet"
+        value="none"
+        label="No specific requirement"
+      />
+    </Fieldset>
+  );
+}
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Fieldset legend="Dietary requirements" disabled>
+        <RadioButtonInput
+          id="diet-halal-dis"
+          name="diet"
+          value="halal"
+          label="Halal"
+          defaultChecked
+        />
+        <RadioButtonInput
+          id="diet-vegetarian-dis"
+          name="diet"
+          value="vegetarian"
+          label="Vegetarian"
+        />
+        <RadioButtonInput
+          id="diet-vegan-dis"
+          name="diet"
+          value="vegan"
+          label="Vegan"
+        />
+        <RadioButtonInput
+          id="diet-none-dis"
+          name="diet"
+          value="none"
+          label="No specific requirement"
+        />
+      </Fieldset>
+    ),
+  },
+);