Component Variants in Design Systems: Naming, Organization, and Scale

Variants aren’t just nice to have —
they’re what make design systems flexible without becoming chaotic.

Done well, component variants allow you to handle every state, style, and context without duplicating work.
Done poorly, they cause confusion, inconsistencies, and bloated files.

Let’s break down how to name, organize, and scale component variants like a pro.

🧠 What Are Component Variants?

Variants are alternate versions of a component — like different button states, sizes, or styles — that live inside one unified component.

For example, a single Button component might have:

• Sizes: Small, Medium, Large

• Styles: Primary, Secondary, Ghost

• States: Default, Hover, Disabled

💬 Variants reduce duplication, improve consistency, and speed up design.

🛠️ Best Practices for Naming Component Variants

1. Use Clear Labels, Not Styles

✅ Primary, Secondary, Ghost
❌ Blue, Gray, Light

💬 Names should describe function — not color or cosmetics.

2. Follow a Consistent Order

✅ Start with type → size → state → optional modifiers
Example:
Button / Primary / Medium / Hover
Tag / Outline / With Icon / Disabled

💬 Predictable order means predictable behavior.

3. Group Similar Options Together

✅ In Figma, use property groups like:

• Style: Primary, Secondary, Ghost

• Size: S, M, L

• State: Default, Hover, Focus, Disabled

💬 This structure mirrors how devs build in code.

4. Use Tokens When Possible

✅ Apply tokens for color, spacing, and typography
✅ Avoid hardcoding visual styles inside variants

💬 Tokens make scaling and theming effortless.

5. Document Variant Usage Clearly

✅ Explain when to use each style (e.g., “Primary = main action”)
✅ Show visual examples with “Do” and “Don’t”
✅ Link to code or implementation references

💬 Documentation turns components into guidelines — not guesses.

🔁 How to Scale Variants Without Chaos

1. Start With the Essentials

✅ Build only what’s needed in v1 — common sizes, key states
✅ Avoid adding edge cases too early

2. Use Boolean Properties When Possible

✅ e.g., With Icon: true/false
✅ Reduces variant bloat

3. Audit and Clean Regularly

✅ Remove unused or duplicated variants
✅ Merge similar ones into a unified logic
✅ Keep file structure clean and labeled

✨ Real Example: Button Variants in Sigma

In Sigma Design System, our Button component includes:

• Styles: Primary, Secondary, Ghost, Danger

• Sizes: S, M, L

• States: Default, Hover, Focus, Disabled

• Modifiers: With Icon, Full Width

We use tokens for spacing, color, and typography — and every variant is documented in both Figma and our live docs.

📘 Want a Head Start?

Check out Sigma Design System — built with scalable variants, systemized naming, and ready-to-use component logic.