Design System Naming Conventions Made Simple

You can design the most elegant component in the world —
But if it’s named Button2_final_FINAL_v3, no one will ever use it correctly.

Naming conventions are the backbone of scalable design systems.
They bring clarity, predictability, and flow to your components, tokens, and documentation.

Here’s how to create naming conventions that work — and stick.

🧠 Why Naming Conventions Matter

• Findability: Components show up instantly in search

• Clarity: Designers and devs know what’s what

• Consistency: Reduces duplicates, errors, and rework

• Scalability: Easier to grow a system without confusion

💬 The name is the interface of your design system.

🛠️ Where Naming Conventions Apply

• ✅ Components (e.g., Button, Modal, Card)

• ✅ Variants (e.g., Primary, Hover, Disabled)

• ✅ Tokens (e.g., color.primary.500, spacing.md)

• ✅ Layers and frames in Figma

• ✅ Documentation references and links

🔤 Best Practices for Naming Design System Components

1. Use a Clear Hierarchy

✅ Start with the object → then type → then state
Example:
Button / Primary / Hover
Card / Image-Left / With CTA

💬 Think like a folder structure.

2. Stick to Lowercase or Title Case (Consistently)

✅ Decide: camelCase, kebab-case, snake_case, or Title Case — and commit.
Figma often works best with Title Case for visual clarity.
Tokens typically use kebab-case or dot.notation.

3. Be Descriptive, Not Clever

✅ Button / Warning is better than Button / Orange
✅ Input / With Icon is better than Input / Fancy

💬 Your future teammates will thank you.

4. Use Tokens Like a Language

✅ color.primary.500 — follows a visual and code logic
✅ spacing.lg — readable across design and dev
✅ font.body.lg.semibold — scoped, clear, scalable

💬 Tokens should feel modular, like Lego bricks.

5. Standardize States and Variants

✅ Use the same order and naming everywhere
Example:
Default → Hover → Focus → Active → Disabled

💬 State naming should be so predictable, it fades into the background.

🔁 Real-World Naming Systems

💬 Your system should follow your brand’s tone, scale, and structure.

🧩 How to Document Naming Conventions

• Create a naming convention page in your design system docs

• Add real-world examples and “bad vs good” practices

• Show how it maps to tokens, dev files, and UI search

💬 Documentation removes guesswork.

📘 Want a Starter Structure?

Sigma Design System uses a simple, scalable naming system — built for clarity and speed. Whether you're starting fresh or refining your current setup, it’s a smart reference point.