Token Naming Conventions
Structure token names hierarchically using global, alias, and component-specific naming tiers.
Token Naming Conventions is a free CSS Academy lesson on CoddyKit — lesson 2 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 CSS Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Naming Matters
Inconsistent token names make it impossible to predict what a token does without reading its value. A clear, predictable naming convention is foundational to a scalable token system.
Category-Property-Variant Pattern
A common pattern: [category]-[property]-[variant]. Example: color-text-primary, color-text-secondary, spacing-inset-sm. Each segment narrows meaning progressively.
Semantic vs Palette Names
Avoid palette names like blue-500 in components. Use semantic names: color-action-default, color-feedback-error. Semantic names survive brand color changes without component updates.
State Modifiers
Append state at the end: color-button-bg-default, color-button-bg-hover, color-button-bg-disabled. Consistent state suffixes make token sets predictable and complete.
Scale Naming
Use t-shirt sizes (xs, sm, md, lg, xl) or numeric scales (100, 200...900) consistently. Numeric scales allow insertion of intermediate values; t-shirt sizes are more human-readable for small sets.
Namespace Prefixes
For multi-brand or multi-product systems, prefix tokens with a namespace: brand-a-color-primary vs brand-b-color-primary. Namespaces prevent collision when merging token sets.
CSS Variable Output
Kebab-case translates directly to CSS custom properties: color-text-primary becomes --color-text-primary. Camel-case tokens need transformation; kebab-case tokens do not.
Documentation as Part of Naming
Good names are self-documenting: spacing-stack-md (vertical spacing between stacked elements, medium) communicates intent without a comment. Poor names like s3 require external documentation to understand.
Avoiding Breaking Changes
Once tokens are in use, renames are breaking changes. Use deprecation aliases: keep the old name but have it reference the new token. Give consumers a migration period before removing deprecated tokens.
Tooling Enforcement
Lint token names with custom rules in Style Dictionary or a CI script. Reject tokens that don't match the naming pattern. Automated enforcement prevents naming drift as the system grows.
Team Alignment
Publish a naming guide with examples of correct and incorrect names. Run a brief workshop so design and engineering teams agree on conventions before the system scales. Consistency requires shared understanding, not just documentation.
Knowledge Check
Why should component tokens use semantic names rather than palette names like "blue-500"?
Summary
A consistent token naming convention using category-property-variant patterns, semantic names, state suffixes, and namespace prefixes makes token systems predictable, self-documenting, and resilient to brand changes without breaking component code.
Frequently asked questions
Is the “Token Naming Conventions” lesson free?
Yes — the full text of “Token Naming Conventions” is free to read here on the web, and the CSS Academy 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 CSS Academy course, upgrade to CoddyKit PRO.
What will I learn in “Token Naming Conventions”?
Structure token names hierarchically using global, alias, and component-specific naming tiers. You practise CSS Academy 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 CSS Academy?
No prior experience is required. CSS Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Token Naming Conventions” 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 CSS Academy lesson?
Yes. Every CSS Academy 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.