Facebook Design System: Token Architecture

Context

Design tokens are the atomic layer of a design system, the named values for color, typography, spacing, size, and corner radius that everything else is built on. When token naming is inconsistent, the entire system becomes harder to maintain, harder to scale, and impossible to automate.

The Facebook Design System had 863 tokens. They didn't have a unified naming framework.

Without consistent naming conventions, spec accuracy suffered, engineers were working from token references that were wrong or ambiguous roughly 40% of the time. More critically, as AI-assisted design tooling matured, the system wasn't ready for it. Machine-readable nomenclature isn't a nice-to-have when you're building at Meta's scale. It's infrastructure.

I owned this problem end to end.

Approach

The framework. I designed a comprehensive token naming system built around a 4-tier architecture: base → semantic → category → component. Each tier has a specific role, base tokens define raw values, semantic tokens assign meaning, category tokens group by use case, and component tokens map directly to UI elements. This hierarchy isn't just organizational, it's what makes tokens legible to both humans and machines.

For each of the five foundational token types (color, typography, spacing, size, and corner radius) I created naming formulas, rules, and a writing style guide that could be applied consistently across the entire library. The goal wasn't just standardization, it was to build naming conventions that an AI model could read, interpret, and generate from.

The tool. A framework is only as good as its adoption. So I built one.

The Token Namer is an internal tool built on a modern web stack that validates and generates correctly-named tokens. It has three core features: a guided builder with typeahead that walks designers through the naming formula step by step; a live token browser for exploring the existing library; and, the part I'm most proud of, AI-powered screenshot analysis.

The AI feature uses Claude's API to read Figma screenshots, extract visual properties, and suggest compliant token names based on the framework. In practice, a designer can screenshot a component, run it through the tool, and get a naming suggestion in seconds, one that follows every rule in the framework without having to memorize them.

This is what "AI-native by practice" actually looks like in a design system context.

Outcome

• 863 tokens standardized under a unified naming framework across 5 foundational token types
• 118 new tokens added as part of the framework rollout
• Spec accuracy improved from 60% to 85%, a 25-point jump that directly reduces engineering rework and handoff friction
• A 4-tier token architecture that supports theming at scale and enables AI-assisted component generation
• An internal tool that automates token creation, reduces manual naming errors, and demonstrates how LLMs can enforce design system governance at the infrastructure level

Insight

This project changed how I think about the relationship between design systems and AI. Most conversations about AI in design focus on generation, using AI to make things. This was about using AI to enforce standards, making sure the things we make are named correctly, consistently, and in a way that future tooling can understand.

The 4-tier architecture wasn't designed for today's workflows. It was designed for the workflows coming next: automated theming, AI-assisted component generation, design-to-code pipelines that don't need a human in the middle to translate token names.

What I'd do differently: I'd build the tool earlier in the process and use it as a research instrument. Running designers through the naming builder before the framework was finalized would have surfaced edge cases faster than workshopping them in documents.

The thing that stuck with me: naming is a form of design. A token named well is a token that doesn't need to be explained. That's the same standard I hold for any component, any piece of documentation, any system I work on.