diff --git a/docs/claude-design.md b/docs/claude-design.md
index 375eb6e..bd07f1a 100644
--- a/docs/claude-design.md
+++ b/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)