I’ve changed my opinion on design token management, and I’m not going back. After years of working with design systems, I’ve become convinced that Figma should not be the source of truth for design tokens. Instead, it should be a consumer.
The Traditional Approach: Figma as Source
Many teams start their design token journey with Figma plugins that export tokens from their design files. It seems logical at first — designers work in Figma, so why not extract tokens directly from there?
The problem is that this creates a fundamental architectural flaw: your design system’s foundation lives inside a proprietary design tool, accessible only through its API and plugin ecosystem.
The Better Way: Code as Source of Truth
Here’s what I advocate for now: Design tokens should live in a version-controlled JSON file in your codebase. This file becomes the single source of truth, and both your application code and Figma consume from it.
Why This Matters
Version Control: When tokens live in a JSON file, they benefit from Git’s version control. You get:
- Complete change history with meaningful commit messages
- Code review processes for token changes
- Easy rollbacks when something goes wrong
- Branch-based workflows for token experiments
Developer Accessibility: Developers can read, update, and understand design tokens without needing Figma access or navigating through design files. The tokens are right there in the codebase where they’re used.
Automation and CI/CD: With tokens in JSON, you can:
- Run validation checks in your CI pipeline
- Generate documentation automatically
- Transform tokens into platform-specific formats (CSS, SCSS, JavaScript, iOS, Android)
- Catch breaking changes before they reach production
Tool Independence: Your design system isn’t locked into Figma. If you need to switch tools, migrate platforms, or support multiple design tools, your tokens remain stable and accessible.
W3C Compliance: JSON-based tokens can follow the W3C Design Tokens specification, ensuring interoperability and future-proofing your system.
Figma as a Consumer
Instead of exporting from Figma, you import tokens into Figma. This means:
- Designers update tokens in the JSON file (or request changes through your team’s process)
- Tokens are validated and merged into the codebase
- The same tokens are synced into Figma using import plugins
- Both code and design stay in perfect sync from a single source
Why I Stopped Using Export Plugins
I no longer use Figma token export plugins in my work because they create the wrong dependency direction. They make code depend on design tool state, when it should be the other way around.
Export plugins also often:
- Require manual intervention to keep things in sync
- Introduce inconsistencies based on how designers structure their files
- Lack the validation and governance that code-based tokens provide
- Create a disconnect between what’s in version control and what’s in production
The Mental Shift
This approach requires a mental shift: design tokens are code, not design files. They’re the contract between design and development, and like any contract, they need to be versioned, reviewed, and managed with the same rigor as your application code.
Figma is an incredible tool for design work, but it’s not built to be a version control system or a source of truth for your product’s design foundation. Let it do what it does best — be a canvas for creativity and collaboration — while your design tokens live where they belong: in code.
“The source of truth should live where it can be properly versioned, validated, and consumed by all parties equally.”
Getting Started
If you’re interested in adopting this approach:
- Define your tokens in JSON following the W3C specification
- Set up validation (tools like Design Token Validator can help)
- Create build scripts to transform tokens into platform-specific formats
- Use Figma import plugins to sync tokens into your design files
- Establish a process for token changes that includes code review
Your future self will thank you for making this architectural decision early.
