FigmaVars Hooks

React 19 hooks library and CLI for the official Figma Variables REST API. Type-safe synchronization between Figma and React apps with 100% test coverage.

GitHub npm Package

Bring Figma Variables into React

Design systems teams were copying design tokens from Figma to code while variable versions drifted between tools. I built FigmaVars Hooks to bring Figma Variables into React development.

Token synchronization problems

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 did not use official APIs

My role: Creator & Maintainer
Timeline: 2024 - Present
Built with: React 19TypeScriptFigma REST APIVitestNode.jsCLInpm

In this case study

Keep credentials out of the browser

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.

The browser consumes approved design-token data exported as JSON in the Figma Variables API response format. Authentication stays in the server or build/export process; credentials are never passed to the browser.

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.

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

Offline fallback

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

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

Hooks, CLI, Storybook, and validation examples

Hooks and provider

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

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

export function App() {
  return (
    <FigmaVarsProvider
      token={null}
      fileKey={null}
      fallbackFile={exportedVariables}
    >
      <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>
}

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

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

bash
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 to use the approved JSON export across your component docs. Refresh the export when approved variables change:

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

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

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

export default preview

Runtime guards and errors

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

100% test coverage

The Vitest suite covers:

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

Use the same data contract outside React

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

React integration, security, and supported workflows

React 19 Features

The React 19 integration uses:

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

Developer Experience

The package includes:

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

Supported workflows include:

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

Package capabilities and status

The library is published on npm and actively maintained. Its use cases include production token pipelines, Storybook dashboards, and Figma-to-code workflows.

This work became the starting point for Primitree, which adds architecture rules, token graphs, generated output, and change reports around the variable data.

Project notes

100%

Vitest coverage for hooks, API errors, runtime validation, and CLI output

Type-Safe

Full TypeScript support with runtime guards and error helpers

Open Source

MIT licensed and actively maintained for the design systems community