DEV Community: Alexander

Stop exporting JSON tokens and use CSS variables instead

Alexander — Wed, 14 Oct 2026 16:30:41 +0000

A designer tagged me in a Figma comment on Tuesday morning. They wanted to know if we could start exporting our brand tokens as deeply nested JSON files. They had just read an article about complex token pipelines. I just stared at my screen for a minute. We are a web team building a React application. We do not need a massive parsing engine just to read a blue hex code.

This happens all the time in our industry. Teams get obsessed with the idea of a universal format. They build massive configurations to transform JSON into something the browser can actually use. It feels like everyone is overcomplicating the simplest part of frontend development.

The pipeline trap

I see this pattern everywhere. A team decides they need a design system. They set up a pipeline that exports something like this from Figma.

{
  "color": {
    "brand": {
      "primary": {
        "value": "#0052cc",
        "type": "color"
      }
    },
    "background": {
      "base": {
        "value": "#ffffff",
        "type": "color"
      }
    }
  }
}

Then the web developers have to write a script to flatten this object. They have to map it to their styling solution. Maybe they are using Tailwind. Maybe they are using styled-components. Either way, it adds a completely unnecessary layer of complexity.

If a colour breaks in production, you cannot just inspect it easily. You have to trace the error back through your build script. You have to figure out if the JSON was malformed or if your parser failed. That is a lot of wasted time for a background colour.

The browser already solved this

CSS variables are the only token format that actually matters for the web. You do not need a build step to use them. You just load the file and the browser understands it immediately.

Look at how much cleaner the CSS approach is.

:root {
  --color-brand-primary: #0052cc;
  --color-background-base: #ffffff;
}

You can inspect this directly in Chrome DevTools. You can change the values on the fly to test new designs. You can scope them to specific components. JSON cannot do any of that natively.

Theming is where CSS variables really show their power. If you want to add a dark mode using JSON, you usually have to output multiple files. Then you have to write JavaScript logic to swap those themes in your application. With CSS variables, the browser does all the heavy lifting for you.

[data-theme="dark"] {
  --color-brand-primary: #4c9aff;
  --color-background-base: #111111;
}

You just toggle a data attribute on your HTML tag. The browser updates every single component instantly. There is no JavaScript required. There is no complex state management. It just works.

What about native apps?

This is always the counter-argument I hear. People say you need JSON so iOS and Android can consume the exact same tokens.

That is technically true if you work at a massive tech company with dedicated mobile teams. But most teams are web-first. Even if you do have mobile developers, forcing the web team to parse JSON just to appease iOS is backwards. Let the mobile teams compile what they need. The web should just get CSS. You should optimise for the platform where your users actually spend their time.

A better workflow

We stopped doing the JSON dance months ago. Now we just push CSS variables straight from Figma to our repository.

The designer updates a colour in Figma. A pull request automatically appears in our GitHub repository with the raw CSS file. The developer reviews the visual diff and merges it. The pipeline is entirely transparent. There are no build scripts to maintain.

This is exactly why I built Design System Sync. I got incredibly tired of writing parsing scripts for different teams. I wanted a tool that respects how the web actually works. It exports your Figma variables directly to GitHub or Bitbucket as ready-to-use CSS variables. It handles the formatting automatically.

You can check it out at https://ds-sync.netlify.app?utm_source=devto&utm_medium=post&utm_campaign=bot or grab the plugin directly from the Figma Community at https://www.figma.com/community/plugin/1561389071519901700?utm_source=devto&utm_medium=post&utm_campaign=bot.

It also supports W3C formats if you really need them. But honestly, you probably just need CSS.

Are you still maintaining custom build scripts to parse JSON tokens for your web application?

JSON design tokens are a massive frontend anti-pattern

Alexander — Wed, 07 Oct 2026 16:30:57 +0000

A Slack message popped up at 4 PM last Thursday. A junior developer was completely stuck on a simple button component. He was trying to map a dark mode background colour. I looked at his screen share. He had imported a massive nested JSON file from our design system package.

He was writing a complex JavaScript helper function. Its only job was to extract a hex code based on a React theme context provider. He had spent two hours trying to figure out why the nested object paths kept returning undefined. The token structure had changed slightly in the latest design system release. A new category called interactive was added. His static paths were completely broken.

This is absolute madness. We have completely overcomplicated how we handle design tokens on the web.

The parsing nightmare

JSON is a fantastic format for data transfer. It is a terrible format for frontend styling. Somewhere along the line we decided that raw JSON was the ultimate source of truth. We started shipping these massive files directly into our web codebases.

Think about the workflow. You get a raw token file from Figma. It has nested objects for typography, colours, and spacing. Your web app cannot read this natively. So you add a build step. You bring in Style Dictionary. You configure a complex pipeline just to flatten the JSON into something usable.

You end up writing custom formatters. You write regex patterns to catch specific token names. You spend days maintaining a build pipeline that produces basic style values.

Or worse, you load it at runtime in your components.

import tokens from './tokens.json'
import styled from 'styled-components'

const Button = styled.button`
  background-color: ${(props) => props.theme === 'dark'
    ? tokens.colors.dark.interactive.primary
    : tokens.colors.light.interactive.primary};
  border-radius: ${tokens.spacing.radius.sm};
  padding: ${tokens.spacing.layout.md};
`

Look at that code. You are using JavaScript to do a job the browser engine was built to handle automatically. You are bloating your bundle size with a massive object full of values you might never even use. You are adding runtime overhead just to paint a blue box on the screen.

Every time a component mounts it has to evaluate those object paths. It has to check the theme context. It is incredibly inefficient.

Real world token disasters

I have seen this break in so many different ways across different companies.

A few months ago I consulted for a team using Vue. They had a really strict design system. They had built a custom Vite plugin just to convert their JSON design tokens into SCSS variables on the fly. The build time was incredibly slow.

Every time a designer updated a single padding value in Figma, the entire frontend had to recompile from scratch. The Vite plugin had to parse a massive JSON file. It generated hundreds of SCSS variables. Then the SCSS compiler had to process all of those variables across fifty different components. They were maintaining thousands of lines of build configuration just to change a border radius.

Then there is the React Native approach creeping into the web. Teams load the entire JSON object into a global state manager like Redux or Zustand. They pass it down through context providers. Every single component re-renders if a theme value changes.

I saw a dashboard application freeze for two full seconds when a user clicked the dark mode toggle. The browser had to recalculate the style of every single DOM node using JavaScript. It was a massive performance hit.

We keep building these complex abstractions. We write utility functions to resolve alias tokens. We write fallbacks for missing values. We write type definitions for deeply nested objects. We are doing all of this work to recreate features that CSS already has built right in.

The browser already solved this

CSS variables are the only token format web developers should care about. They are native. They are fast. They are incredibly powerful.

They cascade naturally down the DOM tree. They update instantly without a page reload or a JavaScript re-render. You do not need a bundler to read them. You do not need a custom Vite plugin.

:root {
  --brand-primary: #0052cc;
  --spacing-md: 16px;
  --radius-sm: 4px;
}

@media (prefers-color-scheme: dark) {
  :root {
    --brand-primary: #4c9aff;
  }
}

.btn {
  background-color: var(--brand-primary);
  padding: var(--spacing-md);
  border-radius: var(--radius-sm);
}

This is so much cleaner. The browser handles the dark mode switch automatically through the media query. You drop the JavaScript context providers entirely. You drop the complex build steps. You just write simple CSS.

If a token changes, the browser repaints the affected elements instantly. There is no JavaScript evaluation. There is no bundle bloat. The browser engine is highly optimised for exactly this task.

The mobile argument

Now I know exactly what the platform architects will say. They will tell me that JSON is the only way to share tokens across iOS, Android, and the web. They will say we need a single agnostic format to rule them all.

They are right about mobile development. iOS and Android genuinely need those JSON files. Swift and Kotlin cannot read CSS variables natively. They need a data structure they can parse and compile into their own native style objects.

But that does not mean the web team should be punished. You do not have to force a generic data format into a web environment just for the sake of consistency. Consistency is useless if it hurts performance and developer experience.

The solution is to generate the native formats right at the source.

When a designer updates a token in Figma, the web team should get a CSS file automatically. The iOS team should get a JSON file. The Android team should get an XML file. You should not have to run a complex transformation pipeline in your own web repository. The formatting should happen before the code ever reaches your pull request.

This is exactly why I built Design System Sync. I wanted a way to skip the middleman entirely. You run the plugin in Figma and it generates a pull request directly to your GitHub or Bitbucket repository. It can export standard W3C JSON tokens for your mobile teams if you need them. But for the web it spits out pure CSS variables. It even handles the light and dark mode media queries automatically. You can check out the Design System Sync website or grab it directly from the Figma Community to see how it works.

Stop forcing your web apps to parse massive JSON files for basic styling. Let the browser do the heavy lifting.

Are you still shipping raw token objects in your JavaScript bundles?

Stop writing hex codes in your CSS

Alexander — Wed, 30 Sep 2026 16:30:41 +0000

The hover state that started it all

A design review last Monday morning really got under my skin. Our lead designer noticed a subtle mismatch in a button hover state. I opened the component file to check the code. Right there in the styled component was a hardcoded #3B82F6.

The problem is our primary brand blue changed to #2563EB three months ago.

This developer had just copied the hex code straight from the Figma inspector. They pasted it into the CSS and moved on to the next ticket. It worked perfectly on their machine. It passed the visual review for that specific PR. But it created a tiny bit of technical debt that eventually broke our visual consistency.

This happens everywhere. I see it in almost every codebase I audit. We spend weeks arguing about component architecture and state management. Then we just throw raw hex codes into our styles like it is 2010.

It needs to stop.

The find and replace nightmare

Let us look at a really common scenario. You are building a new dashboard. You need a subtle grey border. You grab #E5E7EB and drop it in.

.card {
  background-color: #FFFFFF;
  border: 1px solid #E5E7EB;
  color: #111827;
}

A month later the design team decides all borders need to be slightly darker for accessibility. They want #D1D5DB. You open your code editor and do a global search for #E5E7EB.

You find 47 results. But wait. Are all of these borders? Some of them are background colours for disabled buttons. Some are divider lines. You cannot just do a blind find and replace. You have to manually check every single instance. A five minute design tweak just became an hour of tedious code archaeology.

This is a massive waste of developer time. It also introduces a huge risk of human error. You will inevitably miss one instance or accidentally change a background colour that happened to share the same hex value.

The dark mode scaling problem

The pain gets much worse when you introduce dark mode. If you use raw hex codes you have to write completely separate style blocks for your dark theme.

.button-primary {
  background-color: #2563EB;
  color: #FFFFFF;
}

@media (prefers-color-scheme: dark) {
  .button-primary {
    background-color: #3B82F6;
    color: #1F2937;
  }
}

Now imagine doing this for fifty different components. Your CSS file sizes explode. Your maintenance burden doubles. Every time a colour changes you have to update it in two places. If you forget one the whole UI looks broken for half your users.

It makes your components incredibly rigid. A simple button suddenly needs to know entirely too much about your global theme configuration.

The multi-brand chaos

This scales terribly if you build white label products. I worked on a SaaS platform last year that had to support five different client brands.

The previous team had tried to solve this with massive Sass maps full of hex codes. Every time they onboarded a new client they had to duplicate hundreds of lines of colour definitions. The compilation times were awful. The developer experience was miserable.

Every new feature required testing across five hardcoded themes. It was a complete disaster for productivity.

The counter argument

I know what you might be thinking right now. Setting up a full token system feels like overkill for small projects. Sometimes you just need to ship a quick landing page by Friday. You do not want to spend two hours configuring CSS variables before you even write a line of markup.

I get that completely. Speed matters. But the reality is that copying and pasting hex codes is a false economy. You save five minutes today to lose five hours next month.

Semantic variables are the only way

The solution is actually very simple. You just need to stop thinking about colours and start thinking about intent.

We should never write #2563EB. We should write var(--color-primary-base). We should never write #E5E7EB. We should write var(--border-subtle).

:root {
  --color-primary-base: #2563EB;
  --border-subtle: #E5E7EB;
  --text-main: #111827;
}

.card {
  border: 1px solid var(--border-subtle);
  color: var(--text-main);
}

When the design team updates the brand you change one line of code. When you need dark mode you just redefine those variables in a media query or a data attribute. The component CSS never changes. It just works.

Connecting the source of truth

The real challenge is keeping those variables in sync with the design team. Designers work in Figma. Developers work in code editors.

This exact friction is why I built Design System Sync. It is a tool that bridges this gap completely. You define your colours and variables in Figma. The plugin exports those exact design tokens directly to GitHub or Bitbucket via automatic pull requests.

It supports standard W3C Design Tokens and raw CSS variables. It handles all the formatting for you. It even does visual diffs so you can see exactly what changed before you merge. You can check out the website to see how it works. You can also grab it directly from the Figma Community.

When you automate the handover you completely remove the temptation to hardcode things. The variables are just there waiting for you in your codebase.

So look at your main stylesheet today. How many raw hex codes are sitting there waiting to break your next redesign? Are you really saving time by skipping variables?

Stop exporting design tokens to JSON for your web apps

Alexander — Wed, 23 Sep 2026 16:30:49 +0000

A PR review last Thursday morning triggered this thought. A developer had written a 40-line utility function in our main web repository. Its only job was to parse a deeply nested JSON file from our design system. They were mapping tokens.color.brand.primary.value into a styled-component. I stared at the screen for a good five minutes. We were shipping extra JavaScript to the client just to figure out what shade of blue a button should be. It felt completely backwards.

I asked the developer why they did not just use a simple CSS class. They told me the design system team only provided a JSON file. This is a massive disconnect. Design system teams are optimising for their own theoretical architecture. They completely ignore how browsers actually work.

The parsing madness

We have collectively lost our minds with token pipelines. Someone decided a few years ago that JSON is the universal language of design tokens. So now we force web developers to jump through massive hoops just to apply a background colour.

You take a beautiful Figma file. You export it to a massive JSON blob. Then you run it through a build tool like Style Dictionary. Then you import it into your React or Vue app. Then you write a helper function to read it safely.

Here is what that looks like in practice.

// Why are we doing this to ourselves?
import tokens from './design-tokens.json'

const getSpacing = (size) => {
  if (!tokens.spacing[size]) {
    return tokens.spacing.base.value
  }
  return tokens.spacing[size].value
}

We treat design systems like backend APIs. We fetch the data. We parse it. We map it. But CSS is not a database. It is a styling language. Browsers have spent decades perfecting how to cascade and apply styles efficiently. When we wrap tokens in JSON and JavaScript, we are actively fighting the browser.

This is completely unnecessary for web applications. The browser already has a highly optimised native engine for reading, cascading, and updating design values. They are called CSS variables.

The debugging nightmare

Think about the developer experience when things go wrong. Let us say a button has the wrong padding.

If you are using JSON tokens injected via JavaScript, debugging is miserable. You open Chrome DevTools. You inspect the button. You see a hashed class name like .sc-bczRLJ. You have to go back to your code editor. You search for the component. You trace the utility function back to the JSON file. You finally find the wrong value.

If you use CSS variables, the process takes ten seconds.

/* Native and easy to debug */
.button {
  padding: var(--spacing-md);
}

You inspect the button in DevTools. You see the variable name. You click it. The browser takes you straight to the :root declaration where the value is defined. You can even tweak it right there in the browser to test a fix.

The runtime penalty

When you rely on JSON and JavaScript to handle your design tokens, you introduce real performance problems.

First, you bloat your JavaScript bundle. Every single colour, spacing value, and typography scale gets shipped in a JS file. The browser has to download and parse this before it can even paint the screen properly.

Second, theme switching becomes an absolute nightmare. If you want to support a dark mode, you end up tying your styling to React state. You have to trigger a full component tree re-render just to change a background from white to black.

With CSS variables, a theme switch is completely trivial. You just swap a class on the HTML body tag.

/* This is all you actually need for themes */
:root {
  --brand-primary: #2563eb;
  --bg-surface: #ffffff;
}

.theme-dark {
  --brand-primary: #60a5fa;
  --bg-surface: #0f172a;
}

The browser handles the repaint instantly. No JavaScript parsing required. No massive JSON objects sitting in memory.

The cross-platform myth

I know what the architecture purists are going to say right now. They will point out that JSON is platform agnostic. They will argue that you need a raw JSON format to support iOS and Android teams alongside the web.

That is completely true if you are actually building native mobile apps. But honestly most of us are not. Most teams are building web applications. We are forcing web developers to use a complex abstraction layer just in case an iOS team magically appears next year. Do not build for a future that might never happen.

Keep it native to the web

We need to stop overcomplicating our token pipelines. If your target platform is the web, your output format should be CSS variables. Period.

I got so tired of watching teams build custom JSON parsers that I built a better way. I created Design System Sync. It is a Figma plugin that exports your design tokens straight to GitHub or Bitbucket via automatic pull requests.

It generates visual diffs so you can see exactly what changed. And most importantly, it can output raw CSS variables ready for production. You do not need to set up a complex build step or write JSON parsers. You get 5 free exports a month if you want to try it out.

What do you think? Are you still shipping massive JSON token files to your users, or have you embraced native CSS variables?

Generating dynamic Tailwind configs from Figma variables without breaking CI

Alexander — Wed, 16 Sep 2026 16:30:27 +0000

The missing class disaster

I was staring at our production error logs on a Friday afternoon. A silent deployment had just gone out. Every primary button on the dashboard was completely transparent. Users could not click anything. It was a complete disaster.

I checked the codebase. The React components still had className="bg-brand-blue-500". But that class was doing absolutely nothing. Tailwind simply ignored it.

Turns out a designer had renamed a colour variable in Figma earlier that morning. They changed brand-blue to core-blue to match a new naming convention. Our naive automated sync script did exactly what it was told to do. It grabbed the new JSON file from Figma. It overwrote our Tailwind config. The CI pipeline saw no syntax errors. The build passed perfectly.

But React was still looking for the old class name. Tailwind stripped out the missing class during the production build. The styles vanished.

We realised we had a massive blind spot. You cannot just blindly dump Figma variables into a Tailwind config. You need a safety net. You need to know if a design token rename is going to break your components before you merge the pull request.

Mapping W3C tokens to Tailwind safely

Figma exports variables in the W3C Design Token format. This is basically a massive nested JSON object. Tailwind expects a very specific flat object structure for its theme configuration.

Here is what Figma gives you.

{
  "core": {
    "blue": {
      "500": {
        "value": "#3b82f6",
        "type": "color"
      }
    }
  }
}

Here is what Tailwind actually wants in your tailwind.config.js file.

module.exports = {
  theme: {
    colors: {
      core: {
        blue: {
          500: '#3b82f6'
        }
      }
    }
  }
}

Our first script just recursively stripped out the value and type keys. It was a simple map function. But this is exactly what caused the bug. It had no concept of history. It did not know what tokens existed yesterday.

We needed a validation step. The script had to compare the new Figma JSON against the current Tailwind config. If a token was missing, the script had to scan the codebase to see if we were still using it.

Building a validation layer in Node

We decided to write a custom Node script. This script runs in GitHub Actions every time a new token payload arrives from Figma.

First we flatten the new Figma tokens into a list of Tailwind class names. We just join the object keys with hyphens.

const fs = require('fs');

function flattenTokens(obj, prefix = '') {
  let classes = [];
  for (const key in obj) {
    if (obj[key].value) {
      classes.push(`${prefix}${key}`);
    } else {
      const newPrefix = prefix ? `${prefix}-${key}-` : `${key}-`;
      classes = classes.concat(flattenTokens(obj[key], newPrefix));
    }
  }
  return classes;
}

const figmaJson = JSON.parse(fs.readFileSync('./tokens.json', 'utf8'));
const newTailwindClasses = flattenTokens(figmaJson);

So basically this gives us an array like ['core-blue-500', 'core-blue-600'].

Next we do the exact same thing for our existing tailwind.config.js theme object. We compare the two arrays. We find out which classes were deleted.

const oldConfig = require('./tailwind.config.js');
const oldTailwindClasses = flattenTokens(oldConfig.theme.colors);

const deletedClasses = oldTailwindClasses.filter(
  className => !newTailwindClasses.includes(className)
);

if (deletedClasses.length > 0) {
  console.log('Warning: The following tokens were removed from Figma:');
  console.log(deletedClasses);
}

This is where the magic happens. If deletedClasses is empty, we just write the new config and move on. But if a designer deleted or renamed a token, we stop. We take that array of deleted classes and we scan our React components.

Catching broken components before the merge

We use a simple regular expression to search our .tsx files. We are looking for any string that matches the deleted Tailwind classes. We want to fail the CI build if we find a match.

const path = require('path');

function scanDirectory(dir, deletedClasses) {
  let brokenFiles = [];
  const files = fs.readdirSync(dir);

  for (const file of files) {
    const fullPath = path.join(dir, file);
    const stat = fs.statSync(fullPath);

    if (stat.isDirectory()) {
      brokenFiles = brokenFiles.concat(scanDirectory(fullPath, deletedClasses));
    } else if (fullPath.endsWith('.tsx')) {
      const content = fs.readFileSync(fullPath, 'utf8');

      for (const deletedClass of deletedClasses) {
        const regex = new RegExp(`bg-${deletedClass}|text-${deletedClass}|border-${deletedClass}`);
        if (regex.test(content)) {
          brokenFiles.push({ file: fullPath, missingClass: deletedClass });
        }
      }
    }
  }

  return brokenFiles;
}

const errors = scanDirectory('./src/components', deletedClasses);

if (errors.length > 0) {
  console.error('Build failed. The following files use deleted Figma tokens:');
  errors.forEach(err => console.error(`${err.file} depends on ${err.missingClass}`));
  process.exit(1);
}

This tiny Node script completely changed how we handle design updates.

When the designer renames brand-blue to core-blue now, the GitHub Action runs. It notices brand-blue-500 is missing from the new JSON. It scans the src/components folder. It finds Button.tsx is still using bg-brand-blue-500. The script exits with a status code of 1. The pull request fails.

The developer gets a clear error message in GitHub. They know exactly which file to update. They change the class to bg-core-blue-500 in the React component. They push the commit. The pull request passes. The deployment goes out safely.

A packaged way to handle token drift

Writing custom regex parsers and AST scanners for your codebase is fun. I honestly enjoy building these little Node tools. But it takes time to maintain them. You have to handle edge cases for hover states. You have to handle responsive prefixes. It gets complicated really fast.

I ended up building a tool to handle this entire pipeline automatically. It is called Design System Sync. I created it because I was tired of writing the same W3C token parsers for every new project.

It is a Figma plugin that exports your variables directly to GitHub or Bitbucket. It automatically formats everything for Tailwind or plain CSS. It creates the pull request for you. It even generates visual diffs so you can see exactly which colours changed before you merge anything. It handles all the multi-mode variable exports for light and dark themes out of the box.

If you want to stop breaking staging environments with missing classes, you can check out the website at https://ds-sync.netlify.app?utm_source=devto&utm_medium=post&utm_campaign=bot. You can also grab the plugin directly from the Figma Community.

You really need a safety net between Figma and your frontend code. Designers should be able to rename things. Developers should be able to merge things confidently. A solid validation pipeline makes both of those things possible.

Mapping semantic colour roles to a Tailwind configuration

Alexander — Wed, 09 Sep 2026 16:31:32 +0000

I was looking at a component file yesterday. A developer had written a massive string of utility classes on a primary button. It looked like a complete mess. It had specific blue hex classes for light mode. It had specific slate classes for dark mode. Then I checked another file. Someone else used entirely different shades for a supposedly identical button. The hardcoded utility classes were multiplying rapidly. We had no single source of truth for what a primary surface actually meant in our code.

When you write raw colour names in your styling framework, you are tying your code to a specific visual appearance. That is a dangerous game. If the design team decides the primary brand colour needs to be a bit darker, you have a massive problem. You have to run a global find and replace across your entire repository.

But you cannot just blindly replace everything. What if someone used that exact same blue for a chart line? Or maybe they used it for an informational banner. You have to check every single instance manually. Honestly, this is a massive waste of time.

The thing is, semantic colour roles fix this entirely. You stop naming things by what they look like. You start naming them by what they do. A button background is a primary surface. The text inside it is text on primary. A red error message is a danger surface.

Defining your naming convention

Before you write any code, you have to agree on a naming convention. This is usually the hardest part. Designers and developers need to speak the same language.

A good structure usually has three distinct levels.

First is the category. This covers base properties like colour, spacing, or typography.

Second is the concept or element type. This applies to things like surface, text, border, or icon.

Third is the specific role or state. This defines states like primary, danger, hover, or disabled.

When you combine these levels together, you get a highly predictable token name. A variable named color-surface-primary-hover tells you exactly what it is and where it belongs. Any developer can guess the name of a token without having to look it up in the documentation.

The prerequisites

You need a project with your utility CSS framework already installed. You also need access to your configuration file. I am using React for the component examples here. The logic applies exactly the same way to Vue or Svelte.

Building the semantic structure

Everything starts with a structured JSON file. This is your single source of truth. It holds the design decisions away from the actual application code.

{
  "color": {
    "surface": {
      "primary": {
        "default": { "value": "#2563eb" },
        "hover": { "value": "#1d4ed8" }
      },
      "danger": {
        "default": { "value": "#ef4444" }
      }
    },
    "text": {
      "on-primary": { "value": "#ffffff" }
    }
  }
}

This structure is very intentional. We group things by their category first. Then we define the role. Finally we define the state.

Generating the CSS variables

You could manually type out all the CSS variables. That gets tedious very quickly. It is much better to write a small script to do the heavy lifting for you.

Create a simple Node script in your project root. Let us call it build-tokens.js.

const fs = require('fs');

const tokens = JSON.parse(fs.readFileSync('./tokens.json', 'utf8'));

let css = '@layer base {\n  :root {\n';

function flattenTokens(obj, prefix = '--color') {
  for (const key in obj) {
    const value = obj[key];
    if (value.value) {
      css += `    ${prefix}-${key}: ${value.value};\n`;
    } else {
      flattenTokens(value, `${prefix}-${key}`);
    }
  }
}

flattenTokens(tokens.color);
css += '  }\n}\n';

fs.writeFileSync('./src/tokens.css', css);

This script reads the JSON file. It walks through the nested objects recursively. It flattens the structure into standard CSS variables. It writes the result to a new stylesheet.

The output looks exactly like what you would write by hand.

@layer base {
  :root {
    --color-surface-primary-default: #2563eb;
    --color-surface-primary-hover: #1d4ed8;
    --color-surface-danger-default: #ef4444;
    --color-text-on-primary: #ffffff;
  }
}

Handling the dark theme

You might be wondering why we do not just inject the hex codes directly into the framework configuration. The answer is dark mode.

If you put hex codes directly into your configuration object, you have to use prefix classes everywhere in your markup. Your components become bloated with conditional logic. You end up with a mess of utility classes.

When you use CSS variables, the browser handles the theme switch automatically. You just define a different set of variable values for your dark theme class.

@layer base {
  .dark {
    --color-surface-primary-default: #3b82f6;
    --color-surface-primary-hover: #60a5fa;
    --color-surface-danger-default: #f87171;
    --color-text-on-primary: #0f172a;
  }
}

The component code never changes. The framework just references the variable. The browser figures out what colour that variable should be based on the active theme.

Updating the configuration

Now we need to tell our utility framework about these new semantic roles. We map the CSS variables to the theme object in the configuration file.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{js,jsx,ts,tsx}"],
  theme: {
    extend: {
      colors: {
        surface: {
          primary: {
            DEFAULT: "var(--color-surface-primary-default)",
            hover: "var(--color-surface-primary-hover)"
          },
          danger: {
            DEFAULT: "var(--color-surface-danger-default)"
          }
        },
        text: {
          "on-primary": "var(--color-text-on-primary)"
        }
      }
    }
  }
}

Notice how we use the DEFAULT keyword here. This is a nice little trick. It allows us to write shorter class names in our components. Instead of writing the full path every time, the framework knows to use the default value when no specific state is provided.

The final component

Let us look at how this changes the actual component code. This is where the magic happens.

export function PrimaryButton({ children }) {
  return (
    <button className="bg-surface-primary hover:bg-surface-primary-hover text-text-on-primary px-4 py-2 rounded-md transition-colors">
      {children}
    </button>
  );
}

Look at how clean that is. There are no hardcoded hex codes. There are no complicated dark mode prefixes. The class names describe exactly what the colours are doing. Any new developer joining the team can read this and understand the intent immediately.

If the design team decides to rebrand tomorrow, you do not have to touch this component at all. You just update the JSON file. You run the script to generate the new CSS variables. The entire application updates instantly.

This approach completely eliminates a whole category of visual bugs. People can no longer use the wrong shade of blue by mistake. They have to use the semantic role.

Tbh I got really tired of manually exporting these JSON files from my design tools. Copying and pasting hex codes across different files was driving me crazy. So basically I built a plugin called Design System Sync to automate this whole workflow. It exports all your variables directly to GitHub using automatic pull requests. You can check it out at https://ds-sync.netlify.app?utm_source=devto&utm_medium=post&utm_campaign=bot or find it on the Figma Community at https://www.figma.com/community/plugin/1561389071519901700?utm_source=devto&utm_medium=post&utm_campaign=bot if you want to try it out.

Auto-syncing Tailwind config from Figma variables on every pull request

Alexander — Wed, 02 Sep 2026 16:30:47 +0000

The merge conflict that broke staging

I opened GitHub last Tuesday and saw a massive red error on our main deployment pipeline. Staging was completely broken. Two different frontend teams had tried to update our Tailwind configuration file at the exact same time.

Team A added new spacing utilities for a marketing landing page. Team B added custom brand colours for a new product dashboard. Git got confused during the merge. Someone resolved the conflict manually and force-pushed the changes. We lost half the core brand colours and production deployments ground to a halt.

This happens all the time when a single configuration file becomes a bottleneck. Developers manually copy hex codes and pixel values from Figma. They paste them into a massive JavaScript object. Someone makes a typo. Someone else accidentally deletes a bracket. It is a fragile process.

I realised we needed to remove humans from this specific loop. The source of truth for design decisions is Figma. The destination is Tailwind. The bridge between them should be code.

The structure of a proper token file

We decided to use the W3C Design Token format. It is a standard JSON structure that represents design decisions. It keeps everything predictable.

Here is what a raw token file looks like when exported properly.

{
  "colors": {
    "brand": {
      "primary": {
        "$value": "#2563eb",
        "$type": "color"
      },
      "secondary": {
        "$value": "#4f46e5",
        "$type": "color"
      }
    },
    "surface": {
      "background": {
        "$value": "#ffffff",
        "$type": "color"
      }
    }
  },
  "spacing": {
    "sm": {
      "$value": "0.5rem",
      "$type": "dimension"
    },
    "md": {
      "$value": "1rem",
      "$type": "dimension"
    },
    "lg": {
      "$value": "1.5rem",
      "$type": "dimension"
    }
  }
}

Notice how clean that is. Every token has a value and a explicit type. We just need to transform this nested JSON into a flat object that Tailwind understands.

Writing the conversion script

We wrote a small TypeScript utility to handle the translation. We wanted it to run automatically in our CI pipeline. The script reads the JSON tokens and outputs a valid Tailwind preset.

Here is the exact code we use. I kept it simple and focused.

import fs from 'fs'
import path from 'path'

interface TokenNode {
  $value?: string
  $type?: string
  [key: string]: any
}

function flattenTokens(obj: TokenNode, prefix = ''): Record<string, string> {
  let result: Record<string, string> = {}

  for (const key in obj) {
    if (key.startsWith('$')) continue

    const node = obj[key]
    const newPrefix = prefix ? `${prefix}-${key}` : key

    if (node.$value !== undefined) {
      result[newPrefix] = node.$value
    } else if (typeof node === 'object') {
      const nested = flattenTokens(node, newPrefix)
      result = { ...result, ...nested }
    }
  }

  return result
}

function generateTailwindTheme() {
  const rawData = fs.readFileSync(path.join(__dirname, 'tokens.json'), 'utf8')
  const tokens = JSON.parse(rawData)

  const colors = flattenTokens(tokens.colors || {})
  const spacing = flattenTokens(tokens.spacing || {})

  const tailwindConfig = {
    theme: {
      extend: {
        colors,
        spacing
      }
    }
  }

  const fileContent = `export default ${JSON.stringify(tailwindConfig, null, 2)}`
  fs.writeFileSync(path.join(__dirname, 'tailwind.preset.js'), fileContent)
  console.log('Tailwind preset generated successfully')
}

generateTailwindTheme()

This script recurses through the W3C token tree. It ignores the metadata keys that start with a dollar sign. It builds flat strings like brand-primary and assigns the hex code. Finally it writes a complete JavaScript module to the disk.

You do not need to touch your main Tailwind config anymore. You just import this generated preset.

import designSystemPreset from './tailwind.preset.js'

export default {
  presets: [designSystemPreset],
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [],
}

Setting up the GitHub Action

A script is useless if you have to remember to run it. We needed this to happen automatically whenever design tokens changed.

We set up a GitHub Action. It listens for changes to our token file. When a pull request updates the JSON data the action runs our conversion script. It then commits the updated Tailwind preset right back to the same pull request.

Here is the workflow file we built.

name: Sync Tailwind Preset

on:
  pull_request:
    paths:
      - 'tokens.json'

jobs:
  build-preset:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
        with:
          ref: ${{ github.head_ref }}

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Generate Preset
        run: npx ts-node scripts/generate-preset.ts

      - name: Commit changes
        run: |
          git config --global user.name 'github-actions[bot]'
          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
          git add tailwind.preset.js
          git commit -m "chore: update tailwind preset from tokens" || echo "No changes to commit"
          git push

Now the process is entirely hands off. A designer updates a variable in Figma. A pull request is created with the new JSON. GitHub Actions spots the change and regenerates the Tailwind preset. The developers just review the code and click merge. No more merge conflicts. No more manual data entry.

Letting designers own the source of truth

Building this pipeline from scratch was a fun weekend project. But maintaining custom conversion scripts gets tedious when you start dealing with complex typography rules or multiple dark mode themes.

That is exactly why I built Design System Sync. It handles this entire workflow out of the box. You run the plugin inside Figma. It exports your variables and styles directly to GitHub or Bitbucket. It automatically creates the pull request with a visual diff. It supports W3C Design Tokens and CSS Variables natively.

If you want to skip writing custom token parsers you can check out the product page at https://ds-sync.netlify.app?utm_source=devto&utm_medium=post&utm_campaign=bot. You can also grab the plugin directly from the Figma Community. The free tier gives you five exports a month which is plenty for testing out a new workflow.

Stop manually copying hex codes. Let the machines do the boring work so you can focus on building actual features.

Stop using hex codes in your CSS

Alexander — Wed, 26 Aug 2026 16:30:45 +0000

The dark mode disaster

I was reviewing a pull request for a dark mode toggle last Wednesday. The developer had written a massive CSS file. It was just hundreds of lines overriding hex codes. Things like background-color: #121212 and color: #FFFFFF were everywhere. It honestly hurt my eyes to read.

Hardcoded hex codes are a trap. We all start there. You click a button in Figma. You copy the hex code. You paste it into your CSS. It feels fast. But it creates technical debt instantly.

Let me explain why this habit ruins codebases.

Theming becomes a nightmare

If you hardcode #0052CC for your primary buttons, you create a rigid system. What happens when you need a dark theme? You have to write a media query. Then you manually map that exact hex to a new one. Now multiply that by fifty different components.

/* Please stop doing this */
.button {
  background-color: #0052CC;
  color: #FFFFFF;
}

@media (prefers-color-scheme: dark) {
  .button {
    background-color: #4C9AFF;
    color: #121212;
  }
}

This approach scales terribly. You end up with media queries scattered across dozens of files. If the design team decides to tweak the dark mode blue, you have to hunt down every instance of #4C9AFF. It is a massive waste of time.

Opacity adjustments are terrible

Say you need a hover state. The designer wants a background with 10% opacity of that primary colour. You have two bad choices with hex codes.

You either calculate an obscure eight-digit hex code like #0052CC1A. Good luck reading that and knowing what it means. Or you convert it to RGBA manually every single time. Both options are frustrating.

Semantic CSS variables solve all of this. You define the raw values once. Then you reference them everywhere.

/* Do this instead */
:root {
  --color-brand-primary: 0 82 204;
}

.button {
  background-color: rgb(var(--color-brand-primary));
}

.button:hover {
  background-color: rgba(var(--color-brand-primary), 0.1);
}

This is so much cleaner. You can adjust the opacity natively. You can swap the base colour in one place. The entire app updates instantly.

The naming problem

Another issue with hex codes is that they lack context. A hex code tells you what a colour looks like. It tells you absolutely nothing about how to use it.

When you see #E3F2FD in a codebase, you have to guess its purpose. Is it a background for an alert? Is it a disabled button state? Is it a table row hover effect? You do not know.

Semantic tokens fix this entirely. A variable named var(--surface-info-background) tells a clear story. Any developer can look at that and know exactly where it belongs. It removes the guesswork from building user interfaces.

The counter argument

I hear the same complaint every time I bring this up. People tell me hex codes are just easier. They say their project is too small for a full token system. They argue that copying from Figma is the fastest workflow.

And sure, if you are building a weekend side project, go wild. Paste those hex codes. But if you work on a team, you are just pushing the pain onto someone else down the line. A small project today is a legacy codebase tomorrow.

Automating the boring parts

The real issue is the handoff. Designers work in hex codes because that is how design tools display colour by default. Developers need semantic variables. You have to bridge that gap with automation.

I actually built Design System Sync to fix this exact workflow. It is a Figma plugin that takes your Figma variables and automatically turns them into semantic CSS variables. It opens a PR directly to your GitHub or Bitbucket repository. No more copying and pasting hex codes. You get proper W3C design tokens straight into your codebase. It even handles multi-mode exports for light and dark themes out of the box.

It takes an hour to set up a proper semantic colour system. It takes weeks to untangle a massive app full of hardcoded hex values. Stop pasting them into your code.

Are you still copying hex codes manually, or have you finally moved to semantic tokens?

CSS variables are the only design token format that matters

Alexander — Wed, 19 Aug 2026 16:30:23 +0000

The JSON parsing nightmare

I was looking at a Slack thread in our frontend channel yesterday afternoon. A mid-level React developer was asking how to parse a massive nested JSON file just to apply a button background colour.

The design team had just adopted a new token architecture in Figma. They exported everything into a deeply nested W3C design token format. Our frontend team was suddenly tasked with building a complex transformation pipeline just to read a simple colour value. The developer shared a snippet of what they were dealing with.

{
  "color": {
    "background": {
      "button": {
        "primary": {
          "default": {
            "$value": "{color.brand.blue.500}",
            "$type": "color"
          }
        }
      }
    }
  }
}

This is the exact moment we need to stop and ask ourselves what we are actually doing. We are building websites. Browsers do not understand deeply nested JSON objects. Browsers understand CSS.

We have collectively decided that abstracting our design decisions into complex JavaScript objects is the professional way to build interfaces. I think this is a massive mistake for most web teams. CSS variables are the only design token format that actually matters for the web.

The over-engineering trap

Let us look at a typical modern workflow. A designer updates a colour in Figma. A plugin exports that colour as a JSON file. A developer runs a tool like Style Dictionary to transform that JSON into CSS variables or a Tailwind configuration file.

This creates multiple points of failure. It requires maintaining a build step just for colours and spacing.

You end up writing configuration code that looks like this just to get your tokens into Tailwind.

// tailwind.config.js
const tokens = require('./tokens.json');

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: tokens.color.background.button.primary.default.value,
      }
    }
  }
}

This is completely unnecessary complexity. Every time the design team changes the structure of their tokens in Figma, your build script breaks. You have to go back and map the new JSON paths to your frontend configuration. It wastes hours of development time.

CSS variables solve this natively. The browser handles the mapping. The browser handles the cascading. The browser handles the scoping.

:root {
  --color-brand-blue-500: #0052cc;
  --color-bg-button-primary: var(--color-brand-blue-500);
}

This code does exactly the same thing as the complex JSON structure and the build pipeline combined. It is instantly readable by any web developer. You can inspect it directly in the Chrome DevTools. You can override it effortlessly in a specific component.

Theming is a browser job

People love to use JSON tokens for theming. They create a light.json and a dark.json. Then they write JavaScript logic to swap these files out or inject different values into their CSS-in-JS provider.

This is fighting the platform. CSS variables were literally designed for this exact use case. You do not need a state management library to change your background colours. You just need a media query or a data attribute.

:root {
  --bg-primary: #ffffff;
  --text-primary: #172b4d;
}

[data-theme="dark"] {
  --bg-primary: #091e42;
  --text-primary: #ffffff;
}

.card {
  background-color: var(--bg-primary);
  color: var(--text-primary);
}

this is the one thing nobody talks about. When you use raw CSS variables, you ship less JavaScript to the client. The browser repaints the screen instantly when the data attribute changes. There is no React reconciliation cycle holding up the visual update.

The cross-platform argument

I know exactly what the counter-argument is. People always say they need JSON because they build for iOS and Android alongside the web. They argue that a platform-agnostic format is the only way to keep everything synchronised.

That is absolutely true if you actually have native mobile apps. But the vast majority of teams are building web applications. They are building React dashboards or NextJS marketing sites. They adopt these massive enterprise token architectures because big tech companies use them. They pay the tax of maintaining complex transformations for platforms they do not even target.

If you are a web team, you should optimise for the web.

Cutting out the middleman

I got so tired of setting up transformation pipelines for web projects that I built a tool to skip the JSON step entirely.

When a designer changes a value in Figma, we should be able to update our CSS directly. That is why I created Design System Sync. It connects Figma directly to your GitHub repository. It reads your Figma variables and automatically generates a pull request with ready-to-use CSS variables.

You can configure it to export W3C JSON if you really need it. But the real magic happens when you just let it write CSS. You get a clean pull request with visual diffs showing exactly which colours changed. You merge it and your site updates. No build scripts required.

You can try it out for free at https://ds-sync.netlify.app?utm_source=devto&utm_medium=post&utm_campaign=bot or grab it directly from the Figma Community.

We need to stop treating CSS like a compilation target for our design tokens. CSS is the native language of the web. Why are we so desperate to avoid writing it?

Auto-generating Tailwind configs directly from Figma variables in CI

Alexander — Wed, 12 Aug 2026 16:30:48 +0000

I woke up to a sea of red CI failure notifications last Tuesday. A junior developer had tried to update our primary brand colour in the codebase. They manually copied the new hex code from Figma into our Tailwind config file. But they accidentally nested the new colour key under the wrong object level. This broke fifty different React components that relied on the bg-primary-500 utility class.

The fix took two minutes. The underlying problem took me a week to solve properly.

We were relying on humans to act as translation layers between our Figma variables and our code. Humans get tired. Humans make typos. We needed a machine to do this.

I decided to build a pipeline that automatically generates our Tailwind config directly from our Figma variables. Every time a designer updates a colour or a spacing unit in Figma, a GitHub Action catches the change and opens a pull request with the updated tailwind.config.js file.

This is exactly how we built it.

Getting the raw data out of Figma

The first step is getting the variable data out of Figma in a format we can actually use. Figma provides a REST API that lets you fetch local variables from a file.

You need a personal access token and your file key. You can find the file key in your Figma URL right after the figma.com/file/ part.

We wrote a simple Node script to pull this data.

const fetch = require('node-fetch')
const fs = require('fs')

const FIGMA_TOKEN = process.env.FIGMA_TOKEN
const FILE_KEY = process.env.FIGMA_FILE_KEY

async function fetchFigmaVariables() {
  const response = await fetch(
    `https://api.figma.com/v1/files/${FILE_KEY}/variables/local`,
    {
      headers: {
        'X-Figma-Token': FIGMA_TOKEN
      }
    }
  )

  const data = await response.json()

  fs.writeFileSync('./raw-figma-vars.json', JSON.stringify(data, null, 2))
  console.log('Figma variables saved successfully.')
}

fetchFigmaVariables()

This gives you a massive JSON file. It contains a lot of metadata you do not care about. You will see collection IDs and mode IDs mixed in with the actual values. We need to filter this down to just the raw values.

Here is a simplified look at what the relevant part of that JSON structure looks like.

{
  "meta": {
    "variables": {
      "VariableID:123": {
        "name": "colors/primary/500",
        "resolvedType": "COLOR",
        "valuesByMode": {
          "ModeID:456": {
            "r": 0.1,
            "g": 0.33,
            "b": 0.85,
            "a": 1
          }
        }
      }
    }
  }
}

Notice how Figma stores colours as RGBA values between 0 and 1. Tailwind expects standard hex codes or CSS rgb strings. We have to convert this.

Parsing Figma JSON into a Tailwind theme

Now we need a script to read that raw JSON and spit out a valid Tailwind configuration object. We want to map the Figma variable names to Tailwind utility classes.

Our designers use a naming convention like colors/primary/500. We need to parse that into a nested object that Tailwind understands.

Here is the parser script we use to handle colours and spacing.

const fs = require('fs')

function rgbaToHex(r, g, b, a) {
  const toHex = (value) => {
    const hex = Math.round(value * 255).toString(16)
    return hex.length === 1 ? '0' + hex : hex
  }

  if (a !== 1) {
    const alpha = toHex(a)
    return `#${toHex(r)}${toHex(g)}${toHex(b)}${alpha}`
  }

  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
}

function generateTailwindConfig() {
  const rawData = JSON.parse(fs.readFileSync('./raw-figma-vars.json', 'utf8'))
  const variables = rawData.meta.variables

  const tailwindTheme = {
    colors: {},
    spacing: {}
  }

  Object.values(variables).forEach(variable => {
    const nameParts = variable.name.split('/')
    const category = nameParts[0] 

    const modeId = Object.keys(variable.valuesByMode)[0]
    const rawValue = variable.valuesByMode[modeId]

    if (category === 'colors' && variable.resolvedType === 'COLOR') {
      const colorName = nameParts[1]
      const shade = nameParts[2] || 'DEFAULT'

      const hexValue = rgbaToHex(rawValue.r, rawValue.g, rawValue.b, rawValue.a)

      if (!tailwindTheme.colors[colorName]) {
        tailwindTheme.colors[colorName] = {}
      }
      tailwindTheme.colors[colorName][shade] = hexValue
    }

    if (category === 'spacing' && variable.resolvedType === 'FLOAT') {
      const spacingName = nameParts[1]
      tailwindTheme.spacing[spacingName] = `${rawValue}px`
    }
  })

  const configContent = `
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{js,jsx,ts,tsx}"],
  theme: {
    extend: ${JSON.stringify(tailwindTheme, null, 2)}
  },
  plugins: [],
}
`

  fs.writeFileSync('./tailwind.config.js', configContent)
  console.log('Tailwind config generated successfully.')
}

generateTailwindConfig()

This script reads the raw data and builds a clean theme object. It handles the RGBA to hex conversion automatically. It also maps the nested Figma names into the exact structure Tailwind needs.

Automating the sync with GitHub Actions

Running scripts locally is fine for testing. But we want this to happen automatically. We need a GitHub Action that runs on a schedule or triggers via a webhook from Figma.

We set up a workflow that runs every night. It pulls the latest variables and generates the config. If there are changes, it opens a pull request.

Here is the workflow file we put in .github/workflows/sync-tokens.yml.

name: Sync Figma Variables to Tailwind

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install node-fetch

      - name: Fetch Figma Variables
        env:
          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
          FIGMA_FILE_KEY: ${{ secrets.FIGMA_FILE_KEY }}
        run: node scripts/fetch-figma.js

      - name: Generate Tailwind Config
        run: node scripts/generate-tailwind.js

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: "chore: sync tailwind config with figma variables"
          title: "Design System Update: Tailwind Config"
          body: "Automated PR to sync Tailwind config with the latest Figma variables."
          branch: "update-design-tokens"
          base: "main"

This workflow is entirely hands-off. The designers update a hex code in Figma. The next morning there is a PR waiting for review. The developers just check the diff and hit merge. Nobody copies and pastes hex codes anymore.

Skipping the custom scripts entirely

Building this pipeline taught me a lot about the Figma API. But maintaining custom parser scripts can get annoying. You have to update your regex every time a designer decides to use a new naming convention.

I actually built a tool to solve this exact problem without the custom code. I created a plugin called Design System Sync. It exports Figma variables directly to GitHub or Bitbucket via automatic pull requests.

It handles all the format conversions for you. You can export W3C Design Tokens or raw CSS Variables. It also handles change detection with visual diffs so you can see exactly what changed before you merge.

If you are tired of manually updating your configs, you can check out the website at https://ds-sync.netlify.app?utm_source=devto&utm_medium=post&utm_campaign=bot. You can also grab the plugin directly from the Figma Community here: https://www.figma.com/community/plugin/1561389071519901700?utm_source=devto&utm_medium=post&utm_campaign=bot.

Automating this handoff is one of the highest return investments you can make for your team. It completely eliminates a whole category of visual bugs. Stop pasting hex codes. Let the machines do the translation.

Building a CSS motion token pipeline for custom easing curves

Alexander — Wed, 05 Aug 2026 16:31:11 +0000

You open a pull request for a new modal component. The developer wrote transition: all 0.3s ease-in-out. You check the dropdown component that was merged yesterday. That one uses transition: opacity 150ms linear. Then you look at the drawer component. It has a custom cubic-bezier(0.4, 0, 0.2, 1) with a 500ms duration.

The motion design is a complete mess. The app feels jittery and disconnected because every developer is just guessing the animation timing.

Motion is usually the last thing teams formalise. We nail down our colours and typography early on. But animations just slip through the cracks. The result is a codebase full of magic numbers and inconsistent transitions.

Good motion design is not just about making things look pretty. It provides crucial spatial context to the user. When a drawer slides in from the right it tells the user where that information lives. When a button subtly scales down on click it confirms the system received the input. But when these timings are inconsistent the application feels cheap. It breaks the illusion of a solid digital product.

Today we are going to fix this by building a dedicated motion token pipeline. We will map specific durations and easing curves to CSS variables. This creates a single source of truth for all animations in your app.

Prerequisites

You need Node installed on your machine. You also need a basic understanding of JSON structure. We will use Style Dictionary to compile our tokens into usable code. Make sure you have an empty project folder ready to go in your terminal.

Step 1: Defining motion primitives

The biggest mistake developers make is jumping straight into semantic names like modal-enter. We need primitive values first. These are the raw ingredients for our animations.

Create a file called motion.json in your project root. We will define two distinct concepts here. First we need durations for how long things take. Then we need easing curves for how things accelerate and decelerate.

In modern UI design we typically split easing into two categories. Productive easing is for small quick interactions like button hovers or checkboxes. Expressive easing is for larger structural changes like opening a full screen menu or a large modal.

Here is what our primitive JSON looks like.

{
  "motion": {
    "duration": {
      "fast": { "value": "150ms" },
      "normal": { "value": "250ms" },
      "slow": { "value": "400ms" }
    },
    "easing": {
      "productive": { "value": "cubic-bezier(0.2, 0, 0.38, 0.9)" },
      "expressive": { "value": "cubic-bezier(0.4, 0.14, 0.3, 1)" },
      "linear": { "value": "linear" }
    }
  }
}

Step 2: Compiling to CSS

Now we need to turn this JSON file into CSS custom properties. We will use Style Dictionary for this heavy lifting.

First you need to install the package. Run npm install style-dictionary in your terminal.

Then create a build script called build.js in the same folder. This script tells Style Dictionary where to find our JSON and how to format the output. We want standard CSS variables that we can use anywhere.

const StyleDictionary = require('style-dictionary');

const config = {
  source: ['*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [{
        destination: 'variables.css',
        format: 'css/variables'
      }]
    }
  }
};

const sd = StyleDictionary.extend(config);
sd.buildAllPlatforms();

Run this script by typing node build.js in your terminal. This generates a clean CSS file inside a new build folder. But we are not entirely done yet.

Step 3: Creating semantic motion roles

Primitives are great but they are not enough for a large team. A developer should not have to guess if a tooltip needs a fast or slow duration. We need semantic roles that tell developers exactly what variable to use for a specific context.

Let us create a new file called semantic-motion.json. This file will reference our primitives using aliases. Aliasing is a powerful concept. It means if we ever change the raw duration of our fast token it will automatically update everywhere the alias is used.

{
  "motion": {
    "semantic": {
      "hover": {
        "duration": { "value": "{motion.duration.fast.value}" },
        "easing": { "value": "{motion.easing.productive.value}" }
      },
      "modal": {
        "enter": {
          "duration": { "value": "{motion.duration.normal.value}" },
          "easing": { "value": "{motion.easing.expressive.value}" }
        },
        "exit": {
          "duration": { "value": "{motion.duration.fast.value}" },
          "easing": { "value": "{motion.easing.productive.value}" }
        }
      }
    }
  }
}

Notice how the modal exit is faster than the modal enter. This is a common pattern in motion design. Users want things to disappear quickly when they dismiss them. But they need a bit more time to process new information entering the screen.

Step 4: Integrating with Tailwind CSS

If your team uses Tailwind you can easily map these CSS variables into your configuration file. This gives you utility classes that match your design system perfectly.

Open your tailwind.config.js file and extend the theme section. You can map your custom variables to the transition duration and transition timing function properties.

module.exports = {
  theme: {
    extend: {
      transitionDuration: {
        'modal-enter': 'var(--motion-semantic-modal-enter-duration)',
        'modal-exit': 'var(--motion-semantic-modal-exit-duration)',
        'hover': 'var(--motion-semantic-hover-duration)',
      },
      transitionTimingFunction: {
        'expressive': 'var(--motion-semantic-modal-enter-easing)',
        'productive': 'var(--motion-semantic-hover-easing)',
      }
    }
  }
}

Let us look at how this actually looks in a React component. With our Tailwind config updated we can build a modal that perfectly matches the design specifications.

export function Modal({ isOpen, children }) {
  return (
    <div 
      className={`
        fixed inset-0 bg-black/50
        transition-all duration-modal-enter ease-expressive
        ${isOpen ? 'opacity-100 scale-100' : 'opacity-0 scale-95'}
      `}
    >
      <div className="bg-white p-6 rounded-lg">
        {children}
      </div>
    </div>
  );
}

Notice how clean this is. The developer does not need to know that the expressive curve is a complex cubic bezier string. They just know they are building a modal so they use the modal tokens. This is the exact workflow we want to achieve.

The final output

When you run your build script again with both JSON files included you get a beautiful CSS cascade. The semantic variables point directly to the primitive variables.

:root {
  --motion-duration-fast: 150ms;
  --motion-duration-normal: 250ms;
  --motion-duration-slow: 400ms;
  --motion-easing-productive: cubic-bezier(0.2, 0, 0.38, 0.9);
  --motion-easing-expressive: cubic-bezier(0.4, 0.14, 0.3, 1);
  --motion-easing-linear: linear;

  --motion-semantic-hover-duration: var(--motion-duration-fast);
  --motion-semantic-hover-easing: var(--motion-easing-productive);

  --motion-semantic-modal-enter-duration: var(--motion-duration-normal);
  --motion-semantic-modal-enter-easing: var(--motion-easing-expressive);
  --motion-semantic-modal-exit-duration: var(--motion-duration-fast);
  --motion-semantic-modal-exit-easing: var(--motion-easing-productive);
}

This approach completely changes how a team handles animations. You stop arguing about milliseconds in code reviews. The design system dictates the physics of your application. Everything feels unified and intentional.

Honestly I got really tired of manually updating these JSON files every time a designer tweaked an easing curve. The back and forth was exhausting and prone to human error. So basically I built a tool to automate this entire process. It is a Figma plugin called Design System Sync. It exports your Figma variables directly to GitHub as pull requests. It handles all the formatting for CSS and Style Dictionary automatically. You get 5 free exports a month if you want to try it out. You can grab it from the Figma Community or check out the website for more details.

Multi-brand design systems are a massive waste of time

Alexander — Wed, 29 Jul 2026 16:30:41 +0000

The premature scaling problem

I was on a Zoom call last Friday with a lead designer. We were building a new component library for a startup that literally launched two months ago. He shared his screen to show me his completely restructured Figma file. He looked incredibly proud.

He had set up four different brand themes using Figma variables. He spent a whole week mapping primitive colors to semantic tokens for brands that do not even exist yet. He created a primary brand, a secondary brand, a dark mode for both, and a high contrast mode for each. The matrix of design tokens was absolutely massive.

I asked him why we needed all of this. He told me that the company might launch a spin-off product next year. He wanted the architecture to be ready for it.

This is a massive trap. Building a multi-brand design system before you actually have multiple brands is an anti-pattern. It slows down development and frustrates everyone involved. You end up maintaining a complex architecture for a future that might never arrive.

The illusion of flexibility

When you build for multiple brands from day one, you complicate every single layer of your tech stack. Let us look at the CSS side of things.

A simple button component suddenly needs a complex theming context in React. Instead of just writing a straightforward CSS file, you end up passing brand props down a massive component tree. Your simple components turn into logic heavy monsters.

Look at this typical multi-brand setup in React:

import { createContext, useContext } from 'react';
import { themeA, themeB } from './tokens';

const ThemeContext = createContext(themeA);

export const ThemeProvider = ({ brand, children }) => {
  const currentTheme = brand === 'brandB' ? themeB : themeA;

  return (
    <ThemeContext.Provider value={currentTheme}>
      <div style={currentTheme.variables}>
        {children}
      </div>
    </ThemeContext.Provider>
  );
};

This looks clean enough here. But imagine scaling this across hundreds of components. Every new developer has to understand the theming context before they can build a simple landing page. They have to know which token to use for a border color because border-subtle changes meaning depending on the active brand.

The cognitive load is completely unnecessary. Most teams just need a solid primary color palette and a working dark mode. That is it.

The maintenance nightmare in Figma

The complexity is not just in the code. It ruins the design workflow too.

Every time a designer wants to introduce a new semantic color, they cannot just add it and move on. They have to define what that color looks like across all hypothetical brands. A simple task like adding a warning background color turns into a data entry job.

I have seen designers spend hours cross checking contrast ratios for a brand theme that nobody actually uses in production. They get bogged down in variable management instead of designing better user experiences. The tool starts dictating the workflow. Figma is brilliant for managing variables but you do not have to use every feature just because it is there.

When you export these tokens using tools like Style Dictionary, the JSON files become absolutely huge. You end up shipping hundreds of CSS variables to the browser that sit there doing nothing. It bloats your stylesheets and makes debugging a nightmare. When a color looks wrong on the staging environment, you have to trace it back through three layers of aliases across four different brand files.

/* This is what over-engineered token output looks like */
:root {
  --core-color-blue-500: #1a56db;
  --core-color-red-500: #ef4444;

  /* Brand A */
  --brand-a-primary: var(--core-color-blue-500);
  --brand-a-danger: var(--core-color-red-500);

  /* Brand B */
  --brand-b-primary: var(--core-color-red-500);
  --brand-b-danger: var(--core-color-blue-500);

  /* Semantic layer */
  --button-primary-bg: var(--brand-a-primary); /* Wait, how do I change this for Brand B dynamically? */
}

This CSS setup usually requires complex build steps to split the themes into separate files. You spend days configuring Webpack or Vite just to swap stylesheets.

But what about future growth?

I know exactly what people say to this. They argue that refactoring a single brand system into a multi-brand system later is incredibly painful. They say it is better to build the foundation right from the start so you are prepared for acquisitions or white label products.

They are not entirely wrong. Refactoring a massive codebase is hard. But building features nobody needs is worse. You should optimise for your current reality. If you only have one brand, build a fast and reliable system for that single brand. You can cross the multi-brand bridge when a client actually pays you to do it.

Keep it simple and automate the rest

Honestly, the best approach is to start with a flat token structure. Use semantic names that make sense for your current product. Build a solid dark mode and stop there.

If you absolutely must support multiple brands because you already have them, you need to remove the human error from the equation. You cannot manage that much complexity manually. I actually built a tool to solve this specific pain point when I was drowning in token updates.

I created a plugin called Design System Sync. It exports Figma design tokens directly to GitHub or Bitbucket via automatic pull requests. If you are managing multiple modes or brands, it handles the visual diffs and generates the CSS variables for you. You can grab it from the Figma Community if you want to stop copying and pasting JSON files all day.

Stop future proofing your design tokens for brands that do not exist. Build what you need today.

Are you currently maintaining a multi-brand system that only has one real brand?