# 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.

From "Design systems", a free course by Venkat R. Murty: https://designervenkat.online/learn/design-systems/version-control

## 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.

- **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. **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. **Make the change:** Edit the component, token, or asset on your branch. Use clear names so the change is easy to find later.
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. **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. **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. **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. **Preview it:** Select that version and look at it before you change anything. Make sure it is the state you want.
3. **Restore it:** Choose the restore option for that version. Figma makes the chosen version the current one.
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. **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. **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. **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. **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. **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. **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?

A. Duplicate each product file and fix the buttons one by one, then leave the shared button as it is.
B. Create a branch for the change, preview it in each product, get a review, and merge only after approval. If the main version breaks, restore the last working version from history.
C. Ask every product team to copy the new button into their own files, so no shared version needs to be changed at all.

**Answer:** B. Branches keep the change away from the main version until it is tested and reviewed. Restoring the last working version from history returns the team to a known good state.

**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?

A. Make all three styles directly in the main library, then delete the ones the team does not like.
B. Create a separate branch for each style, review them, and merge only the approved style into the main file.
C. Save the styles as separate names in the same file, so the main library always shows all three options.

**Answer:** B. Each branch keeps its experiment separate from the main file. Only the approved work is merged, which keeps the shared library clean.

**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?

A. Open the version history, look for the saved change around Tuesday, read its note and author, and compare the versions to see what changed.
B. Guess the cause and change the card layout in the product file, since the spacing value is the team's responsibility.
C. Delete the spacing token and create a new one with a different name, so the old changes no longer matter.

**Answer:** A. The history shows who changed the value, when, and why. Comparing versions shows the exact difference, which helps the team decide whether to restore or fix the value on a new branch.

## Sources

- [Git Branching Basics (AlgoMaster)](https://algomaster.io/learn/git/branching-basics)
- [How to Create a Branch in Git? (Atlassian Git Tutorial)](https://www.atlassian.com/git/tutorials/using-branches)
- [Git Branches Explained (DEV Community)](https://dev.to/kushkrg/git-branches-explained-how-to-create-switch-merge-and-delete-branches-4n6l)
- [Git Explained for Beginners (DEV Community)](https://dev.to/adhikareeprayush/git-explained-for-beginners-without-the-confusing-parts-5036)
- [Quick recap on Git Basics: Commits and Branches (KIT documentation)](https://mmesiti.github.io/git-intermediate/commits/)
- [What Are Git Branches? (APXML)](https://apxml.com/courses/getting-started-with-git/chapter-4-branching-merging-basics/what-are-git-branches)
- [Introducing branching: space to iterate and explore freely (Figma blog)](https://www.figma.com/blog/introducing-branching-space-to-iterate-and-explore-freely/)
- [Merge branch into main file (Figma Help Center)](https://help.figma.com/hc/en-us/articles/5691189138839-Merge-branch-into-main-file)
- [How to Go Back in Figma (Layerpath)](https://www.layerpath.com/learn/how-to-go-back-in-figma)
- [Figma Version History: View, Save and Restore Versions (Figma Plugins guide)](https://figmaplugins.co/guides/figma-version-history/)
- [How to View Version History in Figma (Saltfish)](https://saltfish.ai/tutorials/figma/how-to-view-version-history)
- [Managing Versions in Figma (GeeksforGeeks)](https://www.geeksforgeeks.org/websites-apps/how-do-you-handle-version-control-in-figma/)
- [How to Restore a Previous Version in Figma (Digidop)](https://www.digidop.com/blog/history-figma-how-to-restore-an-older-version)
- [Figma Branching and Version Control for Component Libraries (Supernova)](https://www.supernova.io/blog/how-to-use-figma-branching-versioning-for-your-component-library)
- [Branching In Figma (Phoenix Group Compound)](https://compound.thephoenixgroup.com/latest/figma/project-files/branching-in-figma-qyZBeLhG)
- [Working In Branches (Phoenix Group Compound)](https://compound.thephoenixgroup.com/latest/figma/project-files/working-in-branches-qyZBeLhG)
- [How to Use Figma Branching (UI Guides)](https://www.uiguides.com/guides/how-to-use-figma-branching)
- [Figma Branching Workflows (ResumeLens blog)](https://www.resumelens.org/blog/figma/figma-branching-workflows)
- [How I use Figma Branching in my design process (Medium)](https://medium.com/@ychsieh93/how-i-use-figma-branching-in-my-design-process-651ddc84d8dd)
