Design tokens are named design decisions, such as color.primary or space.md, stored as data so every platform reads the same values. The Design Tokens Community Group format writes them in JSON with $value and $type, and lets one token point at another with curly braces. Tools then turn that JSON into CSS variables, Tailwind themes or app code.
| Tier | Example name | Holds |
|---|---|---|
| Base (primitive) | color.blue-500 | A raw value: a colour, size or font |
| Semantic (alias) | color.primary | A role that points at a base token |
| Component | button.background | A role scoped to one component |
Updated
Most explanations stop at the definition. Paste or edit token JSON below in the community group format and see, as you type, the CSS custom properties and the Tailwind v4 theme it produces, with aliases resolved to var() references.
Edit the token file and the CSS variables and Tailwind theme update as you type. The starting file converts to:
{
"color": {
"$type": "color",
"blue-500": { "$value": { "colorSpace": "srgb", "components": [0.31, 0.596, 0.984] } },
"gray-900": { "$value": { "colorSpace": "srgb", "components": [0.067, 0.067, 0.067] } },
"primary": { "$value": "{color.blue-500}", "$description": "Buttons and links" },
"text": { "$value": "{color.gray-900}" }
},
"space": {
"$type": "dimension",
"sm": { "$value": { "value": 0.5, "unit": "rem" } },
"md": { "$value": { "value": 1, "unit": "rem" } }
},
"font": {
"body": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] },
"bold": { "$type": "fontWeight", "$value": 700 }
},
"motion": {
"fast": { "$type": "duration", "$value": { "value": 150, "unit": "ms" } }
}
}:root {
--color-blue-500: rgb(79 152 251);
--color-gray-900: rgb(17 17 17);
--color-primary: var(--color-blue-500); /* Buttons and links */
--color-text: var(--color-gray-900);
--space-sm: 0.5rem;
--space-md: 1rem;
--font-body: Inter, system-ui, sans-serif;
--font-bold: 700;
--motion-fast: 150ms;
}@import "tailwindcss";
@theme {
--color-blue-500: rgb(79 152 251);
--color-gray-900: rgb(17 17 17);
--color-primary: var(--color-blue-500);
--color-text: var(--color-gray-900);
--spacing-sm: 0.5rem;
--spacing-md: 1rem;
--font-body: Inter, system-ui, sans-serif;
--font-weight-bold: 700;
--motion-fast: 150ms;
}The card only reads --surface and --text. The dark block reassigns those two names, and the card follows without any change to its own rules.
<style>
:root { --gray-50: #f8fafc; --gray-900: #0f172a; --blue-500: #4f98fb;
--surface: var(--gray-50); --text: var(--gray-900); --accent: var(--blue-500); }
.dark { --surface: var(--gray-900); --text: var(--gray-50); }
.card { background: var(--surface); color: var(--text); padding: 14px; border-radius: 12px; margin: 6px 0;
border-left: 6px solid var(--accent); }
</style>
<div class="card">Light theme card</div>
<div class="dark"><div class="card">Same card inside .dark</div></div>Composite tokens group several values. Here the colour is itself an alias, and offsets use dimension objects.
{
"shadow": {
"card": {
"$type": "shadow",
"$value": {
"color": "{color.gray-900}",
"offsetX": { "value": 0, "unit": "px" },
"offsetY": { "value": 4, "unit": "px" },
"blur": { "value": 12, "unit": "px" },
"spread": { "value": 0, "unit": "px" }
}
}
}
}Without tokens, the brand blue lives as a hex code pasted into hundreds of places across CSS, mobile apps and design files. Changing it means a search and replace that always misses one.
With tokens, that blue has one name and one home. Designers and developers talk about color.primary, and a build step writes the value into each platform's own format.
Any object with a $value is a token; any other object is a group. Properties that start with a dollar sign are reserved by the format: $value, $type, $description, $deprecated and $extensions.
The spec defines simple types such as color, dimension, fontFamily, fontWeight, duration, cubicBezier and number, plus composite types like shadow, border, transition, typography, strokeStyle and gradient. Dimensions and durations are objects with a numeric value and a unit.
A small site can keep tokens straight in CSS as custom properties. Once you ship to more than one platform, or design in a tool that exports tokens, generate the CSS from JSON instead so there is a single source.
Dark mode becomes a second set of semantic values. Base colours stay the same, and the semantic layer swaps which base each role points to inside a dark-scheme media query or a data attribute.
A design token is a name paired with a design value, for example color.text holding a near-black colour. Code and design files use the name, so changing the value in one place updates every button, page and app that refers to it.
Yes. The Design Tokens Community Group at the W3C published the Format Module 2025.10 as a final community group report on 28 October 2025 and describes it as stable. It is a community group report, not a W3C Recommendation.
Tokens are the source data, independent of any platform. CSS custom properties are one output. The same token file can also generate Swift, Android or JavaScript constants, which CSS variables alone cannot give you.
In Tailwind v4 you declare theme variables inside @theme, such as --color-primary. Tailwind creates utilities like bg-primary from them and also emits them as normal CSS variables on :root, so tokens and utilities stay in sync.
In the 2025.10 format a colour value is an object with a colorSpace, such as srgb, and an array of components from 0 to 1, with optional alpha. The converter here also accepts plain strings so you can paste older token files.
Related: CSS variables guide, Design system examples, shadcn/ui theme generator, Tailwind colour palette generator, Dark mode guide.
Start for free or see all free tools. We.Inc is free to start, with no card needed. AI building is on paid plans from $20 a month.
We.Inc is an AI-powered website builder you can resell under your own brand. Launch a branded client dashboard, bill on Stripe Connect, and deliver AI-generated websites in minutes. White-label plans start at $99 a month for 25 client sites, with a 7-day free trial and no per-site fees.