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.
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/4Styles
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
- 1Build with auto layout so components resize with their content and padding/gap are explicit.
- 2Bind fills, strokes, radius, padding and gaps to variables; apply text styles to all text.
- 3Create one main component per variation, then combine them into a component set with variant properties (e.g.
Variant,Size,State). - 4Add component properties instead of more variants where possible: text (button label), boolean (show icon), instance swap (which icon).
- 5Use nested instances (e.g. the Icon component inside Button) and expose their properties when useful.
- 6Set resizing (hug / fill / fixed) and constraints correctly so instances behave in any layout.
- 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
| Thing | Convention | Example |
|---|---|---|
| Components | Clear noun, slash for grouping | Button, Input / Text field, Navigation / Tab bar |
| Variant properties | Same names as code props | Variant=Primary, Size=MD, State=Hover |
| Internal / private components | Prefix with . or _ so they aren't published | _Button base, .Icon slot |
| Variables | Slash groups from general to specific | color/text/secondary, space/inset/md |
| Layers | Describe the part | Label, 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
- Create Primitives and Semantic variable collections with Light and Dark modes.
- Create text styles for heading, body and label.
- Build a Button component set with Variant, Size and State variants, plus a boolean and instance-swap icon property.
- Build a Text field with label, input, helper text and error state.
- 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.
