Skip to content

Commit 875844f

Browse files
mrosvikBarsnes
mrosvik
and
Barsnes
authored
docs: get started with your theme (#4224)
Co-authored-by: Tobias Barsnes <[email protected]>
1 parent c17bb7b commit 875844f

File tree

10 files changed

+215
-117
lines changed

10 files changed

+215
-117
lines changed

‎apps/www/app/content/fundamentals/en/themebuilder/own-theme.mdx‎

Lines changed: 109 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,106 +1,154 @@
11
---
22
title: Build your theme
33
sidebar_title: Build your theme
4-
description: Learn how to use Designsystemet with your own brand colors and preferences.
5-
date: 2025-02-28
6-
category: Theme Builder
4+
description: Learn how to use Designsystemet with your own brand colours and preferences.
5+
date: 2025-11-07
6+
category: Theme builder
77
color: blue
88
icon: PaletteIcon
99
published: true
1010
order: 10
1111
---
1212

13-
Designsystemet is designed to be used with your own visual identity — including colors and other preferences. This means you don’t need to build a new design system from scratch. With Designsystemet’s [Theme Builder](https://theme.designsystemet.no/en), you can set up your own theme and generate Design Tokens that can be used in both design tools and code.
13+
Designsystemet is designed to be used with your own visual identity, including colours and other preferences. With the [Designsystemet Theme Builder](https://theme.designsystemet.no), you can set up your theme and generate Design Tokens that can be used both in design tools and in code. Design Tokens ensure that both design and code use the same values.
1414

15-
## Connection between design and code
16-
The first thing to consider is whether you want a connection between design and code. Either way, you should ensure the same Design Tokens are used in both, so that designers and developers are working from the same rules. This ensures consistency between what’s designed and what’s built. You’ll need to decide whether to handle this manually or through a connection.
15+
<Alert data-color="info">
16+
We recommend that both a developer and a designer take part in the process when setting up your theme.
17+
</Alert>
1718

18-
**Option 1:** _Without_ a connection between Figma and code
19-
**Option 2:** _With_ a connection between Figma and code
19+
## How to get started:
2020

21-
Which option you choose depends on your needs and constraints. Setting up a connection requires a **pro license** for the [Tokens Studio](https://tokens.studio/) plugin. We hope to make this easier with our own plugin in the future.
21+
1. Copy the configuration file below and save it as `designsystemet.config.json`
2222

23-
We’ll walk you through both options below.
23+
```json
24+
{
25+
"outDir": "./design-tokens",
26+
"clean": true,
27+
"themes": {
28+
"theme": {
29+
"colors": {
30+
"main": { "primary": "#0062BA", "accent": "#1E98F5" },
31+
"neutral": "#1E2B3C",
32+
"support": { "extra1": "#F45F63", "extra2": "#E5AA20" }
33+
},
34+
"borderRadius": 4
35+
}
36+
}
37+
}
38+
```
39+
2. Find a Git repository where you can store your Design Tokens. Place the `designsystemet.config.json` file in the root of the repository.
2440

41+
3. Clone the repository locally to your machine, open a terminal, and navigate to the folder containing the repository.
2542

26-
## Option 1: Without direct connection
43+
4. Make sure you have Node.js installed, version 20 or higher.
2744

28-
This option does **not** require Token Studio. With this option, you run the same code snippet from the theme builder in Designsystemet's Figma plugin and in the terminal to generate Design Tokens for building in code. There will not be a direct connection, but the variables/tokens will be generated using the same method, thus giving you similar values in code and Figma.
45+
5. Run the following command in the terminal:
46+
```bash
47+
npx @digdir/designsystemet@latest tokens create --config designsystemet.config.json
48+
```
49+
This will generate Design Tokens based on the configuration file and save them in a folder called `design-tokens`. Push the changes to your repository.
2950

30-
### Here's how to proceed:
51+
<Alert data-color="info">
52+
Next, we will move into Figma. Make sure you are using the Figma desktop app, not the browser version.
53+
</Alert>
3154

32-
1. Get the component library from [Figma Community](https://www.figma.com/community/file/1322138390374166141/designsystemet-core-ui-kit) (Click "Open in Figma") to your organization that has at least a pro license. Note that this will be a copy of the component library without any connection to the main file. The file has now been placed in "drafts", so you need to move it to a suitable location in your organization.
33-
2. Install Designsystemet's [plugin for Figma](https://www.figma.com/community/plugin/1382044395533039221/designsystemet-beta).
34-
3. Go to the [Theme Builder](https://theme.designsystemet.no/en) and generate the color scale based on your brand colors. Keep the same color names and don't remove colors (This only works with [option 2](/en/fundamentals/themebuilder/own-theme#option-2-with-connection).)
55+
6. Fetch the component library from [Figma Community (figma.com)](https://www.figma.com/community/file/1322138390374166141/designsystemet-core-ui-kit) (Click “Open in Figma”) into your organisation that has at least a Pro licence. Note that this will be a copy of the component library without any connection to the main file.
3556

36-
Click "Apply theme". Copy the code snippet.
57+
7. Install the plugin [Tokens Studio (figma.com)](https://www.figma.com/community/plugin/843461159747178978/Tokens-Studio-for-Figma-(Figma-Tokens)). This plugin enables synchronisation between Figma and code. You do *not* need a Pro licence.
3758

38-
4. Paste the code snippet into the plugin you installed in step 2. (To generate Design Tokens for code, the developer must run the same code snippet in a terminal.)
39-
40-
Select "Update variables" in the plugin. Now you should see all components with your own brand colors in Figma. For other designers in the organization to use the components, you need to publish the file.
41-
42-
43-
44-
<ResponsiveIframe
45-
src="/img/plugin-alt1.mp4"
46-
title="The video goes through steps 1-4 as described above."
47-
frameBorder="0"
48-
allow="autoplay; fullscreen; picture-in-picture"
49-
allowFullScreen
50-
aspectRatio="16-9"
59+
<Image
60+
src='/img/tokenstudio.png'
61+
alt='Screenshot of Figma showing where to find plugins'
62+
boxShadow={false}
5163
/>
5264

65+
- In the plugin, set up the connection to your Git repository. See Tokens Studio’s guide “[Sync your Design Tokens with code (tokens.studio)](https://docs.tokens.studio/token-storage-and-sync/sync-provider-overview)” which explains how to do this for different Git providers.
66+
- Remember to set the “Token storage location” to `design-tokens` (or whatever you have named your Design Tokens folder).
5367

68+
<Alert data-color="info">
69+
We recommend *not* pushing changes to Design Tokens from Tokens Studio, as this may cause you to lose your overrides when updating.
70+
</Alert>
5471

55-
## Option 2: With connection
72+
8. Go to the [Theme Builder](https://theme.designsystemet.no) and generate colour scales based on your brand colours. Click “Apply theme”. Copy the configuration file and paste it into the `designsystemet.config.json` file in your repository. Run the command below and push the changes.
5673

57-
A connection means you don't have to enter the variables into Figma manually; instead, you import them from the "Tokens Studio" plugin. This option requires knowledge of Git.
5874

59-
<Card
60-
data-color="brand2"
61-
data-variant="tinted"
62-
>
63-
Note: You must have at least a pro license of Figma and a pro license of the "Tokens Studio" plugin to set up this connection. You also need a place to store the files that can be accessed by Token Studio, e.g., in a [Github repository](https://github.com/new).
64-
</Card>
75+
```bash
76+
npx @digdir/designsystemet@latest tokens create --config designsystemet.config.json
77+
```
6578

79+
**Remember to run this command every time you make changes to the configuration file.**
6680

67-
### Here's how to proceed:
81+
9. In Tokens Studio, select the “Pull” icon to fetch the new tokens into Figma.
6882

69-
1. Get the component library from [Figma Community](https://www.figma.com/community/file/1322138390374166141/designsystemet-core-ui-kit) (Click "Open in Figma") to your organization that has at least a pro license. Note that this will be a copy of the component library without any connection to the main file. The file has now been placed in "drafts", so you need to move it to a suitable location in your organization.
70-
71-
2. Go to the [Theme Builder](https://theme.designsystemet.no/en) and generate the color scale based on your brand colors. Click "Apply theme". Copy the code snippet and run it in a terminal in your Git repo. Commit and push the files.
83+
<Image
84+
src='/img/fundamentals/themebuilder/own-theme/tokens-studio-pull-button.png'
85+
alt='Screenshot of Tokens Studio showing where to find the pull button'
86+
boxShadow={false}
87+
/>
7288

73-
3. Install the [Tokens Studio](<https://www.figma.com/community/plugin/843461159747178978/Tokens-Studio-for-Figma-(Figma-Tokens)>) plugin for Figma. Tokens Studio ensures connection between Figma and code using Design Tokens.
89+
Select `Styles & variables` and `Export styles & variables to Figma`.
7490

7591
<Image
76-
src="/img/tokenstudio.png"
77-
alt="Screenshot of Figma showing where to find plugins"
92+
src='/img/fundamentals/themebuilder/own-theme/tokens-export.png'
93+
alt='Screenshot of Tokens Studio showing where to find the export button'
7894
boxShadow={false}
79-
8095
/>
8196

82-
- Follow Tokens Studio's guide "[Sync your Design Tokens with code](https://docs.tokens.studio/token-storage-and-sync/sync-provider-overview)" to set up connection to your Git repo.
83-
- Remember to set "Token storage location" to `design-tokens` (or whatever you have chosen to call your folder with Design Tokens).
84-
85-
4. Under "Tokens" in Tokens Studio, you should now see all the colors you generated with the Theme Builder in step 2. In Tokens Studio, select `Styles & variables` and `Export styles & variables to Figma` and follow the steps to export tokens to variables in Figma. Make sure you have these settings when exporting the variables:
97+
Make sure you have these settings before clicking `Confirm`:
8698

8799
<Image
88-
src="/img/token-studio-settings.png"
89-
alt="Screenshot showing selected settings in Tokens Studio. Under variables, everything is turned on. Under styles, color is turned off. Under export, 'Ignore first part of token name for styles' and 'Prefix styles with active theme name' are turned off"
100+
src='/img/fundamentals/themebuilder/own-theme/tokens-export-options.png'
101+
alt='Screenshot of Tokens Studio showing which settings to use when exporting tokens to Figma'
90102
boxShadow={false}
91-
92103
/>
93104

94-
Be aware that modes already in the Community file are not deleted by Token Studio. Delete the themes you don't need in Figma "Local variables" under "Theme". The same can happen under "Main" and "Support".
105+
Select `Themes`, `Select All`, and `Export to Figma`:
95106

96107
<Image
97-
src="/img/brutte-referanser.png"
98-
alt="Screenshot showing broken links in Figma variables. Right-click and delete the themes you don't need."
108+
src='/img/fundamentals/themebuilder/own-theme/tokens-export-themes-select.png'
109+
alt='Screenshot of Tokens Studio showing that you must select Themes and then Select All'
99110
boxShadow={false}
100-
101-
102111
/>
103112

104-
5. Now you should see all components with your own brand colors in Figma. For other designers in the organization to use the components, you need to publish the file.
105-
106-
6. Done! PS. If you need to make changes to tokens in Tokens Studio, you can push the changes to your repo by clicking on the "Upload" icon (Push) at the bottom.
113+
You should now see all components using your brand colours in Figma. Note: If you changed the names of the colours in the Theme Builder, you must go into Figma Variables and manually delete the old colours.
114+
115+
If you want additional themes, you can generate a new theme in the Theme Builder and update the configuration file in your repository. Run the command again to generate new Design Tokens, push the changes, and use the “Pull” button in Tokens Studio to fetch the new themes into Figma.
116+
117+
118+
```json
119+
{
120+
"outDir": "./design-tokens",
121+
"clean": true,
122+
"themes": {
123+
"theme-one": {
124+
"colors": {
125+
"main": { "primary": "#0062BA", "accent": "#1E98F5" },
126+
"neutral": "#1E2B3C",
127+
"support": { "extra1": "#F45F63", "extra2": "#E5AA20" }
128+
},
129+
"borderRadius": 4
130+
},
131+
"theme-two": {
132+
"colors": {
133+
"main": { "primary": "#0062BA", "accent": "#1E98F5" },
134+
"neutral": "#1E2B3C",
135+
"support": { "extra1": "#F45F63", "extra2": "#E5AA20" }
136+
},
137+
"borderRadius": 4
138+
}
139+
}
140+
}
141+
```
142+
143+
<Alert data-color="info">
144+
When the Design Tokens are updated in code, you can easily fetch the new values into Figma by using the “Pull” button in Tokens Studio again.
145+
</Alert>
146+
147+
148+
10. To generate CSS from your theme, run the following command:
149+
150+
```bash
151+
npx @digdir/designsystemet@latest tokens build --config designsystemet.config.json
152+
```
153+
154+
Remember that this must also be done whenever the tokens are updated.

0 commit comments

Comments
 (0)