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:

javascript

{
  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