Lesson 9: Accessibility as a system contract

Lesson 9: Accessibility as a system contract

ctoi

Oct 23

∙

Preview

What you’ll be able to do

Put accessibility where it can only be done once: inside the shared primitives, written down as a contract, and checked by a gate that renders every story and every app page in a real browser. You’ll know you’ve got this when you delete one line from FormField, press Run gate, and watch fourteen targets across Storybook and the Control Tower turn red, with the exact rule named, without writing a single line of app code.

The concept

Think of a building’s fire code. Nobody asks each tenant to remember to install sprinklers; the building has them, an inspector checks them against a written code, and every tenant who moves in is covered without lifting a finger. Accessibility at scale works the same way: the primitive owns the promise (a label wired to its input, a focus ring on Tab), A11Y_CONTRACT is the written code, and pnpm a11y is the inspector that checks real rendered pages, not source files. See the picture: lesson-09-design-diagram.svg. The point is where the fix lives. If a promise breaks, it breaks in one file, and the gate shows you every consumer it reached.

The visual deliverable

A new Accessibility panel, second on the Control Tower, drawn from the gate’s real report: six fact cards, every primitive rendered live with its contract checked in the page, a pass or fail cell for each of 29 targets in light and dark, and the exact axe and contract findings for any cell you click. A Run gate button runs the same gate CI runs, and the panel turns red or green without a reload.

Continue reading this post for free in the Substack app

© 2026 ctoi
548 Market Street PMB 72296, San Francisco, CA 94104