FigmaVars Hooks

• 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

Quick Start (hooks + provider)

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

• 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

• 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

// .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

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

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

Runtime Guards + Error Utilities

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

100% Test Coverage

• 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

React 19 Features

• 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

Developer Experience

• 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

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

Use Cases

• 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

• 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