Skip to content
NewTemplates & toolkits are on the way — join the waitlist
Hecham Gazhi

Design Systems · Lesson 10 / 13

Design systems in Figma

How to build a design system library in Figma: file structure, variables and modes, styles, components with auto layout, variants and properties, naming, publishing libraries, updates and keeping it healthy.

5 min read · 5 quiz questions

Planning the library

Figma is the most widely used tool for building and sharing design system libraries. A well-structured library makes components easy to find and use, and makes updates safe.

One file or several?

  • Small systems: one library file with foundations and components.
  • Larger systems: separate files, e.g. Foundations (variables, styles, icons), Components, and Patterns/Templates. Product files enable only what they need.
  • Multi-brand or multi-platform: shared core components plus brand or platform files, using variable modes.

Pages inside the library

  • Cover (name, version, status, links to docs).
  • Getting started and changelog.
  • Foundations: colour, typography, spacing, elevation, icons.
  • One page per component or component group (Buttons, Inputs, Navigation…).
  • A hidden or archive page for work in progress.

Variables

Figma variables store reusable values — the design-tool version of design tokens. There are four types: colour, number, string and boolean.

  • Organise variables into collections, e.g. Primitives and Semantic (and optionally Component).
  • Semantic variables alias primitives: color/text/primary → gray/900.
  • Collections can have modes: Light and Dark, Comfortable and Compact, Brand A and Brand B. Switching a frame's mode updates every variable inside it.
  • Use scoping so variables only appear where relevant (e.g. spacing variables only in gap and padding fields).
  • Use number variables for spacing, radius and sizes, and bind them in auto layout and corner radius fields.
  • Add code syntax to variables so Dev Mode shows the matching CSS/iOS/Android token names.
Exampletext
Primitives (collection, 1 mode)
  blue/500 = #146EF5      gray/0 = #FFFFFF     gray/900 = #0F0F0D
  space/4 = 16            radius/md = 8

Semantic (collection, modes: Light | Dark)
  color/surface         = gray/0     | gray/950
  color/text/primary    = gray/900   | gray/50
  color/action/primary  = blue/500   | blue/300
  space/inset/md        = space/4    | space/4

Styles

Variables cover single values. Styles cover composite values:

  • Text styles — font family, size, weight, line height, letter spacing (and they can reference variables).
  • Effect styles — shadows and blurs for elevation levels.
  • Grid styles — layout grids for each breakpoint.
  • Colour styles — older approach; many teams now use colour variables instead, or styles for gradients and images.

Building components

  1. 1Build with auto layout so components resize with their content and padding/gap are explicit.
  2. 2Bind fills, strokes, radius, padding and gaps to variables; apply text styles to all text.
  3. 3Create one main component per variation, then combine them into a component set with variant properties (e.g. Variant, Size, State).
  4. 4Add component properties instead of more variants where possible: text (button label), boolean (show icon), instance swap (which icon).
  5. 5Use nested instances (e.g. the Icon component inside Button) and expose their properties when useful.
  6. 6Set resizing (hug / fill / fixed) and constraints correctly so instances behave in any layout.
  7. 7Add a description and a link to the documentation in the component's properties.

Common mistake: Creating a variant for every combination when a boolean or instance-swap property would do. A button with 4 icon positions as variants quadruples the component set; one boolean and one instance swap keep it small.

Naming conventions

ThingConventionExample
ComponentsClear noun, slash for groupingButton, Input / Text field, Navigation / Tab bar
Variant propertiesSame names as code propsVariant=Primary, Size=MD, State=Hover
Internal / private componentsPrefix with . or _ so they aren't published_Button base, .Icon slot
VariablesSlash groups from general to specificcolor/text/secondary, space/inset/md
LayersDescribe the partLabel, Leading icon, Container

Publishing and updating

  • Publish the file as a team library; product files enable it from the Assets panel.
  • Write a short description with every publish ("Added Size=SM to Button; fixed focus ring colour").
  • Consumers receive an update notification and can review and accept changes.
  • Changes to properties flow to all instances; overrides (like changed label text) are preserved when layer names and structure stay the same.
  • Renaming layers or restructuring a component can reset overrides — plan breaking changes carefully.
  • Use branches (on supported plans) to work on changes without affecting the published library, then review and merge.

Keeping the library healthy

  • Use library analytics (on supported plans) to see which components are used most, and which are often detached.
  • A frequently detached component is a signal that it doesn't meet needs — talk to the teams detaching it.
  • Mark deprecated components clearly (e.g. prefix with "⚠️ Deprecated") and point to the replacement.
  • Keep design and code in sync: same names, same properties, same states.
  • Use Dev Mode and Code Connect (where available) so developers see the real component code for each instance.

Do

  • Use variables with modes for themes and density.
  • Build every component with auto layout and variables.
  • Prefer component properties over extra variants.
  • Write a changelog with every publish.

Don't

  • Use raw hex values or random spacing inside components.
  • Publish internal helper components.
  • Rename layers carelessly after teams start using a component.
  • Let the Figma library drift from the coded components.

Key takeaways

  • Structure the library with clear files and pages: foundations, components, changelog.
  • Use variables (colour, number, string, boolean) in primitive and semantic collections, with modes for themes.
  • Build components with auto layout, variables, text styles, variant properties and component properties.
  • Name everything consistently and match variant properties to code props.
  • Publish with notes, manage updates carefully, and watch analytics for detached components.

Exercise

Build a mini library

  1. Create Primitives and Semantic variable collections with Light and Dark modes.
  2. Create text styles for heading, body and label.
  3. Build a Button component set with Variant, Size and State variants, plus a boolean and instance-swap icon property.
  4. Build a Text field with label, input, helper text and error state.
  5. Publish the library and use it in a new file to design a sign-in screen in both modes.

Test yourself

Design systems in Figma quiz

5 questions. Score 70% or more to complete the lesson.

  1. 1.Which Figma feature supports Light and Dark themes for tokens?
  2. 2.Which four types can Figma variables have?
  3. 3.What makes a component resize with its content?
  4. 4.A button can show or hide an icon. What's usually better than two variants?
  5. 5.Many teams detach a component. What does that signal?