Marcus Andrey Study
Ler em português Library

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 bascule bridge over a channel: two quays, a leaf hinged on each, and the same block standing on both shores. Bring the pointer to the middle of the channel and the two leaves come down until they meet level; move out over the quays and they lift again. That's this step: the Figma library and the code are two shores holding the same component, and the work is keeping a deck between them that both sides can cross. This step has four lessons: building a Figma library, Code Connect and the design-code bridge, Storybook and living documentation, and versioning and releases.Illustration: Marcus Andrey, drawn with Hairline (MIT, Lucas Marques).

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

Harbour Foundations published as a library
  • 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
Harbour Components uses Foundations
  • 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
Harbour's Figma library as two files, read from the pages panel. Foundations holds the variables and styles; Components uses them and holds the components, one page each, in alphabetical order. Every file opens with the same three pages, so people always know where the version, the instructions and the changes are. The page names and the split are Harbour's choice, not a Figma rule.

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

VariableTypeMode 1Mode 2Code syntax (Web)
Primitives · one mode, hidden from publishing
color.blue.600Colour#1F5FAE(one mode)not published
color.blue.400Colour#5B95DB(one mode)not published
color.ink.900Colour#14202B(one mode)not published
color.sand.50Colour#FBF8F2(one mode)not published
space.3 · space.4Number12 · 16(one mode)not published
Colour · modes Light and Dark
color.action.primaryColour→ blue.600→ blue.400var(--hb-color-action-primary)
color.text.defaultColour→ ink.900→ sand.50var(--hb-color-text-default)
color.surface.defaultColour→ sand.50→ ink.900var(--hb-color-surface-default)
Density · modes Comfortable and Compact
space.inset.mdNumber→ space.4 (16)→ space.3 (12)var(--hb-space-inset-md)
Harbour's tokens as Figma variables, in three collections. Primitives hold raw values and stay out of the published library, so designers pick meanings, not hex codes. Semantic variables are aliases: in each mode they point at a different primitive. The code syntax field is what Dev Mode shows a developer, so it carries the same name as the CSS custom property.

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.md is 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.control to 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 it Type in 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.600 instead of action.primary and 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)

  1. Write the pages of your team's main Figma file as a list, top to bottom.
  2. Mark each one: would a new designer know what it's for from the name alone?
  3. 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

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Tokens from Figma to code · Themes and modes · Variants, properties and slots · Design a component with variants in Figma · Handoff to developers

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close