Learning design tokens one level at a time.

Design tokens are table stakes for any serious design system, but the W3C format is hard to internalize from the source material. The spec is precise by necessity: $value, $type, group inheritance, aliases, composite types. That precision makes it a good reference but hard to learn from: after reading it, you know the terms but not how to apply them.

In the game, you learn aliases by using one to clear a sector. Each rule is a sector you can't pass until your code applies it, the fixed sequence gives you a path, and pass-or-fail results tell you what to fix. By the end, you have written spec-correct tokens yourself.

Token Adventure looks like a deep-space arcade cabinet. You select sectors from a star chart, clear waves, log intel to a pilot log, and rank up from Recruit to Ace. Under that presentation, every sector is a small coding exercise. The preview shows your code running, and a pass means your tokens meet the spec.

Grading the exercises means inspecting code that runs in an isolated sandbox the host page can't reach directly. The solution is a fully serializable assertion DSL: every check is a plain data object, so it crosses the postMessage boundary into the sandbox, runs there against the live DOM and parsed token tree, and returns a plain result.

The design-token checks follow the spec's rules instead of matching text. tokenAliasResolves doesn’t look for the string {color.brand.primary} in your file. It follows the reference chain the way a translation tool would and checks the resolved value, so players can't pass by pattern-matching.

The final sector is a broken tokens.json file with four realistic 2025.10 violations, and the player has to find and fix all four. It is the closest the game gets to real design system work.

Twenty sectors are grouped into three arcs, in the order the spec has to be learned: foundations first, then aliases and composite types, then build, theming, migration, and audit work. You can’t reason about aliases until you can name a single token, and you can’t audit a broken library until you understand the types it’s supposed to honor.

Token Adventure builds accessibility into the game and also teaches it. In the game itself, every motion effect becomes static under prefers-reduced-motion, and the celebration interstitial is a real dialog with focus management, Escape and backdrop dismissal, and a scroll lock.

In the lessons, several sectors grade the player’s rendered output with axe, contrast, and keyboardReachable assertions, holding the player to the same WCAG AA ratios and axe-core rules the app holds itself to. You learn to ship tokens that produce accessible interfaces.

The arcade is built entirely from CSS and the Web Animations API, with no game loop and no canvas. The constraint was deliberate: keep the bundle small and the Core Web Vitals clean while still feeling like an arcade game. Difficulty is color-coded throughout, cyan for beginner, yellow for intermediate, and magenta for expert, so color always signals which arc you are in.

The game is built on the same kind of token system it teaches: three tiers, with light, dark, and high-contrast modes, matching the architecture in sector 9.

Because the refresh was motion-heavy, I built a precision feedback loop instead of eyeballing changes: a headless-Chrome screenshot harness captures every key screen at desktop and mobile for before-and-after diffing, and a ?nomotion escape hatch freezes the reveal animations so full-page captures show the settled layout. I also held the source to zero em-dashes and en-dashes anywhere, verified by grep, and shipped only after astro check and a clean build pass.