Back to field notes

Tokens are a promise to future you

A design token is more than a reusable value. It is a small agreement about how a system should change without losing its shape.

It is easy to call every repeated value a token. The harder question is whether the name captures a decision someone will need to make again. A color called `blue-500` describes a sample. A color called `action` describes a job.

Good names leave room for the system to evolve. When the brand changes, an action color can move from blue to another hue without changing the component's meaning. When a spacing value changes, a layout token can be adjusted once instead of searched for in a hundred files.

That promise has limits. Tokens should not hide meaningful differences just to reduce the number of values. If two surfaces behave differently, give them names that preserve the distinction. A small vocabulary is useful only when people can still tell what each choice means.

Name a token for the decision it represents, then keep the contract small enough to understand.