Token Naming Conventions
Designtoken-naming-conventionsToken Naming Conventions is an Agent Skill for design published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/development/token-naming-conventions/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/token-naming-conventions, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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