Mark Learst | Lead Design Engineer (Design Systems, React, Accessibility, DX + AI Tooling)

The Problem

Design systems teams using Figma Variables faced a critical workflow challenge: there was no official way to programmatically access Figma's design variables from React applications. This created:

Manual copy-paste workflows to sync design tokens from Figma to code
Version drift between Figma variables and application code
No way to validate variables at runtime in React apps
Inability to dynamically load Figma variables in Storybook or dev tools
Fragmented token export solutions that didn't leverage official APIs

When Figma released their Variables REST API in 2024, I saw an opportunity to build the missing piece: a React hooks library that made Figma Variables a first-class citizen in React development.

The Solution

FigmaVars Hooks is a React 19 hooks library that provides type-safe access to the Figma Variables REST API, paired with a CLI tool for exporting variables into CI/CD pipelines.

Quick Start (hooks + provider)

A lightweight provider wraps your app while hooks fetch and cache variables with SWR under the hood:

import { FigmaVarsProvider, useVariables } from '@figma-vars/hooks'

const FIGMA_TOKEN = process.env.NEXT_PUBLIC_FIGMA_TOKEN
const FIGMA_FILE_KEY = 'your-file-key'

export function App() {
  return (
    <FigmaVarsProvider token={FIGMA_TOKEN} fileKey={FIGMA_FILE_KEY}>
      <Variables />
    </FigmaVarsProvider>
  )
}

function Variables() {
  const { data, isLoading, error } = useVariables()
  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>
  const variables = Object.values(data?.meta.variables ?? {})
  return <pre>{JSON.stringify(variables, null, 2)}</pre>
}

React Hooks API

Built custom React hooks that fetch and cache Figma variables at runtime:

useFigmaVariables() - Fetch all variables from a Figma file
useFigmaVariable() - Get a specific variable by ID or name
useFigmaCollection() - Access variable collections
Built-in caching and request deduplication for performance
Full TypeScript support with exported response types and type guards
SWR configuration for revalidation, retry, and cache control

CLI Export Tool

Created figma-vars-export CLI for exporting Figma variables as JSON in CI/CD pipelines:

Runs in GitHub Actions or any CI environment
Exports variables to JSON format compatible with Style Dictionary
Supports filtering by collection, mode, or variable name
Validates exported data with runtime guards before writing

FIGMA_TOKEN=your_token npx figma-vars-export --file-key YOUR_FILE_KEY --out ./figma-variables.json

FIGMA_TOKEN=your_token figma-vars-export --file-key YOUR_FILE_KEY --out ./figma-variables.json

figma-vars-export --help

Storybook Integration

Wrap stories once and surface live variables across your component docs:

// .storybook/preview.tsx
import { FigmaVarsProvider } from '@figma-vars/hooks'
import type { Preview } from '@storybook/react'

const FIGMA_TOKEN = process.env.STORYBOOK_FIGMA_TOKEN
const FIGMA_FILE_KEY = process.env.STORYBOOK_FIGMA_FILE_KEY

const preview: Preview = {
  decorators: [
    Story => (
      <FigmaVarsProvider token={FIGMA_TOKEN} fileKey={FIGMA_FILE_KEY}>
        <Story />
      </FigmaVarsProvider>
    ),
  ],
}

export default preview

Offline Fallback

Teams without Enterprise can still ship by exporting JSON once and using fallbackFile for static or local environments. This keeps Storybook and design system dashboards in sync without live API calls.

import exportedVariables from './figma-variables.json'

<FigmaVarsProvider
  token={null}
  fileKey={null}
  fallbackFile={exportedVariables}
>
  <App />
</FigmaVarsProvider>

Runtime Guards + Error Utilities

The library ships type guards and error helpers so apps can validate data and respond to API failures without guessing.

isLocalVariablesResponse() - Validate local responses
isPublishedVariablesResponse() - Validate published data
isFigmaApiError() + helpers for status code handling
redactToken() for safe logging and support flows

100% Test Coverage

Built comprehensive test suite with Vitest covering:

All hook behaviors and edge cases
API request/response mocking and error handling
Runtime validation for all data structures
CLI command execution and file output

Technical Architecture

React 19 Features

Leveraged React 19's new capabilities:

Server Components for initial data fetching when used in Next.js
Use hook for async data loading
Built-in caching strategies with React's cache function

Typed Core Entrypoint

A core build ships for non-React use cases (server scripts, TanStack Query, or custom fetchers) while preserving the same data contracts.

Developer Experience

Optimized for DX:

Clear error messages with suggestions for common issues
Comprehensive TypeScript types exported from package
Detailed README with code examples and API reference
Minimal configuration required to get started
ESM-first build with CJS interop and Node 20 toolchain

Security and Rate Limits

Token handling and rate-limit resilience are built in:

Redaction helpers for safe token logging
Retry utilities with exponential backoff for 429 responses
Documented scopes for read/write access

Use Cases

Enables powerful workflows:

Live Storybook integration showing actual Figma variables
Design token validation tools that check Figma against codebase
Admin panels for managing design tokens across teams
CI/CD pipelines that auto-sync Figma changes to code repos

Impact & Adoption

FigmaVars Hooks bridges the gap between Figma Variables and React development while keeping design systems predictable at scale:

Eliminates manual token sync by providing programmatic access to Figma Variables directly from React
Type-safe runtime validation ensures variables are valid before use in applications
100% test coverage provides confidence for teams adopting the library in production
Open-source contribution to the design systems community, filling a critical gap in the Figma Variables ecosystem
CLI tool enables CI/CD workflows that auto-sync design tokens on every Figma change
Enterprise and offline paths cover both live API usage and static exports for non-Enterprise teams

The library is published on npm, actively maintained, and is the backbone for teams building production token pipelines, Storybook dashboards, and Figma-to-code workflows.