A fintech startup we worked with had a Figma file with 400+ hardcoded hex color values. No token system. No semantic naming. Designers set colors manually. Developers copied hex codes. Every update was manual work.
In 7 days, we transformed it. One token system. Primitives, semantic, and component layers. Automated export to npm. Clean handoff to a codebase that actually uses the tokens. Here's exactly how we did it, and what the team got on day 7.
What "Chaotic Figma" Looks Like
Before we started, the symptoms were obvious:
- Color named "Rectangle 4 Color" with value #2A3E5C
- Same color used in 8 different places with 8 different names
- Spacing values hardcoded as 8px, 16px, 24px with no pattern
- Typography using manual font sizes instead of a scale
- No way to update the primary color in one place
- Developers copying hex codes into CSS files by hand
- QA finding "color drift" where a button doesn't match the design
The problem cascaded. Designers couldn't change colors easily. Developers had to ask "what's the right color?" Consistency eroded. Every new feature took longer.
Day 1-2: The Audit
We spent day 1 and 2 analyzing, not building.
Question 1: How many unique colors actually exist? Sounds simple. Answer: 47 unique hex values, but 200+ color components because they were copied and renamed.
Question 2: Which colors appear in which layers? We built a map. Light mode primary button background: #A8FF57. Dark mode: #2A3E5C. Same color used for text emphasis. Same color used for status badges.
Question 3: What's the naming logic? There wasn't one. "Button Blue" and "Action Primary" were the same color.
Question 4: What does the code expect? We checked the dev codebase. They had CSS variables for some colors but weren't using them consistently. Lots of hardcoded hex codes.
By end of day 2, we had a complete picture. Not a pretty one, but clear.
Day 3: Building the Primitive Layer
Start with primitives: the raw material. Every unique color, spacing value, and typography size that exists in the current Figma file. No abstraction. Just names and values.
We created these groups in Figma variables:
color-primitive-gray-50(#F9FAFB)color-primitive-gray-100(#F3F4F6)color-primitive-gray-200(#E5E7EB)- ... and so on through grays, blues, oranges, greens
spacing-primitive-4(4px)spacing-primitive-8(8px)spacing-primitive-16(16px)spacing-primitive-24(24px)typography-primitive-light(300 weight, DM Sans)typography-primitive-regular(400 weight)typography-primitive-bold(700 weight)
For spacing and typography, we worked backward from the code. The codebase had a Tailwind config already. We just mirrored it into Figma. For colors, we consolidated the 47 unique values into a rational color scale. Design system 101: 50-900 scale for grays, oranges, greens, etc.
By end of day 3, Figma had a complete primitive layer. Every design element was remapped to use a primitive variable.
Day 4: Semantic Tokens and Aliases
Primitives are the building blocks. Semantics are the meaning.
color-primitive-blue-600 is a primitive. color-semantic-primary is a semantic token. It aliases to the blue-600 primitive. This separation matters: designers and developers work with semantic names ("primary", "secondary", "error") while primitives stay stable underneath.
We created semantic tokens for:
- Actions:
color-semantic-action-primary(blue),color-semantic-action-secondary(gray),color-semantic-action-destructive(red) - Status:
color-semantic-status-success(green),color-semantic-status-warning(orange),color-semantic-status-error(red) - Content:
color-semantic-text-primary(main text),color-semantic-text-secondary(muted text),color-semantic-text-disabled(very light) - Backgrounds:
color-semantic-bg-primary(page background),color-semantic-bg-elevated(cards, modals)
Each semantic token has two modes: light and dark. When you switch modes in Figma, colors flip automatically.
For spacing and typography, we created semantic tokens too:
spacing-semantic-xs(4px)spacing-semantic-sm(8px)spacing-semantic-md(16px)spacing-semantic-lg(24px)typography-semantic-body(aliases to 400 weight, 1rem)typography-semantic-heading(aliases to 700 weight, 1.5rem)
By end of day 4, the middle layer was complete. Figma now had a two-tier system: primitives (stable values) and semantics (meaning). Every component used semantic tokens.
Day 5: Component Tokens and Wiring
Component tokens go one level deeper: specific tokens for specific components. Button has its own tokens, distinct from a Card.
We created:
button-primary-bg(aliases tocolor-semantic-action-primary)button-primary-text(aliases to white)button-primary-border(aliases to blue-700 for hover state)form-input-border(aliases tocolor-semantic-border)form-input-border-focus(aliases tocolor-semantic-action-primary)form-input-bg-error(aliases to error color with 10% opacity)
Why? Because now if a designer says "we need a new button variant," it's not 10 manual color picks. It's one new component token that aliases to semantic tokens. Changes cascade automatically.
We also wired everything up in Figma: every button instance now used component-level tokens instead of hardcoded colors. Every form input used input-specific tokens. Every type style used typography tokens.
By end of day 5, the three-tier system was complete: primitives → semantics → components. All wired together with aliases. One change at the top ripples down.
Day 6-7: QA, Documentation, Handoff
Day 6 morning: Export tokens to JSON. We set up a GitHub Action that reads the Figma token file, validates the schema (all semantics must reference primitives, all components must reference semantics), and publishes to npm.
Test export: 250 lines of clean JSON. Design team reviews. Changes one alias. Exports again. Works.
Day 6 afternoon: Wired it into the dev codebase. The CSS preprocessor now imports tokens from npm. A button using color-semantic-action-primary in Figma automatically gets the right hex code in the browser.
Push a test PR. Build succeeds. Visual regression test passes. Button colors match perfectly.
Day 7 morning: Documentation. We created a Storybook file (just markdown) that shows the token structure, explains each tier, gives examples, and documents the export process. Design team adds it to their wiki. Dev team bookmarks it.
Day 7 afternoon: Training call with the team. 30 minutes. "Here's a semantic token. Here's how you use it in Figma. Here's how it exports to code. Here's what to do when you need a new token."
Ship the final PR: redesigned Figma file + token JSON + documentation. Done.
What the Team Gets on Day 7
Specific deliverables the fintech team shipped with:
- Figma file: Complete token structure (80 primitives, 45 semantics, 20 component tokens). All components use tokens.
- Token JSON: Automatically exported to npm on every Figma update. Version 1.0.0 published.
- Code integration: CSS build pipeline imports tokens. All hardcoded hex codes removed from the codebase.
- Storybook: A documentation page showing token structure, usage examples, and naming conventions.
- Documentation: How to add new tokens, how to use them in code, how the export process works.
- Maintenance process: Designer updates color in Figma → exports → npm updates → code automatically gets new values. No manual steps.
The team's immediate impact:
- Time to add a new color: 5 minutes (used to take 30, with manual coordination)
- Time to update all blues across the product: 5 minutes in Figma, auto-exports, done (used to take 2 hours)
- Design-dev alignment: 100% (token names force agreement)
- QA bugs from color mismatches: dropped to zero
- New developer onboarding: "Here's the token file. Use these names. Don't hardcode colors."
Three months after the sprint, that team shipped 8 new features. They credited the token system for 20% reduction in dev time—no more "what color should this be?" back-and-forth. Clean specification from day one.