[Placeholder] Notes on tokens

Design tokens are the quietest part of a system. When they’re right, nothing looks out of place. When they drift, every surface in the product stops making sense together — and the only way back is to pay the tax all at once.

What a healthy token set looks like

The habit I keep returning to is to name tokens for intent, not appearance. “Surface” over “grey-2”. “Danger” over “red-500”. The surface layer can swap underlying values when the brand shifts, when accessibility targets change, or when a new theme arrives, and nothing downstream has to move. Components reference meaning, and meaning stays stable even as the pixels underneath redecorate.

A few rules that have held up across projects:

• Name for role, not colour.
• Keep the scale tight — more values make less sense, not more.
• Dark mode is a token change, not a rewrite.
• Spacing is a scale, not a free-for-all.
• Treat radius and shadow as design decisions, not CSS defaults.

If you can’t rename a token without stopping to think, it isn’t a token yet — it’s a value with a label.

A thin ergonomics layer helps teams adopt the system without ceremony:

.button {
  background: var(--color-accent);
  color: var(--color-accent-contrast);
  padding: var(--space-3) var(--space-4);
  border-radius: var(--radius-md);
}

The payoff isn’t aesthetic consistency alone. It’s that the next designer who joins can walk in on a Monday morning, ship a new component in an afternoon, and have it look like it belonged from day one. That’s what good tokens buy you — not polish, but momentum.