| name | token-naming-conventions |
| description | Standardizes design token naming patterns using hierarchical slash notation, dimension ordering, and consistent formatting rules. Use when establishing token naming standards, converting between naming formats, or organizing token hierarchies. |
Token Naming Conventions
When to use this skill
Use this skill when you need to:
- Establish consistent token naming patterns across design systems
- Convert between different naming conventions (hyphens vs slashes)
- Create hierarchical token structures with proper organization
- Define dimension ordering for token names
- Transform token names for different platforms (CSS, Figma, code)
- Validate token naming compliance
Core naming principles
1. Hierarchical structure
Tokens use forward slash notation to create clear hierarchies:
component/variant/state/property
button/primary/hover/background-color
card/elevated/default/shadow-blur
2. Semantic organization
Names should read naturally from general to specific:
- General → Specific:
typography/heading/large/font-size - Context → Detail:
surface/primary/hover/background-color - Category → Property:
spacing/component/padding-x
3. Consistent formatting
- Use lowercase letters only
- Use hyphens within segments:
background-color,font-weight - Use forward slashes between segments:
button/primary/hover - No spaces or special characters
Dimension ordering patterns
Default order (recommended)
- Component (optional):
button,card,input - Variant/Intent:
primary,secondary,success - State:
default,hover,active,disabled - Size:
xs,sm,md,lg,xl - Property:
background-color,border-radius,font-size
Example: button/primary/hover/md/background-color
Custom ordering
You can customize dimension order based on design system needs:
Priority-based ordering
- Component:
button - Property:
background-color - Variant:
primary - State:
hover
Example: button/background-color/primary/hover
Context-first ordering
- Theme:
light - Component:
button - Variant:
primary - State:
hover - Property:
background-color
Example: light/button/primary/hover/background-color
Token categories and naming
Primitive tokens
Raw foundational values with simple, descriptive names:
Color primitives
colors/red/100
colors/red/500
colors/red/900
colors/neutral/50
colors/blue/600
Spacing primitives
spacing/xs (4px)
spacing/sm (8px)
spacing/md (16px)
spacing/lg (24px)
spacing/xl (32px)
Typography primitives
font-size/xs (12px)
font-size/sm (14px)
font-size/md (16px)
font-size/lg (18px)
font-weight/light (300)
font-weight/normal (400)
font-weight/semibold (600)
Semantic tokens
Purpose-driven tokens that reference primitives:
Color semantics
color/primary → colors/blue/500
color/success → colors/green/500
color/warning → colors/yellow/500
color/danger → colors/red/500
Role-based semantics
surface/primary → colors/neutral/50
surface/secondary → colors/neutral/100
text/primary → colors/neutral/900
text/secondary → colors/neutral/600
border/default → colors/neutral/200
Component tokens
Component-specific tokens for contextual usage:
Button tokens
button/primary/default/background-color
button/primary/hover/background-color
button/primary/active/background-color
button/primary/disabled/background-color
button/primary/default/text-color
button/primary/default/border-radius
Card tokens
card/elevated/default/background-color
card/elevated/default/shadow-color
card/elevated/default/border-radius
card/flat/default/border-color
Platform-specific formatting
CSS custom properties
Convert slashes to double hyphens:
button/primary/hover/background-color
↓
--button--primary--hover--background-color
JavaScript/JSON
Convert slashes to nested objects:
{
button: {
primary: {
hover: {
backgroundColor: '#value'
}
}
}
}
Figma variables
Keep slash notation (Figma supports it natively):
button/primary/hover/background-color
SCSS variables
Convert slashes to hyphens with prefix:
button/primary/hover/background-color
↓
$button-primary-hover-background-color
Naming validation rules
Valid characters
- Lowercase letters:
a-z - Numbers:
0-9 - Hyphens:
-(within segments only) - Forward slashes:
/(between segments only)
Invalid patterns
❌ Button/Primary/Hover (uppercase)
❌ button_primary_hover (underscores)
❌ button-primary-hover (no hierarchy)
❌ button//primary//hover (double slashes)
❌ button/primary-/hover (trailing hyphens)
Valid patterns
✅ button/primary/hover/background-color
✅ typography/heading/large/font-size
✅ spacing/component/padding-x
✅ color/semantic/success
Common patterns
State variations
// Interactive states
component/variant/default/property
component/variant/hover/property
component/variant/active/property
component/variant/focus/property
component/variant/disabled/property
// Validation states
component/state/success/property
component/state/warning/property
component/state/error/property
Size variations
// T-shirt sizing
component/variant/xs/property
component/variant/sm/property
component/variant/md/property
component/variant/lg/property
component/variant/xl/property
// Numeric sizing
component/variant/100/property
component/variant/200/property
component/variant/400/property
Theme variations
// Theme-aware tokens
theme/light/component/variant/property
theme/dark/component/variant/property
theme/high-contrast/component/variant/property
Best practices
- Be consistent: Establish rules and follow them across all tokens
- Be descriptive: Names should clearly indicate purpose and context
- Be hierarchical: Order dimensions from general to specific
- Be platform-aware: Consider how names will be used in different contexts
- Be scalable: Design naming patterns that can grow with your design system
- Document conventions: Maintain clear guidelines for your team
Migration strategies
When updating naming conventions:
- Create mapping: Document old → new name conversions
- Gradual transition: Support both old and new names during migration
- Automated tools: Use scripts to convert tokens systematically
- Team communication: Ensure all stakeholders understand changes
- Update documentation: Reflect new conventions in design system docs