Design tokens

Where we started

When I joined the Alchemy team, the system already had a set of variables in place—but they were rigid, difficult to reason about, and inconsistent across design and code.

Engineers frequently had to ask how values were intended to be combined. Documentation described individual variables, but not the structure or decision model behind them. There was no shared taxonomy tying Figma styles to their coded counterparts.

The CTI format we were using provided a way to store values, but without hierarchy or intent. Tokens existed as isolated definitions rather than a coherent system.

Who felt the pain

Engineers felt the breakdown most acutely. At the time, Figma relied on styles (pre-Variables), and naming conventions often differed between design files and code.

When engineers received a Figma file for reference, they were frequently forced to interpret intent—mapping visual styles to coded variables through assumption rather than clarity. This led to velocity churn, rework, and, in some cases, issues that shipped incorrectly.

In an organization where technical and design debt was rarely paid down, these problems compounded over time instead of being corrected at the source.

The turning point

During our 2023 planning cycle, the team made a deliberate decision to pause feature expansion and focus on foundational cleanup and enhancement.

The lead Front-End Engineer and I wanted to evaluate the system holistically rather than continue layering improvements onto a strained foundation. Design tokens were emerging as a best practice, but more importantly, they offered a way to address the core issue: the lack of a shared, enforceable structure that could scale across teams.

Ownership and authorship

I led the definition of the design token taxonomy and hierarchy end-to-end. This included extensive research into industry best practices and comparative systems.

Given the similarities in scale and product complexity, I used Intuit’s CTI model as a foundational reference and arranged working sessions with Intuit’s design system leadership to better understand their decisions, tradeoffs, and long-term maintenance approach.

I defined Alchemy’s taxonomy and naming conventions, created the master token spreadsheet the team aligned around, and implemented the resulting variables directly into the Figma libraries—establishing a shared foundation for both design and engineering.

Design principles

The token system was guided by a few core principles.

• Predictability over exhaustiveness. We focused on a selective set of primitives rather than attempting to encode every possible scenario.
• Flexibility without ambiguity. Tokens needed to communicate intent clearly while supporting multiple themes and contexts.
• Parity across design and code. The same structure, language, and hierarchy had to exist in both environments.

Why we didn’t choose fully semantic tokens

Given the breadth of Alchemy’s customer base, a fully semantic-only model would not have scaled. Teams varied widely in audience, workflow complexity, and UI needs.

Instead, we adopted a progressive taxonomy that moves from general to specific:

Theme → Type → Attribute → Purpose → Prominence / Size / Speed → State

This structure allowed teams to reuse shared foundations while supporting granular, contextual application without fragmenting the system.

What changed

We saw immediate benefits with pilot customers across both design and engineering. Collaboration became more deliberate and less interpretive.

With clear parity between Figma and code, teams moved faster and with greater confidence. Conversations shifted away from “what does this map to?” toward fit, finish, and quality.

Tradeoffs and maturity

This work required significant upfront investment and multiple rounds of iteration. Establishing a shared taxonomy and enforcing naming discipline introduced structure that required alignment and care.

We made that tradeoff intentionally. The result was a system that was easier to reason about, safer to extend, and resilient as the organization continued to grow.

Reflection

This work reinforced my belief that design systems are less about enforcing consistency, and more about creating shared foundations that let teams move faster without losing cohesion.