DESIGN.md overstates two contrast floors #61

New Issue

2026-07-28T08:56:48Z

archvillainette commented

2026-07-28 08:56:48 +00:00

Found while resolving wayfinder research ticket #50 (contrast headroom). Filed separately because it is a documentation correction, not a design decision.

Problem

DESIGN.md states two values as being at the AA floor. Both are comfortably above it, and measured ratios prove it:

DESIGN.md:205 — "Placeholders are Ash Text at 74% alpha (the floor that keeps 4.5:1 contrast)." The actual 4.5:1 edge, with the alpha flattened over the real input well, is α ≈ 0.659. The shipped 0.74 measures 5.38:1 — roughly 8 alpha points of slack, not zero.
DESIGN.md:222 — "Ash Text (#b9b2a6) on Crypt Black is the floor." That pairing measures 9.19:1, which is AAA with room to spare. The real floor for body copy is a good deal darker than Ash Text.

Why it matters

These are not harmless roundings. DESIGN.md is the document a designer or agent reads before touching colour, and it is currently telling them there is no slack in two places that have plenty — while the places that genuinely have none are undocumented. The palette re-tune planned in #47 will read this file and make worse decisions because of it.

Specifically: Plum Noir #351E28 is very close to the real body-copy ceiling (L=0.0184 against a limit of L=0.0245), so a future "lighten the panels a touch" pass costs a text token immediately. That is the constraint worth documenting, and it is not in the file.

Fix

Correct both figures. Note the real ceiling on surface lightness while the file is open. The measured tables are in the resolution comment on #50 and in docs/research/palette-contrast-headroom.md on branch research/palette-contrast-headroom.

Caveat to carry across: these are WCAG 2.x conformance numbers, which are harsh on light-on-dark. Anything under about 5:1 still deserves a look in a browser before it ships.

Found while resolving wayfinder research ticket #50 (contrast headroom). Filed separately because it is a documentation correction, not a design decision. ## Problem `DESIGN.md` states two values as being at the AA floor. Both are comfortably above it, and measured ratios prove it: 1. **`DESIGN.md:205`** — "Placeholders are Ash Text at 74% alpha (the floor that keeps 4.5:1 contrast)." The actual 4.5:1 edge, with the alpha flattened over the real input well, is **α ≈ 0.659**. The shipped 0.74 measures **5.38:1** — roughly 8 alpha points of slack, not zero. 2. **`DESIGN.md:222`** — "Ash Text (#b9b2a6) on Crypt Black is the floor." That pairing measures **9.19:1**, which is AAA with room to spare. The real floor for body copy is a good deal darker than Ash Text. ## Why it matters These are not harmless roundings. `DESIGN.md` is the document a designer or agent reads before touching colour, and it is currently telling them there is no slack in two places that have plenty — while the places that genuinely have none are undocumented. The palette re-tune planned in #47 will read this file and make worse decisions because of it. Specifically: Plum Noir `#351E28` is very close to the real body-copy ceiling (`L=0.0184` against a limit of `L=0.0245`), so a future "lighten the panels a touch" pass costs a text token immediately. That is the constraint worth documenting, and it is not in the file. ## Fix Correct both figures. Note the real ceiling on surface lightness while the file is open. The measured tables are in the resolution comment on #50 and in `docs/research/palette-contrast-headroom.md` on branch `research/palette-contrast-headroom`. Caveat to carry across: these are WCAG 2.x conformance numbers, which are harsh on light-on-dark. Anything under about 5:1 still deserves a look in a browser before it ships.

archvillainette added the needs-triage label 2026-07-28 08:56:48 +00:00

archvillainette removed the needs-triage label 2026-07-31 16:04:09 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: ShadowsOverWestgate/sow-nodebb-theme#61