How to Structure a Figma Component Library

A Figma component library that isn't structured well becomes a liability faster than almost anything else in design. Designers can't find what they need, so they build new components that duplicate existing ones. Engineers get handed inconsistent designs because each designer is working from different parts of the file. The library becomes an archaeological site — layers of old decisions on top of old decisions, with no one confident about what's current.

Structuring a Figma library well from the start isn't complicated, but it requires making deliberate decisions upfront that most teams skip. This post covers how to do it: the three-level hierarchy, naming conventions, Figma variables, auto-layout, documentation, publishing, and the mistakes that cause library structures to fall apart.

The Three Levels of a Component Library

Before you open a new Figma file, understand that a component library has three distinct levels that need to be separated — both conceptually and structurally.

Foundations are the atomic design decisions: color tokens, typography scale, spacing, border radius, shadow, and iconography. These are not components. They're the raw material that components are built from. In Figma, foundations live as Variables (for tokens) and as reference pages (for visual documentation of the token set).

Components are the reusable UI building blocks: buttons, inputs, checkboxes, modals, tables, badges, navigation, cards. Each component has defined variants, states, and properties. These are the things that end up in the Figma asset panel that designers drag onto their canvases.

Patterns are documented combinations of components that solve specific design problems: an empty state pattern, a settings page layout, a data table with pagination and filtering. Patterns aren't necessarily published as components — they're often reference designs with annotations. They answer "how should we design this type of screen" rather than "here is a reusable element."

These three levels need to be organizationally separated. Mixing foundations in with components causes confusion. Treating patterns as reusable components causes fragility — patterns that are too specific to be truly reusable end up getting used incorrectly.

Figma Library File Structure

A clean Figma library file has this page structure:

Page 1: Cover — A simple page with the library name, version, and last-updated date. This gives a quick read on the file's status.

Page 2: Tokens — Visual documentation of your token system: color swatches with token names, type scale samples, spacing scale, shadow examples. This is reference material for anyone who needs to understand the token system. The actual tokens live in the Variables panel, not on this page — but this page makes them visually scannable.

Page 3: Icons — Your icon set, organized into categories, each icon labeled with its name. Icons are technically components in Figma but they're organized separately because there are typically many of them and they need their own browsing experience.

Pages 4–N: Components — One page per component category works well for larger libraries. Alternatively, one page for all components is manageable for smaller ones. Common categories: Actions (buttons, links), Inputs (text, select, checkbox, radio, toggle), Feedback (toast, alert, badge, spinner), Overlays (modal, drawer, tooltip, popover), Navigation (nav bar, sidebar, tabs, breadcrumb), Data Display (table, card, avatar, list), Layout (divider, container, grid reference).

Final Page: Patterns — Annotated reference designs for common patterns. Not published as components — these are for designer reference.

Keep the library file clean. Never put working designs in the library file. The library file is a product you maintain — treat it with the discipline you'd apply to production code.

Naming Conventions That Match Engineering

This is where most Figma libraries fail. Components get named for what they look like in design rather than what they're called in code. The result is that every design handoff starts with a translation step — "what they call a 'card container' in Figma, we call a 'Panel' in our codebase."

The rule: name your Figma components to match your engineering component names.

This requires a conversation with engineering before you start naming things. What is the button component called in the codebase? Button. What is the modal called? Modal. What is the badge called? Badge. Use those names in Figma.

Figma uses a slash-separated naming convention that creates nested groupings in the assets panel. Use it like this:

• Button/Primary → renders as "Button > Primary"
• Button/Secondary
• Button/Ghost
• Button/Destructive
• Input/Text
• Input/Select
• Input/Checkbox
• Modal/Default
• Table/Row/Default
• Table/Row/Selected

The first segment should be the component name as engineering knows it. The subsequent segments are variants. This way, when an engineer opens a Figma file and sees a "Button/Primary," they know immediately what component to use in code and which variant prop to set.

For component properties inside the component, use the same prop names engineering uses. If the button in code has a size prop with values sm, md, lg — the Figma component's property should be called Size with options sm, md, lg. Not "Small/Medium/Large," not "S/M/L." Exact match.

Using Figma Variables for Design Tokens

Figma Variables are the right way to implement design tokens in Figma. They replaced Styles as the token layer and support modes (light/dark, themes) in a way Styles don't.

Set up your Variables in this collection structure:

Collection: Color

• Group: Primitive → blue/100, blue/200 ... blue/900, neutral/100 ... etc.
• Group: Semantic → color/primary/default, color/primary/hover, color/text/primary, color/surface/default etc.
• Semantic variables reference primitive variables. Don't use hex values in semantic tokens — always reference a primitive.

Collection: Spacing

• space/1 = 4px
• space/2 = 8px
• space/3 = 12px
• space/4 = 16px
• space/6 = 24px
• space/8 = 32px
• space/12 = 48px
• space/16 = 64px

Collection: Radius

• radius/sm, radius/md, radius/lg, radius/full

Collection: Shadow

• shadow/sm, shadow/md, shadow/lg

Collection: Typography (if your Figma plan supports text variables)

• Font size, line height, font weight values

Connect every fill, stroke, and corner radius in your components to a Variable, not a hardcoded value. This is the difference between a system that can respond to theme changes and one that requires manual updates across hundreds of components.

When you add dark mode or a secondary brand theme, you add a new mode to the collection and remap the semantic variables. Every component that uses semantic variables updates automatically.

Auto-Layout Best Practices for Components

Auto-layout is what makes components scale correctly when text content changes or when used in different contexts. Every component should use auto-layout. If you're building components without it, you're building fragile components.

A few specific rules:

Use spacing tokens in auto-layout. When you set padding on a component, use a spacing variable — not a hardcoded number. space/4 (16px), not 16. This connects the component's spatial behavior to the spacing system.

Design for content variance. Your button component should handle both "Save" (four characters) and "Save changes and continue to next step" (much longer). Test your components with realistic content extremes before publishing. Components that break with unusual content are common and avoidable.

Use fixed dimensions only when truly fixed. Buttons have a minimum width but usually grow with content. Table cells have a fixed width (because the table is a grid). Modals have a fixed maximum width but may be responsive. Know which dimensions are fixed and which are flexible, and set auto-layout accordingly.

Layer your auto-layout. A button has auto-layout for its internal padding. A button group has auto-layout for the spacing between buttons. A form has auto-layout for the spacing between form fields. Each layer is responsible for its own spatial relationships. Don't try to control all spacing from the parent — let each component manage its own internals.

Set fill behavior on text layers. Text inside a component should usually be set to "Fill container" horizontally so it responds to the component width. A common mistake is setting text to "Fixed" width in a component that's meant to be flexible — the text clips or truncates unexpectedly.

How to Document Components in Figma

Documentation in Figma works best as a combination of in-file annotations and external documentation (Storybook, Zeroheight, or a custom site). Figma alone is not enough — but good in-file documentation reduces the friction of getting to the external docs.

In Figma, document each component section with:

Component header frame: Place each component category in a frame with a clear header: "Button," "Input," etc. Add a one-sentence description of what the component is and a link to the external documentation if it exists.

Variant matrix: Show all variants × states in a grid. Rows = variants (Primary, Secondary, Ghost). Columns = states (Default, Hover, Focus, Disabled, Loading). This lets designers see every combination at a glance.

Do / Don't examples: Add at least one "Do" and one "Don't" example per component. Real product context, annotated with a brief explanation. These prevent misuse better than written rules.

Spec annotations: For any non-obvious spacing or behavior, add a spec annotation. Don't annotate what's already visible — annotate what engineers need to know to implement it correctly. Focus states, interaction timing, responsive behavior.

The Figma component description field (accessible via right-click → Component properties → Description) is also useful. Add a one-liner and a link to docs. Designers see this in the asset panel tooltip.

Publishing and Updating a Team Library

Publishing the library is the step that makes it available to all design files in the team. In Figma, team libraries work at the Team level (Figma Organization) or Project level (depending on your plan).

Before publishing the first time:

• Run through every component and confirm all variants are correct
• Confirm all text and fill styles are connected to Variables, not hardcoded
• Confirm component names match engineering names
• Confirm the cover page shows the current version

When you publish, all team files get a notification that the library has been updated. For major updates (new components, changed APIs), add a changelog entry in the cover page so designers know what changed and what they need to update in their files.

For ongoing updates, follow a versioning discipline: minor additions (new variant of an existing component) can be published anytime. Breaking changes (renamed component, changed property API) should be batched and communicated clearly, with a migration note.

A library update that breaks existing designs — because a component was renamed or a property was removed — will create resentment in the design team. Over-communicate changes. Document them. Give designers time to update their files before you publish if possible.

Common Structural Mistakes

Putting working designs in the library file. The library file should only contain published components and reference material. When working designs live alongside components, the file gets cluttered, the component organization gets confusing, and the published assets become unreliable.

Using Styles for color tokens instead of Variables. Styles don't support modes. If you want to support dark mode or theming, you need Variables. Migrating from Styles to Variables later is painful. Start with Variables.

Naming components for appearance, not function. "Blue rounded button" tells you nothing about when to use it or how to refer to it in code. "Button/Primary/Default" tells you exactly what it is, what variant it is, and what state it's in.

Publishing a component before all its states are designed. An incomplete component in a published library is worse than no component — designers use it, hit the missing state in their designs, and build around it. Now you have a component in the library and a bunch of overrides in design files. Finish the component before publishing.

No clear owner for library maintenance. The library needs an owner who reviews contributions, approves changes, and publishes updates. A library with no owner drifts within months. Assign ownership explicitly — even if it's one senior designer spending a few hours per week.

Summary

Structure your Figma component library in three levels: foundations (tokens), components (reusable UI elements), and patterns (reference combinations). Name everything to match engineering. Connect all fills and spacing to Variables. Use auto-layout on every component. Document with variant matrices and Do/Don't examples. Publish deliberately, with a changelog, and maintain clear ownership.

The structural discipline upfront saves enormous time later. A well-organized library that designers trust and use is the foundation that makes everything else in your design system work.

If you're building a design system for your SaaS product and want to see how we approach this work, our design subscription includes design system work as part of ongoing engagements — including Figma library structure and handoff to engineering.

Frequently Asked Questions