From 648f1afcfd0912bcbd0d11ece2c8f2a5d99b1647 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 18 May 2026 14:58:26 +0000 Subject: [PATCH] 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 | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) 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)