How to Use Figma Team Libraries and Shared Components (Publish, Update, Consume)

Quick answer

A Figma team library is a published file whose components, styles, and variables other files can consume. Build masters in a dedicated library file, click Publish (requires edit access on a paid team plan), then in each product file open Assets → Libraries and enable the library. When the library updates, consuming files show an Update available badge—review changes before Accept update so instances do not break silently. Keep one source of truth per brand, name components for handoff (Button/Primary), and coordinate releases with multiplayer etiquette. Start with components and variants basics and the Figma guides hub.

---

Who this is for

• Design leads publishing the first shared UI kit.
• Contributors pulling buttons from another team’s library.
• Developers who need to know why their instance shows “missing library.”

---

Library file vs project file (separate concerns)

File type	Holds	Who edits
Library (design system)	Components, color/text styles, variables	Design system owners
Project (feature)	Screens, flows, experiments	Feature squads

Verdict: never treat a sprint file as the library. Product files should be mostly instances linked to published masters.

Mirror page structure from how to organize a Figma file: Cover, Components (local only if needed), Examples, and Archive in the library file.

---

Prerequisites

• Team or Organization plan with library publishing (Starter has limits—confirm your plan).
• Edit access on the library file.
• Agreed naming convention (Component/Variant, color/text/primary).
• Components built with auto layout and consistent layer names (Auto Layout in practice).

---

Step 1: Prepare components for publishing

1. Open the library file (create one if needed: Acme Design System).
2. Build or move components and component sets onto a Components page.
3. Create color, text, and effect styles—or bind variables and modes for theming.
4. Remove experimental frames from the publish surface; move WIP to WIP / Do not publish.
5. Run a quick audit: no detached instances on the masters page, no Rectangle 47 layer names on production components.

Common mistake: publishing before variants are merged—consumers get duplicate buttons with unclear property names.

---

Step 2: Publish the library

1. Click the file name → Publish library (or Assets panel → Publish).
2. Add a short changelog (“Added Input/Search; deprecated Button/Legacy”).
3. Choose what to include: components, styles, variables (as applicable).
4. Confirm Publish.

Published assets appear in the team library for enabled files. Variables publish separately in newer Figma versions—coordinate with color system and typography owners.

---

Step 3: Enable the library in a project file

1. Open a product file.
2. Go to Assets → Libraries (book icon).
3. Find your team library → toggle on.
4. Drag components from Assets into screens—they arrive as instances.

Org-wide libraries: admins can pin libraries at the workspace level so new files enable them by default—document which libraries are required vs optional.

---

Step 4: Consume without breaking the system

Do	Don’t
Override text, icons, and exposed properties	Detach to “fix” padding on one screen
Use instance swap for card media	Copy-paste the master from the library file
Link to library documentation components	Duplicate masters into the project file

When you must detach, add a comment and ticket to replace with a proper variant—detached UI debt compounds fast (beginner mistakes).

---

Updates: review before Accept

When publishers ship a new version:

1. Open the consuming file; look for Update available on the library or instances.
2. Open Review updates (library updates modal).
3. Scan breaking changes: renamed properties, removed variants, resized components.
4. Accept per component or bulk when safe.

Workflow for breaking changes:

• Ship deprecated variants for one sprint before removal.
• Announce in Slack with a link to the changelog frame in the library file.
• Pair with branching etiquette so feature branches do not merge mid-update.

Common mistake: accepting all updates minutes before a stakeholder demo—schedule library releases like small deploys.

---

Styles and variables alongside components

Asset type	Consumption
Color & text styles	Apply from the style picker in any enabled file
Variables	Bind after library enable; modes sync when published
Effect styles	Shadows, blurs—keep aligned with dark mode tokens

Prefer variables for semantic tokens (color/bg/surface) and styles for legacy files until migration completes.

---

Permissions and governance

Role	Typical permission
Design system lead	Edit library file, publish
Product designer	Enable library, place instances
Freelancer / guest	View-only or single-project enable

Use view-only library access for vendors when possible. For sensitive brands, restrict who can publish to one rotation per week.

Document contribution rules: propose components in a Proposals page; owners merge into the published set.

---

Multiple libraries (when one is not enough)

Pattern	Example
Core + brand	Acme Core + Acme Marketing
Platform	Web kit + iOS kit with shared color variables
White-label	Partner library enabled per client file

Avoid enabling five overlapping libraries—naming collisions (Button/Primary in two libs) confuse search. Prefix slugs: Mkt/Button/Primary.

---

Handoff to engineering

• Dev Mode reads instances linked to published components—detached layers lose the link (Dev Mode checklist).
• Publish changelog frames designers can reference in tickets.
• Align with dev handoff plugins only after the library is stable—plugins do not fix bad component structure.

---

Troubleshooting

“Missing library” on instances

The library was disabled or you lack access. Re-enable under Libraries or request access from the file owner.

Updates do not appear

You are in a duplicate of the file, or the publisher did not click Publish—only saving the file is not enough.

Wrong component inserted

Two libraries share similar names—rename with team prefix or use description fields in component metadata.

Variables out of sync

Republish the library; in the consumer file, refresh variable sources from the library panel.

---

FAQ

Can I publish a library from the free plan?

Publishing to a shared team library requires a paid Professional, Organization, or Enterprise seat on most teams. Check Figma’s current plan docs; solo files can still use local components without team publish.

Should marketing templates be in the product library?

Usually no—marketing frames change often and bloat search. Use a separate marketing library or template roundup with clear enable rules.

How often should we publish?

Weekly for active systems; immediate for critical bugfixes (contrast, tap target). Batch cosmetic tweaks to reduce update fatigue.

Library vs import from Sketch?

Libraries are for ongoing sync. Sketch import is a one-time migration—rebuild as components before publishing.

---

Recommended next steps

1. Audit one production file for detach rate; fix the top three offenders in the library.
2. Publish a changelog component designers must read before Accept.
3. Connect tokens to semantic color and ship Dev Mode with instance names engineers can map to code.

Team libraries only work when publish discipline matches product urgency—treat the library like production code, not a sticker sheet.