From Figma to npm Package: Automate Your Design Tokens Pipeline

In my previous article, I wrote about why developers should care about design tokens. If you haven’t read it yet, or don’t have a clue what design tokens are, you should take a few minutes to check it out.

Design tokens keep your product looking and feeling the same everywhere. But only if developers can actually use them. So in this article, we’ll take those tokens your design team worked on and turn them into a shareable npm package. That way, every app can pull from one source of truth instead of everyone styling things differently.

For this (not so) simple trick, we’ll need the following tools:

• Figma
• Tokens Studio Plugin
• Node.js and an npm account
• Style Dictionary
• GitHub
• A code editor/IDE
• Some JavaScript knowledge and a few other packages

An important prerequisite: DTCG standards alignment

Before you start this process, your development and design teams should align on using the DTCG (Design Tokens Community Group) standards for setting up your tokens.

Without this alignment, you'll likely run into several issues:

• Naming convention conflicts: Figma Variables and Tokens Studio might structure token names differently than what Style Dictionary expects, causing transformation failures.
• Type mismatches: A token defined as a "color" in your design tool might not map correctly to CSS variables if the type definitions aren't standardized.
• Broken token references: Aliased tokens (tokens that reference other tokens) can fail to resolve properly during the transformation process.
• Manual cleanup overhead: You'll spend countless hours manually fixing JSON files after each sync instead of having an automated pipeline.

The DTCG format provides a common language that ensures your tokens maintain their integrity as they move from design tool to code. Have this conversation with your design team early; ideally before any tokens are created. If your tokens are already set up in a non-standard format, you may need to refactor them before proceeding with this workflow.

Brief overview of how this works

Here’s a quick look at how we go from tokens to an npm package. Your design tokens start in Figma, either as Variables or inside Tokens Studio. From there, you’ll sync them to GitHub, where they’ll live as JSON files. Then we’ll use a few tools to turn those files into code-friendly formats like CSS variables and JSON objects. Finally, we’ll package everything up and publish it to npm so every team can use the same design values everywhere.

That’s it. Design → Sync → Transform → Publish → Use.

How to publish your design tokens

Import your Figma Variables into Tokens Studio

The Tokens Studio plugin is a powerful tool for managing design tokens. For the purpose of achieving our goal, it helps us export the variables defined in Figma as JSON to be stored in a GitHub repository.

If your tokens are in Figma Variables, this guide should help you get them into Tokens Studio. Or you can bypass this process entirely by using the Tokens Studio plugin to set up your tokens. Using this guide, you can export them to Figma as variables to be used in the design process.

So your flow either looks like one of these two.

If you do not have any tokens to set up, you can copy the tokens I will be using for this demo from my samples folder. It’s a small three-level token setup with only the values needed to demonstrate our results at the end. Do the following:

• Create a new Figma file.
• Click on ‘Actions’, switch to the ‘Plugin & Widgets’ tab, search for ‘Tokens Studio for Figma’, and select it.

• When the plugin loads, select ‘New empty file’.

• Rename the default set to ‘options’, then create two others called ‘semantics’, and ‘components.’ All lower case.

• Copy and paste the JSON objects from the files into the corresponding JSON editor on each set.

• Make sure you start with ‘options’. Since each set references the previous, you must do this in order. Click save on each then check the list screen to ensure each style saved correctly.

Your tokens are now ready for export!

Setup the GitHub <> Tokens Studio sync

Tokens Studio plugin offers a native integration with GitHub to sync your tokens with the repo. You can follow the official Tokens Studio guide here to achieve this connection.

If you’re using the free version of the plugin, you’ll only be able to connect to your main branch. This means that updates from design to GitHub will be pushed directly to the main branch. To switch branches, you must upgrade to the Pro version of the Tokens Studio plugin.

I am exporting all tokens into a single file called tokens.json, and I have appended .json to indicate that I want all tokens stored in a single file. Multiple files are a Pro feature.

Create an npm account and set up your organization

You’ll need an account to publish your package.

• Go to the npm signup page https://www.npmjs.com/signup.
• Fill the signup form and submit.
• Click on the user image, then select ‘Add Organization’.

• Enter the organization name of your choice. You can select to create public or private (paid) packages. I’ll go with public.

• You might be prompted to add users to the organization. You can skip this step for now.

• We need to set up trusted publishing between GitHub and npm to enable automated deployments. A package needs to exist before we can set up trusted publishing, so we need a placeholder package.
• We’ll create one using setup-npm-trusted-publish by azu.
• Log in to npm through your terminal by running npm login. This takes you to the browser to complete the login process. Once successful, you should see “Logged in on https://registry.npmjs.org/.” in your terminal.
• In a terminal window, run npm install -g setup-npm-trusted-publish
• Run setup-npm-trusted-publish <package-name>. For me, that looks like:

1setup-npm-trusted-publish @jensdemo/design-tokens

• You should see a success message. Refresh your organization’s page on npm to see the new package.

• To continue the trusted publishing set up, click on the package and navigate to the ‘Settings’ tab. Then select ‘GitHub Actions’ as your publisher.

• Under ‘Organization or user’, enter your GitHub username or your organization’s name. Also enter your repository name. For ‘Workflow file name’, enter release.yml.

• Click ‘Setup connection’.

Set up your local repository

If you followed the ‘Setup the GitHub <> Tokens Studio sync’ guide, then you should have a repository on GitHub with one or more JSON files containing your design tokens. The next step is to set up locally.

• First, clone the repository that holds your tokens. You can follow the GitHub guide on how to do this.
• Create a package.json file by running npm init.
• In the utility workthrough, enter your package name exactly as it appears on npm e.g. @jensdemo/design-tokens
• Enter 0.0.1 as the version.
• You can accept the defaults for everything else, or update them if needed.
• Create a .gitignore file, and paste in the following:

1node_modules

Transform your tokens into CSS variables and JSON objects

Back to the fun part! We’re going to take the design tokens that currently live in our repository and convert them into CSS variables and JSON objects.

First, we’re going to install Style Dictionary, Tokens Studio’s SD Transforms, and Typescript. These packages will handle the heavy lifting behind the scenes. The Style Dictionary is what actually builds and outputs our tokens into formats such as CSS or JSON. The Tokens Studio SD Transforms plugin helps it understand the structure that comes from Figma, so references resolve correctly. And TypeScript ensures that everything we generate and export has proper types.

• Open your terminal and ensure you’re in the repo’s directory. Then run:

1npm i -D style-dictionary @tokens-studio/sd-transforms typescript

• Now, we’re going to manually update the package.json file with some needed configurations.
  • type: set it to "module" so Node and modern bundlers treat the files as ES modules.
  • main: this points to the CommonJS build so older projects can still import it easily.
  • module: this gives modern tools an ES module entry for faster, cleaner imports.
  • types : this tells TypeScript users where to find the type definitions.
  • exports: add it so users can import CSS, JSON, or raw tokens from specific paths.
  • files: limits what gets published so the npm package stays clean and lightweight.
  • tokens:build: this script builds the tokens into ready-to-use files.
  • tokens:watch: this script rebuilds automatically whenever token files change.
  • prepublishOnly: it ensures the tokens build before every publish to npm.
  • keywords – these make the package easier to find on npm. This helps if you’re publishing a public package that you want others developers to adopt.

You can see my package.json below.

1{
2  "name": "@jensdemo/design-tokens",
3  "version": "0.0.1",
4  "description": "Design tokens from our design system.",
5  "type": "module",
6  "main": "dist/index.cjs",
7  "module": "dist/index.js",
8  "types": "dist/index.d.ts",
9  "exports": {
10    ".": {
11      "types": "./dist/index.d.ts",
12      "import": "./dist/index.js",
13      "require": "./dist/index.cjs"
14    },
15    "./css/variables.css": "./dist/css/variables.css",
16    "./json/components.json": "./dist/json/components.json",
17    "./raw/tokens.json": "./tokens.json"
18  },
19  "files": [
20    "dist",
21    "tokens.json",
22    "README.md",
23    "LICENSE"
24  ],
25  "scripts": {
26    "tokens:build": "style-dictionary build --config sd.config.js --verbose",
27    "tokens:watch": "style-dictionary build --config sd.config.js --watch --clean",
28    "prepublishOnly": "npm run tokens:build"
29  },
30  "keywords": [
31    "design-tokens",
32    "style-dictionary",
33    "tokens-studio"
34  ],
35  "author": "jenoftencodes",
36  "license": "MIT",
37  "bugs": {
38    "url": "https://github.com/jenniferokafor/design-tokens-package/issues"
39  },
40  "homepage": "https://github.com/jenniferokafor/design-tokens-package#readme",
41  "devDependencies": {
42    "@tokens-studio/sd-transforms": "^2.0.1",
43    "style-dictionary": "^5.1.1",
44    "typescript": "^5.9.3"
45  }
46}

• In the root folder, create an sd.config.js file. This is where we will transform our JSON objects into usable style variables. If you’re using the same token structure as I am, then the transforms below should work for you. It’s possible that there’s a cleaner, more native way to do this, but the approach below has worked for me so far.

1/** sd.config.js */
2import fs from "fs";
3import StyleDictionary from "style-dictionary";
4import * as sdTransforms from "@tokens-studio/sd-transforms";
5
6sdTransforms.register(StyleDictionary);
7const raw = JSON.parse(fs.readFileSync("tokens.json", "utf8"));
8
9/**
10 * Deep merge function to combine token sets while preserving nested structures
11 */
12const deepMerge = (target, source) => {
13  const output = { ...target };
14  if (source && typeof source === "object" && !Array.isArray(source)) {
15    Object.keys(source).forEach((key) => {
16      if (
17        source[key] &&
18        typeof source[key] === "object" &&
19        !Array.isArray(source[key]) &&
20        !source[key].$type &&
21        !source[key].$value
22      ) {
23        output[key] = deepMerge(target[key] || {}, source[key]);
24      } else {
25        output[key] = source[key];
26      }
27    });
28  }
29  return output;
30};
31
32// Deep merge options and semantics as base (for reference resolution)
33// This preserves nested structures so options.color.teal.500 and semantics.color.primary
34// can coexist at color.teal.500 and color.primary
35const base = deepMerge(raw.options ?? {}, raw.semantics ?? {});
36
37const tokens = {
38  ...base,
39  components: raw.components ?? {},
40  $metadata: raw.$metadata ?? {},
41};
42
43// Filter to only include tokens inside the components set
44const onlyComponents = (token) => token.path[0] === "components";
45
46/**
47 * Custom name transform that removes the "components" prefix
48 * and converts to kebab-case.
49 */
50StyleDictionary.registerTransform({
51  name: "name/kebab-no-components",
52  type: "name",
53  transform: (token) => {
54    const path =
55      token.path[0] === "components" ? token.path.slice(1) : token.path;
56
57    return path
58      .join("-")
59      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
60      .replace(/[\s_]+/g, "-")
61      .toLowerCase();
62  },
63});
64
65/**
66 * Helper function to extract nested component tokens and remove the "components" prefix.
67 * Uses the nested dictionary.tokens structure and extracts just the resolved values.
68 */
69const extractComponentsFromTokens = (tokensObj) => {
70  if (!tokensObj || !tokensObj.components) {
71    return {};
72  }
73
74  const extractValues = (obj) => {
75    if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
76      return obj;
77    }
78
79    if ("$value" in obj && Object.keys(obj).length > 1) {
80      return obj.$value;
81    }
82
83    const result = {};
84    for (const [key, value] of Object.entries(obj)) {
85      result[key] = extractValues(value);
86    }
87    return result;
88  };
89
90  return extractValues(tokensObj.components);
91};
92
93/**
94 * Format for ESM JavaScript export
95 */
96StyleDictionary.registerFormat({
97  name: "javascript/esm-components",
98  format: ({ dictionary }) => {
99    const tokens = extractComponentsFromTokens(dictionary.tokens);
100    return `export default ${JSON.stringify(tokens, null, 2)};`;
101  },
102});
103
104/**
105 * Format for CJS JavaScript export
106 */
107StyleDictionary.registerFormat({
108  name: "javascript/cjs-components",
109  format: ({ dictionary }) => {
110    const tokens = extractComponentsFromTokens(dictionary.tokens);
111    return `module.exports = ${JSON.stringify(tokens, null, 2)};`;
112  },
113});
114
115/**
116 * Format for nested JSON export
117 */
118StyleDictionary.registerFormat({
119  name: "json/nested-components",
120  format: ({ dictionary }) => {
121    const tokens = extractComponentsFromTokens(dictionary.tokens);
122    return JSON.stringify(tokens, null, 2) + "
123";
124  },
125});
126
127export default {
128  tokens,
129  preprocessors: ["tokens-studio"],
130  clean: true,
131  platforms: {
132    css: {
133      transformGroup: "tokens-studio",
134      transforms: ["name/kebab-no-components"],
135      buildPath: "dist/css/",
136      files: [
137        {
138          destination: "variables.css",
139          format: "css/variables",
140          options: { selector: ":root" },
141          filter: onlyComponents,
142        },
143      ],
144    },
145    json: {
146      transformGroup: "tokens-studio",
147      buildPath: "dist/json/",
148      files: [
149        {
150          destination: "components.json",
151          format: "json/nested-components",
152          filter: onlyComponents,
153        },
154      ],
155    },
156    js: {
157      transformGroup: "tokens-studio",
158      buildPath: "dist/",
159      files: [
160        {
161          destination: "index.js",
162          format: "javascript/esm-components",
163          filter: onlyComponents,
164        },
165        {
166          destination: "index.cjs",
167          format: "javascript/cjs-components",
168          filter: onlyComponents,
169        },
170      ],
171    },
172  },
173};

• If you’re using a different token structure or need more custom transforms, read the documentation for Style Dictionary and Style Dictionary Transforms for Tokens Studio to set up your own transformation.
• If your setup works, you should be able to run npm run tokens:build and see the CSS, JSON, index.cjs, and index.js outputs in dist/.

1/** dist/css/variables.css */
2/**
3 * Do not edit directly, this file was auto-generated.
4 */
5
6:root {
7  --hero-background: #2f1893;
8  --hero-text: #ffffff;
9  --hero-max-width: 665px;
10  --hero-gap: 20px;
11  --hero-heading-color: #ffffff;
12  --hero-heading-accent-color: #25dac5;
13  --hero-heading-font-family: 'DM Sans', system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
14  --hero-heading-font-size: 52px;
15  --hero-heading-font-weight: 700;
16  --hero-heading-line-height: 1.2px;
17  --hero-body-color: #ffffff;
18  --hero-body-font-family: 'DM Sans', system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
19  --hero-body-font-size: 18px;
20  --hero-body-font-weight: 400;
21  --hero-body-line-height: 1.2px;
22  --button-primary-background: #25dac5;
23  --button-primary-text: #ffffff;
24  --button-primary-radius: 30px;
25  --button-primary-padding-x: 46px;
26  --button-primary-padding-y: 22px;
27  --button-primary-font-family: 'DM Sans', system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
28  --button-primary-font-size: 16px;
29  --button-primary-font-weight: 500;
30  --button-primary-line-height: 1px;
31}

Support TypeScript and autocomplete

Now that your tokens build correctly, let’s make them TypeScript-friendly. This step adds type definitions so you get autocomplete and type safety when using the tokens in your code. It’s not required, but it makes the developer experience much smoother.

1/** dist/json/components.d.ts */
2/**
3 * Type definitions for JSON component tokens export
4 *
5 * @example
6 * ```ts
7 * import components from '@jensdemo/design-tokens/json/components.json';
8 *
9 * const heroBg = components.hero.background;
10 * ```
11 */
12export interface ComponentTokens {
13  [key: string]: string;
14}
15
16export interface Components {
17  [componentName: string]: ComponentTokens;
18}
19
20declare const components: Components;
21export default components;

1// dist/index.d.ts
2/**
3 * Design tokens exported from Tokens Studio
4 *
5 * Each component token is an object with string values representing
6 * design properties like colors, sizes, typography, etc.
7 */
8export interface ComponentTokens {
9  [key: string]: string;
10}
11
12/**
13 * Design tokens organized by component
14 *
15 * Generated from Tokens Studio/Figma tokens
16 *
17 * @example
18 * ```ts
19 * import tokens from '@jensdemo/design-tokens';
20 *
21 * const heroBg = tokens.hero.background; // "#2f1893"
22 * const buttonColor = tokens.buttonPrimary.background; // "#25dac5"
23 * ```
24 */
25declare const designTokens: {
26  [componentName: string]: ComponentTokens;
27};
28
29export default designTokens;

Publish package updates

After transforming our tokens into design assets, we need to publish the updates to the package.

• First, update your README to provide users with proper documentation on what your design tokens include, an installation guide, how-to guides, and examples.
• Next, install semantic-release. We’ll use this to automate the release process triggered by pushes from Figma and your local environment. Read more in the docs. To install, run:

1npm i semantic-release

• Next, create your release.yml file and paste this config:

1# .github/workflows/release.yml
2name: Release
3
4on:
5  push:
6    branches:
7      - main
8  workflow_dispatch:
9
10permissions:
11  id-token: write
12  contents: write
13  issues: write
14  pull-requests: write
15
16jobs:
17  release:
18    runs-on: ubuntu-latest
19    steps:
20      - name: Checkout repository
21        uses: actions/checkout@v4
22        with:
23          fetch-depth: 0
24
25      - name: Setup Node.js
26        uses: actions/setup-node@v4
27        with:
28          node-version: "lts/*"
29          registry-url: "https://registry.npmjs.org"
30          scope: "@jensdemo"
31
32      - name: Install dependencies
33        run: npm ci
34
35      - name: Build package
36        run: npm run tokens:build
37
38      - name: Release
39        env:
40          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
41        run: npx semantic-release

• Change the scope to your organization's name.

• Commit your changes with a message starting with “feat:” or “fix:”. Because we are using semantic-release for automated release and versioning, the commit message structure matters. All commits that need to trigger a release must be prefixed with "feat:", "fix:", or "BREAKING CHANGE:". If semantic-release doesn't find any conventional commits, the updates to tokens will not reflect in the package.

• Push your changes, and you should see a running action on GitHub. When successful, the status icon should display a green color.

• Your transformed design tokens should be live and ready for use!

Updating the package using the Tokens Studio Plugin

• To update the package from Figma, simply make the needed changes to the tokens. You can either update your Figma Variables and import the changes into Tokens Studio, or update Tokens Studio directly and export the changes to your variables.
• Once the tokens in Tokens Studio change, the ‘Push’ icon becomes active and shows an indicator.

• Click the icon, enter a commit message prefixed with "feat:", "fix:", or "BREAKING CHANGE:", if you want to trigger a release, and click ‘Push Changes’.

• This should immediately trigger a release action on GitHub. Once successful, the changes will be live in your package.

Conclusion

There you have it! A complete, automated workflow that takes your design tokens from living in a neglected design file to a shared source of truth that everyone can work with. Of course, there’s a lot more customization you can do to create a workflow that fits your team’s unique needs. But I hope this serves as a great starting point.

Check out the repo used for demonstration in this article, as well as the published package on npm. Build something fun!