Learning Track
Filter content by your role to see the most relevant sections
Accessibility as System Infrastructure
Treat accessibility as infrastructure the system earns, not a checklist it passes: constraints encoded in tokens and contracts, verified by validators at build time, and sustained by an architecture where the accessible path is the default path.
Why This Matters
The industry's default model of accessibility is the audit: build the product, then run the checklist, then fix what it finds. The model fails predictably because it makes accessibility a terminal process on a system whose every earlier decision already settled the outcome. You cannot audit your way to accessible products any more than you can inspect quality into manufactured goods—the capability has to be built into the process that produces them.
The system's model is different in one specific way: accessibility constraints are encoded where the decisions are made. Contrast floors live in the token validator, so a failing pair cannot merge. Touch-target minimums live in the dimension tokens, so a cramped control is a token-layer question. Focus, semantics, and naming live in the component contracts, so a component that ships without them is visibly incomplete. Reduced motion lives in the motion system, so opting out is honored by CSS and script from the same signal.
This page is the track's map. The five pages behind it cover the standards that define the constraints, the token-level encoding, the assistive technologies the constraints serve, the tooling that verifies them, and the philosophy that keeps all of it honest when deadlines argue.
Core Concepts: The Track in Five Moves
1. The Standards Are the Source of Constraints
WCAG 2.1 is the normative floor: perceivable, operable, understandable, robust. Its numeric thresholds—the 4.5:1 and 3:1 contrast ratios, the 44px target guidance, the 320px reflow requirement, the animation-from-interactions criteria—are the derived values this system's tokens encode. Standards-first means every constraint in the system can name its citation, which is what makes it non-negotiable in review. (/blueprints/foundations/accessibility/standards)
2. Tokens Are Where Constraints Get Teeth
A constraint in a document is guidance; a constraint in a token is a default. The tap-target floor as dimension.tapTargetMin, contrast pairs as validator-enforced role combinations, motion safety as the reduced-motion contract, legibility spacing as scale minimums—each encoding moves the constraint from "remembered" to "structural." (/blueprints/foundations/accessibility/tokens)
3. Assistive Technology Defines the Real Interface
Screen readers, keyboard-only navigation, switch access, voice control, magnification—these are consumers of the system's semantics, and their expectations are the actual contract. Meaningful-or-decorative for icons, DOM order equal to reading order, names on every control: the rules come from how AT consumes the tree, not from what looks organized. (/blueprints/foundations/accessibility/assistive-tech)
4. Tooling Makes Verification Continuous
jsx-a11y catches static markup sins at lint speed; axe-core audits rendered output in the component tests; the token validator checks numeric claims at build; Playwright walks real keyboard paths. Four layers, each cheaper than the incident it prevents. (/blueprints/foundations/accessibility/tooling)
5. Philosophy Keeps It Honest Under Pressure
Every accessibility practice fails at the same moment: the deadline. The philosophy page is the argument that survives that moment—accessibility as a design constraint that improves the product for everyone, and as a fairness obligation that does not scale down with the timeline. (/blueprints/foundations/accessibility/philosophy)
The Infrastructure Test
One question summarizes the track: when this system is used lazily, does accessibility still hold? A component author who references only tokens, ships the contract's slots and bindings, and passes the checks has produced accessible output—without having thought about accessibility at all. That is infrastructure: the good path is the path of least resistance. Every page in this track is about moving one more constraint across that line.
System Roles: Accessibility Across the Layers
Design Impact
Designers inherit the constraints as creative material: the floors are fixed, and the design work happens in the space they guarantee. The track's pages repeatedly show the same reversal—constraints adopted early become affordances, not restrictions.
Engineering Impact
Engineers inherit the encoding: the validators, the contract fields, the test layers. The obligation is maintenance—when a check rots or a contract field goes unused, the infrastructure claim quietly becomes false.
Governance Impact
Governance inherits the arbitration: when a derived constraint conflicts with a chosen preference, derived wins. That single rule, applied consistently, is most of what "accessibility governance" means in a tokenized system.
Design & Code Interplay
On the design side, the infrastructure shows up as defaults that are already accessible: palettes whose ramps bracket the thresholds, size scales that respect targets, contrast plugins sharing the validator's math. The designer experiences accessibility less as a review stage and more as the shape of the material.
On the code side, the same constraints as checks a lazy implementation cannot skip:
// Token layer: the floor is data
--core-dimension-tap-target-min: 44px;
// Contract layer: semantics are fields, not best wishes
"a11y": { "role": "img", "labeling": ["aria-label"], "keyboard": [] }
// Lint layer: static sins fail fast
'jsx-a11y/alt-text': 'error'
// Test layer: rendered output audited (axe, wcag2a/wcag2aa)
// Build layer: pair ratios validated from token sources
// The lazy path — consume tokens, fill the contract, pass checks —
// is the accessible path. That is the entire engineering argument.Applied Example: Following One Constraint Through the System
Take a single constraint—body text contrast—and watch it ride the whole architecture:
- Standard: WCAG 2.1 SC 1.4.3, 4.5:1 for normal text—cited, not asserted.
- Ramp: the Adaptive-DS-Colors keying places
500at ≈4.9:1 on white, so the "which step for text" question is answered by the scale itself. - Role:
foreground.primary/secondaryresolve per mode—the pair is checkable, not vibes. - Validator:
WCAG_LEVELS+validateColorPairwalk the declared pairs per mode at build time. - Test: axe's
color-contrastrule audits the rendered components in vitest. - Outcome: a product engineer who never read SC 1.4.3 ships text that passes it—because every layer below them already did the work.
Six layers, one constraint, zero heroics. Multiply by the constraint set and you have this track's thesis in miniature.
Constraints & Trade-offs
- Infrastructure vs audit: encoding costs engineering time now and pays on every change forever; auditing costs less now and compounds silently. Systems that cannot fund the encoding should at least fund the tracking of the debt honestly.
- Floors vs flexibility: hard minimums remove options (no 28px targets, ever) and buy the "lazy path is safe" property. The escape hatches that exist (visual size vs hit area) are designed, not discovered.
- Standards vintage: WCAG 2.1 is the enforceable floor; 2.2 and APCA are directions. Encoding 2.1 tightly while leaving room for the validators to learn new math is the posture this system takes.
Common Pitfalls & Failure Modes
1. The audit as a stage
Late audits find late problems at late prices. The fix is not better audits but earlier encoding—every finding is a constraint looking for its token, contract, or check.
2. Passing checks, failing users
Automation covers the computable subset (contrast, names, tree structure); it cannot cover comprehension, task flow, or real screen reader behavior. Manual AT passes remain load-bearing—the tooling page covers the split.
3. Accessibility as one person's job
A specialist without structural authority becomes a bottleneck of rubber stamps. The infrastructure model distributes the work into the layers everyone already touches.
4. Retrofitting under deadline
The classic death spiral: skip the constraints, miss the audit, promise to fix later. Later has the same deadline pressure plus rework. The track exists to make the cheap-early path visible.
Verification Checklist
Additional Resources
- The track — standards, tokens, assistive-tech, tooling, and philosophy pages under
/blueprints/foundations/accessibility/ - WCAG 2.1 — the normative source (
https://www.w3.org/TR/WCAG21/) - Color Foundations — the contrast ledger this track's token page builds on (
/blueprints/foundations/color)
Related Concepts
Reflection Questions
Apply This Concept
Pick one accessibility failure you have shipped or witnessed. Which layer—token, contract, check, or culture—should have caught it, and what would the encoding look like?
Reflect
The infrastructure test asks whether lazy use of the system is still accessible. Where does your current system fail that test most often, and what does the failure pattern have in common?
