DesignSystems.One LogoDesignSystems.One

Naming Conventions

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

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]