Notes on design tokens
When I first set up tokens for a small project, I created around forty color values. I told myself it would make future changes easier. In practice I used six of them. The rest were aliases pointing at values I never intended to change independently.
Tokens need a consumer
The mistake was treating tokens as a way to store every decision in advance. A token is only useful when something consumes it and someone has a reason to change it separately from its neighbors. A token with no consumer is documentation pretending to be code.
Name by role, not by value
color-surface survives a rebrand. color-blue-500 does not. The first describes what the color is for. The second describes what it looks like, and only the first stays meaningful when the palette shifts.
I learned this the slow way. A palette change touched every file in one project, and I spent an afternoon hunting hardcoded hex values that should have been tokens all along. Now I keep a rough rule: if a value appears in two places for the same reason, it gets a role name.
Role names also help reviews. When someone sees --color-danger-text in a pull request, they know the intent without looking up the hex value.
What I'd do differently
Keep the list short. Document the three or four decisions behind it, such as why the surface levels are spaced the way they are. Then delete anything nothing uses. An unused token with a good name still makes the next person wonder whether they're missing something.