web-starter
A dyslexia-first design system with a contrast gate that fails the build. This site is the running artifact.
The constraint
The design system stopped at the page level. Below that, every screen was bespoke.
I am dyslexic, and the previous app I shipped had a specific, observed failure.
It had a good token palette and a set of layout components. Header, section, card, badge, callout. It had no interactive components at all.
So every form hand-rolled its own control styling as local string constants. The largest editor screen reached 797 lines.
The decision
Two rules, and they are the whole template.
A design system that stops before its controls is not a design system. So controls live in one file, and a page that needs four utility classes to build something card-shaped is missing a variant.
The colour and type layers are tokenised and gated. Otherwise they drift back to ad-hoc values the first time someone is in a hurry.
The gate is a script that parses the stylesheet's token block rather than carrying its own copy of any colour value. It then asserts every text pair the app actually renders against WCAG 2.1.
It has already caught a failure that looked fine by eye. A control-boundary token drafted at 2.14:1, which fails WCAG 1.4.11 for anything that is the sole indicator of a control's edge.
It runs in the same command as typecheck and lint. A colour change that breaks contrast cannot be committed.
The first option I rejected: shipping a purpose-built dyslexia typeface as the default
It is the obvious move and the evidence does not support it.
Eye-tracking work by Rello and Baeza-Yates (2013) found OpenDyslexic improved neither reading speed nor measured readability against plain faces. Kuster and colleagues (2018) found the same for Dyslexie against Arial, and what benefit did appear traced to spacing rather than letterforms.
So the template fixes the things with evidence behind them. Letter spacing, line height, measure, left alignment, an off-white page, sentence case, bold instead of italic.
The typeface is a runtime switch the reader controls. The controls at the bottom of this page are that decision.
The second option I rejected: importing a whole design language
Two design systems in one codebase, and a gate that can only police one of them.
Bootstrap-style kits and off-the-shelf component libraries were considered and dropped. They bring a second class system, a second token system and somebody else's brand identity.
Evidence
This site is the running artifact. It uses the framework unchanged, including the gate. The repository is private for now.