A PR diff from last week really annoyed me. A developer had added a custom utility class to a button component. The class was w-[18px].
I left a comment asking why they did not just use our standard spacing classes like w-4 or w-5. They replied quickly. They told me the design team had added a new spacing token in Figma called space-4.5. This token mapped exactly to 18px.
I checked our codebase. Our Tailwind config was completely out of date. Nobody had updated it for three months. Designers were adding new variables in Figma daily. Developers were just using arbitrary square brackets in Tailwind to match the new designs.
This completely defeats the purpose of a design system.
We needed a way to force our Tailwind configuration to stay perfectly aligned with our Figma variables. Manual updates were clearly failing. I decided to write a script that generates the Tailwind config automatically every time our tokens change.
The problem with manual mapping
Tailwind is fantastic when your config matches your design tool. It becomes a nightmare when they drift apart.
Designers update a colour ramp or tweak a border radius in Figma. They publish the changes to the team library. The developers look at the new designs and see values that do not exist in their Tailwind autocomplete.
The immediate fix is always an arbitrary value like bg-[#0F172A]. This creates tech debt instantly. We end up with dozens of hardcoded hex values scattered across thousands of components.
We needed a single source of truth. Figma variables had to dictate the Tailwind theme object.
Reading the raw tokens
The first step is getting the data out of Figma. We export our Figma variables as a W3C standard JSON file. This format is predictable and easy to parse.
Here is a simplified version of what our exported tokens.json looks like.
{ "colors": { "brand": { "primary": { "500": { "$value": "#3b82f6", "$type": "color" }, "600": { "$value": "#2563eb", "$type": "color" } } } }, "spacing": { "4.5": { "$value": "1.125rem", "$type": "dimension" } } } This JSON structure is great for machines. It is not ready for Tailwind. Tailwind expects a specific JavaScript object structure for its theme configuration. We need to bridge that gap.
Writing the transformer script
We need a Node script to read this JSON file and transform it. The script must walk through the nested token tree. It needs to identify colours, spacing, and typography. Then it must build a new object that matches the Tailwind theme specification.
I wrote a TypeScript utility to handle this exact transformation. We run this script using ts-node in our CI pipeline.
Here is the core logic for parsing the tokens.
import fs from 'fs' import path from 'path' interface TokenNode { $value?: string $type?: string [key: string]: any } function processTokens(node: TokenNode, category: string): Record<string, any> { const result: Record<string, any> = {} for (const key in node) { if (key.startsWith('$')) continue const child = node[key] if (child.$value !== undefined) { if (child.$type === category) { result[key] = child.$value } } else { const nested = processTokens(child, category) if (Object.keys(nested).length > 0) { result[key] = nested } } } return result } function generateTailwindTheme(tokensPath: string) { const rawData = fs.readFileSync(tokensPath, 'utf8') const tokens = JSON.parse(rawData) const colors = processTokens(tokens.colors || tokens, 'color') const spacing = processTokens(tokens.spacing || tokens, 'dimension') return { colors, spacing } } This script uses a recursive function. It looks at every key in the JSON file. If it finds a $value property, it checks the $type. If the type matches what we are looking for, it adds it to our result object.
This handles deeply nested colour palettes perfectly. The structure colors.brand.primary.500 translates exactly into the nested object Tailwind expects.
Generating the configuration file
Having a JavaScript object in memory is not enough. Tailwind reads from a physical file. We need to take our generated theme object and write it to tailwind.theme.js.
We do not overwrite the entire tailwind.config.js file. That file often contains important plugins or content paths. Instead, we generate a standalone theme file that the main config can import.
Let us add the file generation logic to our script.
function writeThemeFile(theme: any, outputPath: string) { const fileContent = ` // This file is auto-generated from Figma variables. // Do not edit this file directly. module.exports = ${JSON.stringify(theme, null, 2)} `.trim() fs.writeFileSync(outputPath, fileContent) console.log('Tailwind theme generated successfully.') } const tokensFilePath = path.join(__dirname, 'tokens.json') const outputFilePath = path.join(__dirname, 'tailwind.theme.js') const theme = generateTailwindTheme(tokensFilePath) writeThemeFile(theme, outputFilePath) Now we have a script that reads tokens.json and outputs a clean JavaScript file.
The final step in the codebase is updating the main tailwind.config.js to use this new file. We just require the generated file and spread it into the theme extension.
const generatedTheme = require('./tailwind.theme.js') module.exports = { content: [ "./src/**/*.{js,jsx,ts,tsx}", ], theme: { extend: { colors: generatedTheme.colors, spacing: generatedTheme.spacing }, }, plugins: [], } This setup completely isolates our design tokens from our build configuration. The generated file is treated as a build artifact. We can safely ignore it in our code reviews because we know it comes straight from Figma.
Automating the process in CI
Running this script manually locally is okay. Automating it on every pull request is much better.
We use GitHub Actions to enforce this workflow. Whenever a pull request updates the tokens.json file, we want our pipeline to run the transformer script automatically. It should then commit the updated tailwind.theme.js back to the same branch.
This guarantees that the Tailwind config never falls behind the raw tokens.
Here is the GitHub Actions workflow we use to achieve this.
name: Sync Tailwind Theme on: push: paths: - 'tokens.json' jobs: update-tailwind: 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 typescript ts-node @types/node - name: Generate Tailwind Theme run: npx ts-node scripts/generate-theme.ts - name: Commit changes uses: stefanzweifel/git-auto-commit-action@v4 with: commit_message: "chore: update tailwind theme from figma tokens" file_pattern: "tailwind.theme.js" This simple workflow completely fixed our drift problem.
When the design team updates the spacing scale in Figma, they export the new tokens.json. They open a pull request with that single file. Our GitHub Action detects the change. It runs the TypeScript parser. It generates the new tailwind.theme.js and commits it immediately.
By the time a developer pulls the latest main branch, their local Tailwind autocomplete already has space-4.5 ready to use. No more arbitrary square brackets.
A simpler way to handle this
Writing and maintaining custom AST parsers and CI pipelines is fun. Tbh it is also quite time consuming. You have to handle edge cases like typography composite tokens or responsive scales.
I built a tool to handle this entire process directly from Figma so you do not have to maintain these scripts.
It is called Design System Sync. It exports your Figma variables directly to GitHub or Bitbucket via automatic pull requests. It handles W3C Design Tokens natively. It also generates the exact CSS variables or Tailwind configurations you need automatically.
You just map your Figma collections to your repository paths once. The plugin handles the visual diffs, assigns the reviewers, and formats the code perfectly. You can check out the website here or try it directly from the Figma Community.
Keeping design and code in sync should not require a massive custom pipeline. It should just work. Start automating your configs and stop fighting with arbitrary utility classes.
