Add legibility analysis section to Claude Design guide

Documents every colour pairing to check, WCAG contrast targets for each
role, and common failure modes (saturated accents, muted text on tinted
backgrounds, dark-mode text-muted). Checklist expanded with contrast items.

https://claude.ai/code/session_01NQKywehSj8Ku4yKhwB4VNB

docs/claude-design.md

@@ -214,12 +214,53 @@ uses its own per-callout colour settings rather than the semantic variables.
 
 ---
 
+## Legibility analysis
+
+Before finalising any theme — and especially when refactoring an existing one —
+work through every colour pairing in the design and check that text is
+readable against its background.
+
+**Pairs to check:**
+
+| Text | Background |
+|---|---|
+| `text` | `background` |
+| `text-muted` | `background` |
+| `nav-link` | `nav-background` |
+| `nav-link-active` | `nav-background` |
+| `nav-section-heading` | `nav-background` |
+| `nav-sitename` | `nav-background` |
+| `nav-description` | `nav-background` |
+| `nav-toggle` | `nav-background` |
+| `accent` | `background` (used for inline links in content) |
+| `colours-semantic.*` | `background` (callout borders and tinted backgrounds) |
+| `colours-semantic-dark.*` | dark `background` |
+
+**WCAG contrast targets:**
+- Body text (`text`) on `background`: aim for **7:1** (AAA). Never go below 4.5:1 (AA).
+- Secondary text (`text-muted`, `nav-section-heading`, `nav-description`): minimum **3:1**, aim for 4.5:1.
+- Nav links and site name: minimum **4.5:1** against `nav-background`.
+- Active/hover states: minimum **3:1** (they are reinforced by other visual cues).
+
+**Common failure modes to look for:**
+- A saturated accent on a white background can be vibrant but low-contrast — reds and oranges are frequent offenders.
+- `text-muted` on a tinted or coloured background often falls below 3:1.
+- Dark-mode `text-muted` on a near-black background is easy to get wrong when porting from a light-mode palette.
+- `nav-description` and `nav-toggle` are small and low-weight, so they need more contrast than the minimum to feel comfortable — lean toward the higher targets for these.
+
+When a pairing is marginal, adjust the lighter or darker of the two values by enough to clear the target. Do not simply accept values that are close to failing.
+
+---
+
 ## Checklist before finalising a theme
 
 - [ ] All six nav colour keys (`nav-link`, `nav-link-active`, `nav-section-heading`,
       `nav-sitename`, `nav-description`, `nav-toggle`) set for both `light` and
       `dark` whenever `nav-background` is non-neutral
-- [ ] All nav colours contrast against `nav-background` (WCAG AA minimum)
+- [ ] All nav colours contrast against `nav-background` (WCAG AA minimum; see Legibility analysis above)
+- [ ] `text` on `background` meets 7:1 (AAA); never below 4.5:1
+- [ ] `text-muted` and header element colours meet at least 3:1; aim for 4.5:1
+- [ ] `accent` on `background` meets 4.5:1 (used for inline links)
 - [ ] `colours-semantic-dark` provided with lighter variants of each colour
 - [ ] `callouts` `primary-colour` matches `colours-semantic` values for consistency
 - [ ] `divider` omitted unless the auto-derived value looks wrong (check hr and table borders)