Guide · glossary
what is a design token?
A design token is a named value that stands in for one design decision. Instead of writing the hex code #0066ff in forty places, you name it once, call the name everywhere, and change the value in a single spot when the brand shifts. The Design Tokens Community Group, the group behind the emerging cross-tool standard, defines a token as "an information associated with a name, at minimum a name/value pair." That is the whole idea. Everything else is naming discipline and tooling on top of that one move.
Tokens are what let a design system stay a system instead of a pile of similar-looking values that quietly drift apart. And because a token is just a name pointing at a value, the same set can drive a Figma file, a CSS stylesheet, an iOS build, and an Android build without anyone retyping numbers.
a token is a named value, not a variable in the abstract
The clearest way to understand a token is to look at the value it replaces.
Hardcoded, a button might read background: #0066ff; padding: 12px 20px; border-radius: 8px. Every one of those literals is a decision frozen in place. Tokenized, the same button reads background: var(--color-action); padding: var(--space-3) var(--space-5); border-radius: var(--radius-md). Now the decisions have names, the names are shared, and changing --color-action once recolors every action button in the product at once.
Material Design 3 frames tokens as small assignments that "hold information such as a hex code for color," swapped in "rather than hard-coded values." That swap is the entire value proposition, so it is worth being precise about what a token is not. A token is not a component, not a stylesheet, and not a theme by itself. It is the smallest unit: one name, one value.
the six token families you will actually see
Most people meet design tokens as color and stop there. A real system tokenizes far more than color. Here are the families that show up on almost every polished site, with concrete raw values so the abstraction stays honest.
| family | what it captures | example token | raw value |
|---|---|---|---|
| color | brand, text, surface, borders, states | color.action | #0066ff |
| typography | family, size, weight, line height | font.size.body | 16px / 1.5 |
| spacing | the padding and gap scale | space.4 | 16px |
| radius | corner rounding | radius.md | 8px |
| shadow | elevation and depth | shadow.card | 0 1px 3px rgba(0,0,0,0.12) |
| motion | duration and easing | motion.ease.standard | cubic-bezier(0.2, 0, 0, 1) |
The Design Tokens Format Module goes further and names types for each of these, including color, dimension, font family, font weight, duration, and cubic Bézier, plus composite types like border, shadow, and typography that bundle several primitives into one. Motion tokens are the family people forget most, and they are exactly the Bézier coordinates and millisecond durations that make an interface feel like the brand rather than a default. Tokenizing them is what separates a design system from a color palette.
why teams use them: change once, stay consistent
Two problems push teams toward tokens, and both are boring in the way that matters.
The first is consistency. Without tokens, a value like a specific blue gets pasted into dozens of components, stylesheets, and design files, and over months those copies diverge. One is #0066ff, another is #0067ff, a third is an old brand blue no one remembers. Tokens collapse that back to a single source of truth.
The second is change. When the value does need to move, hardcoding forces you to hunt down every instance. Contentful describes the payoff plainly: define a value once with a meaningful name, reference the name everywhere, and one edit updates every place it is used. A dark mode, a rebrand, a tightening of the spacing scale: each becomes an edit to a token file instead of a manual sweep across the codebase.
There is a third, quieter reason that matters more every year: tokens are the format an AI coding agent can actually build from. A screenshot forces a model to guess. A named set of values, color.action = #0066ff, radius.md = 8px, gives it the real decisions with no inference in between. That is the difference between an agent that rebuilds your look and one that produces generic AI-slop UI.
primitive, semantic, component: the three tiers
As systems grow, teams split tokens into three tiers. It is worth knowing the vocabulary because nearly every design system doc uses it.
- Primitive (also called global or reference) tokens hold raw values with no opinion about use:
blue.500 = #0066ff. They are the palette, not the application. - Semantic (also called alias) tokens add intent by pointing at a primitive:
color.action = blue.500. This is the resilient layer. If brand blue changes,color.actionkeeps its name and just points somewhere new, so nothing downstream has to change. - Component tokens scope a decision to one part:
button.radius = radius.md. They reference semantic tokens and let a single component vary without touching the rest.
You do not need all three tiers on day one. A small project can ship with a flat list of primitives and be perfectly fine. The tiers are a way to absorb change later without a rewrite, not a rule you owe anyone up front.
how a tool extracts tokens from a live page
You can author tokens by hand. You can also read them back off a site that already exists, which is what design token extractors do. There are three shapes of output in this category, and they are not interchangeable.
Most extractors read the CSS Object Model of a rendered page and report computed styles. A Chrome extension like Design Token Extractor or a CSS analyzer walks the DOM, collects every color, font size, and radius in use, buckets them, and hands you a panel or a JSON export. That is genuinely useful for a person doing the next step by hand. The known weak spot: reading raw CSS alone can miss which blue is the primary button versus a one-off link, because the code does not label intent. That is the semantic layer, and it does not live in the stylesheet.
uiscanner takes a different path. Paste any public URL and it reads the rendered page with vision plus the DOM, so it catches what a code-only scraper misses: the real primary button, a centered versus split hero, and decorative imagery it describes as prompts to recreate as originals. It returns the six token families above, a section-by-section structure, and a Claude-tailored build prompt, then hands you an id and a shareable uiscanner.com/t/<id> link. It describes and tokenizes; it never copies or re-hosts the original site's asset bytes, so you rebuild in your own stack from the tokens and structure.
If you want to see the output shape rather than read about it, the Stripe teardown and the Linear teardown show real tokens pulled off two of the most-studied sites on the web. To pull tokens yourself from your terminal:
npx -y uiscanner-mcp@latest scan stripe.com --target landing
Or wire it into Claude Code as an MCP server so an agent can request a teardown mid-build:
claude mcp add uiscanner -- npx -y uiscanner-mcp@latest
That runs locally over stdio. The quota is unified across the web app, MCP, and CLI on a rolling 30-day window: Free is 5 scans, Indie ($12/mo) is 100, Studio ($39/mo) is 400.
the short version
A design token is a name for one design decision, kept in one place so it stays consistent and changes cleanly. Color, typography, spacing, radius, shadow, and motion are the families worth tokenizing. Primitive, semantic, and component are the tiers you grow into. And whether you author tokens by hand or extract them from a page that already nailed the look, the point is the same: turn frozen literals into named values a person, a team, or an AI agent can build from without guessing.