docs: get started with your theme

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

@@ -1,106 +1,154 @@
 ---
 title: Build your theme
 sidebar_title: Build your theme
-description: Learn how to use Designsystemet with your own brand colors and preferences.
-date: 2025-02-28
-category: Theme Builder
+description: Learn how to use Designsystemet with your own brand colours and preferences.
+date: 2025-11-07
+category: Theme builder
 color: blue
 icon: PaletteIcon
 published: true
 order: 10
 ---
 
-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.
+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.
 
-## Connection between design and code
-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.
+<Alert data-color="info">
+We recommend that both a developer and a designer take part in the process when setting up your theme.
+</Alert>
 
-**Option 1:** _Without_ a connection between Figma and code  
-**Option 2:** _With_ a connection between Figma and code
+## How to get started:
 
-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.
+1. Copy the configuration file below and save it as `designsystemet.config.json`
 
-We’ll walk you through both options below.
+```json
+{
+  "outDir": "./design-tokens",
+  "clean": true,
+  "themes": {
+    "theme": {
+      "colors": {
+        "main": { "primary": "#0062BA", "accent": "#1E98F5" },
+        "neutral": "#1E2B3C",
+        "support": { "extra1": "#F45F63", "extra2": "#E5AA20" }
+      },
+      "borderRadius": 4
+    }
+  }
+}
+```
+2. Find a Git repository where you can store your Design Tokens. Place the `designsystemet.config.json` file in the root of the repository.
 
+3. Clone the repository locally to your machine, open a terminal, and navigate to the folder containing the repository.
 
-## Option 1: Without direct connection
+4. Make sure you have Node.js installed, version 20 or higher.
 
-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.
+5. Run the following command in the terminal:
+```bash
+npx @digdir/designsystemet@latest tokens create --config designsystemet.config.json
+```
+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.
 
-### Here's how to proceed:
+<Alert data-color="info">
+Next, we will move into Figma. Make sure you are using the Figma desktop app, not the browser version.
+</Alert>
 
-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.
-2. Install Designsystemet's [plugin for Figma](https://www.figma.com/community/plugin/1382044395533039221/designsystemet-beta).
-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).)
+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.
 
-    Click "Apply theme". Copy the code snippet.
+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.
 
-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.)
-
-    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.
-
-
-
-<ResponsiveIframe
-  src="/img/plugin-alt1.mp4"
-  title="The video goes through steps 1-4 as described above."
-  frameBorder="0"
-  allow="autoplay; fullscreen; picture-in-picture"
-  allowFullScreen
-  aspectRatio="16-9"
+<Image
+  src='/img/tokenstudio.png'
+  alt='Screenshot of Figma showing where to find plugins'
+  boxShadow={false}
 />
 
+  - 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.
+  - Remember to set the “Token storage location” to `design-tokens` (or whatever you have named your Design Tokens folder).
 
+<Alert data-color="info">
+We recommend *not* pushing changes to Design Tokens from Tokens Studio, as this may cause you to lose your overrides when updating.
+</Alert>
 
-## Option 2: With connection
+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.
 
-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.
 
-<Card
-  data-color="brand2"
-  data-variant="tinted"
->
-  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).
-</Card>
+```bash
+npx @digdir/designsystemet@latest tokens create --config designsystemet.config.json
+```
 
+**Remember to run this command every time you make changes to the configuration file.**
 
-### Here's how to proceed:
+9. In Tokens Studio, select the “Pull” icon to fetch the new tokens into Figma.
 
-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.
-
-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.
+<Image
+  src='/img/fundamentals/themebuilder/own-theme/tokens-studio-pull-button.png'
+  alt='Screenshot of Tokens Studio showing where to find the pull button'
+  boxShadow={false}
+/>
 
-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.
+Select `Styles & variables` and `Export styles & variables to Figma`.
 
 <Image
-  src="/img/tokenstudio.png"
-  alt="Screenshot of Figma showing where to find plugins"
+  src='/img/fundamentals/themebuilder/own-theme/tokens-export.png'
+  alt='Screenshot of Tokens Studio showing where to find the export button'
   boxShadow={false}
-
 />
 
-  - 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.
-  - Remember to set "Token storage location" to `design-tokens` (or whatever you have chosen to call your folder with Design Tokens).
-
-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:
+Make sure you have these settings before clicking `Confirm`:
 
 <Image
-  src="/img/token-studio-settings.png"
-  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"
+  src='/img/fundamentals/themebuilder/own-theme/tokens-export-options.png'
+  alt='Screenshot of Tokens Studio showing which settings to use when exporting tokens to Figma'
   boxShadow={false}
-
 />
 
-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".
+Select `Themes`, `Select All`, and `Export to Figma`:
 
 <Image
-  src="/img/brutte-referanser.png"
-  alt="Screenshot showing broken links in Figma variables. Right-click and delete the themes you don't need."
+  src='/img/fundamentals/themebuilder/own-theme/tokens-export-themes-select.png'
+  alt='Screenshot of Tokens Studio showing that you must select Themes and then Select All'
   boxShadow={false}
-
-
 />
 
-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.
-
-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.
+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.
+
+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.
+
+
+```json
+{
+  "outDir": "./design-tokens",
+  "clean": true,
+  "themes": {
+    "theme-one": {
+      "colors": {
+        "main": { "primary": "#0062BA", "accent": "#1E98F5" },
+        "neutral": "#1E2B3C",
+        "support": { "extra1": "#F45F63", "extra2": "#E5AA20" }
+      },
+      "borderRadius": 4
+    },
+    "theme-two": {
+      "colors": {
+        "main": { "primary": "#0062BA", "accent": "#1E98F5" },
+        "neutral": "#1E2B3C",
+        "support": { "extra1": "#F45F63", "extra2": "#E5AA20" }
+      },
+      "borderRadius": 4
+    }
+  }
+}
+```
+
+<Alert data-color="info">
+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.
+</Alert>
+
+
+10. To generate CSS from your theme, run the following command:
+
+```bash
+npx @digdir/designsystemet@latest tokens build --config designsystemet.config.json
+```
+
+Remember that this must also be done whenever the tokens are updated.