How to Build a Component Library in Figma

A component library is the foundation of any scalable design workflow. Built well, it saves hours every week. Built poorly, it becomes technical debt that everyone ignores.

Naming conventions

Consistent naming is the difference between a library people use and one they abandon. Figma uses the / character to create hierarchy in component names.

Structure your names as: Category/Component/Variant

Examples:

• Buttons/Primary/Default
• Buttons/Primary/Hover
• Inputs/Text/Default
• Inputs/Text/Error
• Navigation/TopNav/Desktop

This hierarchy shows up in the component picker and in the assets panel. Teams can navigate your library without needing to read documentation first.

Avoid names like Button copy 2 or New button. Be ruthless about keeping names clean — messy names signal a messy library.

Creating variants

Variants let you group related component states together into a single component with switchable properties. Instead of five separate button components, you have one button component with five variants.

To create variants: make your base component (Cmd+Alt+K), then right-click and "Add variant." Figma adds a variant frame. Keep adding until you have all your states.

The key is the Variant Properties panel that appears on the component set. Name your properties and values explicitly:

• Property: State, Values: Default, Hover, Pressed, Disabled
• Property: Type, Values: Primary, Secondary, Destructive, Ghost
• Property: Size, Values: Small, Medium, Large
• Property: Icon, Values: None, Left, Right

Figma generates a grid showing all combinations. You don't need to fill every combination — just the ones you'll actually use.

Component properties

Component properties are separate from variant properties. They let instances customize specific aspects without switching to a different variant.

The three types you'll use most:

Text properties: Expose a text layer so instances can change the label. Your button's label becomes a property called "Label" rather than a nested layer that requires double-clicking to edit.

Boolean properties: Toggle a layer's visibility. Use this for optional icons, badges, or indicators. "Has icon" as a boolean property is cleaner than maintaining two variants.

Instance swap properties: Let instances swap out a specific nested component. The icon inside a button becomes an Instance Swap property called "Icon" — the instance can use any icon from your icon library without entering the component.

To add these: select the component, go to the right panel, and click "+" in the Component Properties section. Then link each property to the appropriate layer.

Try Figma Free

Nesting components

Components can contain other components. An input field component might contain a label component, an icon component, and a helper text component. A card might contain a button, an avatar, and a tag.

Nesting is how you build a coherent, maintainable system. When the base component updates, every component that includes it updates too.

Practical rule: if the same element appears in three or more places, it should be its own component that others nest. If it only appears in one context, it doesn't need to be a standalone component.

Publishing to a team library

Libraries in Figma are published from within a file. Anyone on your team can then enable the library and use your components in their own files.

Steps:

1. Build your components in a dedicated library file (not a working design file)
2. Click the Figma menu → "Publish styles and components"
3. Review what you're publishing — you can exclude drafts or works in progress
4. Publish

Team members go to Assets panel → the team libraries icon → toggle on your library.

When you update components and republish, team members see a notification to accept the updates. This keeps everyone on the same version.

Documenting components in Figma

Add documentation directly in Figma using:

• Component descriptions: Right-click a component → "Edit description." This text appears in the assets panel when someone hovers the component. Use it to explain when to use this component vs alternatives.
• Annotation frames: Create a separate page in your library file called Documentation. Build annotated examples showing correct and incorrect usage.
• Links to Storybook: In the component description, add a link to the corresponding Storybook story.

The code-side equivalent: Storybook

Figma handles the design side. On the engineering side, Storybook is the equivalent — a component library in code where developers can browse components, see all their states, and read usage documentation.

The goal is alignment between Figma and Storybook. Every component in Figma should have a matching Storybook story. When the two drift apart — when Figma has a variant that Storybook doesn't implement — bugs happen and trust erodes.

Some teams use tools like Chromatic (Storybook's visual testing platform) to automatically compare Figma designs against rendered components. It's worth exploring once your system matures.

Maintenance habits

A library that no one maintains becomes a liability. Build these habits from the start:

• Audit unused components every quarter and archive them
• Don't add a new component until three teams have asked for it (prevents one-off proliferation)
• Version your library — use Figma's branching to test major changes before publishing them
• Treat the library file as a shared resource, not anyone's personal workspace

A solid component library takes 2–4 weeks to build from scratch for a typical product. The return on that investment is immediate.