@figma-vars/hooks 3.0.0-beta.1 → 3.1.0

package/README.md

@@ -1,278 +1,522 @@
+# FigmaVars/hooks
+
 <p align="left">
   <img src="assets/figma-vars-tagline-light.png" alt="FigmaVars Logo" width="700px" />
 </p>
 
-A fast, typed React 19 hooks library for the Figma Variables API: fetch, update, and manage design tokens via the official [Figma REST API](https://www.figma.com/developers/api#variables).
+Built and maintained by Mark Learst.
+
+A fast, typed React 19.2.3 hooks library for the Figma Variables API: fetch, update, and manage design tokens via the official [Figma REST API](https://www.figma.com/developers/api#variables).
 
-Built for the modern web, this library provides a suite of hooks to fetch, manage, and mutate your design tokens, making it easy to sync them between Figma and your React applications, Storybooks, or design system dashboards.
+Built for the modern web, this library provides a suite of hooks to fetch, manage, and mutate your design tokens/variables, making it easy to sync them between Figma and your React applications, Storybooks, or design system dashboards.
 
 ![Status](https://img.shields.io/badge/status-stable-brightgreen)
-![CI](https://github.com/marklearst/figma-vars-hooks/actions/workflows/publish.yml/badge.svg)
+![CI](https://github.com/marklearst/figma-vars-hooks/actions/workflows/ci.yml/badge.svg)
 [![codecov](https://codecov.io/gh/marklearst/figma-vars-hooks/branch/main/graph/badge.svg)](https://codecov.io/gh/marklearst/figma-vars-hooks)
 ![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
 ![License](https://img.shields.io/github/license/marklearst/figma-vars-hooks)
 ![GitHub last commit](https://img.shields.io/github/last-commit/marklearst/figma-vars-hooks)
 ![GitHub code size](https://img.shields.io/github/languages/code-size/marklearst/figma-vars-hooks)
-![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue?logo=typescript)
-![npm](https://img.shields.io/npm/v/@figma-vars/hooks)
-![npm downloads](https://img.shields.io/npm/dm/@figma-vars/hooks)
-
----
 
-## 🚀 Features
+## 📌 Why 3.0
 
-- **✅ Token Agnostic for the Best DX**: Our library doesn't care _how_ you get your Figma token. Use environment variables, `localStorage`, a state management library, or even a simple input field. This framework-agnostic approach means it works seamlessly with Vite, Next.js, Create React App, and more, without locking you into a specific build tool.
-- **⚛️ Modern React Hooks**: A full suite of hooks for fetching and mutating Figma variables, collections, and modes.
-- **✍️ Ergonomic Mutations**: A `useMutation`-style API for creating, updating, and deleting variables, providing clear loading and error states.
-- **🔒 TypeScript-first**: Strictly typed for an ergonomic and safe developer experience. Get autocompletion for all API responses.
-- **📖 Storybook & Next.js Ready**: Perfect for building live design token dashboards or style guides.
+- ✨ **New DX Features**: SWR configuration support, error handling utilities, cache invalidation helpers
+- 🔧 **React 19.2 Ready**: Optimized hooks with proper cleanup and stable function references
+- 🛡️ **Better Error Handling**: `FigmaApiError` class with HTTP status codes for better error differentiation
+- ✅ **Type Safety**: Removed unsafe type assertions, improved type definitions throughout
+- 🚀 **Performance**: Hardened SWR usage (stable keys, `null` to disable, cleaner fallback handling)
+- 📦 **Modern Tooling**: Node 20+ toolchain, strict TypeScript, and ESM-first packaging with CJS interop
+- 🖥️ **CLI Export Tool**: Automate variable exports with `figma-vars-export` for CI/CD (Enterprise required)
 
----
-
-## 🧱 Architecture Highlights
+## 🚀 Features at a Glance
 
-- ✅ **100% Test Coverage** - Comprehensive test suite with 78 tests covering all hooks, utilities, and edge cases via Vitest
-- ✅ **Consistent Error Handling** - Standardized error propagation with clear messages from the Figma API
-- ✅ **Strictly Typed APIs** - Modern TypeScript best practices with full type inference and autocompletion
-- ✅ **Predictable Hook Signatures** - Consistent, composable patterns designed for safe React integrations
-- ✅ **Developer-First Architecture** - Clean folder structure, path aliases, and logical component separation
-- ✅ **React Ecosystem** - Built specifically for React apps, Storybook, Next.js, and design system dashboards
-- ✅ **Ergonomic DX** - Intuitive API that's easy to use in both prototype and production environments
-- ✅ **Minimal Dependencies** - Leverages SWR for caching with careful dependency selection for optimal bundle size
-
----
+- **Modern React 19.2 hooks** for variables, collections, modes, and published variables
+- **Ergonomic mutation hooks** with consistent loading/error states
+- **SWR configuration support** for customizing caching and revalidation behavior
+- **Error handling utilities** for type-safe error checking and status code access
+- **Cache invalidation helpers** for automatic data refresh after mutations
+- **CLI export tool** (`figma-vars-export`) for automating variable exports to JSON (Enterprise required)
+- **Fallback JSON support** (object or string) for offline/static use - works without Enterprise!
+- **Typed core entrypoint** for non-React consumers (Axios, TanStack Query, server scripts)
+- **100% test coverage** + strict TypeScript + clean exports/attw/publint/size-limit checks
 
 ## 📦 Install
 
 ```bash
 npm install @figma-vars/hooks
 # or
-yarn add @figma-vars/hooks
-# or
 pnpm add @figma-vars/hooks
 ```
 
-> **Peer dependencies:** You'll need `react` and `react-dom`.
+Peer deps: `react` and `react-dom`.
 
----
+## 🖥️ CLI Export Tool
+
+The package includes a **CLI tool** (`figma-vars-export`) for automatically exporting Figma variables to JSON via the REST API. Perfect for CI/CD pipelines, build scripts, or one-off exports.
+
+> ⚠️ **Enterprise Required**: The CLI tool uses the Figma Variables REST API, which requires a **Figma Enterprise account**. Without Enterprise, use the [Dev Mode plugin export](#exporting-variables-for-fallback) method instead.
+
+```bash
+# Using npx (no install needed)
+FIGMA_TOKEN=your_token npx figma-vars-export --file-key YOUR_FILE_KEY --out ./variables.json
+
+# After installing
+npm install @figma-vars/hooks
+FIGMA_TOKEN=your_token figma-vars-export --file-key YOUR_FILE_KEY --out ./variables.json
 
-## 🛠️ Setup & Usage
+# Show help
+figma-vars-export --help
+```
+
+**Options:**
+
+- `--file-key` - Figma file key (required, or set `FIGMA_FILE_KEY` env var)
+- `--out` - Output path (default: `data/figma-variables.json`)
+- `--help` - Show help message
+
+**Environment Variables:**
+
+- `FIGMA_TOKEN` or `FIGMA_PAT` - Figma Personal Access Token (required)
+- `FIGMA_FILE_KEY` - Figma file key (optional)
+
+**Example Output:**
+
+```
+Saved variables to ./variables.json
+Variables count: 42
+```
 
-The library is designed to be as flexible as possible. You provide the Figma token and file key, and the hooks handle the rest.
+**No Enterprise?** See [Exporting variables for fallback](#exporting-variables-for-fallback) for alternative methods that work without Enterprise.
 
-Wrap your application (or the relevant component tree) with the `FigmaVarsProvider`. This makes the Figma token and file key available to all the hooks.
+## 🛠️ Quick Start (SWR-powered hooks)
 
 ```tsx
-// src/main.tsx or App.tsx
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { FigmaVarsProvider } from '@figma-vars/hooks'
-import App from './App'
+import { FigmaVarsProvider, useVariables } from '@figma-vars/hooks'
 
-// The token can come from anywhere: .env, localStorage, state, etc.
 const FIGMA_TOKEN = import.meta.env.VITE_FIGMA_TOKEN
-const FIGMA_FILE_KEY = 'your-figma-file-key'
+const FIGMA_FILE_KEY = 'your-file-key'
 
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
+function App() {
+  return (
     <FigmaVarsProvider
       token={FIGMA_TOKEN}
-      fileKey={FIGMA_FILE_KEY}>
-      <App />
+      fileKey={FIGMA_FILE_KEY}
+      swrConfig={{
+        revalidateOnFocus: false,
+        dedupingInterval: 5000,
+      }}>
+      <Tokens />
     </FigmaVarsProvider>
-  </React.StrictMode>
+  )
+}
+
+function Tokens() {
+  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>
+}
+```
+
+## 🧩 Non-SWR Usage (Core entrypoint)
+
+Use the `/core` build when you prefer Axios/TanStack/server scripts without React/SWR.
+
+**Axios example (GET + bulk PUT)**
+
+```ts
+import axios from 'axios'
+import { FIGMA_FILE_VARIABLES_PATH } from '@figma-vars/hooks/core'
+
+const token = process.env.FIGMA_TOKEN!
+const fileKey = process.env.FIGMA_FILE_KEY!
+
+// Fetch local variables
+const url = `https://api.figma.com${FIGMA_FILE_VARIABLES_PATH(fileKey)}/local`
+const { data } = await axios.get(url, {
+  headers: { 'X-FIGMA-TOKEN': token, 'Content-Type': 'application/json' },
+})
+
+// Bulk update
+await axios.put(
+  `https://api.figma.com${FIGMA_FILE_VARIABLES_PATH(fileKey)}`,
+  { variables: [{ action: 'UPDATE', id: 'VariableId:123', name: 'new-name' }] },
+  { headers: { 'X-FIGMA-TOKEN': token, 'Content-Type': 'application/json' } }
 )
 ```
 
-### Fetching Data
+**TanStack Query example**
+
+```ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { FIGMA_FILE_VARIABLES_PATH, fetcher, mutator } from '@figma-vars/hooks/core'
+
+const token = process.env.FIGMA_TOKEN!
+const fileKey = process.env.FIGMA_FILE_KEY!
 
-Now, you can use the query hooks anywhere in your app:
+export function useLocalVariables() {
+  return useQuery({
+    queryKey: ['figma-local', fileKey],
+    queryFn: () => fetcher(`${FIGMA_FILE_VARIABLES_PATH(fileKey)}/local`, token),
+    staleTime: 60_000,
+  })
+}
+
+export function useBulkUpdate() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (payload: unknown) =>
+      mutator(FIGMA_FILE_VARIABLES_PATH(fileKey), token, 'UPDATE', payload),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['figma-local', fileKey] }),
+  })
+}
+```
+
+## 🛡️ Fallback JSON (offline/static)
+
+Pass `fallbackFile` (object or JSON string) to `FigmaVarsProvider` to bypass live API calls:
 
 ```tsx
-// src/components/TokenList.tsx
-import { useVariables } from '@figma-vars/hooks'
+import exportedVariables from './figma-variables.json'
+;<FigmaVarsProvider
+  token={null}
+  fileKey={null}
+  fallbackFile={exportedVariables}>
+  <App />
+</FigmaVarsProvider>
+```
 
-export function TokenList() {
-  const { data, isLoading, error } = useVariables()
+### Exporting variables for fallback
 
-  if (isLoading) return <div>Loading tokens...</div>
-  if (error) return <div>Error: {error.message}</div>
+There are several ways to get your Figma variables as JSON:
+
+1. **Dev Mode / plugin export (recommended, no Enterprise needed)** ⭐
+   - Use a Variables exporter plugin in Figma Dev Mode to download the full Variables panel as JSON
+   - Save anywhere (e.g., `data/figma-variables.json`) and pass it to `fallbackFile`
+   - Works for everyone, no Enterprise account required!
+
+2. **CLI export tool (Enterprise required)** 🚀
+   - Automatically exports via REST API - perfect for CI/CD and automation
+   - See the [CLI Export Tool](#-cli-export-tool) section above for full usage details
+   - Also available from cloned repo: `node scripts/export-variables.mjs --file-key KEY --out file.json`
+
+- **Desktop MCP (manual/partial)**: Selecting a frame and running `get_variable_defs` returns only that selection’s variables. Use plugin/REST exports for complete coverage.
+
+4. **Style Dictionary**
+   - Once you have the JSON (from any path), feed it into Style Dictionary to emit platform-specific artifacts
+   - Or import it directly via `fallbackFile`
+
+## 🔧 Mutation Hooks (verbs fixed)
+
+- `useCreateVariable` → POST via bulk endpoint with `action: 'CREATE'`
+- `useUpdateVariable` → PUT via bulk endpoint with `action: 'UPDATE'`
+- `useDeleteVariable` → DELETE via bulk endpoint with `action: 'DELETE'`
+- `useBulkUpdateVariables` → PUT bulk payload (collections, modes, variables, values)
+
+All return `{ mutate, data, error, isLoading, isSuccess, isError }`.
+
+### Example: Creating and updating variables
+
+```tsx
+import { useCreateVariable, useUpdateVariable, useInvalidateVariables } from '@figma-vars/hooks'
+
+function VariableEditor() {
+  const { mutate: create } = useCreateVariable()
+  const { mutate: update } = useUpdateVariable()
+  const { invalidate } = useInvalidateVariables()
+
+  const handleCreate = async () => {
+    await create({
+      name: 'Primary Color',
+      variableCollectionId: 'CollectionId:123',
+      resolvedType: 'COLOR',
+    })
+    invalidate() // Refresh cache after mutation
+  }
 
-  // The 'data' object contains variables, collections, and modes
-  const variables = Object.values(data?.variables ?? {})
+  const handleUpdate = async (id: string) => {
+    await update({
+      variableId: id,
+      payload: { name: 'Updated Name' },
+    })
+    invalidate() // Refresh cache after mutation
+  }
 
   return (
-    <ul>
-      {variables.map((variable) => (
-        <li key={variable.id}>
-          {variable.name}: {JSON.stringify(variable.valuesByMode)}
-        </li>
-      ))}
-    </ul>
+    <>
+      <button onClick={handleCreate}>Create Variable</button>
+      <button onClick={() => handleUpdate('VariableId:123')}>Update</button>
+    </>
   )
 }
 ```
 
-### Mutating Data
+## 🛡️ Error Handling
 
-To create, update, or delete variables, use the provided mutation hooks. They follow a standard pattern, returning a `mutate` function and states for `data`, `isLoading`, and `error`.
+### Error Boundaries (Recommended)
 
-Here's an example of creating a new variable:
+Wrap your Figma-connected components with an error boundary to gracefully handle errors:
 
 ```tsx
-// src/components/CreateVariableForm.tsx
-import { useCreateVariable } from '@figma-vars/hooks'
-import type { CreateVariablePayload } from '@figma-vars/hooks'
-
-function CreateVariableForm({ collectionId }: { collectionId: string }) {
-  const { mutate, data, isLoading, error } = useCreateVariable()
-
-  const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
-    event.preventDefault()
-    const form = event.currentTarget
-    const variableName = (
-      form.elements.namedItem('variableName') as HTMLInputElement
-    )?.value
-
-    if (!variableName) return
-
-    const payload: CreateVariablePayload = {
-      name: variableName,
-      variableCollectionId: collectionId,
-      resolvedType: 'COLOR', // Example type
-    }
-    mutate(payload)
-  }
+import { ErrorBoundary } from 'react-error-boundary'
+import { FigmaVarsProvider } from '@figma-vars/hooks'
+
+function FigmaErrorFallback({ error }: { error: Error }) {
+  return (
+    <div role='alert'>
+      <h2>Failed to load Figma data</h2>
+      <pre>{error.message}</pre>
+    </div>
+  )
+}
 
+function App() {
   return (
-    <form onSubmit={handleSubmit}>
-      <input
-        name="variableName"
-        placeholder="New variable name"
-      />
-      <button
-        type="submit"
-        disabled={isLoading}>
-        {isLoading ? 'Creating...' : 'Create Variable'}
-      </button>
-      {error && <p>Error: {error.message}</p>}
-      {data && <p>Created variable with ID: {data.id}</p>}
-    </form>
+    <ErrorBoundary FallbackComponent={FigmaErrorFallback}>
+      <FigmaVarsProvider
+        token={FIGMA_TOKEN}
+        fileKey={FIGMA_FILE_KEY}>
+        <YourApp />
+      </FigmaVarsProvider>
+    </ErrorBoundary>
   )
 }
 ```
 
-### Figma PAT Security
+> **Note:** The provider validates fallback file structure at runtime and logs warnings in development. Invalid fallback data won't crash the app but will result in `undefined` data.
+
+### Runtime Validation
 
-When using the Figma API, it's essential to keep your Personal Access Token (PAT) secure. Here are some best practices:
+Use type guards to validate data at runtime:
+
+```tsx
+import { isLocalVariablesResponse, isPublishedVariablesResponse } from '@figma-vars/hooks'
 
-- Never hardcode your PAT in your code.
-- Use environment variables or a secure storage mechanism to store your PAT.
-- Limit the scope of your PAT to only the necessary permissions.
-- Rotate your PAT regularly.
+// Validate before using
+if (isLocalVariablesResponse(data)) {
+  // Safe to access data.meta.variables
+}
+```
 
-### Advanced Usage
+### Error Utilities
 
-For advanced use cases, you can use the `useFigmaToken` hook to access the token and file key from the context.
+3.0.0 introduces powerful error handling utilities for type-safe error checking:
 
 ```tsx
-// src/components/AdvancedUsage.tsx
-import { useFigmaToken } from '@figma-vars/hooks'
-
-function AdvancedUsage() {
-  const { token, fileKey } = useFigmaToken()
-
-  // Use the token and file key to make custom API requests
-  const apiRequest = async () => {
-    const response = await fetch(
-      `https://api.figma.com/v1/files/${fileKey}/variables`,
-      {
-        headers: {
-          'X-Figma-Token': token,
-        },
-      }
-    )
+import { isFigmaApiError, getErrorStatus, getErrorMessage, hasErrorStatus } from '@figma-vars/hooks'
+
+function ErrorHandler({ error }: { error: Error | null }) {
+  if (!error) return null
 
-    const data = await response.json()
-    console.log(data)
+  // Type guard for FigmaApiError
+  if (isFigmaApiError(error)) {
+    const status = error.statusCode
+
+    if (status === 401) {
+      return <div>Authentication required. Please check your token.</div>
+    }
+    if (status === 403) {
+      return <div>Access forbidden. Check file permissions.</div>
+    }
+    if (status === 429) {
+      return <div>Rate limit exceeded. Please wait before retrying.</div>
+    }
+    if (status === 404) {
+      return <div>File or variable not found.</div>
+    }
+  }
+
+  // Helper functions
+  const status = getErrorStatus(error) // number | null
+  const message = getErrorMessage(error) // string
+
+  // Convenience check
+  if (hasErrorStatus(error, 401)) {
+    // Handle unauthorized
   }
 
-  return <button onClick={apiRequest}>Make API Request</button>
+  return <div>Error: {message}</div>
 }
 ```
 
-### Error Handling
+**Common HTTP Status Codes:**
 
-All hooks return an `error` state that you can use to handle errors.
+- `401` - Unauthorized (invalid or missing token)
+- `403` - Forbidden (insufficient permissions)
+- `404` - Not Found (file/variable doesn't exist)
+- `429` - Too Many Requests (rate limit exceeded)
+
+## 🔄 Cache Management
+
+After mutations, use `useInvalidateVariables` to refresh cached data:
 
 ```tsx
-// src/components/ErrorHandling.tsx
-import { useVariables } from '@figma-vars/hooks'
+import { useUpdateVariable, useInvalidateVariables } from '@figma-vars/hooks'
 
-function ErrorHandling() {
-  const { data, isLoading, error } = useVariables()
+function UpdateButton({ variableId }: { variableId: string }) {
+  const { mutate, isLoading } = useUpdateVariable()
+  const { invalidate, revalidate } = useInvalidateVariables()
+
+  const handleUpdate = async () => {
+    await mutate({
+      variableId,
+      payload: { name: 'New Name' },
+    })
 
-  if (error) {
-    return (
-      <div>
-        <h2>Error</h2>
-        <p>{error.message}</p>
-      </div>
-    )
+    // Option 1: Invalidate (refetch on next access)
+    invalidate()
+
+    // Option 2: Revalidate immediately (refetch now)
+    // revalidate()
   }
 
-  // Render data or loading state
+  return (
+    <button
+      onClick={handleUpdate}
+      disabled={isLoading}>
+      {isLoading ? 'Updating...' : 'Update Variable'}
+    </button>
+  )
 }
 ```
 
----
+## ⚙️ SWR Configuration
 
-## 🧩 API Reference
+Customize SWR behavior globally through the provider:
 
-### Core Hooks
+```tsx
+<FigmaVarsProvider
+  token={FIGMA_TOKEN}
+  fileKey={FIGMA_FILE_KEY}
+  swrConfig={{
+    revalidateOnFocus: false, // Don't refetch on window focus
+    dedupingInterval: 5000, // Dedupe requests within 5s
+    errorRetryCount: 3, // Retry failed requests 3 times
+    errorRetryInterval: 1000, // Wait 1s between retries
+    onError: error => {
+      // Global error handler
+      if (isFigmaApiError(error) && error.statusCode === 429) {
+        console.warn('Rate limited, backing off...')
+      }
+    },
+  }}>
+  <App />
+</FigmaVarsProvider>
+```
+
+**Common SWR Options:**
 
-- `useVariables()`: Fetches all local variables for the file key provided to the `FigmaVarsProvider`. Returns a SWR hook state with `data`, `isLoading`, and `error` properties. The actual Figma response is in `data.data`.
-- `useVariableCollections()`: A convenience hook that returns just the variable collections from the main `useVariables` data.
-- `useVariableModes()`: A convenience hook that returns just the variable modes from the main `useVariables` data.
-- `useFigmaToken()`: A simple hook to access the token and file key from the context.
+- `revalidateOnFocus` - Refetch when window regains focus (default: `true`)
+- `dedupingInterval` - Deduplication interval in ms (default: `2000`)
+- `errorRetryCount` - Max retry attempts (default: `5`)
+- `refreshInterval` - Polling interval in ms (default: `0` = disabled)
+- `onError` - Global error callback
 
-### Mutation Hooks
+## 📚 API Cheat Sheet
 
-All mutation hooks return an object with the following shape: `{ mutate, data, isLoading, error }`.
+### Hooks
 
-- `useCreateVariable()`: Creates a new variable. The `mutate` function expects a `CreateVariablePayload` object.
-- `useUpdateVariable()`: Updates an existing variable. The `mutate` function expects an object `{ variableId, payload }` where `payload` is an `UpdateVariablePayload`.
-- `useDeleteVariable()`: Deletes a variable. The `mutate` function expects the `variableId` (string) of the variable to delete.
-- `useBulkUpdateVariables()`: Creates, updates, or deletes multiple entities in a single batch operation. The `mutate` function expects a `BulkUpdatePayload` object.
+- **Queries**: `useVariables` (local), `usePublishedVariables` (library/published), `useVariableCollections`, `useVariableModes`, `useFigmaToken`
+- **Granular Selectors**: `useCollectionById`, `useModesByCollection`, `useVariableById` (optimized selectors for specific entities)
+- **Mutations**: `useCreateVariable`, `useUpdateVariable`, `useDeleteVariable`, `useBulkUpdateVariables`
+- **Cache**: `useInvalidateVariables` (invalidate/revalidate cache)
+
+### Utilities
+
+- **Filtering**: `filterVariables` (filter by type, name, etc.)
+- **Error Handling**: `isFigmaApiError`, `getErrorStatus`, `getErrorMessage`, `hasErrorStatus`
+- **Type Guards**: `isLocalVariablesResponse`, `isPublishedVariablesResponse`, `validateFallbackData` (runtime validation)
+- **SWR Keys**: `getVariablesKey`, `getPublishedVariablesKey`, `getInvalidationKeys` (centralized cache key construction)
+- **Core helpers**: `fetcher`, `mutator`, constants for endpoints and headers
 
 ### Types
 
-All types are exported from `@figma-vars/hooks`. The core response type from Figma for local variables is `LocalVariablesResponse`.
+- **Responses**: `LocalVariablesResponse`, `PublishedVariablesResponse`
+- **Variables**: `FigmaVariable`, `FigmaCollection`, `VariableMode`
+- **Mutations**: `BulkUpdatePayload`, `CreateVariablePayload`, `UpdateVariablePayload`
+- **Errors**: `FigmaApiError` (extends `Error` with `statusCode`)
 
----
+## 🔐 Auth & Scope
+
+- Header: `X-FIGMA-TOKEN: <PAT>`
+- Scopes: `file_variables:read` for GETs, `file_variables:write` for mutations.
+- Enterprise Full seat required for live API; fallback JSON works without a token.
 
-## 📚 Storybook & Next.js Integration
+## ⚠️ Enterprise Requirement and Offline Options
 
-The provider model makes integration trivial. Simply wrap your Storybook stories or Next.js pages with the `FigmaVarsProvider`.
+- The Figma Variables REST API requires a Figma Enterprise seat for live requests. Without Enterprise, live calls will fail even with a valid PAT.
+- The library remains useful without Enterprise: supply `fallbackFile` (object or JSON string) exported from Figma (Dev Mode plugin, CLI, or Figma MCP server output) and all read hooks work offline/for static deployments.
+- MCP/other exporters: as long as they emit the same JSON shape as the Variables API, you can feed that JSON into `fallbackFile`; mutations still require Enterprise access.
+
+## 🚫 Do Not Publish Tokens or File Keys
+
+- Never commit PATs or file keys to git, Storybook static builds, or client bundles.
+- Use environment variables (`process.env` / `import.meta.env`) and secret managers; keep them server-side where possible.
+- Prefer `fallbackFile` with `token={null}`/`fileKey={null}` for demos and public Storybooks.
+- Avoid logging tokens or keys; scrub them from error messages and analytics.
+
+## 📈 Rate Limits
+
+- Figma enforces per-token limits. Rely on SWR/TanStack caching, avoid unnecessary refetches, and prefer fallback JSON for static sites.
+- Use `swrConfig` to customize `dedupingInterval` and `errorRetryCount` to optimize API usage.
+- Handle `429` rate limit errors with `isFigmaApiError` and implement exponential backoff if needed.
+
+## 📚 Storybook & Next.js
+
+- **Storybook decorator**: wrap stories once so hooks have context and tokens.
 
 ```tsx
-// In a Storybook story
-import { FigmaVarsProvider, useVariables } from '@figma-vars/hooks'
+// .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 const TokensStory = () => (
-  <FigmaVarsProvider
-    token="YOUR_TOKEN"
-    fileKey="YOUR_FILE_KEY">
-    <TokenList />
-  </FigmaVarsProvider>
-)
+export default preview
+```
+
+- **Next.js App Router**: provide context in a shared provider file.
 
-const TokenList = () => {
-  const { data } = useVariables()
-  return <pre>{JSON.stringify(data?.variables, null, 2)}</pre>
+```tsx
+// app/providers.tsx
+import { FigmaVarsProvider } from '@figma-vars/hooks'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <FigmaVarsProvider
+      token={process.env.NEXT_PUBLIC_FIGMA_TOKEN}
+      fileKey={process.env.NEXT_PUBLIC_FIGMA_FILE_KEY}>
+      {children}
+    </FigmaVarsProvider>
+  )
 }
 ```
 
+## 🧪 Tooling & Quality Gates
+
+- `pnpm run build`, `pnpm test`, `pnpm run test:coverage`
+- `pnpm run check:publint`, `pnpm run check:attw`, `pnpm run check:size`
+
+## 🧭 Release Checklist (for 3.0.0)
+
+- Run `pnpm run check:release`
+- Tag `v3.0.0` (CI publishes to npm)
+- Update dist-tags on npm if needed (`latest` → 3.0.0)
+
 ---
 
 ## 📝 Contributing
@@ -282,4 +526,4 @@ PRs and issues are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gu
 ## 📝 License
 
 This project is licensed under the [MIT License](LICENSE).
-© 2024–2025 Mark Learst
+© 2024–2026 Mark Learst