Projects

The constraint. 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 — and no interactive components at all. So every form hand-rolled its own control styling as local string constants, and the largest editor screen reached 797 lines. The design system stopped at the page level; below that line every screen was bespoke.

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. And the colour and type layers are tokenised and gated, because 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, 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, so 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 — and makes the typeface 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. 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, which means two design systems in one codebase and a gate that can only police one of them.

Evidence. This site is the running artifact — it uses the framework unchanged, including the gate. The repository is private for now.