From b0ea3144e1a53fec8e2312340f86c096f6b41fa4 Mon Sep 17 00:00:00 2001
From: Richie <richie.phillips@proton.me>
Date: Wed, 25 Mar 2026 19:55:12 +1100
Subject: [PATCH] Fix P2 accessibility issues across atom components
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Input: Record<string, any> → Theme type for boxShadow theme accessor
- Button: Document aria-label requirement for icon-only usage
- Badge: Document aria-label requirement for icon-only badges
- Switch: Strengthen a11y docs — always wrap in FormControlLabel with example
- Radio: Strengthen a11y docs — always use RadioGroup + FormControlLabel with example
- Chip: Document aria-label requirement for icon-only deletable chips

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/components/atoms/Badge/Badge.tsx   |  3 +++
 src/components/atoms/Button/Button.tsx |  4 ++++
 src/components/atoms/Chip/Chip.tsx     |  4 ++++
 src/components/atoms/Input/Input.tsx   |  3 ++-
 src/components/atoms/Radio/Radio.tsx   | 13 +++++++++++--
 src/components/atoms/Switch/Switch.tsx |  8 +++++++-
 6 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/src/components/atoms/Badge/Badge.tsx b/src/components/atoms/Badge/Badge.tsx
index 7273a64..b385403 100644
--- a/src/components/atoms/Badge/Badge.tsx
+++ b/src/components/atoms/Badge/Badge.tsx
@@ -77,6 +77,9 @@ const softColors: Record<BadgeColor, (t: Theme) => { bg: string; text: string }>
  * Variant options:
  * - `soft` (default) — tonal background, coloured text. Calmer, preferred for FA.
  * - `filled` — solid background, white text. For high-priority emphasis.
+ *
+ * **Accessibility**: If a Badge contains only an icon (no text children),
+ * provide an `aria-label` prop so screen readers can announce the status.
  */
 export const Badge = React.forwardRef<HTMLDivElement, BadgeProps>(
   (
diff --git a/src/components/atoms/Button/Button.tsx b/src/components/atoms/Button/Button.tsx
index a0e3418..6612963 100644
--- a/src/components/atoms/Button/Button.tsx
+++ b/src/components/atoms/Button/Button.tsx
@@ -29,6 +29,10 @@ export interface ButtonProps extends MuiButtonProps {
  * - `outlined` + `secondary` — Outlined grey (neutral border)
  * - `text` + `primary` — Ghost / text button (copper text)
  * - `text` + `secondary` — Ghost secondary (grey text)
+ *
+ * **Accessibility**: Icon-only buttons (no visible text) require an
+ * `aria-label` prop. Without it, screen readers announce nothing.
+ * Example: `<Button startIcon={<DeleteIcon />} aria-label="Delete item" />`
  */
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
   (
diff --git a/src/components/atoms/Chip/Chip.tsx b/src/components/atoms/Chip/Chip.tsx
index 12b8aec..a644f82 100644
--- a/src/components/atoms/Chip/Chip.tsx
+++ b/src/components/atoms/Chip/Chip.tsx
@@ -38,6 +38,10 @@ export interface ChipProps extends MuiChipProps {
  *
  * Selected state:
  * - `selected` prop applies brand styling (filled primary bg or outlined primary border)
+ *
+ * **Accessibility**: If a Chip has no visible label text (icon-only) and is
+ * deletable, provide an `aria-label` so screen readers can announce what
+ * is being removed.
  */
 export const Chip = React.forwardRef<HTMLDivElement, ChipProps>(
   (
diff --git a/src/components/atoms/Input/Input.tsx b/src/components/atoms/Input/Input.tsx
index b956685..ed6ae76 100644
--- a/src/components/atoms/Input/Input.tsx
+++ b/src/components/atoms/Input/Input.tsx
@@ -5,6 +5,7 @@ import OutlinedInput from '@mui/material/OutlinedInput';
 import type { OutlinedInputProps } from '@mui/material/OutlinedInput';
 import FormHelperText from '@mui/material/FormHelperText';
 import InputAdornment from '@mui/material/InputAdornment';
+import type { Theme } from '@mui/material/styles';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -140,7 +141,7 @@ export const Input = React.forwardRef<HTMLDivElement, InputProps>(
                 borderColor: 'success.main',
               },
               '&.Mui-focused': {
-                boxShadow: (theme: Record<string, any>) =>
+                boxShadow: (theme: Theme) =>
                   `0 0 0 3px ${theme.palette.common.white}, 0 0 0 5px ${theme.palette.success.main}`,
               },
             },
diff --git a/src/components/atoms/Radio/Radio.tsx b/src/components/atoms/Radio/Radio.tsx
index 63f313f..656f4b6 100644
--- a/src/components/atoms/Radio/Radio.tsx
+++ b/src/components/atoms/Radio/Radio.tsx
@@ -18,10 +18,19 @@ export interface RadioProps extends MuiRadioProps {}
  * From Parsons 1.0 Figma radio component — 16px circle with brand dot.
  *
  * Usage:
- * - Always use inside a RadioGroup for proper keyboard navigation
- * - Pair with FormControlLabel for accessible labels
  * - For binary on/off, use Switch instead
  * - For multi-select, use Checkbox (planned) or Chip
+ *
+ * **Accessibility**: Always use inside a `RadioGroup` and wrap each Radio
+ * in `FormControlLabel`. A standalone Radio without a label or group is
+ * inaccessible — screen readers cannot announce the option or allow
+ * keyboard arrow-key navigation between options.
+ * ```tsx
+ * <RadioGroup value={value} onChange={handleChange}>
+ *   <FormControlLabel value="burial" control={<Radio />} label="Burial" />
+ *   <FormControlLabel value="cremation" control={<Radio />} label="Cremation" />
+ * </RadioGroup>
+ * ```
  */
 export const Radio = React.forwardRef<HTMLButtonElement, RadioProps>(
   (props, ref) => {
diff --git a/src/components/atoms/Switch/Switch.tsx b/src/components/atoms/Switch/Switch.tsx
index 5d673d9..7bcf0ec 100644
--- a/src/components/atoms/Switch/Switch.tsx
+++ b/src/components/atoms/Switch/Switch.tsx
@@ -20,8 +20,14 @@ export interface SwitchProps extends MuiSwitchProps {}
  *
  * Usage:
  * - Use for boolean settings ("Include catering", "Add memorial video")
- * - Pair with a label via FormControlLabel for accessibility
  * - For mutually exclusive options, use Radio instead
+ *
+ * **Accessibility**: Always wrap in `FormControlLabel` with a `label` prop.
+ * A standalone Switch without a visible label is inaccessible — screen
+ * readers cannot announce what the toggle controls.
+ * ```tsx
+ * <FormControlLabel control={<Switch />} label="Include catering" />
+ * ```
  */
 export const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(
   (props, ref) => {