By Mehdi HassanHow do you build a component library in Figma?
You build a Figma component library in a dedicated library file, on top of variables, one component at a time, in the order your product uses them. Each component gets auto layout, token-based styling and a property panel that matches how the coded component will be configured. Then you publish it so product files use instances instead of copies.
The angle that makes a library useful rather than pretty is parity with code. If the Figma button has a variant called Type with options Primary and Ghost, and the React button has a prop called variant with options primary and ghost, a developer reads the design and knows exactly what to write. That parity is the core of a working system, as our guide to design systems for startups explains.
How do Figma component properties map to React props?
Figma's component properties map almost directly to React props. Variants become enum props, boolean properties become boolean props, text properties become string props or children, and instance swap properties become component or icon props. Treat the Figma property panel as the component's API.
Figma property | Use it for | React equivalent | Example |
|---|---|---|---|
Variant | Options that change appearance | Enum prop | size: sm, md, lg |
Boolean | Showing or hiding a part | Boolean prop | hasIcon, isLoading |
Text | Editable labels | String prop or children | label, helperText |
Instance swap | Swappable icons or sub-components | Component or icon prop | icon: Plus, Search |
Nested instance (exposed) | Configuring a child from the parent | Props passed through to a child | Avatar size inside a list item |
Variable mode | Theme or density context | Context provider or data attribute | Dark mode, compact density |
Name properties the way engineers will. If code uses size and variant, don't call them Scale and Kind in Figma. Agree on the names before building the first component, and write them in a shared table. Later, Figma Code Connect can map these properties to real code snippets in Dev Mode, but only if the two APIs already line up.
What should a Figma component library include first?
A Figma component library should start with the small set of components that appear on almost every screen. For most products that's form controls, buttons, feedback elements and a couple of layout containers. Build them well, with every state, before adding anything specialized. The list below is the pool to pick from, not a quota: start with the ones your screens actually use.
- Actions: button, icon button, link.
- Form controls: text input, textarea, select, checkbox, radio, switch.
- Feedback: badge, toast, inline alert, tooltip.
- Containers: card, modal or dialog, popover or dropdown menu.
- Navigation: tabs, sidebar item, breadcrumb.
- Data: table cell and row, empty state, skeleton.
Data-heavy products should prioritize the table early. It's usually the most complex component and the one most likely to be designed differently on every screen. Our SaaS dashboard design checklist covers what a good table needs.
How do you build one component step by step?
Build each component the same way, so the library stays consistent and developers learn one pattern. Here is the order we use, shown for a button.
Write the API first
List the props in a note next to the component: variant (primary, secondary, ghost, destructive), size (sm, md, lg), state (default, hover, focus, disabled, loading), iconLeft, iconRight, label. This list is the contract with code.
Build the base with auto layout
Create a frame with horizontal auto layout, padding from spacing variables, a gap token between icon and label, and hug contents width. See our guide to Figma auto layout for how these settings match CSS flexbox.
Apply tokens only
Fill, stroke, radius, padding and text color all use semantic variables. No raw values. This is what lets one component work in light and dark mode.
Add properties
Add a text property for the label, boolean properties for each icon slot, and instance swap properties so designers pick icons from the library's icon set.
Combine variants
Create variants for variant, size and state. Name the variant properties exactly like the props you wrote down. Only make a variant when the appearance actually changes.
Document and publish
Add a short description with usage notes and a link to the code component, then publish the library update with a change note.
How should you handle states and edge cases in components?
Handle states inside the component as variants, so every state a developer must build is visible in one place. At minimum that's default, hover, focus, disabled and, for anything async, loading. Inputs also need filled, error and read-only.
Edge cases are where handoff usually breaks. Show what happens with a very long label, a missing image, a zero count and a truncated name. Put these on a documentation frame next to the component rather than as extra variants. Our Figma handoff checklist lists the states developers most often find missing.
Hypothetical example: one table row, built for parity
For example, suppose a product has a users table. In Figma, the row component has variants for density (compact, comfortable) and state (default, hover, selected), a boolean for showing the checkbox column, and a nested avatar instance exposed so its size can be set from the row.
In React, the row takes density, isSelected and selectable props and renders the same avatar component. Hover isn't a prop because CSS handles it, so the Figma hover variant is documented as visual only. A developer looking at any table in the product files can read the row instance's properties and write the matching JSX without asking a question.
How do you organize and maintain a Figma component library?
Organize the library by component category, one page per group, with a cover page and a changelog. Keep the library file separate from product files, and make it the only place components are edited.
Pros
- Product designers build screens from instances, so fixes update everywhere
- Developers read props from the property panel instead of guessing
- New designers learn the product's patterns from one file
- Code Connect and AI tools work far better with consistent component APIs
Cons
- A library needs an owner, or it drifts away from code
- Publishing changes can break detached or overridden instances
- Too many components make the asset panel hard to search
- Parity with code needs regular checks as both sides change
If your team also maintains a marketing site, its section components follow the same rules but serve a different user, the marketer editing a CMS. Our guide to page builder blocks covers that version. The tokens underneath both should be the same Figma variables.
When is a Figma component library ready for developers?
A Figma component library is ready for developers when every component uses only tokens and auto layout, every property matches a code prop by name, and every state is drawn. If any of those three fails, developers will invent the missing parts and the build will drift from the design.
We build libraries this way because our designers and developers are the same team, so we feel any mismatch immediately. If you want a brand refresh or redesign explored in Figma first, our brand and design sprint is $3,000, fixed. See what's included on our pricing.
