Decision
Introduce a deliberately small set of semantic ‘Intent’ tokens, named by purpose, priority, and property, as the only theming API consumers touch. An intent names what an element is for in the experience and defers its cosmetic values to be resolved later in the lifecycle by the party responsible for them. Keep the set as small as the system can bear rather than letting it grow on request.
Alternatives Considered
Leave variables unclassified, as plain values
| 👍 Pros | 👎 Cons |
|---|---|
| Maximum flexibility Nothing to learn beyond the values |
No shared way to reason about what a variable is for Purpose and cosmetic styling stay tangled together Meaning lives only in whoever defined it |
Per-component theming APIs
| 👍 Pros | 👎 Cons |
|---|---|
| Tailored to each component | Inconsistent across the library Explodes the surface area to maintain |
Reasoning
Naming tokens by intent (action, surface, text), priority (primary, secondary, auxiliary), and property clearly describes the purpose of an element in the experience, and separates that purpose from the cosmetic styles, which are settled later in the lifecycle by another responsible party. That keeps the system predictable and bounded, and a small, semantic vocabulary co-designed with design counterparts goes much further than letting hundreds of one-off values proliferate. It is also the foundation the rest of the system builds on: these same intents are exactly what nested modes re-value within a scope, so expression in Mise en Mode comes from re-valuing intents rather than minting new tokens. A bounded set of intents is what makes that possible.
Why it mattered
Intents gave designers and engineers one shared language for theming, and the discipline is to keep that set as small as possible, ideally fewer than three dozen, since every constraint held is what keeps the system legible. The closest relative of this idea is Mise en Mode, which leans directly on these intents; Tokenpedia plays a different role, more like a dictionary for the vocabulary itself.
All decisions