Building a Component Library

A component library is the backbone of any scalable, consistent design system. Rather than redrawing a button, card, or navigation bar every time you need one, a component library lets you define an element once and reuse it infinitely — while guaranteeing that a single edit to the original propagates instantly across every screen in your project. Understanding how components work, how to organise them, and how to share them with a team transforms Figma from a drawing tool into a true design-system platform.

What Is a Component?

At its core, a component in Figma is a special type of frame that acts as the single source of truth for a repeating UI element. Every component exists in one of two roles: the main component or an instance.

The main component is the authoritative original. It is typically stored in a dedicated page (often named "🧩 Components" or "_Library") or published through a team library. When Figma refers to the assets panel, it is surfacing all main components that are available to the current file. Because the main component is the definitive version, designers treat it like production code — changes to it are intentional and carry consequences across the entire file or even across an organisation.

An instance is a linked copy of the main component that you place on the canvas. Instances inherit every property of the main component by default: fill colours, typography, layout, auto-layout settings, effects, and layer structure. However, instances also support overrides — locally applied changes such as swapping an icon, editing label text, or toggling a layer's visibility. Overrides affect only that specific instance and do not alter the main component or any other instance.

When you edit the main component, every instance in the file updates simultaneously. If you have 47 screens that each contain a primary button and you need to increase its corner radius from 4 px to 8 px, editing the main component makes that change everywhere in one action. This is the fundamental productivity gain that component libraries offer.

Detaching an instance (right-click → Detach Instance, or Ctrl/Cmd+Alt+B) converts it into a regular group or frame. The visual appearance is preserved at the moment of detachment, but the inheritance link is permanently severed. Detached frames no longer receive updates from the main component. Detaching is appropriate only when you need a one-off variation that genuinely cannot be expressed as a variant or override — it should be the exception, not the rule.

• Main component: stored in the assets panel or a dedicated page; the single source of truth.
• Instance: inherits all properties of the main component; overrides are local only.
• Edit propagation: changes to the main component update every instance across the file.
• Detach: converts the instance to a plain frame, permanently breaking the link.

Creating Components from Existing Elements

The most common workflow is to design an element normally — place shapes, text, icons, and auto-layout as you usually would — and then promote it to a component. Select the element on the canvas and press Ctrl+Alt+K (Windows) or Cmd+Option+K (Mac). Figma wraps it in a component frame marked with a hollow diamond icon in the layers panel, indicating it is now the main component.

Naming convention is critically important for a usable library. Figma reads forward-slash characters in a component's name as hierarchical separators. A component named Button/Primary will appear under a "Button" group in the assets panel, alongside Button/Secondary and Button/Ghost. Deeply nested paths like Form/Input/Text Field/Default are valid. Consistent, descriptive naming makes the assets panel searchable and logical for the whole team.

A well-built component is self-contained: it should not rely on a parent frame to give it a specific width, nor should it depend on styles defined outside itself. Using auto-layout with hug sizing (rather than fixed dimensions) is a best practice because instances can then resize predictably based on their content overrides.

Figma allows you to add a description and a link to each component through the right-hand panel when the main component is selected. A short description such as "Use for primary CTAs only. Min width 88 px." gives teammates the context they need without having to ask in Slack. This metadata is surfaced when a designer hovers over a component in the assets panel.

• Select any element and press Ctrl/Cmd+Alt+K to create a main component instantly.
• Use slash notation (Button/Primary) to group components hierarchically in the assets panel.
• Design components to be self-contained — they should not depend on external frame sizing.
• Add a description in component properties so teammates understand the intended usage context.

Component Variants

Before variants existed, designers created a separate main component for every state of a UI element: Button/Primary/Default, Button/Primary/Hover, Button/Primary/Disabled, and so on. Variants consolidate all these states into a single component set — a purple-bordered frame that groups related components — and expose them through named, typed properties.

To create a variant set, select two or more existing components and click the "Combine as variants" button in the right-hand Design panel, or add variants directly through the "+" button on the component's property row. A component set is defined by one or more variant properties. Each property has a name (e.g., State) and a list of values (e.g., Default, Hover, Pressed, Disabled). A second property, say Size, could hold Small, Medium, Large. The total number of variant combinations equals the product of all property values — in this example, 4 states × 3 sizes = 12 individual variants, all managed within one component set.

When a designer selects an instance on canvas, the right-hand panel displays dropdowns for each variant property. Switching from State: Default to State: Hover swaps the underlying component but preserves local overrides where the layer names match between variants. If the label text layer is called "Label" in every variant, a text override typed on the Default variant survives the switch to Hover. This is why consistent layer naming across all variants is essential — mismatched names break override preservation.

For prototype interactions, variant naming consistency becomes even more important. Interactive components allow Figma prototypes to trigger a variant swap on hover or click without linking separate frames. For this to work, the property values that change must be exactly the same string across all components in the set (capitalisation matters: Hover and hover are treated as different values).

• Variants group related states inside a single component set with named properties and values.
• Each property (e.g., State, Size) accepts multiple comma-separated values.
• Switching variants preserves text and icon overrides where layer names match exactly.
• Consistent property value naming across all variants is required for prototype interactions to work.

Consider a practical example. Below is a summary of how a button component set might be structured across two properties:

Slots, Nesting, and Component Composition

Component composition is the practice of building complex UI elements from smaller, independent components rather than drawing everything as a flat group. A Card component, for instance, might nest an Avatar instance, a Badge instance, and a Button instance inside it. Each nested element is called a nested component (or nested instance), and it retains its own override capability independently of the parent card.

This architecture is powerful because a change to the main Avatar component cascades into every Card that uses it, with no manual updates required. Composition also enforces a discipline of keeping each component small and focused — an Avatar should only concern itself with displaying a user image and online indicator, nothing more. This makes each component easier to test visually, easier to document, and easier to understand in isolation.

A common pattern is the slot — a placeholder layer inside a parent component that a designer can swap for a different instance. In Figma, this is achieved through the "Instance Swap" component property. You define a property on the main component that exposes a nested instance as swappable, so teammates can replace, say, a default icon with any icon from the icon library directly from the right-hand panel, without entering the component's layer structure.

The risk to manage is over-nesting. A component that is six layers deep in nested instances creates a layers panel that is difficult to navigate, slows Figma's rendering on complex files, and makes it harder for less experienced team members to understand the structure. A practical guideline is to nest no more than two or three levels deep, and to split very complex components (like a full navigation bar) into sub-components (logo, nav links, user menu) that are assembled on the canvas rather than all nested within one monolithic component.

Published team libraries extend the reach of composition beyond a single file. When you publish a library from one Figma file, every component and style in that file becomes available to any other file in the team's workspace. Teams typically maintain a dedicated "Design System" file that is published as the master library, and product designers work in separate feature files that consume that library. Changes to the master library are pushed as library updates that consuming files must accept.

• Nested components inside a parent retain their own independent override capability.
• Composition keeps individual components small, focused, and easier to maintain and test.
• Avoid over-nesting — more than two or three levels deep harms navigability and performance.
• Published team libraries allow components and styles to be shared across multiple Figma files.

Using the Assets Panel and Team Library

The assets panel (keyboard shortcut: Alt+2 or Option+2) is the primary interface for discovering and placing components. Its search bar filters components in real time by name — typing "card" instantly surfaces all components whose names contain that string. This is another reason slash-notation naming matters: descriptive, consistent names are the only text available for search.

Components are not the only asset managed through the panel. Colour styles (design tokens for fills, strokes, and effects) and text styles (predefined type scales) can be created in the same library file and published alongside components. When every fill in your library references a colour style named Brand/Primary/500 rather than a raw hex code, updating the brand colour in one place ripples through every component and every screen that uses that style. This is the practical implementation of design tokens within Figma.

When a library file's maintainer publishes an update — adding a new component variant, fixing a spacing issue in a card, or renaming a colour style — files that consume that library receive a notification. Team members must explicitly accept incoming changes to bring their file up to date. This deliberate acceptance step prevents unwanted changes from landing mid-presentation, but it requires team discipline: ignoring update notifications for weeks can lead to a file that is significantly out of sync with the current design system.

Enabling a library in a file is straightforward: open the Assets panel, click the book icon (Libraries), and toggle on any shared library available in the workspace. Once enabled, all components and styles from that library appear in the local assets panel as if they were part of the current file, ready to be dragged onto the canvas.

• The assets panel search bar filters components by name — consistent naming is critical for discoverability.
• Colour and text styles can be published alongside components to enforce design tokens across the system.
• Library updates require team members to accept incoming changes to stay in sync with the design system.
• Enabling a library in a file adds all its published components and styles to the local assets panel.

The following table summarises the key actions and their corresponding shortcuts or locations in Figma for building and managing a component library:

Bringing these concepts together, a well-structured component library starts with clearly named, self-contained main components, organises states and sizes through variant sets, uses composition and nesting to build complex UI from simple building blocks, and is distributed through a published team library so that every designer on the project works from the same authoritative source. Mastering this workflow is what separates a collection of artboards from a genuine, maintainable design system.