DEV Community: Alexander

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?

Catching Rogue Hex Codes in CI Before They Reach Production

Alexander — Wed, 22 Jul 2026 16:30:47 +0000

The rogue grey incident

I was reviewing a pull request for a new onboarding flow last Thursday. The code looked perfectly fine at first glance. The logic was solid and the tests were passing. But then I looked at the CSS-in-JS styles. Someone had written color: '#4B5563' on a subheader component.

That specific hex code is not in our design system. Our official slate grey is #475569. The developer had just used a colour picker on a mockup and pasted the result directly into the codebase.

This happens all the time. Designers tweak a colour slightly in Figma. Developers inspect it and hardcode the value. Slowly but surely your codebase fills up with fifty shades of grey. You end up with a massive technical debt problem. Your design system becomes a suggestion instead of a rule.

We needed a way to stop this at the gate. We needed our continuous integration pipeline to catch raw hex codes and fail the build if they did not match our official tokens.

Here is exactly how we built a token drift detector using TypeScript and GitHub Actions.

Parsing components for raw values

Regular expressions are not smart enough to catch every hardcoded colour. You might have hex codes in string literals, template strings, or object properties. You need to parse the Abstract Syntax Tree of your files to find them reliably.

We wrote a small Node script using the TypeScript compiler API. It scans all our React components and looks for string literals that match a hex code pattern.

import * as ts from 'typescript'
import { readFileSync } from 'fs'
import { globSync } from 'glob'

const HEX_REGEX = /^#([A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$/

function findHardcodedColours(node: ts.Node, sourceFile: ts.SourceFile, found: any[]) {
  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
    const text = node.text
    if (HEX_REGEX.test(text)) {
      const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
      found.push({
        value: text,
        line: line + 1,
        character: character + 1,
        file: sourceFile.fileName
      })
    }
  }

  ts.forEachChild(node, child => {
    findHardcodedColours(child, sourceFile, found)
  })
}

const files = globSync('src/components/**/*.tsx')
const violations = []

files.forEach(file => {
  const source = readFileSync(file, 'utf8')
  const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true)
  findHardcodedColours(sourceFile, sourceFile, violations)
})

console.log(JSON.stringify(violations, null, 2))

This script is fast and catches every single hex string in the codebase. But finding hex codes is only half the battle. We also need to know if those hex codes are actually valid tokens.

Comparing against the dictionary

We keep our design tokens in a standard JSON format. The next step is to load that dictionary and build a map of valid colour values. If a developer hardcodes a hex value that exactly matches a token we want to suggest they use the token name instead. If the hex value is completely unknown we want to throw a hard error.

import tokens from '../tokens.json'

function buildTokenMap(obj: any, prefix = ''): Record<string, string> {
  let map: Record<string, string> = {}

  for (const key in obj) {
    if (obj[key].value) {
      const tokenName = prefix ? `${prefix}.${key}` : key
      map[obj[key].value.toLowerCase()] = tokenName
    } else if (typeof obj[key] === 'object') {
      const newPrefix = prefix ? `${prefix}.${key}` : key
      const nested = buildTokenMap(obj[key], newPrefix)
      map = { ...map, ...nested }
    }
  }

  return map
}

const validTokens = buildTokenMap(tokens.colors)

violations.forEach(violation => {
  const lowerHex = violation.value.toLowerCase()
  const matchingToken = validTokens[lowerHex]

  if (matchingToken) {
    console.warn(`Warning: Use token '${matchingToken}' instead of ${violation.value} in ${violation.file}:${violation.line}`)
  } else {
    console.error(`Error: Unknown colour ${violation.value} found in ${violation.file}:${violation.line}`)
    process.exitCode = 1
  }
})

This script now does something incredibly useful. It transforms a silent design drift into a loud terminal error. But we want this to happen automatically on every pull request.

Annotating the pull request

GitHub Actions allow you to create custom annotations. These are the little error messages that show up directly inline on the code diff. We can format our script output to trigger these annotations automatically.

GitHub looks for a very specific string format in the standard output. It looks like ::error file={name},line={line},col={col}::{message}. We can update our script to log this exact format.

violations.forEach(violation => {
  const lowerHex = violation.value.toLowerCase()
  const matchingToken = validTokens[lowerHex]

  if (matchingToken) {
    console.log(`::warning file=${violation.file},line=${violation.line},col=${violation.character}::Hardcoded colour found. Please use the design token '${matchingToken}' instead of ${violation.value}.`)
  } else {
    console.log(`::error file=${violation.file},line=${violation.line},col=${violation.character}::Rogue colour detected. ${violation.value} is not in the design system. Check Figma for the correct token.`)
    process.exitCode = 1
  }
})

Now we just need to wire this up in a YAML workflow file. We want this to run whenever a developer opens or updates a pull request.

name: Token Drift Detector

on:
  pull_request:
    paths:
      - 'src/components/**/*.tsx'
      - 'src/components/**/*.ts'

jobs:
  detect-rogue-colours:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run AST Token Checker
        run: npx ts-node scripts/check-tokens.ts

When a developer pushes code with a random hex value the CI pipeline fails. An error pops up right on the specific line of code in the GitHub UI. It tells them exactly what they did wrong and how to fix it. This completely eliminated the manual back and forth in our code reviews.

Automating the source of truth

This entire pipeline relies on one crucial thing. The tokens.json file in your repository must be perfectly in sync with your Figma files. If a designer adds a new primary colour in Figma and the developer tries to use it the build will fail unless the JSON file is updated first.

Manual handoffs for these JSON files are a nightmare. People forget to export them. They copy and paste the wrong versions into Slack. The CI pipeline fails because the tokens dictionary is stale.

I actually built a tool to solve this exact problem. I created a plugin called Design System Sync. It exports your Figma design tokens directly to GitHub or Bitbucket via automatic pull requests. As soon as a designer updates a colour in Figma they can push a button to generate a PR with the new W3C formatted tokens.

The plugin handles CSS Variables and Style Dictionary formats natively. It even includes AI code generation for React or HTML. You can check it out at ds-sync.netlify.app or grab it directly from the Figma Community.

So basically by combining a strict CI check with automated Figma syncs you create a closed loop. Designers control the tokens in Figma. Developers are forced to use them in code. The CI pipeline enforces the rules without anyone having to be the bad guy in a pull request review.

Generating Fluid Typography CSS Clamps from Static JSON Variables

Alexander — Wed, 15 Jul 2026 16:31:58 +0000

A designer hands you a beautiful new typography spec on a Tuesday morning. The design file has two distinct columns. One shows the mobile type scale and the other shows the desktop scale. Your job is to make the entire application transition smoothly between these two extremes. You open your editor and realise you need to calculate CSS clamp functions for fifteen different text styles manually. This involves finding the minimum viewport width, the maximum viewport width, and doing a bunch of linear interpolation math just to figure out the preferred value. Doing this once is annoying. Doing it every time the design team tweaks a font size by two pixels is enough to make you want to change careers entirely.

Usually a developer looks at the two sizes and just writes a standard media query. This creates a harsh jump when the user rotates their tablet or resizes their browser. The designer inevitably complains that intermediate screen sizes look completely broken. The text is either way too massive or far too tiny. A fluid scale fixes this visual bug completely. The text grows at a continuous rate relative to the viewport.

We need a few basic tools to automate this nightmare. You need Node installed on your machine. We are going to use Style Dictionary to process out our raw data. You also need a basic understanding of how CSS clamp works under the hood. The goal is to feed a simple JSON file into a script and get perfectly calculated fluid typography variables out the other side.

Defining the raw tokens

First we need to define our typography tokens in a format our script can understand. Instead of writing a single static pixel value we give each token a minimum and maximum size. We define these values in rems to keep everything accessible by default.

{
  "typography": {
    "heading": {
      "h1": {
        "min": { "value": "2.5" },
        "max": { "value": "4.5" }
      },
      "h2": {
        "min": { "value": "2.0" },
        "max": { "value": "3.5" }
      },
      "body": {
        "min": { "value": "1.0" },
        "max": { "value": "1.125" }
      }
    }
  }
}

This structure is exceptionally clean and easy to read. It tells us exactly what the text should do at the smallest and largest screen sizes. You can easily map this directly to the columns in your design file.

The interpolation math

A CSS clamp function takes three distinct values. It needs a minimum value, a preferred fluid value, and a maximum value. The preferred value is usually a combination of a fixed rem value and a viewport width percentage. To calculate this slope we need to know your minimum and maximum viewport breakpoints.

Let us say our mobile breakpoint is 320px and our desktop breakpoint is 1200px. We convert those to rems assuming a standard 16px base size. That gives us 20rem for mobile and 75rem for desktop.

The slope represents the constant rate of change. We take the desktop font size and subtract the mobile font size. Then we divide that result by the desktop viewport width minus the mobile viewport width. This gives us a tiny decimal number. We multiply that number by one hundred to get our viewport width percentage.

Then we need the y-axis intersection. This is the theoretical font size when the viewport is exactly zero pixels wide. We calculate this by taking the mobile viewport width and multiplying it by our slope. We subtract that result from our mobile font size. This gives us the fixed rem portion of our preferred value. When you combine the fixed rem value and the viewport width percentage you get a line that perfectly connects your mobile and desktop sizes.

Writing the token transform

Now we write a custom Style Dictionary transform to do this math for us. This script will look for any token that has a minimum and maximum property. It will then calculate the exact clamp function and return it as a single string.

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

const MIN_VIEWPORT = 20; 
const MAX_VIEWPORT = 75; 

StyleDictionary.registerTransform({
  name: 'size/fluid-clamp',
  type: 'value',
  matcher: function(token) {
    return token.original.min !== undefined && token.original.max !== undefined;
  },
  transformer: function(token) {
    const minSize = parseFloat(token.original.min.value);
    const maxSize = parseFloat(token.original.max.value);

    const slope = (maxSize - minSize) / (MAX_VIEWPORT - MIN_VIEWPORT);
    const yAxisIntersection = -MIN_VIEWPORT * slope + minSize;

    const preferredValue = `${yAxisIntersection.toFixed(3)}rem + ${(slope * 100).toFixed(3)}vw`;

    return `clamp(${minSize}rem, ${preferredValue}, ${maxSize}rem)`;
  }
});

This little block of code is doing all the heavy lifting. It calculates the slope and the intersection point flawlessly every single time. Then it constructs a perfectly formatted CSS string. You never have to open a calculator app to figure out typography scaling again.

Formatting the final stylesheet

We need to tell Style Dictionary how to output this data. We register a custom format that writes out a standard CSS file with perfectly scoped variables.

StyleDictionary.registerFormat({
  name: 'css/fluid-variables',
  formatter: function({ dictionary }) {
    let css = ':root {\n';

    dictionary.allTokens.forEach(token => {
      if (token.value.includes('clamp')) {
        const name = token.path.join('-');
        css += `  --${name}: ${token.value};\n`;
      }
    });

    css += '}\n';
    return css;
  }
});

const sd = StyleDictionary.extend({
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      transforms: ['attribute/cti', 'name/cti/kebab', 'size/fluid-clamp'],
      buildPath: 'build/css/',
      files: [{
        destination: 'typography.css',
        format: 'css/fluid-variables'
      }]
    }
  }
});

sd.buildAllPlatforms();

You run this script and it sweeps through your entire JSON directory. It grabs every multi-size token and generates the exact CSS variables your project needs.

The generated result

Let us look at what this script actually produces. It generates a clean CSS file that you can drop directly into your modern web project.

:root {
  --typography-heading-h1: clamp(2.5rem, 1.773rem + 3.636vw, 4.5rem);
  --typography-heading-h2: clamp(2rem, 1.455rem + 2.727vw, 3.5rem);
  --typography-body: clamp(1rem, 0.955rem + 0.227vw, 1.125rem);
}

You can now use these variables anywhere in your application. Your headings will scale smoothly and automatically as the browser window resizes.

Using viewport units alone for typography is a massive accessibility failure. If a user zooms in their browser plain viewport units do not scale at all. The text stays exactly the same size. This fails basic accessibility requirements immediately. This is exactly why we use the clamp function with rems for the minimum and maximum boundaries. The user retains total control over their experience. If they bump their default browser font size up to twenty four pixels the rem values scale proportionally. The clamp boundaries shift gracefully to accommodate their preferences while maintaining your beautiful fluid slope.

Honestly I got really tired of writing custom transformation scripts and manually moving JSON files out of the design tool every time typography scales changed. So basically I built a plugin called Design System Sync to handle this automatically. It exports your variables directly to GitHub or Bitbucket and opens a pull request for you. It handles W3C formats and CSS variables out of the box so you do not have to write custom parsers anymore. You can grab it from the Figma Community if you want to save yourself a few hours of configuration work.

Generating a Tailwind theme from semantic colour tokens

Alexander — Wed, 08 Jul 2026 16:30:59 +0000

You are looking at a pull request with over six hundred lines of hardcoded hex codes in Tailwind arbitrary values. Someone actually wrote bg-[#1a56db] across fifty different React components. The codebase is a mess of magic numbers. The design team just published a beautifully structured semantic colour system in Figma. They gave you a JSON file full of nested objects like surface.primary.hover. You need to get these into Tailwind somehow without breaking everything.

Standard Tailwind colours are brilliant for prototyping. They become a massive headache when you need to maintain a strict brand identity across a large product. You cannot ask developers to remember which shade of blue maps to a primary button state. Semantic tokens solve this by naming colours after their intent rather than their appearance.

We are going to write a small Node script to fix this. It will take a raw token file and map it directly into a Tailwind configuration.

Prerequisites

You will need Node installed on your machine. You also need a web project already set up with Tailwind CSS. Finally you need a raw JSON file containing your design tokens. Most design tools can export this format natively or via a community tool.

The Raw Token Data

Let us look at the raw data first. Most modern design tools spit out tokens in the W3C draft format. It looks quite heavy at first glance. It uses a deeply nested structure to organise the design decisions.

Create a file called tokens.json in your project root and add this data.

{
  "color": {
    "surface": {
      "primary": {
        "default": { "$value": "#1a56db", "$type": "color" },
        "hover": { "$value": "#1e40af", "$type": "color" }
      },
      "danger": {
        "default": { "$value": "#dc2626", "$type": "color" },
        "hover": { "$value": "#b91c1c", "$type": "color" }
      }
    },
    "text": {
      "on-primary": { "$value": "#ffffff", "$type": "color" },
      "critical": { "$value": "#991b1b", "$type": "color" }
    }
  }
}

This structure is great for machines but terrible for Tailwind. Tailwind expects a flat object or a gently nested one for its colour configuration. We need to bridge the gap.

The Transformation Script

Tbh nobody wants to map these by hand every time a hex code changes. We will write a small Node script to automate the boring part. This script reads the W3C format and flattens it into a structure Tailwind can actually understand.

Create a file called build-theme.js in your project root.

const fs = require('node:fs')

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

function flattenTokens(obj, prefix = '') {
  let result = {}

  for (const key in obj) {
    const value = obj[key]
    let newKey = prefix ? `${prefix}-${key}` : key

    if (newKey.endsWith('-default')) {
      newKey = newKey.replace('-default', '')
    }

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

  return result
}

const tailwindColors = flattenTokens(tokens.color)

fs.writeFileSync(
  './tailwind-theme.json',
  JSON.stringify(tailwindColors, null, 2)
)

console.log('Successfully generated Tailwind theme.')

Let us break down what is happening here. The script reads the JSON file and passes the colour object into a recursive function. The function walks through every nested level. It builds a string key by combining the parent names.

Notice the special handling for the word default. In Figma you might name a token surface.primary.default. In Tailwind you just want to write bg-surface-primary. The script strips out the default suffix automatically to keep your classes clean.

Run this script in your terminal.

node build-theme.js

Plugging it into Tailwind

Now we have a clean JSON file sitting in our project. We just need to tell Tailwind to use it. Open your tailwind.config.js file. We will require the generated JSON and spread it into the extend block of our theme.

/** @type {import('tailwindcss').Config} */
const customTheme = require('./tailwind-theme.json')

module.exports = {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {
      colors: customTheme
    }
  },
  plugins: []
}

By placing the custom colours inside the extend block we keep all the default Tailwind colours available. This is usually the safest approach. If you want to strictly enforce only your semantic colours you would move the customTheme object up one level to completely overwrite the default palette.

What the output looks like

When you run your build process Tailwind picks up these new semantic colours. You can now use them exactly like the built-in utility classes.

<div class="p-6 bg-surface-primary hover:bg-surface-primary-hover rounded-lg">
  <h2 class="text-text-on-primary font-bold text-xl">
    Semantic colours are brilliant
  </h2>
  <button class="mt-4 bg-surface-danger hover:bg-surface-danger-hover text-text-on-primary px-4 py-2 rounded">
    Delete Project
  </button>
</div>

This is so much better than arbitrary values. Your team can read the classes and immediately understand the intent behind the styling. If the design team decides the primary surface needs to be slightly darker next month you just replace the token file and rerun the script. Not a single React component needs to change.

The best part is how this scales. When your design system grows to include borders and shadows you can update the script to parse those token types too. You just map them to their corresponding Tailwind configuration keys.

Honestly I got really tired of writing and maintaining these parser scripts for every new project. It felt like solving the exact same problem over and over again. So I built a tool called Design System Sync. It connects your Figma variables directly to your code repository and generates the exact formats you need automatically. It handles the Tailwind mapping right out of the box so you never have to write another recursive parser function. 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 here: https://www.figma.com/community/plugin/1561389071519901700?utm_source=devto&utm_medium=post&utm_campaign=bot. It creates pull requests with visual diffs whenever a designer updates a colour.