Skip to content
.mdDesign.md Store

Docs / Best practices

Naming tokens

Token names are the vocabulary your AI agent uses when talking about your design system. Good names make rules unambiguous; bad names force the agent to guess intent.

Semantic vs. descriptive names

The single most impactful naming decision is choosing semantic names (what the token means) over descriptive names (what itlooks like).

Descriptive (avoid)
Semantic (prefer)
Why
dark-blue
primary
An agent knows 'primary' applies to the main CTA; 'dark-blue' does not convey that
light-grey
neutral
The role is clear from the name
red
error
Context implies when to use it
white
surface
Distinguishes elevated surfaces from backgrounds
off-white
bg
Maps directly to page background intent

Color naming patterns

Use a two-tier color system: semantic aliases over a numeric scale. Define the scale for completeness; use the aliases in components.

Recommended pattern

colors:
  # Semantic aliases (use in components)
  primary:    "#0A0A0A"
  accent:     "#E63946"
  surface:    "#FFFFFF"
  error:      "#D32F2F"
  success:    "#388E3C"
  text-1:     "#0A0A0A"
  text-2:     "#555250"
  text-3:     "#8C8884"

  # Scale (optional, for completeness)
  grey-50:  "#FAFAFA"
  grey-100: "#F5F5F5"
  grey-900: "#171717"

Typography role names

Typography tokens are keyed by role. Use names that describe where the style is applied — not how it looks.

Role key
Applied to
h1
Top-level page headings
h2
Section headings
h3
Subsection headings and card titles
body
Default paragraph text
body-sm
Small body text, footnotes
label
Form labels, all-caps eyebrows
caption
Image captions, meta text
mono
Code snippets, technical values

Spacing scale names

Two conventions both work — choose one and use it consistently across the entire file. Don’t mix numeric and named scales.

Numeric (Tailwind-style)

spacing:
  1: 4px
  2: 8px
  4: 16px
  8: 32px
  16: 64px

Named (t-shirt sizes)

spacing:
  xs:  4px
  sm:  8px
  md:  16px
  lg:  32px
  xl:  64px

Component naming

Component keys use kebab-case. The naming pattern component-variant helps agents understand when to apply each rule.

Pattern
Example keys
Notes
Default
button, card, input
Applied when no variant is specified
Named variant
button-primary, card-elevated
Most explicit — prefer this
Size variant
button-sm, button-lg
Size modifiers
State variant
input-error, input-disabled
Error and disabled states
Match your codebase. The most effective naming is the one that matches the component names already in your codebase. If your design system calls the pink badge StatusBadge, use status-badge in DESIGN.md — not badge-pink. Agents can map component names to DESIGN.md keys automatically when they match.

Names to avoid

Avoid names that encode the token value rather than its role:

  • color-1, color-2 — no semantic signal
  • dark-navy-blue-500 — descriptive, not semantic
  • bigButton — camelCase is inconsistent with the kebab-case convention
  • NEW_primary — SCREAMING_SNAKE_CASE is not valid
Writing for AIVersioning