Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 36 ยท Design Systems and Variables

Publishing Libraries and Versioning

Publish a Figma team library, let others use it, handle library updates and breaking changes with versioning, changelogs and branching.

A design system is only useful if other files can use it. In Figma you share components, styles and variables by publishing a file as a library. Teammates enable the library in their own files and drag components from the Assets panel. When you publish changes, they get an update notification and can accept it when ready.

Figma cannot run on this site. Menu names here match Figma at the time of writing but may move. The code is a labelled JavaScript stand-in for versioning logic and is not part of Figma.

Publishing a library

  1. Open the Assets panel and click the Library icon (book).
  2. Choose Publish. A dialog lists all components, styles and variables in the file; untick the ones that should stay private, then add a description of the change.
  3. Click Publish.

For variables, you can mark a collection or individual variable as Hide from publishing; that suits primitives and helpers.

To use the library in another file, open the Assets panel, click the Library icon and toggle the library on. Components appear in the Assets panel and can be dragged out as instances linked to the library's main components.

On team plans, you can control who can edit or only use the library by file permissions: viewers can use published components without editing the source.

Updating and reviewing changes

When you publish changes, every file using the library shows an Updates available indicator. A designer opens the update dialog, sees a list of changed components and a preview, and chooses Update all or reviews them individually. This gives teams control: nobody's screens change under their feet in the middle of a presentation.

If an update would break an instance (for example you deleted a layer that had an override), Figma tries to keep overrides by layer name. Renaming layers is the typical reason for lost overrides, as you saw in Nested Components and Swapping.

Versioning your system

Figma keeps version history for the file (named versions and autosaves). Use named versions at milestones: "v2.1 โ€“ new button sizes". Semantic versioning ideas fit nicely:

  • Patch (1.0.1): fixes that change nothing for users (spacing bug, wrong description).
  • Minor (1.1.0): backwards-compatible additions (new variant, new component).
  • Major (2.0.0): breaking changes (renamed or removed components, changed properties, tokens renamed).

The stand-in below suggests a version bump from a list of changes.

JS Stand-in: suggest a semantic version bump

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Renaming a property counts as breaking because designers' instances and developers' code both depend on that name.

Changelogs

Write a short changelog for each release in the publish message and in a "Changelog" page. Keep entries user-facing: what changed, why, what to do.

JS Stand-in: build a changelog entry

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Deprecation instead of deletion

Deleting a component breaks every file that uses it. Mark it deprecated first: rename it with a prefix ([Deprecated] Button/Old), add a description pointing to the replacement, and move it to a "Deprecated" section. Remove it in the next major version, after teams have had a cycle to migrate.

Branching

On Organization and Enterprise plans, branching lets you work on library changes in a branch of the library file, review the differences visually, and merge them to main. It works like a code pull request: contributors propose changes, maintainers review and merge, then publish. Without branching, duplicate the file for experiments and copy approved changes manually.

flowchart LR
    M["Main library"] --> B["Branch: new button sizes"]
    B --> R["Review changes"]
    R --> G["Merge to main"]
    G --> P["Publish update"]
    P --> U["Teams update files"]

Branches isolate work; publishing releases it.

Governance habits

  • Name an owner for the system and a channel for questions.
  • Give contributors a clear process (request, design, review, release).
  • Track adoption: library analytics (where available) show component usage and detach rates.
  • Keep the system in sync with code: each Figma component should reference its code equivalent in its description.
  • Release on a schedule so teams can plan updates.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do other files get your components?

    Libraries link instances to the published main components.
  2. 2. Renaming a component property is what kind of change?

    Names are a contract with instances and code, so renaming breaks users.
  3. 3. What is the safest way to retire a component?

    Deprecation gives teams time to migrate.
  4. 4. What does branching let you do?

    Branches isolate changes until they are reviewed and merged.

Summary

  • Publish a file as a library so components, styles and variables can be used and updated across files.
  • Consumers choose when to accept updates.
  • Version with major, minor and patch semantics; write changelogs.
  • Deprecate before removing; use branching where available.
  • Assign ownership and a contribution process.

Next: Comments, Sharing and Permissions