The tangible win
After this lesson, you should be able to tell whether a token name is too raw, just meaningful enough, or too component-specific.
Why tokens exist
Material Design says tokens are building blocks used across design, tools, and code (Material tokens). Carbon describes tokens as a way to apply color consistently instead of hard-coding values like hex codes (Carbon color tokens).
That is true, but for product design the deeper point is this: tokens let you name decisions at the right level of abstraction.
The three-level ladder
The Singapore Government Design System describes a layered token architecture where each layer can reference the layer below it (SGDS token architecture). For now, use this simplified ladder:
| Layer | Question it answers | Example |
|---|---|---|
| Primitive | What raw value exists? | red.600, space.16 |
| Semantic | What product meaning exists? | color.text.danger, space.stack.md |
| Component | How does this component express it? | alert.error.border, button.primary.bg |
Backend analogy: don’t leak storage into domain code
You would not want every service to depend on a raw storage detail if the domain meaning is “customer is suspended.” Design tokens follow the same instinct.
/* raw value: useful inside the system */
--red-600: #da1e28;
/* semantic meaning: useful across product UI */
--color-text-danger: var(--red-600);
/* component contract: useful inside one component */
--alert-error-border: var(--color-text-danger);If the brand later decides danger should be orange, semantic and component names still survive.
Practice: choose the right layer
Scenario: You are styling validation text under a failed form input: “Email is required.” Which token layer is the best direct dependency for the text color?
A small naming rule
When naming a token, avoid names that describe only the current appearance if the real decision is semantic.
| Weaker | Stronger | Why |
|---|---|---|
redText | color.text.danger | Names the product meaning. |
bigGap | space.section.lg | Names the layout role. |
grayBorder | color.border.subtle | Names the visual emphasis. |
Retrieval check
Without looking above, say out loud:
- What does a primitive token name?
- What does a semantic token name?
- What does a component token name?
If you can answer those, you have the basic token ladder.
Read next
Primary source: read SGDS Token architecture. Focus on the idea of layers referencing lower layers; ignore details that feel too advanced for now.
Ask me any follow-up. For example: “show me bad token names,” “apply this to a dashboard,” or “how does this map to Tailwind?”