esc
  • WorkflowsPages
  • Case studiesPages
  • Machine Learning FoundationsLearn
  • AI EngineeringLearn
  • AI Guardrails & Red TeamingLearn
  • UI/UXLearn
  • Design SystemsLearn
  • Production System DesignLearn
  • Book a callContact
  • Download ResumeContact
Let’s talk

I’ll build the agent for it.

Version Control: Track Every Design System Change and Undo Mistakes Safely

Learn how teams record each change to a design system, work on changes in isolation, review them, and go back to a safe state when something breaks.

In short

Version control records every change to a design system, lets teams work on changes in isolation, review them, and go back to a safe state when something breaks.

12 min readFree

What does version control do?

A design system changes all the time. A button gets a new color. A spacing value is fixed. A team asks for a new icon. Version control is the set of habits and tools that record each of these changes, so the team can see what happened, who did it, and how to go back if something goes wrong. This lesson explains the idea as it applies to design systems: the component designs, the design tokens, and the files that hold them.

Key words

Version control
A way to record every change to a set of files, so you can look back at the history and return to an older state.
Repository
The stored home of a project's files together with their full history.
Commit
A saved snapshot of the files, with a short note that says what changed.
Branch
A separate line of work that starts from a shared version, so you can change things without touching the main version.
Merge
Bringing approved changes from a branch back into the main version.
Revert
Going back to an earlier saved state after a change causes problems.
Diff
A view that shows what was added, changed, or removed between two versions.
Design token
A named design decision, such as a primary brand color, stored once and used across many screens.

By the end of this lesson you will be able to explain why a design system needs a recorded history, describe how a branch lets someone change a component safely, read the history of a change, and recover from a bad change. You will also see how Figma offers similar ideas inside a design file.

Why does a design system need a written history?

A design system is used by many people at once. Designers, developers, and product teams all depend on the same parts. When a shared part changes without a record, nobody can tell which version a product is using or why a change was made. Version control solves this by keeping a timeline of every change.

  • Who changed what

    Each saved change points to a person and a time, so a question like 'why did the card padding change?' has an answer.

  • Work at the same time

    Several people can change different parts of the system without overwriting each other's work.

  • Undo safely

    If a change breaks something, the team can return to a version that worked, instead of rebuilding parts by memory.

Tip

Think of the history as the memory of the design system. A system with no memory is hard to trust, because nobody knows how it got into its current state.

What are repositories, commits, branches, and merges?

Most version control tools share the same small set of ideas. Learn these four first, and the rest of the topic becomes easier to follow.

  • Repository

    The one place that holds the current files and all of their past states. For a design system, this could hold component files, token values, and design assets.

  • Commit

    A saved snapshot with a note. Each commit is a point you can look at or return to later. Git describes a commit as a snapshot of the project at one point in time, with its own unique identifier.

  • Branch

    A separate path of work. A new branch starts from the current version and can grow on its own. Git stores a branch as a reference to a commit, not as a second copy of the files.

  • Merge

    The step that joins a branch back into the main line. Git either moves the main line forward or creates a special merge commit when both lines have new work.

Every repository has a main line, often called the main branch. This is the version the team treats as the trusted one. Other branches start from it and return to it.

Tip

A branch does not hold a full copy of the project. It is closer to a bookmark on a line of saved points. That is why teams can create many branches without much cost.

Why have one source of truth for the whole team?

A source of truth is the one file or place that the team agrees is correct. In design systems, the main file or main branch should be that place.

Without one trusted place, a team can end up with several slightly different button designs in different files. Each product then looks a little different, and fixing one problem means hunting through many copies. A recorded history in one main version prevents this drift.

Tip

Ask one question before you change any shared part: where is the approved version kept? If the answer is unclear, fix that before you edit anything.

How do you work on a change in isolation?

Isolation means your change lives on its own line until it is ready. Other teams keep using the main version, and they do not see half-finished work. This is the main reason branching exists.

  1. 1

    Start from the main version

    Create a branch from the current approved version. Your branch begins with exactly what the other teams are using.

  2. 2

    Make the change

    Edit the component, token, or asset on your branch. Use clear names so the change is easy to find later.

  3. 3

    Save a checkpoint with a note

    Record your progress with a short description of what you changed and why. A saved point with notes is much easier to review than a long list of unlabeled edits.

  4. 4

    Test the change where it will be used

    Look at the change in real screens, not only on the component page. Check that it still works with the other parts around it.

  5. 5

    Ask for review

    Share the branch so a teammate can compare it with the main version and approve it, or suggest changes.

Figma follows the same idea in its own words. A branch is a copy of a file that you can change, and the main file stays as it was until someone merges the branch.

Review, Merge, and Protect Other Teams

Once a branch is ready, the change must be checked before it joins the main version. This is where the design system's rules are enforced. A merge should only bring in changes that the team has approved, so no single person can quietly change a shared part for everyone.

Review is a conversation about the change. A reviewer compares the branch with the main version, looks at each screen where the part appears, and either approves or asks for changes. In Figma, a reviewer can approve a branch or suggest changes with comments.

Tip

Write the reason for the change in the review note. A reviewer who understands why a token changed can judge whether the change fits the system's rules, not just whether it looks nice.

A merge can also cause conflicts. A conflict happens when two branches changed the same part in different ways. Someone must look at both versions and choose the right result. Figma says conflicts must be reviewed and resolved by hand, and that it may ask you to make updates before the merge is complete.

Reading History and Recovering From Mistakes

The history is useful only if people read it. Good version control lets you answer three questions: what changed, who changed it, and whether you can safely go back.

Comparing Versions

Comparing versions is the first skill. A comparison view, often called a diff, shows what was added, what was changed, and what was removed between two states. Reviewing a diff helps you see the real effect of a change before it reaches other teams.

Reading Who Changed a Component and When

Reading who changed a component and when is the second skill. Figma's history panel shows the name of the collaborator and the time for each saved version. This turns a vague worry into a specific question you can ask the right person.

Reverting a Bad Change

Reverting is the third skill. Revert means returning to an earlier saved state. The steps below show the general pattern in Figma, where restoring an old version is a clear action.

  1. 1

    Find the last working version

    Open the history and look for the saved point just before the problem appeared. Use the note and the time to narrow it down.

  2. 2

    Preview it

    Select that version and look at it before you change anything. Make sure it is the state you want.

  3. 3

    Restore it

    Choose the restore option for that version. Figma makes the chosen version the current one.

  4. 4

    Keep a record

    Check that the restore did not remove the broken state entirely.

Tip

For a mistake made a few minutes ago, a simple undo is often faster than opening the history. For older problems, or changes made by someone else, use the history.

Version Control in Design Tools Like Figma

Not every team uses Git. Many design teams work in Figma, which has version history and branching built into the design file. The ideas are the same, even though the screens look different.

  • Version history

    A list of saved states of a file. You can open it from the file name menu, preview any version, and restore one.

  • Branches

    A copy of a file that you can change safely. Branches can be shared for feedback, reviewed, and then merged into the main file.

  • Merge

    The action that applies approved branch changes to the main file. Figma shows what changed, and the merge can get a name and description in the file history.

  • Access rules

    Viewing history and editing history need different levels of access. Teams often limit who can merge into the library file, so only the design system team controls the main version.

Tip

Save a named version with a note before a big merge. Figma adds its own marker, but a clear manual note explains the milestone much better later.

Worked Example: Changing the Primary Color Token

Imagine a company that keeps its design system in a shared Figma library. The team wants to change the primary color token, the named color used for main buttons and links, from one blue to a slightly darker blue. Here is how the change moves through version control, step by step.

  1. 1

    Create a branch

    A designer creates a branch from the main library file. The main file keeps the current blue, so every product still works as before.

  2. 2

    Change the value

    On the branch, the designer changes the value of the primary color token and adds a note that explains the reason for the darker shade, such as a contrast fix.

  3. 3

    Preview on the checkout screen

    The designer opens a checkout screen that uses the token. She checks the main buttons, the links, and the warning states, so she can see the change in a real flow.

  4. 4

    Request review

    She asks two teammates to review the branch. One reviewer compares the changes and asks for a check on a second product. The other approves it.

  5. 5

    Merge after approval

    Once both approvals are in, the designer merges the branch into the main file. The merge gets a clear name and description, so the history explains why the color changed.

  6. 6

    Revert if needed

    A week later, a product team reports that some dark backgrounds look too muddy. The team restores the version just before the merge. The fix is then planned on a new branch, and the main line is only updated again after review.

The example shows the main value of version control. The change was tested before anyone else depended on it, the reason was written down, and the team could go back to the last working state when the change caused problems.

Common Mistakes to Avoid

  • Editing the main version directly

    Changing a shared component on the main line means every product sees the change at once. Use a branch for every shared change, even small ones.

  • Saving without a note

    A saved point with no description is hard to understand later. Write one sentence that says what changed and why.

  • Merging without testing

    A change that looks fine on a component page can break a real screen. Check at least one real flow before merging.

Tip

Treat the main version like a published product. Only approved, tested changes should reach it.

Check Yourself

Quick check

A teammate edited the shared Button component directly on the main version. Now buttons look broken in three products. Which practice would have let them test the change safely first, and what is the quickest way back?

Quick check

A designer wants to explore three new icon styles for the design system. The team does not want any of these tries to reach the shared library yet. What is the best use of branching here?

Quick check

A product team says a spacing value changed last Tuesday and broke their card layout. What should a design system owner check first?

Sources

How is this lesson?

Last updated on 17 November 2026

Learn with me

Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.