The quiet rebuild of Relay's design system
Six months of token architecture, fourteen breaking changes, and one very patient beta community.
I spent most of last November staring at a spreadsheet with 847 rows. Each row was a color value that had drifted from its source of truth somewhere between the design file, the component library, and the iOS app. Four designers, two platform engineers, and I had been tasked with a deceptively simple mandate: make the design tokens consistent everywhere. The spreadsheet proved otherwise.
The three-tier token architecture
We settled on a three-tier token structure: primitive tokens for raw color values, semantic tokens for meaning (--bg-surface-primary), and component tokens for application (--button-bg-default). Each tier referenced only the tier above it. Changing one primitive cascaded through every component that used it, with every relationship explicit, traceable, and enforced by the build step.
The hardest part wasn't the architecture. It was convincing six product teams to stop hardcoding hex values in their components. We wrote a lint rule that blocked any color literal not wrapped in var(--...), then spent the next week cleaning up the backlog together.