Using Figma Variables as a Single Source of Truth for Design Tokens: From Design to Code

Problem: Fragile Hand‑off of Design Tokens

Teams often copy colors, spacing, or font sizes from a design file into code by reading text layers or inspecting CSS values. That approach is error‑prone: a single change in the design file requires a manual update in every code file, and tokens can drift between designers and developers.

How Figma Variables Solve It

Figma Variables replace the old “text‑layer” trick with a proper design‑token system. A variable is a named value that can be a color, number, string, or boolean. Variables live in collections and can be grouped into modes (e.g., light, dark, brand, white‑label). Modes let you preview different themes instantly, while the same variable name can resolve to different concrete values.

Variables can reference other variables, creating an alias chain. For example, a semantic token like primary‑color might alias a primitive #ff5733. Changing the primitive propagates to every alias, keeping the whole system consistent.

Understanding Variable Structure

Below is a typical JSON representation returned by the REST API for a file that has two collections and two modes. The variables array contains all variable definitions; modes lists the active modes; and aliases shows references.

{
  "variables": [
    {
      "id": "1:2",
      "name": "Primary Color",
      "type": "color",
      "values": {
        "Light": "#ff5733",
        "Dark": "#c70039"
      }
    },
    {
      "id": "1:3",
      "name": "Spacing Small",
      "type": "number",
      "values": {
        "Light": "8",
        "Dark": "8"
      }
    }
  ],
  "modes": [
    {"id": "Light", "name": "Light"},
    {"id": "Dark", "name": "Dark"}
  ]
}

Key points:

• var.type limits the value format – colors are hex strings, numbers are plain decimals, strings are literal text, booleans are true/false.
• Each mode holds a concrete value; if a mode is missing a value, Figma falls back to the first defined mode.
• Aliases are stored as separate variable entries whose values map to the id of the referenced variable.

Syncing Tokens to Code via the REST API

The REST endpoint GET /v1/files/:file_key/variables/local returns the local variable definitions for a file. To use it:

1. Generate a Personal Access Token (PAT) in Figma with the files:read scope.
2. Run the request from a script or tool. Example using curl:

   curl -H "X-Figma-Token: YOUR_PAT" \
     https://api.figma.com/v1/files/FILE_KEY/variables/local
   

3. The response JSON contains variables and modes as shown above.
4. Transform the data into the format your project expects. For CSS‑in‑JS, you might emit --primary-color: #ff5733; for each mode.

Example Node.js script (pseudo‑code, not tested):

const fetch = require('node-fetch');
const fs = require('fs');
const PAT = 'YOUR_PAT';
const FILE_KEY = 'YOUR_FILE_KEY';

async function fetchVariables() {
  const res = await fetch(`https://api.figma.com/v1/files/${FILE_KEY}/variables/local`, {
    headers: { 'X-Figma-Token': PAT }
  });
  const data = await res.json();
  return data;
}

function toCssVariables(vars, mode) {
  return vars.map(v => {
    const value = v.values[mode] || v.values[Object.keys(v.values)[0]];
    return `--${v.name.toLowerCase().replace(/\s+/g, '-')}: ${value};`;
  }).join('\n');
}

(async () => {
  const data = await fetchVariables();
  const css = toCssVariables(data.variables, 'Light');
  fs.writeFileSync('tokens.css', css);
})();

Running this script will generate a tokens.css file containing CSS custom properties for the Light mode. Repeat for Dark mode or output a JSON file for native platforms.

Practical Workflow in Dev Mode

When you enable Dev Mode in a Figma file, the Inspect panel shows a Variable Inspector for any layer bound to a variable. Clicking the Copy code button copies a snippet in the language you selected (CSS, SwiftUI, Jetpack Compose). This reduces the need for a separate export step and guarantees that the code snippet matches the current value of the active mode.

Typical workflow:

1. Designers create a collection Brand Tokens with modes Light and Dark.
2. Developers open the file in Dev Mode, select a component, and copy the CSS snippet.
3. CI pipeline runs the Node script above to regenerate tokens.css and commits the file.
4. Any change in the design file automatically propagates to the codebase on the next CI run.

Trade‑offs and Limitations

• File‑scope collections: Variables are scoped to a single file. To share across multiple files, publish the library file and accept it in downstream files. This adds a publish/accept cycle.
• Local vs. inherited variables: The /variables/local endpoint returns only variables defined in the current file. Inherited variables from a library must be fetched from the library file itself.
• Mode order: The API does not expose mode reordering. The order in the UI determines fallback resolution; be careful when adding new modes.
• Complex values: String variables cannot embed interpolation. For gradients or multi‑value tokens, model them as multiple variables or encode as JSON strings.
• Rate limits: Figma allows ~30 requests per minute per IP. For large monorepos, implement exponential backoff and cache responses to stay within limits.

Actionable Next Steps

1. Enable Variables in your design file and set up a library file for shared tokens.
2. Create a CI job that fetches variables via the REST API and writes them to a platform‑specific format.
3. In Dev Mode, use the Inspect panel to verify that the generated snippets match the API output.
4. Document the token naming convention and alias strategy so that designers and developers stay aligned.
5. Monitor API rate limits and cache responses if you hit the 30‑req/min threshold.

By treating Figma Variables as a single source of truth, you eliminate manual copy‑and‑paste, reduce drift, and enable instant theme previewing in both design and code. Start small—sync just colors or spacing—and expand to full design systems as you gain confidence.