Figma Components and Variants: A Practical Guide for Real Product Files

Quick answer

A component in Figma is a reusable master (button, input, card); an instance is a linked copy that updates when the master changes. Variants are alternate versions of the same component—size=sm|md, state=default|hover—stored in one component set. Use component properties (boolean, text, instance swap) for options that should not multiply into dozens of variant rows. Name properties for handoff (state=pressed, not Variant 4), publish from a library file, and never detach without a reason. For hover and prototype wiring, continue to interactive components; for file structure, see organize a Figma file and the Figma guides hub.

---

Who this is for

• New UI designers who outgrew copy-paste frames.
• Developers reading Figma files who need to know what “instance” means in Dev Mode.
• Teams about to publish their first shared library.

---

Components vs instances (30-second model)

Term	What it is	When to edit
Component	Master definition	In the library or Components page
Instance	Linked copy on a screen	Override text, icons, or exposed properties
Detached instance	Broken link—becomes regular layers	Avoid unless exporting one-offs

Verdict: screens should be mostly instances, not duplicated masters. If you fix a bug, fix the component, not fifty frames.

---

Create your first component

1. Select a button frame (auto layout recommended—see Auto Layout patterns).
2. Press ⌥⌘K (Mac) or Ctrl+Alt+K (Windows/Linux) or use Create component in the right panel.
3. Name it Button/Primary (slash groups in the assets panel).
4. Drag from Assets to place instances on a test screen.
5. Change the master label—instances update unless you overrode that layer.

Common mistake: grouping random layers into a component without auto layout—padding changes on one size will not propagate cleanly.

---

When to add variants

Add variants when the same component needs multiple visual versions that share structure:

• Button sizes (sm, md, lg)
• Input states (default, error, disabled)
• Card layouts (with/without media)

Do not create variants for entirely different components (a navbar vs a footer). Those are separate masters.

Build a variant set

1. Select your base component → Combine as variants (or add variants from the right panel).
2. Figma creates a component set with a purple dashed boundary.
3. Add variant properties: Size, State, Icon (boolean), etc.
4. Design each cell in the matrix—keep layer names consistent across variants so overrides work.

Good property	Bad property
State=Default	Property 1
Size=md	big (unscoped)
Icon=true	Duplicate frames named Button copy 3

---

Component properties (reduce variant explosion)

Figma lets you expose:

• Boolean — show/hide icon, toggle badge
• Text — button label, helper copy
• Instance swap — swap leading icon component
• Variant — pick among variant rows (built-in)

Pattern: use boolean + text for simple toggles; reserve variants for changes that affect layout, color, or border.

Example: a disabled button might only need lower opacity and cursor notes—sometimes a boolean is enough. If disabled changes height because label wraps, use a variant.

For advanced interaction (hover, pressed), read interactive components—that guide assumes you already understand variant sets.

---

Nesting components (cards, forms, modals)

Real UIs nest instances:

Card (instance)
  └─ Button/Primary (instance)
  └─ Badge/Status (instance)

Rules:

• Publish atoms (button, input) before molecules (card, form row).
• Expose only properties the screen designer needs—hide internal icon slots.
• Document behavior in component descriptions (Dev Mode checklist).

Forms are a stress test—see designing forms in Figma for validation and error variants.

---

Overrides: what you can change on instances

Safe overrides	Risky overrides
Text content	Detaching to “fix” one pixel
Instance swaps (icons)	Deleting structural layers
Exposed boolean toggles	Renaming layers inside the instance

Reset overrides from the right panel when an instance drifts too far from the master.

---

Libraries and publishing

1. Keep masters in a library file (🧩 Components page).
2. Publish when changes are reviewed (multiplayer etiquette).
3. Accept updates in consumer files—scan for broken overrides after breaking changes.
4. Pair color and type with semantic color tokens and typography scales.

Team size	Publishing cadence
Solo	Publish when a feature ships
2–5 designers	Weekly or per sprint
Large system	Versioned releases + changelog in descriptions

---

Variants + variables (2026 workflow)

Bind fills and text to variables inside components so modes (light/dark) do not require duplicate variant rows. Start with variables & modes explainer and dark mode tokens.

Rule of thumb: variants for structure and interaction; variables for theme and brand scale.

---

Handoff checklist for components

Before engineers build:

Check	Pass?
Instances used on delivery frames, not detached copies	☐
Variant property names match spec language	☐
Text styles and color variables bound—not hex one-offs	☐
Descriptions explain behavior variants cannot show	☐
Dev Mode shows expected default variant	☐

Cross-check with best dev handoff plugins if your team uses Inspect extensions.

---

Common mistakes

1. Variant matrix too large — split into two component sets (e.g., Button and IconButton).
2. Inconsistent layer names — overrides fail silently across variants.
3. Detaching to ship faster — creates fork debt; use booleans or instance swaps instead.
4. Publishing daily without review — breaks consumer files; batch publishes.
5. Skipping auto layout — responsive buttons break when copy changes.

Beginners also hit these in biggest Figma mistakes—worth a team read.

---

Recommended learning path

1. Master single components + instances on one screen.
2. Add a small variant set (button sizes).
3. Introduce component properties (boolean icon, text label).
4. Publish a library and consume it in a second file.
5. Layer variables for theme, then interactive prototypes for demos.

---

FAQ

How many variants are too many?

If you cannot explain the matrix in one sentence (“size × state”), split the component. Double-digit variant counts often mean you need booleans, nested instances, or variables.

Should developers use variant names in code?

Align with engineering on a token map—Figma State=Error might become error in React. Document the mapping in component descriptions or your Notion spec (Notion × Figma workflow).

Component vs style—what is the difference?

Styles (color, text, effects) are reusable attributes. Components are full UI pieces. Use both: styles inside components.

Can I migrate Sketch symbols to Figma components?

Yes on import—see import Sketch files—then rebuild variant properties; do not assume 1:1 parity.

---

Summary

Components are masters; instances are linked copies; variants handle visual alternatives in one set; properties keep the matrix manageable. Name for handoff, nest thoughtfully, publish libraries with discipline, and bind variables for theme. Next: interactive states, forms, and Dev Mode prep.