Insights.
Notes on UX engineering, design systems, and shipping the gap between Figma and production.
Notes on UX engineering, design systems, and shipping the gap between Figma and production.
Engineering · 6 min read
Close ✕Feb 2025
Most teams discover design tokens when they're tired of searching for the right hex code. They set up a token file, link it to Figma, and declare design-engineering alignment. Then, six months later, the tokens file has 200 entries and nobody agrees on which one to use for "that grey."
The problem isn't the tokens. It's the mental model behind them.
A variable is a placeholder for a value. A contract is an agreement about intent.
When you name a token color-gray-500, you've created a variable. When you name it color-text-secondary, you've made a contract: "this value will always represent secondary text, across every component, in every context."
"Breaking a token name is breaking a promise. That promise is: any component using this token will behave the same way, everywhere."
Good token systems work in layers:
blue-500: #3B82F6. Never used directly in components.color-action-primary: {blue-500}. Used in components.button-bg: {color-action-primary}. Optional, for complex systems.Most teams build the first layer and skip the second. Then they wonder why changing "the brand blue" breaks seventeen things they didn't expect.
The real shift happens when designers and engineers agree that the token name is the spec. Not the hex value — the name. If a component uses color-text-danger, the engineer doesn't need to ask what colour it should be in dark mode. The token contract covers it.
This only works when both sides honour the contract. Designers can't add new hex values that bypass the token system. Engineers can't hardcode colours because the token "doesn't feel right." If either side breaks the contract, the system degrades into chaos.
The best enforcement is automation. Lint rules that flag hardcoded colours. Figma plugins that warn when a design uses an out-of-system value. Storybook addons that surface token usage per component.
None of this requires a design systems team. It requires someone who cares enough to set it up once. That's often the UX Engineer.