Skip to content

Commit 06599c7

Browse files
Febakkemrosvikmimarz
authored
docs: figma guide for migrating to the new color structure (#4967)
Co-authored-by: Marianne Røsvik <marianne.rosvik@digdir.no> Co-authored-by: Michael Marszalek <mimarz@gmail.com>
1 parent c03efab commit 06599c7

11 files changed

Lines changed: 557 additions & 0 deletions

‎apps/www/app/content/blog/en/migrate-simpler-color.mdx‎

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
---
2+
title: "Migrating to the simplified color structure"
3+
description: Learn how to migrate your Designsystemet Figma library to the new color structure.
4+
date: 2026-06-26
5+
author: Designsystemet
6+
imageSrc: /img/blog/migrate-figma-color.png
7+
imageAlt: Illustration showing the previous structure with Main, Support, and Neutral on the left, and the new structure with a single Color collection and color mode on the right.
8+
imageCaption: The new color structure brings all colors together into a single Color collection in Figma, matching how colors are handled in code.
9+
---
10+
11+
## Why are we making this change?
12+
13+
Today, colors in Figma are split across two separate collections, `Main color` and `Support color`, and components are available in the `main`, `support`, and `neutral` variants.
14+
15+
This structure makes design libraries more complex than necessary. It results in more component variants to maintain and makes it harder for designers using the library to choose and update colors.
16+
17+
With the new structure, all colors are brought together into a single `Color` collection. Components no longer need separate `main`, `support`, and `neutral` variants. Instead, users select the desired color directly through **Appearance** using `color mode`, just as it already works in code.
18+
19+
The result is a simpler library with fewer variants to maintain and a more intuitive way for designers to work with colors.
20+
21+
This change is possible because Figma no longer has the previous limitation on the number of colors in a collection. That limitation was the reason the colors were originally split across multiple collections.
22+
23+
## Before you migrate your Figma library
24+
25+
This guide is intended for anyone maintaining a Figma library based on Designsystemet.
26+
27+
Before you start in Figma, make sure your `designsystem.config.json` and `design-tokens` have been updated to the new color structure. You may need help from a developer with this step.
28+
29+
If you run the CLI using `designsystemet tokens create --clean`, both the colors and the configuration are migrated automatically. You can also do this manually by moving the colors from `main` and `support` to `color` in the configuration file.
30+
31+
To verify that your design tokens have been updated, check the `semantic/modes` folder:
32+
33+
- if it contains `main color` and `support color`, you're still using the previous structure
34+
- if it only contains `color`, you're using the new structure
35+
36+
<Image
37+
src='/img/blog/migrate-folders.png'
38+
alt='Illustration showing the folder structure before and after migration. The old structure contains Main color and Support color, while the new structure only contains Color.'
39+
caption='How the folder structure changes when your design tokens are migrated to the new version.'
40+
boxShadow={true}
41+
42+
/>
43+
44+
### What changes in Figma
45+
46+
- `Main color` and `Support color` are merged into a single collection: `Color`
47+
- All variants except `main` are removed
48+
- Component instances and examples are updated accordingly
49+
50+
<Image
51+
src='/img/blog/migrationbeforeafter.png'
52+
alt='Before and after illustration showing the Button component.'
53+
caption='The Button component before and after migration.'
54+
boxShadow={true}
55+
56+
/>
57+
58+
### Plugin or manual migration
59+
60+
We recommend using our migration plugin when following this guide: [Designsystemet migration helper](https://www.figma.com/community/plugin/1641069372132680632/designsystemet-migration-helper). The migration can also be done manually, but it can be a significant amount of work, especially when cleaning up old component variants and instances.
61+
62+
#### Requirements – naming expected by the plugin
63+
64+
The plugin is designed to be dynamic, meaning it can also migrate components you've created yourself. However, it relies on a few specific names to work correctly. If you've renamed any of these, the plugin may fail or produce incorrect results.
65+
66+
- The **color variant property** must be named `color` or `color mode`. If it has been renamed, the plugin won't remove the old variants.
67+
68+
- **`Alert` / `ValidationMessage`**: These variants should remain unchanged. The plugin ignores them as long as the components keep their original names. If they've been renamed, you'll need to check them manually. Otherwise, the variants may be removed.
69+
70+
### What happens to files that use the library?
71+
72+
This refers to Figma files that use components from the library as instances, not the library file itself.
73+
74+
Files that use the library won't be affected by the migration.
75+
76+
Instances using the former `main` variant are automatically reconnected to the new variants. Instances using `support` or `neutral` are not updated automatically by Figma.
77+
78+
Later in this guide, we'll explain how to update those instances using the migration plugin.
79+
80+
## Step 1 – Create a version history snapshot
81+
82+
Create a snapshot so you can restore the file if anything goes wrong. If you prefer working in a branch, you can do that instead.
83+
84+
**Do this:**
85+
- Open **Version history** in Figma.
86+
- Create a new snapshot.
87+
- Give the snapshot a descriptive name, for example **"before migration"**.
88+
89+
<ResponsiveIframe
90+
src='/img/blog/migrate-steg1.mp4'
91+
title='Screen recording showing how to create a snapshot in Figma Version history.'
92+
frameBorder='0'
93+
autoPlay={false}
94+
aspectRatio='16-9'
95+
/>
96+
97+
## Step 2 – Update the variable structure
98+
99+
Update the variable structure before exporting tokens from Token Studio. This ensures the variables are exported to the correct structure.
100+
101+
**Do this:**
102+
1. Run [Designsystemet migration helper](https://www.figma.com/community/plugin/1641069372132680632/designsystemet-migration-helper).
103+
2. Click **Update library**.
104+
3. The plugin checks whether the variable structure is correct.
105+
4. If prompted, click **Prepare variables**.
106+
107+
<ResponsiveIframe
108+
src='/img/blog/migrate-steg2.mp4'
109+
title='Screen recording showing how to update the variable structure using the plugin.'
110+
frameBorder='0'
111+
autoPlay={false}
112+
aspectRatio='16-9'
113+
/>
114+
115+
<Image
116+
src='/img/blog/migrate-steg2variabler.png'
117+
alt='Screenshot showing how the variables should look after the update.'
118+
caption='The variable structure after the update.'
119+
boxShadow={true}
120+
121+
/>
122+
123+
<Card>
124+
<Details>
125+
<Details.Summary>
126+
Update manually
127+
</Details.Summary>
128+
<Details.Content>
129+
1. Find the `Main color` collection and rename it to `Color`.
130+
2. Under **Groups** in the lower-left corner, locate `All/color/main`. Right-click `color` and select **Ungroup**.
131+
132+
<ResponsiveIframe
133+
src='/img/blog/migrate-steg2manuelt.mp4'
134+
title='Screen recording showing how to update the variable structure manually.'
135+
frameBorder='0'
136+
autoPlay={false}
137+
aspectRatio='16-9'
138+
/>
139+
140+
</Details.Content>
141+
</Details>
142+
</Card>
143+
144+
## Step 3 – Sync the updated tokens with Token Studio
145+
146+
Before exporting tokens to Figma, make sure the token structure in GitHub has been updated to the new color structure. Verify that `semantic/modes` only contains `color`, and no longer contains `main color` or `support color`.
147+
148+
**Do this:**
149+
1. Push the updated tokens to GitHub if you haven't already.
150+
2. Open Token Studio and pull the latest tokens from your repository.
151+
3. Export the tokens to Figma.
152+
153+
If you haven't exported tokens with Token Studio before, follow the [guide to creating your own theme](/en/fundamentals/start-here/own-theme). Start at step 7. The earlier steps cover setting up a new theme and aren't needed for this migration.
154+
155+
**Verify that:**
156+
- All colors are in the `Color` collection, including the severity colors `info`, `warning`, `danger`, and `success`.
157+
158+
## Step 4 – Delete the Support color collection
159+
160+
Clean up after the export. Token Studio doesn't remove the `Support color` collection automatically, so you **must** delete it manually.
161+
162+
**Do this:**
163+
1. Open the Variables panel in Figma.
164+
2. Find the `Support color` collection.
165+
3. Delete the `Support color` collection.
166+
167+
**Verify that:**
168+
- The only variable collections are `Color`, `Semantic`, `Theme`, `Size`, `Color scheme`, and `Typography`.
169+
170+
<ResponsiveIframe
171+
src='/img/blog/migrate-steg4.mp4'
172+
title='Screen recording showing how to delete the Support color collection.'
173+
frameBorder='0'
174+
autoPlay={false}
175+
aspectRatio='16-9'
176+
/>
177+
178+
## Step 5 – Run the migration plugin
179+
180+
Most components in the library are available in three color variants: `main`, `support`, and `neutral`.
181+
182+
The `support` variant is no longer used, and the `neutral` variant is no longer needed because components are now controlled using `color mode`.
183+
184+
The plugin removes the old variants and updates all instances in the library file in a single operation.
185+
186+
<Card>
187+
<Details>
188+
<Details.Summary>
189+
What the Designsystemet migration helper does
190+
</Details.Summary>
191+
<Details.Content>
192+
- Removes the `support` and `neutral` variants from components.
193+
- Updates `neutral` instances to `default` and sets `color mode = neutral`.
194+
- Updates `support` instances to `default`, allowing you to choose which `color mode` they should use.
195+
- Replaces instances using old variants with the new variant and applies the correct `color mode`, including instances nested inside other instances.
196+
- Reconnects `Support color` variables applied directly to frames, text, and other layers (not only component instances) to `Color`.
197+
</Details.Content>
198+
</Details>
199+
</Card>
200+
201+
**Do this:**
202+
1. Open [Designsystemet migration helper](https://www.figma.com/community/plugin/1641069372132680632/designsystemet-migration-helper).
203+
2. Click **Update library**.
204+
3. Choose which color should replace `support`. This selection is required.
205+
4. Click **Run migration**.
206+
207+
<ResponsiveIframe
208+
src='/img/blog/migrate-steg5.mp4'
209+
title='Screen recording showing how to run the migration plugin.'
210+
frameBorder='0'
211+
autoPlay={false}
212+
aspectRatio='16-9'
213+
/>
214+
215+
> **Note:** The plugin only shows **Run migration** when the file is ready. If something is missing, the status card explains what needs attention:
216+
> - the variables haven't been renamed yet → click **Rename variables** in the plugin (Step 2), or
217+
> - the `Color` collection is missing the `info`, `warning`, `danger`, or `success` color modes → export the updated tokens from Token Studio and reopen the plugin (Step 3).
218+
219+
**After the migration:** You'll see a summary showing how many variants were removed and how many instances were updated. Most changes are handled automatically. If anything couldn't be updated, it will be listed in the results:
220+
221+
- component sets that already contained errors in Figma (for example variant conflicts). Fix the conflict and run the migration again.
222+
- individual variants that couldn't be updated.
223+
224+
Click a row to jump directly to the component in Figma and fix it manually.
225+
226+
<Card>
227+
<Details>
228+
<Details.Summary>
229+
Update manually
230+
</Details.Summary>
231+
<Details.Content>
232+
Migrating manually is a significant amount of work. You'll need to review components, nested components, and example instances throughout the library file.
233+
234+
Remove all `support` and `neutral` variants, then update instances that use the old variants. `neutral` variants should be changed to `default` with `color mode = neutral`. `support` variants should be changed to `default` using the appropriate `color mode`.
235+
236+
The number of variants to remove depends on your library. [See the full list of variants removed in our standard library](https://github.com/digdir/designsystemet/issues/4893#:~:text=Variant%20cleanup%20scope).
237+
</Details.Content>
238+
</Details>
239+
</Card>
240+
241+
## Step 6 – Review and publish the library
242+
243+
Your library should now be fully migrated.
244+
245+
Review the components and verify that the variables have the correct scope and CSS syntax before publishing the library.
246+
247+
**Do this:**
248+
1. Review the components and verify that the migration looks correct.
249+
2. Run the [Designsystemet – Code syntax & scoping](https://www.figma.com/community/plugin/1500739115059498140/designsystemet-code-syntax-scoping) plugin on the variables in the file.
250+
3. Update the scope and CSS syntax if the plugin finds anything that needs to be fixed.
251+
4. Publish the library.
252+
253+
If your library is used by many designers, it's a good idea to let them know about the change and explain what will happen when they update.
254+
255+
You can read more about [variable scope and CSS syntax in Figma](https://help.figma.com/hc/en-us/articles/15145852043927-Create-and-manage-variables-and-collections#h_01H32HZB74TE7MJXYBWEBBQWJV).
256+
257+
## Update files that use the library
258+
259+
Once you've published the library, everyone using it can update to the new version. Figma automatically reconnects instances using the former `main` variant. As long as you haven't changed the order or names of your colors, these instances will look the same as before.
260+
261+
Instances using `support` or `neutral` are not updated automatically by Figma. They will continue to work, but if you'd like to clean them up, you can use the **Update sketches** flow in the migration plugin.
262+
263+
We recommend that users create a version history snapshot before updating the library or running the plugin. In our testing, we haven't seen any visual changes in files using the library, but a snapshot makes it easy to restore the file if anything unexpected happens.
264+
265+
The plugin replaces old instances with the new ones and applies the correct `color mode`. It can also reconnect `Support color` variables applied directly to frames, text, and other layers to `Color`.
266+
267+
**Do this:**
268+
- Select the **Scope** to limit the migration to the current selection, the current page, or the entire file.
269+
- For `support` instances without a dedicated mode, choose a replacement color from the **Replace 'support' with** dropdown.
270+
271+
## Known issues
272+
273+
After migration, several examples on the **Table** page lose their content. We haven't been able to reproduce this in files using a published library, but we still recommend paying extra attention to tables after updating your files.
274+
275+
On the **Popover** page, the **Popover definition** example is broken after running **Designsystemet migration helper**. This must be fixed manually.
276+
277+
<Contributors authors={['Lasse Febakke Straum']} />

0 commit comments

Comments
 (0)