Why I start every project with tokens, not components
By Adrian Vasquez · · 8 min read
Components encode decisions. Tokens encode intent. Getting intent right first makes the component layer boring — which is the goal.
Components are the wrong first artefact
Every system I have inherited that began with a Button ended up with eleven buttons. A component is a frozen decision; if the underlying intent was never named, each new context forks the component rather than reusing it.
So the first week of a system project produces no components at all. It produces a token set: colour roles, spacing steps, radii, elevation, type scale, and motion durations — each with a name that describes purpose, not appearance.
Name the role, never the value
`--surface-raised` survives a rebrand; `--grey-100` does not. Semantic naming is also what makes dark mode a two-hour job instead of a two-sprint migration: the roles stay, the values swap, and no component file changes.
The rule teams actually feel is simple — components may only read tokens. A raw hex value in a component is a review blocker, enforced by a lint rule so it never becomes a debate.
Make correctness measurable
Contrast pairs are tested in CI. Any foreground/background token combination the system permits must clear WCAG AA, and the build fails if a new value breaks it. That single test removed the most common accessibility regression at Helio Health.
Three teams adopted the library because migration was mechanical and the payoff was immediate: 70% fewer UI defects, and accessibility fixes shipped once instead of four times.
