# 01 Tokens

> The boring, standard substrate everything above it stands on.

Nothing downstream works without a standard, boring substrate. As of October 2025, we finally have one, and boring is exactly the point.

## Summary
- Design tokens stopped being a translation tax in October 2025, when the Design Tokens Community Group shipped its first stable, vendor-neutral format.
- Boring is the point: once the format is settled, the work moves up to where it matters, governance, architecture, and getting design intent into code on every platform.
- Keep them three tiers deep, never let a component point at a raw primitive, and the whole agent stack above gets easier instead of inheriting the mess.

## The argument

For years, design tokens were a translation tax. Every tool had its own dialect, and teams burned weeks converting between them. That is done. In October 2025 the Design Tokens Community Group shipped DTCG v2025.10, the first stable, vendor-neutral format. The file shape stopped being the argument.

That sounds boring. Boring is the point. When nobody fights about the format, the work moves up to where it matters: governance, architecture, and getting design intent into code on every platform.

Here is the distinction that trips people up. A token is not a variable. A variable is storage. A token is a decision, encoded so it survives a jump from web to native without a rewrite. Miss that and you build a system that looks fine and collapses at scale.

Why teams do the work: a full brand refresh, color, radius, shadows, drops from weeks of manual coordination to a single source edit through token PRs and visual review. One source of truth, swapped once.

The traps are predictable. Do not build past three tiers (primitive, semantic, component). Do not rename tokens to feel tidy, that is a breaking change; deprecate instead. Do not let components point at raw primitives, or dark mode becomes a three-month job instead of a fifteen-minute swap.

Tokens are the foundation the whole agent stack stands on. Get them boring, standard, and lintable, and everything above them gets easier. Skip it, and every layer above inherits the mess. But values alone only tell an agent what a thing is, not what it means or when to use it. That is the next layer's job.

## Fact-checked claims
- The DTCG shipped its first stable spec, Format Module 2025.10, in October 2025. Design tokens originated with the Salesforce design system team.
- Stay three tiers: primitive, semantic, component. Components reference semantic tokens, never primitives directly, or a future dark mode becomes a rewrite instead of a swap.

## Sources
- [Design Tokens Community Group](https://www.designtokens.org/): The DTCG's home base. Start here for what tokens are and who is setting the standard.
- [The first stable spec, v2025.10](https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/): The moment it stopped being a draft. DTCG v2025.10, the first stable, vendor-neutral spec.
- [DTCG working repository](https://github.com/design-tokens/community-group): Where the spec actually lives. The working repo and the technical drafts.
- [Malaka Venu, why boring wins](https://malakavenu.com/articles/design-tokens-w3c-2026): On why a boring format is the win, with the six-weeks-to-one-day refresh number.

## Questions to take to the notebook
- What changed when the DTCG spec reached its first stable version?
- Why is a component pointing at a raw primitive a future dark-mode problem?
- How is a token different from a variable?