DEV Community: Alexander

Stop exporting your design tokens as JSON files

Alexander — Wed, 11 Nov 2026 16:31:47 +0000

A frontend developer pinged me on Slack last Thursday. He was trying to style a custom dropdown component for our new dashboard. He just needed the active state border colour. It should have been a ten-second job. Instead he was completely stuck. He was writing a complex helper function to traverse a deeply nested JSON object. Our token pipeline had spit out a massive file. It looked something like this.

{
  "color": {
    "brand": {
      "primary": {
        "500": {
          "value": "#0052CC",
          "type": "color"
        }
      }
    }
  }
}

He had to import this JSON file into his React component. Then he had to map the keys manually. Then he had to pass it down via a styled component prop. It took him twenty minutes just to colour a simple border. This happens every single day in frontend teams. We have convinced ourselves that design tokens must be abstract JSON files. We think we need complex build tools just to get colours onto a screen. It is a massive waste of time.

The abstraction trap

We started using JSON for design tokens with good intentions. We wanted a format that was agnostic. We wanted something that was independent of any specific programming language or framework. But we completely lost the plot along the way.

Browsers gave us the perfect token format years ago. They are called CSS custom properties. You probably know them as CSS variables. They are native to the web platform. They cascade beautifully through your DOM. They handle dark mode effortlessly without any JavaScript logic. Yet we still insist on exporting Figma variables to JSON first. Then we run Style Dictionary. Then we generate Sass maps or massive JavaScript objects. We are building a massive detour for absolutely no reason.

Let us look at how dark mode usually works when you rely on JSON tokens. You end up having to load multiple JSON files. You need one file for your light theme. You need another file for your dark theme. Then you have to write a React context provider to swap these objects based on the user preference. Your components have to re-render every time the theme changes.

const Button = styled.button`
  background-color: ${props => props.theme.color.brand.primary[500].value};
  color: ${props => props.theme.color.text.inverse.value};
`

This is incredibly fragile. If a designer changes the token structure in Figma, your entire application breaks. The build fails. The developers have to hunt down every instance where that specific object path was used. It turns a simple design update into a stressful refactoring job.

The native web approach

Now imagine just using native CSS variables instead. Your component code becomes incredibly simple. It does not need to know about the theme context. It does not need to parse deeply nested objects.

.button {
  background-color: var(--color-brand-primary-500);
  color: var(--color-text-inverse);
}

The browser does all the heavy lifting for you. If you want to support dark mode, you just redefine those variables inside a media query. It requires zero JavaScript. It causes zero React re-renders. It just works immediately.

Debugging is also a completely different experience. When you use JSON and CSS-in-JS, you open Chrome DevTools and see a random generated class name. You have no idea where that colour came from. When you use CSS variables, DevTools shows you exactly which variable is applied. You can click it. You can change it right there in the browser. You can see the computed value instantly. It is a massive upgrade for developer experience.

The mobile argument

You are probably thinking about cross-platform support right now. People always say JSON is the universal language for tokens. They argue you need JSON to support iOS and Android applications. They say native platforms cannot read CSS variables.

That is totally fair. If you are actually building native mobile apps from the exact same Figma file as your web app, you might need a translation layer. But let us be honest with ourselves. Most teams are just building web applications. Many teams have completely separate design files for their native mobile apps anyway. We are paying the complexity tax of a massive multi-platform architecture for a simple React web app. We are making our web developers suffer just in case we build an iOS app three years from now.

Fixing the pipeline

We need to cut out the middleman entirely. We need to export our Figma variables directly to CSS. Your browser understands them natively. Your developers understand them instantly. If a designer changes a primary colour in Figma, you just want a pull request that updates a simple stylesheet. That is it. No parsing logic. No fragile build steps. No broken JSON schemas.

This exact frustration is why I built my own tool. I got tired of fixing broken JSON pipelines every single week. I created Design System Sync to solve this specific problem. It takes your Figma variables and exports them directly as CSS variables. It opens a pull request in GitHub or Bitbucket automatically. It handles all the tedious work for you.

You can still use W3C JSON formats if you really need them. But the best part is just getting raw CSS that works immediately. You can try it out for free at https://ds-sync.netlify.app?utm_source=devto&utm_medium=post&utm_campaign=bot. You can also grab it directly from the Figma Community at https://www.figma.com/community/plugin/1561389071519901700?utm_source=devto&utm_medium=post&utm_campaign=bot. I made sure it handles light and dark modes natively out of the box.

We need to stop over-engineering our design systems. We need to trust the web platform again. CSS variables are powerful enough to be your single source of truth in code.

Are you still running a massive build pipeline just to get a hex code onto your website?

Catching dead CSS variables in CI before they break production

Alexander — Wed, 04 Nov 2026 16:30:46 +0000

A bug report rolled in late on a Friday. The primary call to action on our checkout page was completely invisible. Someone had deleted a colour token in Figma. Our automated pipeline updated the JSON file in our repository. The global CSS variables updated perfectly. But a React component deeper in the tree still referenced the old variable name. The browser could not find it. It fell back to transparent. We lost real money because of a simple typo in a token name.

CSS variables are brilliant. They make theming so easy. You can swap a whole colour palette just by changing a class on the body tag. But they have a massive flaw. If you reference a variable that does not exist, the browser just ignores it. There is no build error. There is no warning in the console. You just get a silent failure.

In a large codebase, this is terrifying. Designers rename things. Tokens get deprecated. And you have no way of knowing which components are still relying on those dead tokens. I decided we needed to catch this in CI before we ever merged a pull request.

The naive regex approach

My first thought was to just write a simple script. I wanted to read our exported Figma JSON file and extract all the valid token names. Then I would scan our codebase for any string matching the CSS variable syntax. If the variable was not in the JSON file, the script would throw an error.

Here is the basic JSON structure we get from our design system.

{
  "colors": {
    "brand": {
      "primary": {
        "value": "#0d6efd",
        "type": "color"
      }
    }
  }
}

This eventually turns into a CSS variable called --colors-brand-primary. So basically we need a script to flatten this JSON and build a list of valid CSS variable names.

Here is the Node script I wrote to do exactly that. Notice I am using standard JavaScript modules.

import fs from 'node:fs'
import path from 'node:path'

const rawData = fs.readFileSync('./tokens.json', 'utf-8')
const tokens = JSON.parse(rawData)

const validVariables = new Set()

function flattenTokens(obj, prefix = '') {
  for (const key in obj) {
    const value = obj[key]
    if (typeof value === 'object' && value !== null && !value.value) {
      flattenTokens(value, `${prefix}${key}-`)
    } else if (value.value) {
      validVariables.add(`--${prefix}${key}`)
    }
  }
}

flattenTokens(tokens)
console.log(validVariables)

This works really well for extracting the valid names. The next step is finding where we actually use them in our CSS and React files.

Scanning the codebase for usages

Finding the variables in the codebase is a bit trickier. You could use an Abstract Syntax Tree to parse the CSS. But we also use these variables inline in our React components. So we need something that just looks at raw text.

I wrote a regular expression to find anything that looks like a CSS variable. It looks for var(-- and captures the variable name.

import { globSync } from 'glob'

const files = globSync('src/**/*.{css,tsx,jsx}')
const variableRegex = /var\((--[a-zA-Z0-9-]+)/g

let hasErrors = false

for (const file of files) {
  const content = fs.readFileSync(file, 'utf-8')
  let match

  while ((match = variableRegex.exec(content)) !== null) {
    const variableName = match[1]

    if (!validVariables.has(variableName)) {
      console.error(`Error in ${file}: Variable ${variableName} does not exist in tokens`)
      hasErrors = true
    }
  }
}

if (hasErrors) {
  process.exit(1)
}

This script is small but it is incredibly powerful. It literally reads every source file and checks every single CSS variable usage against our source of truth. If a designer deletes a token in Figma, this script will fail the build if we are still using it.

The problem with dynamic variables

We ran this script on our main repository. It immediately found twelve dead variables. That felt like a massive win. But then we hit a wall.

Sometimes developers construct CSS variable names dynamically in JavaScript. They might do something like this in a React component.

const buttonColor = `var(--brand-${variant}-500)`

return (
  <button style={{ backgroundColor: buttonColor }}>
    Click me
  </button>
)

Our regex script completely chokes on this. It tries to look up --brand-${variant}-500 in our token list. Obviously that does not exist. It is a dynamic string.

We had two choices. We could try to make the regex smarter. Or we could just ban dynamic CSS variable names entirely.

Honestly, we chose the second option. Banning dynamic variable names makes your codebase much easier to search. If you need a dynamic colour, you should map it to a static variable using a data attribute.

button[data-variant="primary"] {
  background-color: var(--brand-primary-500);
}

button[data-variant="secondary"] {
  background-color: var(--brand-secondary-500);
}

This is much cleaner. And it means our simple regex script works perfectly.

Wiring it up in GitHub Actions

The final piece of the puzzle is running this automatically. You do not want developers to remember to run this script locally. It needs to happen on every pull request.

Here is the GitHub Action workflow we use. It is very straightforward. It checks out the code, installs dependencies, and runs our validation script.

name: Validate Design Tokens

on:
  pull_request:
    branches:
      - main

jobs:
  validate-tokens:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run token validator
        run: node scripts/validate-tokens.js

Now, if someone tries to merge a PR that uses a dead CSS variable, the build goes red. The reviewer can see exactly which file contains the error. It completely eliminates the risk of silent CSS failures in production. this is the one thing nobody talks about when setting up design systems. You need strict validation just like you have for TypeScript.

Getting the tokens into the repo

Writing the validation script is the easy part tbh. The hardest part of this entire workflow is actually getting the token JSON from Figma into your repository reliably.

For a long time, we just asked designers to manually export a JSON file and send it to us on Slack. It was a terrible process. Files got lost. People forgot to send updates. We ended up with massive drift between Figma and code.

I got so tired of this that I built a tool to fix it. I am the creator of Design System Sync. It is a Figma plugin that exports your design tokens directly to GitHub or Bitbucket via automatic pull requests.

You just map your Figma variables, click export, and it generates a PR with the updated JSON and CSS files. It even assigns reviewers automatically. It supports W3C Design Tokens, standard CSS Variables, and Style Dictionary formats. It handles multi-mode variables for light and dark themes perfectly.

You can check out the website here: https://ds-sync.netlify.app?utm_source=devto&utm_medium=post&utm_campaign=bot

And you can 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

If you combine an automated export tool with a strict CI validation script, your design system becomes bulletproof. Designers can clean up tokens with confidence. Developers never have to worry about broken UI. It is just a much better way to work.

Auto-syncing Tailwind config from Figma variables on every PR

Alexander — Wed, 28 Oct 2026 16:30:45 +0000

A failed Vercel build on a Wednesday afternoon caught my attention. The error log complained about an undefined Tailwind utility class. A designer had renamed a core colour variable in Figma from blue-500 to brand-blue-primary. The design team published the update and pushed the new tokens to our repository. The frontend team pulled the new JSON files. Nobody remembered to update the Tailwind configuration file to match the new token names.

The build crashed because a component was still trying to use bg-blue-500. The token no longer existed in the design system. This happens all the time when you separate your design tokens from your framework configuration. You end up with a manual gap between the JSON file and the actual utility classes your developers use.

I decided to fix this permanently. I wanted a system where updating a Figma variable automatically updates the Tailwind configuration in the same pull request.

The manual mapping trap

Most teams export their Figma variables to a JSON file. They usually dump this file into a tokens folder. Then a developer opens tailwind.config.js and manually maps the JSON values to the Tailwind theme object.

This approach is incredibly fragile. It relies entirely on human memory. When a designer adds a new shade of green, a developer has to remember to wire it up in the config file.

Here is what that manual mapping usually looks like in a typical project.

const tokens = require('./tokens/globals.json')

module.exports = {
  theme: {
    colors: {
      primary: tokens.colors.brand.primary.value,
      secondary: tokens.colors.brand.secondary.value,
      danger: tokens.colors.feedback.danger.value
    }
  }
}

This works fine for three colours. It completely falls apart when you have hundreds of variables across multiple themes. The nested structure of the design tokens rarely matches exactly what Tailwind expects. You also lose the ability to use Tailwind autocomplete properly if the tokens are nested too deeply.

Parsing W3C Design Tokens

Figma variables can be exported in the W3C Design Token format. This is a standard way of representing design decisions in JSON. Every token has a value and a type.

We need a script to read this W3C JSON format and flatten it into something Tailwind understands. Tailwind expects a simple object where keys are the class names and values are the CSS values.

I wrote a Node script to handle this transformation. It recursively reads the token object and builds a flat dictionary.

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

const tokensPath = path.resolve(process.cwd(), 'tokens/design-tokens.json')
const tokensRaw = fs.readFileSync(tokensPath, 'utf8')
const tokens = JSON.parse(tokensRaw)

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

  for (const key in obj) {
    const value = obj[key]

    if (value && typeof value === 'object' && 'value' in value) {
      const cleanKey = prefix ? `${prefix}-${key}` : key
      result[cleanKey] = value.value
    } else if (value && typeof value === 'object') {
      const newPrefix = prefix ? `${prefix}-${key}` : key
      const nested = flattenTokens(value, newPrefix)
      result = { ...result, ...nested }
    }
  }

  return result
}

const flatColors = flattenTokens(tokens.colors)

This script takes a deeply nested object and turns it into a flat structure. A token located at colors.brand.blue.500 becomes a key called brand-blue-500. This matches the standard Tailwind class naming convention perfectly.

Generating the configuration file

Now we have a flat object of colours. We need to write this object directly into a new Tailwind configuration file.

I prefer generating a TypeScript file rather than a JSON file. This allows us to keep all the standard Tailwind plugins and type definitions intact. We just inject our dynamic colours into the theme extension object.

const configContent = `
import type { Config } from 'tailwindcss'

export const generatedColors = ${JSON.stringify(flatColors, null, 2)}

const config: Config = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      colors: generatedColors,
    },
  },
  plugins: [],
}

export default config
`

const outputPath = path.resolve(process.cwd(), 'tailwind.config.ts')
fs.writeFileSync(outputPath, configContent, 'utf8')
console.log('Tailwind config generated successfully.')

When you run this script, it completely overwrites the Tailwind config with the latest tokens. You no longer have to map anything manually. If a designer changes a name in Figma, the script generates a config with the new name.

Automating the sync with GitHub Actions

Running a script locally is better than manual mapping. It is still not fully automated. Developers might forget to run the script after pulling new tokens.

The best place to run this script is in your continuous integration pipeline. We use GitHub Actions to catch token updates and regenerate the Tailwind config automatically.

Whenever a pull request modifies the design tokens JSON file, the workflow triggers. It runs the parser script and commits the updated Tailwind config back to the same pull request.

name: Sync Tailwind Config

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

jobs:
  update-config:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

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

      - name: Install dependencies
        run: npm ci

      - name: Generate Tailwind Config
        run: npm run generate-tailwind

      - 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.config.ts
          git commit -m "chore: auto-update tailwind config from design tokens" || echo "No changes to commit"
          git push

This workflow completely removes the human element from the synchronization process. The design tokens act as the absolute source of truth. The framework configuration simply reacts to changes in that source.

Catching drift before it ships

This setup solved our Vercel build failures completely.

Now, when a designer renames a token in Figma, the automated system takes over. The pull request contains the updated JSON file. The GitHub Action runs and updates the tailwind.config.ts file.

During the code review, developers can see exactly how the Tailwind classes will change. If a renamed token breaks an existing component, the standard CI tests will catch the missing class name before the code ever reaches the main branch.

You get a clear visual diff of your design decisions right next to your framework configuration. It forces the design and engineering teams to stay perfectly aligned.

The productised approach

Building the CI pipeline and the parser script handles the code side of things. You still need a reliable way to get the tokens out of Figma and into that pull request in the first place.

I built a tool called Design System Sync to solve this exact problem. It is a Figma plugin that exports your design tokens and variables directly to GitHub or Bitbucket. It automatically generates pull requests with clear visual diffs and assigns reviewers. It exports W3C Design Tokens natively so you can feed them straight into the GitHub Action we just built.

You can learn more about the plugin on the website here https://ds-sync.netlify.app?utm_source=devto&utm_medium=post&utm_campaign=bot and try it out directly from the Figma Community here https://www.figma.com/community/plugin/1561389071519901700?utm_source=devto&utm_medium=post&utm_campaign=bot.

Connecting Figma directly to your Tailwind configuration saves countless hours of debugging. You stop hunting for missing utility classes and start trusting your design system again.

Generating a typesafe Tailwind config from raw Figma variables in CI

Alexander — Wed, 21 Oct 2026 20:22:44 +0000

A PR review on a Tuesday morning caught my eye. A developer had hardcoded a hex value into a custom utility class. I left a comment asking why they did not just use our standard brand token. They replied that their editor autocomplete did not show it.

I checked the main branch. It turns out the design team had updated the token names in Figma three weeks prior. They renamed a bunch of nested colour groups. Nobody had updated the Tailwind config to match.

This happens all the time. Designers update variables in Figma. Developers do not realise the names changed. Autocomplete fails. Developers hardcode values to hit their deadlines. Your design system slowly falls apart.

We needed to fix this at the source. The goal was simple. We wanted to take raw Figma variables and automatically generate a fully typed Tailwind configuration on every PR.

Reading the raw W3C format

Figma variables export as a JSON file. The industry is slowly moving towards the W3C Design Token format. This is a nested JSON structure where actual values are denoted by a $value key.

You might get a file that looks like this from your design team.

{
  "color": {
    "brand": {
      "primary": {
        "$type": "color",
        "$value": "#0F172A"
      },
      "secondary": {
        "$type": "color",
        "$value": "#334155"
      }
    }
  },
  "spacing": {
    "small": {
      "$type": "dimension",
      "$value": "0.5rem"
    }
  }
}

This is great for machines. It is terrible for Tailwind. Tailwind expects a flat or slightly nested object of strings. It does not know what to do with $value or $type keys. We needed a script to flatten this out.

Writing the transformation script

I decided to write a small Node script in TypeScript. Its only job is to read that JSON file and recursively strip out the W3C metadata. We want a clean object that perfectly matches the Tailwind theme specification.

Here is the recursive function we built to handle the flattening. Notice how it checks for the $value key to determine if it has reached a leaf node.

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

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

function flattenTokens(obj: TokenNode): Record<string, any> {
  const result: Record<string, any> = {}

  for (const key in obj) {
    const node = obj[key]

    if (node && typeof node === 'object') {
      if ('$value' in node) {
        result[key] = node.$value
      } else {
        result[key] = flattenTokens(node)
      }
    }
  }

  return result
}

This function is small but it does exactly what we need. It walks through the nested Figma export. When it finds a $value property it grabs the string. Otherwise it keeps going deeper.

We can then map the top level keys to the specific Tailwind theme sections.

function generateTheme(rawJson: Record<string, any>) {
  const flattened = flattenTokens(rawJson)

  return {
    colors: flattened.color || {},
    spacing: flattened.spacing || {},
    borderRadius: flattened.radius || {}
  }
}

Creating the typed configuration file

Just having the JavaScript object is not enough. We need to actually write this to a file that Tailwind can consume. We also want it to be a TypeScript file. This ensures our developers get that sweet editor autocomplete.

The easiest way to do this is to stringify the generated theme object and inject it into a template.

function writeTailwindConfig(theme: Record<string, any>) {
  const themeString = JSON.stringify(theme, null, 2)

  const fileContent = `
import type { Config } from 'tailwindcss'

const generatedTheme = ${themeString}

const config: Config = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: generatedTheme
  },
  plugins: [],
}

export default config
  `.trim()

  fs.writeFileSync(
    path.resolve(process.cwd(), 'tailwind.config.ts'),
    fileContent
  )
}

This script reads the Figma JSON and writes a brand new tailwind.config.ts file into the root of our project. The Config type from Tailwind does a lot of heavy lifting here. It makes sure our generated object conforms to expected types.

Running it in CI

Local scripts are fine. Honestly though people forget to run them. If a designer drops a new JSON file into the repository we want the Tailwind config to update automatically.

We wired this up using GitHub Actions. The workflow listens for changes to our tokens.json file. When it detects a change it runs our transformation script and commits the updated config file back to the branch.

Here is the YAML file we use for this pipeline.

name: Sync Tailwind Config

on:
  push:
    paths:
      - 'design-system/tokens.json'

jobs:
  build-config:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

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

      - name: Install dependencies
        run: npm ci

      - name: Run transformation script
        run: npx ts-node scripts/transform-tokens.ts

      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "chore: update tailwind config from tokens"
          file_pattern: "tailwind.config.ts"

Now the process is completely hands off. A designer updates variables in Figma and exports the JSON. They make a PR with the new JSON file. GitHub Actions sees the change and runs the script. The script generates a fresh tailwind.config.ts file. The action commits that file right back to the designer's PR.

When a developer pulls the branch down their editor instantly knows about the new colours. Autocomplete works perfectly. Nobody hardcodes hex values anymore.

Skipping the manual pipeline

Building this pipeline taught me a lot about how W3C tokens map to utility classes. Tbh maintaining custom transformation scripts across multiple projects gets tedious. You end up copying and pasting the same build scripts everywhere. You also have to handle edge cases like typography ramps and complex shadow arrays.

This exact pain point is why I built Design System Sync. It handles the entire pipeline for you. It exports your Figma variables directly to GitHub or Bitbucket via automatic PRs. It also translates the raw variables into whatever format you actually need. You can get standard W3C JSON or you can have it output perfectly formatted CSS Variables and Tailwind configs.

If you want to stop writing custom token parsers 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.

Setting up a solid bridge between your design tools and your code base takes a bit of work upfront. It is totally worth it. Your developers get reliable autocomplete. Your designers get the confidence that their changes actually ship. And you never have to argue about hardcoded hex values in a PR review again.

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?