How to Build a Component Variant System in Figma

By following this guide, you will build a fully scalable component variant system in Figma that supports multiple states, themes, and responsive breakpoints. The whole setup takes roughly two to three hours, and the system you build will save your team significant time on every future project.

What You'll Build

• A base component architecture with nested primitives that compose into larger UI patterns
• A variant property structure that covers state, size, and theme variations without duplicating frames
• A variable-linked token layer that connects your component variants to your colour and spacing tokens
• A published, documented component set ready for developer handoff

Prerequisites

You will need a Figma account on a Professional, Organisation, or Enterprise plan. Component publishing requires one of those tiers. You should be comfortable with Figma's Auto Layout feature and have a basic understanding of local styles. This guide was written for Figma as of August 2026, using the Figma Variables API (v2) and the updated Component Properties panel released in early 2026.

Step 1: Audit What You Already Have

Before building anything new, take stock of your current file. Open your existing design file and run a quick component inventory. Use the Assets panel (keyboard shortcut: Shift + I) to see every local component in one place.

What should you look for in the audit?

Look for duplicate frames that represent the same component in different states. These are the components that will benefit most from a variant system. Common offenders include buttons, input fields, badges, and cards. Count how many one-off frames exist for states like hover, disabled, loading, and error.

In a typical SMB design file, you will find between 40 and 80 ungrouped component variants scattered across pages. Consolidating them into a proper variant system reduces component count by around 60 percent on average.

Common pitfall: Do not start building until you finish the audit. Skipping this step means you will rebuild components you already have, just with better naming.

Step 2: Define Your Variant Properties

Variant properties are the axes along which a component changes. Think of them as dimensions. A button component might have three dimensions: Size (Small, Medium, Large), State (Default, Hover, Pressed, Disabled, Loading), and Hierarchy (Primary, Secondary, Ghost).

How many properties should a single component have?

Keep it to three or four properties per component. More than four creates a combinatorial explosion. A button with four properties, each having four options, produces 256 variants. Most of those combinations will never be used. Stick to what your product actually needs.

Write your property structure in a simple table before you open Figma. A spreadsheet works well for this. List the component name, each property name, and all possible values for that property. This document becomes your source of truth.

Here is an example structure for a button:

Component: Button

Property 1: Size
  Values: SM | MD | LG

Property 2: Hierarchy
  Values: Primary | Secondary | Ghost | Danger

Property 3: State
  Values: Default | Hover | Focused | Disabled | Loading

Property 4: Icon
  Values: None | Left | Right | Only

This gives you 3 × 4 × 5 × 4 = 240 theoretical combinations. In practice, your designers will use around 30 to 40 of them regularly. The system supports all combinations without requiring you to build each one manually.

Step 3: Build Your Primitive Components First

A primitive is the smallest reusable unit in your system. Icon slots, text labels, state overlays, and loading spinners are all primitives. Build these before you build anything composite.

Why does building primitives first matter?

Composite components nest primitives. If you change a primitive, every composite that uses it updates automatically. This is the core efficiency gain of a well-structured system. If you build composites first, you end up with hard-coded values that break when requirements change.

Create a dedicated page in your file called _primitives. The underscore keeps it sorted to the top of the page list. Build each primitive with Auto Layout, set all spacing values to use variables (covered in Step 5), and name every layer semantically.

Use this naming convention for layers inside a primitive:

[ComponentName]/[Role]

Examples:
  Button/Label
  Button/IconLeft
  Button/StateOverlay
  Input/Placeholder
  Input/LeadingIcon

Step 4: Create the Variant Set in Figma

Now build the actual variant set. Select your base component frame and duplicate it for each value in your first property. Then select all those frames and use the Combine as Variants option from the right-hand panel. Figma will group them into a component set automatically.

What is the correct order for adding properties?

Add your most structurally significant property first. For most UI components, that is Size, because it affects layout dimensions. Then add Hierarchy, then State. Leave boolean properties (like Icon toggle) for last. This order makes the variant grid easier to read in the Assets panel.

After combining, open the Component Properties panel on the right side. Rename each property using clear, consistent names. Avoid abbreviations. Use State not St, and use Hierarchy not H. Your teammates will thank you during handoff.

Pro tip: Use the Figma Component Properties panel to expose nested instance swaps and boolean toggles to the parent level. This means a designer using your button component can toggle the icon slot on or off from the parent without digging into nested layers.

Step 5: Link Variables to Your Variants

Figma Variables (v2, released in 2025 and updated in early 2026) allow you to bind colour, spacing, radius, and typography values directly to your component variants. This is what makes a variant system respond to theme changes.

How do you connect variables to variant properties?

Create a variable collection called Tokens. Inside it, create groups for color, spacing, radius, and typography. Add modes for your themes, such as Light and Dark, or Brand A and Brand B if you work across multiple clients.

Bind variables to fill and stroke properties on each primitive layer. To bind a variable, click the fill swatch, then click the library icon (the four-square grid icon) in the colour picker. Select your variable from the dropdown.

Once every primitive is bound to a variable, your entire component system switches theme in a single click using the Mode toggle at the frame level. For teams working across Australian and Singaporean clients with different brand guidelines, this saves hours per project.

Here is an example of a semantic colour token structure:

Tokens/color/
  interactive/
    primary/default        → #0057FF (Light) / #4D8FFF (Dark)
    primary/hover          → #003FBF (Light) / #6BA3FF (Dark)
    primary/disabled       → #B3C9FF (Light) / #334C80 (Dark)
  feedback/
    error/default          → #D32F2F (Light) / #FF6B6B (Dark)
    success/default        → #2E7D32 (Light) / #66BB6A (Dark)
  surface/
    background             → #FFFFFF (Light) / #121212 (Dark)
    elevated               → #F5F5F5 (Light) / #1E1E1E (Dark)

Step 6: Build Interactive Components for Prototype States

Interactive Components let designers click through prototype states inside a component without leaving the prototype flow. To enable this, add interactions directly inside your component set using the Prototype panel while in component editing mode.

For a button, you would add a Mouse Enter interaction that switches the variant to the Hover state, and a Mouse Leave interaction that switches it back to Default. For a checkbox, you add a Click interaction that toggles between unchecked and checked.

When should you skip interactive components?

Skip them for complex components with more than three interactive states. The prototype wiring becomes hard to maintain. For those components, use separate flows in your prototype file instead of interactive component states.

Common pitfall: Do not mix interactive component interactions with top-level prototype flows. They conflict. Use one or the other for a given component in a given prototype.

Step 7: Annotate and Document Your Components

A component system no one understands does not get used. Add a Documentation page to your file. For each component, include a usage section that covers when to use it, when not to use it, and any known constraints.

Use Figma's Annotation feature (available in all paid plans as of 2026) to add inline notes directly on the canvas. Tag each annotation with the relevant property name. This makes the handoff review faster for developers.

If your team uses a design system documentation tool like Supernova or ZeroHeight, export your component data using the Figma REST API. Both tools support direct Figma integration and will pull component descriptions you add in the component description field automatically.

If you are planning a larger content and branding system alongside this design work, a tool like the Lenka Studio brand health score can help you identify gaps in your brand consistency before you bake incorrect patterns into a component library.

Step 8: Publish and Share the Library

When your components are documented and tested, publish the library. Go to Assets > Team Library > Publish. Write a clear publish message describing what changed. This message appears in the update notification that teammates see in their files.

How do you version your component library?

Figma does not have native semver versioning. Use the publish message as your version log. Start each message with a version tag, for example: v1.2.0 — Added Danger variant to Button; updated Input error state colours. Keep a running changelog in a Notion doc or a CHANGELOG page inside the Figma file itself.

For teams at design agencies or product companies in Canada and the US, connecting your Figma library to a CI/CD pipeline using the Figma REST API ensures developers always have the latest token values in code. See the Figma Platform documentation for the GET /v1/files/:file_key/variables/published endpoint.

Pro tip: Restrict publishing permissions to one or two system owners. Open publishing creates drift. Treat your component library like a codebase, with pull request reviews before changes go live.

Frequently Asked Questions

Next Steps

Your component variant system is now live and published. The next logical step is to connect it to your codebase via a tokens pipeline, so developers pick up changes without manual re-entry. After that, run a usability review with your team to catch any missing states before the system goes into production use.

If you want a second set of eyes on your component architecture before you scale it across a product, the team at Lenka Studio works with SMBs across Australia, Singapore, Canada, and the US to audit and build design systems that hold up at scale. Get in touch and we can take a look at where your current system needs the most attention.