Naming Conventions

Establish consistent, audience-appropriate naming patterns across your design system.

Different audiences need different naming approaches. Select your role below for tailored guidance.

The Audience-First Approach

Naming conventions in a Design System should vary depending on the user group

Designers and developers should speak the same language—at least for the things they both care about, like Design Tokens. The others honestly don't care about tokens 😅

For other Design System users — like agencies (internal and external), brand managers, product managers, contributors, etc. the language should align around components, documentation, and implementation.

I ran several UX research sessions and surveys, and I was surprised to see how different markets and teams within the same company use different terms when it comes to building websites and digital experiences. And most of them don't care how you name Components or Tokens in Figma and Code.

For leadership, it's mostly about results, numbers, and sometimes how to differentiate design systems (design system products) within the company.

What Works

✓ Tailoring naming to specific audiences

✓ Consistent naming within each domain

✓ Clear documentation of naming patterns

✓ Using familiar industry terms for each group

✓ Creating translation guides between domains

What Doesn't Work

✗ One-size-fits-all naming conventions

✗ Overly technical names for non-technical users

✗ Inconsistent naming within a domain

✗ Changing established naming patterns frequently

✗ Using internal jargon with external partners

Common Naming Elements

Understanding the building blocks of naming conventions

Prefixes

Used to namespace components or indicate ownership. Examples: ds-, ui-, app-

Case Styles

camelCase: First word lowercase, others capitalized
PascalCase: All words capitalized
kebab-case: All lowercase with hyphens
snake_case: All lowercase with underscores

Common Modifiers

States: Default, Hover, Active, Disabled
Sizes: XS, SM, MD, LG, XL
Variants: Primary, Secondary, Tertiary
Categories: Form, Navigation, Layout

Element Types

Components: Reusable UI elements
Design Tokens: Visual design properties
Patterns: Combined components and behaviors
Utilities: Helper functions/classes

Component Naming Patterns

Strategies for naming components consistently

For Development

•ButtonPrimary (PascalCase for React)
•ds-button-primary (kebab-case for CSS)
•useButtonState (camelCase for hooks)

For Design

•Button / Primary / Default (in Figma)
•Button/Primary/Hover (in Sketch)

Good Practices

Name by function not appearance (NavigationCard, not BlueCard)
Create clear hierarchies (Card → MediaCard → ProductMediaCard)
Follow platform conventions (PascalCase for React components)

Token Naming Patterns

Strategies for naming design tokens consistently

Common Formats

•--color-background-primary (CSS variables)
•colors.background.primary (JSON structure)
•$color-background-primary (SCSS variables)

Token Categories

• color
• typography
• spacing
• sizing

• shadow
• border
• opacity
• z-index

Structure

Token names typically follow this structure:

[category]-[type]-[scale/variant]-[state]