Token Naming and Tiered Token Architecture
Structure your design tokens into a scalable tiered architecture - primitive, semantic, and component tokens - with naming that survives change.
Token Naming and Tiered Token Architecture is a free Design Systems & Component Libraries lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Design Systems & Component Libraries learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Token Architecture Matters
A flat list of color tokens works at first, then collapses as the system grows. A tiered token architecture keeps tokens scalable and meaningful.
This lesson builds on implementing tokens by structuring and naming them well.
Tier 1: Primitive Tokens
Primitive (or global) tokens are raw values: blue-500 = #3b82f6, space-4 = 16px.
They are the full palette of available values, named by what they are, with no opinion about where they are used.
Tier 2: Semantic Tokens
Semantic (or alias) tokens describe intent: color-action-primary, color-text-danger.
They reference primitives but add meaning. Components use semantic tokens, so re-theming means repointing aliases, not editing every component.
Tier 3: Component Tokens
Component tokens scope values to a specific component: button-background-color, card-padding.
They reference semantic tokens. The chain below shows the three tiers resolving down to a raw value.
const primitive = { 'blue-500': '#3b82f6' };
const semantic = { 'color-action-primary': 'blue-500' };
const component = { 'button-bg': 'color-action-primary' };
function resolve(token) {
let v = component[token] || semantic[token] || token;
v = semantic[v] || v;
return primitive[v] || v;
}
console.log(resolve('button-bg'));The Power of Indirection
Why three tiers? Indirection. Change color-action-primary from blue to green once, and every button, link, and focus ring updates.
Without semantic tokens you would hunt down every hardcoded blue. Tiers turn sweeping changes into one edit.
Naming That Survives Change
Name semantic tokens by role, never by value. color-success survives a palette change; color-green becomes a lie.
The same rule applies to primitives - prefer blue-500 over brand-blue if the brand might shift.
A Consistent Naming Schema
Adopt a predictable pattern: category-property-variant-state, e.g. color-text-link-hover.
When every token follows the same grammar, developers can guess token names instead of searching docs. Consistency is the goal.
Avoiding Over-Tokenization
Not everything needs a token. Tokenizing every one-off value creates noise and maintenance burden.
Tokenize values that repeat or carry meaning. A truly unique magic number can stay inline with a comment.
Themes Live at the Semantic Tier
Light, dark, and brand themes differ at the semantic layer. Primitives stay constant; semantic aliases repoint per theme.
This is why the tier structure makes multi-theme support nearly free - you swap one mapping table.
Documenting the Hierarchy
Show the token chain in your docs: which primitive a semantic token points to, and which components consume it.
This transparency helps contributors choose the right tier and understand the ripple effect of a change.
Architecture That Scales
A tiered, well-named token system scales from one product to dozens of themed, white-labeled apps without rework.
The structure is the difference between tokens that empower and tokens that become technical debt.
Quick Check
Test your token architecture knowledge.
Recap
You structured design tokens into a scalable architecture:
- Primitive tokens hold raw values.
- Semantic tokens add intent; components reference these.
- Component tokens scope values per component.
- Name by role, follow a consistent schema, and avoid over-tokenizing.
Tiered tokens make sweeping design changes a single edit.
Frequently asked questions
Is the “Token Naming and Tiered Token Architecture” lesson free?
Yes — the full text of “Token Naming and Tiered Token Architecture” is free to read here on the web, and the Design Systems & Component Libraries course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Design Systems & Component Libraries course, upgrade to CoddyKit PRO.
What will I learn in “Token Naming and Tiered Token Architecture”?
Structure your design tokens into a scalable tiered architecture - primitive, semantic, and component tokens - with naming that survives change. You practise Design Systems & Component Libraries with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Design Systems & Component Libraries?
No prior experience is required. Design Systems & Component Libraries on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Token Naming and Tiered Token Architecture” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Design Systems & Component Libraries lesson?
Yes. Every Design Systems & Component Libraries lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- What Are Design Tokens?
- Implementing Design Tokens
- Automating Design-to-Code Workflows
- Token Naming and Tiered Token Architecture