Most design systems do not fail because the components are wrong. They fail because the same decision is expressed in four places and three of them fall behind.
Tokens are decisions, not variables
A token earns its place when it names something a designer would argue about: the page background, the rule between sections, the one saturated colour. A variable that merely renames #333 is bookkeeping.
- Name by role, never by appearance — `--color-rule`, not `--grey-3`
- Keep the set small enough to memorise
- Let components read tokens; never let them redefine one
Theming is a constraint, not a feature
The moment a second theme exists, every hard-coded colour becomes a bug waiting for a screenshot. Deciding early whether a theme is in scope is cheaper than retrofitting one.
A design system is the set of decisions you have agreed not to make again.
Documentation is part of the system
An undocumented component is a component that will be rebuilt. The note explaining why a rule exists is what stops the next developer from removing it.