Stop exporting design tokens to JSON for your web apps

A developer's PR review last Thursday prompted a realization about design tokens. The developer had written a 40-line utility function to parse a complex JSON file from the design system. The function mapped tokens.color.brand.primary.value to a styled-component, which seemed unnecessary. The developer questioned why they didn't use a simple CSS class, revealing a disconnect between design system teams and browser functionality. Design system teams focus on theoretical architecture, disregarding browser operations.

The excessive use of JSON for design tokens has become a common practice, forcing web developers to navigate through intricate processes. The pipeline typically involves exporting a Figma file to a large JSON blob, running it through a build tool, and then importing it into a web app. A helper function is then created to read the JSON safely. For example, the following code snippet illustrates this process:

```javascript

import tokens from './design-tokens.json'

const getSpacing = (size) => {

if (!tokens.spacing[size]) {

return tokens.spacing.base.value

}

return tokens.spacing[size].value

}

```

CSS is not a database, but rather a styling language. Web browsers have perfected how to cascade and apply styles efficiently. By wrapping tokens in JSON and JavaScript, we are working against the browser, causing unnecessary complexity. CSS variables are a highly optimized native engine for reading, cascading, and updating design values.

When developers use JSON tokens injected via JavaScript, debugging becomes challenging. For instance, if a button has the wrong padding, the debugging process can take up to ten seconds, requiring the developer to search through code and trace the utility function back to the JSON file.

Moreover, performance issues arise when relying on JSON and JavaScript for design tokens. The JavaScript bundle size increases as every colour, spacing value, and typography scale gets shipped in a JS file. Theme switching becomes a nightmare, as changing a background color from white to black requires a full component tree re-render using React state.

CSS variables, on the other hand, make theme switching trivial, as it only requires swapping a class on the HTML body tag. The browser handles the repaint instantly, without JavaScript parsing or JSON objects in memory.

The architecture purists argue that JSON is platform agnostic and necessary for supporting iOS and Android teams alongside the web. However, for most teams building web applications, this is unnecessary. Instead of overcomplicating token pipelines, outputting CSS variables should be the focus. To help with this, the author created Design System Sync, a Figma plugin that exports design tokens directly to GitHub or Bitbucket via automatic pull requests, generates visual diffs, and outputs raw CSS variables ready for production.