Design Systems · Step 5 · 9 min read
Building a Figma library
A Figma library is the design half of the system: the file other files pull components, styles and variables from. How to split it into files and pages, how Harbour's tokens become variables with modes, how components get properties that match code, and what publishing needs and which plan it takes.
A library is a promise to every designer who enables it: this is the real thing, and it'll still be here next month. A file full of good components isn't a library yet. It becomes one when other files can depend on it: named the way code is named, organised so people find things without asking, and published with a note that says what changed. This lesson is about building that half of the bridge well, so the next lesson can connect it to code.
What you'll be able to do after reading:
- Explain what a Figma library is and what can go in it
- Split a library into files and pages people can find their way around
- Turn a token set into variables, collections and modes
- Publish a library on purpose, with the right plan and a note for every change
1. What a library is, in Figma's words
Figma defines it plainly: "a library is a collection of design assets, like components, styles, and variables", which live in one file and "can be reused across different files" (Figma, Guide to libraries). A file can be published once it has at least one component, style or variable (Figma, Publish a library).
Plan: publishing libraries is on the Professional, Education, Organization, Government and Enterprise plans. On the free Starter plan you can make components, but you can't publish them for other files to use (Figma, Publish a library). Using variables inside one file works on all plans (Figma, Guide to variables).
If you came from What a design system is, this is the "component library" part of the four, seen from inside Figma. It's only half: the other half is the code, and the system is the agreement between them.
2. Files and pages people can find their way around
- Cover name, version, owner
- Read me how to enable, where docs live
- Changelog one entry per publish
- Foundations
- Colour variables, light and dark
- Type text styles
- Space, radius and density number variables
- Elevation effect styles
- Icons one component per icon
- Not for use
- Archive hidden when publishing
- Cover name, version, owner
- Read me how to enable, where docs live
- Changelog one entry per publish
- Components, A to Z
- Button component set + usage notes
- Dialog
- Sailing card
- Select
- Text field
- Not for use
- Building blocks hidden when publishing
- Deprecated kept until the next major
Figma doesn't tell you how to organise a library, so you decide, and you write the decision down. What Harbour does, and why:
- Two files, not one. Foundations (variables, text styles, effects, icons) changes rarely; components change every week. Splitting them means a colour change doesn't sit in the same publish as a new dialog, and teams that only need the foundations, like marketing, can enable just that file. Don't split further until a file gets slow or has two owners.
- The same first three pages in every file: a cover with the name, version and owner, a read-me with how to enable the library and where the docs live, and a changelog. Nobody should have to ask "which version is this?"
- One page per component, alphabetical, with the component set at the top and usage notes next to it.
- A clear place for what's not for use. Building blocks (the parts a component is made of) and deprecated components stay in the file but are hidden when publishing, so they don't show up in people's assets panel. Figma lets you right-click any asset in the library modal and choose Hide when publishing (Figma, Publish a library).
3. Tokens become variables
| Variable | Type | Mode 1 | Mode 2 | Code syntax (Web) |
|---|---|---|---|---|
| Primitives · one mode, hidden from publishing | ||||
color. | Colour | #1F5FAE | (one mode) | not published |
color. | Colour | #5B95DB | (one mode) | not published |
color.ink.900 | Colour | #14202B | (one mode) | not published |
color.sand.50 | Colour | #FBF8F2 | (one mode) | not published |
space.3 · space.4 | Number | 12 · 16 | (one mode) | not published |
| Colour · modes Light and Dark | ||||
color. | Colour | → blue.600 | → blue.400 | var(--hb-color-action-primary) |
color. | Colour | → ink.900 | → sand.50 | var(--hb-color-text-default) |
color. | Colour | → sand.50 | → ink.900 | var(--hb-color-surface-default) |
| Density · modes Comfortable and Compact | ||||
space. | Number | → space.4 (16) | → space.3 (12) | var(--hb-space-inset-md) |
In Figma, tokens live as variables. Figma lists six types (colour, number, string, boolean, and the newer timing and easing), and groups them in collections: "a set of variables and modes". A mode is "a list of values for a variable in a collection, storing one value per variable", which is how one variable can be blue.600 in light and blue.400 in dark (Figma, Overview of variables, collections, and modes). The theory is in Token tiers and Themes and modes; here is how Harbour lays it out:
- Primitives: one collection, one mode, raw values (
color.blue.600 = #1F5FAE,space.4 = 16). Hidden from publishing, so designers choose meanings, not hex codes. - Semantic colour: a collection with Light and Dark modes. Every variable is an alias: Figma lets "a variable reference other variables of the same type" (Figma, Create and manage variables).
- Density: a collection with Comfortable and Compact modes, for the staff console:
space.inset.mdis 16 in one and 12 in the other.
Three settings matter more than they look:
- Scoping limits "which properties the variable can be applied to", for number, colour and string variables. Scope
radius.controlto corner radius and nobody can use it as a gap by accident. - Code syntax: each variable can carry "one name per platform, including Web, Android, and iOS", and Dev Mode shows it in code snippets for CSS, SwiftUI and Compose (Figma, Create and manage variables). Set it to
var(--hb-color-action-primary)and the developer sees the real name, not a guess. - Modes on frames: objects start on Auto and "take on the mode of their parent container" (Figma, Modes for variables). Set Dark on the frame, and everything inside follows.
Plan: the number of modes per collection depends on the plan. Figma's plan page lists up to 10 on Professional, up to 20 on Organization, and unlimited modes with extended collections on Enterprise (Figma, Plans and features). Two modes for light and dark, and two for density, fit any paid plan. The path from these variables to code is in Tokens from Figma to code.
4. Components with properties that match code
A Figma component's properties are its API in design, and they should read like the code's API (see Anatomy and API of a component). Figma has five kinds: variant, boolean (which "only support layer visibility" for now), instance swap, text, and slot, "a flexible area in a component where you can add, edit, and rearrange content" (Figma, Explore component properties). Variants, properties and slots covers when to use which. In the library, three habits keep them honest:
- Same names as code where you can. If the code says
variant, don't call itTypein Figma. Where they differ, the next lesson's mapping has to translate, and every translation is a place to drift. - Fewer variants, more properties. A boolean for "show icon" beats doubling the variant set.
- Preferred instances on instance swaps, so the icon slot offers Harbour's icons first, not the whole library.
5. Publishing on purpose
Every publish asks for a description, and Figma shows that description when people accept the update and in the file's version history. People using the library see a badge and can "review and accept the updates" in their own time (Figma, Publish a library). That last point matters: a publish doesn't change anyone's file until they accept it. So:
- Write the description as a changelog line: what changed, and whether anyone needs to act.
- Publish in batches that match a release, not every time you nudge a pixel (Versioning and releases).
- Admins can set default libraries for a team or organisation, so every new file starts with Harbour enabled (Figma, Guide to libraries). That one setting does more for adoption than a launch email.
6. Common mistakes
- One giant file with everything, which gets slow and has nobody in charge of any part of it.
- Publishing the primitives, so people pick
blue.600instead ofaction.primaryand dark mode breaks. - Figma names that don't match the code names, with no one keeping the translation.
- Publishing with an empty description.
- Leaving deprecated components visible, so new work keeps using them.
- Building variants for every combination instead of using boolean, text and slot properties.
7. Vocabulary
| Term | Meaning |
|---|---|
| Library | A Figma file whose components, styles and variables other files can use |
| Variable | A named, reusable value in Figma: colour, number, string, boolean, timing or easing |
| Collection | A set of variables and the modes they share |
| Mode | One set of values for a collection, such as Light or Compact |
| Alias | A variable whose value is another variable |
| Scoping | Limiting which properties a variable can be applied to |
| Code syntax | The name a variable has in code, shown in Dev Mode |
| Hide when publishing | Keeping an asset in the library file but out of other people's assets panel |
8. Try it (no tools needed)
- Write the pages of your team's main Figma file as a list, top to bottom.
- Mark each one: would a new designer know what it's for from the name alone?
- Write the three pages every file should open with, and one page you'd hide.
Reflection questions: If a developer looked at your variables in Dev Mode today, would the names match anything in their code? Who decides when the library is published?
9. If you already practise
- Audit your published assets in the library modal: anything people shouldn't pick goes hidden.
- Fill in code syntax for every semantic variable, and check it against the CSS custom properties.
- Turn on scoping for spacing and radius variables, and see how many wrong uses disappear.
- Agree with engineering on one release rhythm for the library and the package.
Checklist
Learn more
- Figma Help Center: Guide to libraries in Figma · Publish a library · Overview of variables, collections, and modes · Create and manage variables and collections · Modes for variables · Explore component properties · Figma plans and features (all checked November 2026)
Books, courses and videos to go deeper
- Design SystemsAlla KholmatovaBook · Smashing Magazine, 2017 (Amazon)
- Atomic DesignBrad FrostBrad Frost, 2016 · free to read online (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
Tokens from Figma to code · Themes and modes · Variants, properties and slots · Design a component with variants in Figma · Handoff to developers