@figma-vars/hooks 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mark Learst
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# figma-vars-hooks
+
+A modern, type-safe React hooks & utilities library for the [Figma Variables API](https://www.figma.com/developers/api#variables). Fetch, update, and sync design tokens between Figma and your app, Storybook, or design system dashboard.
+
+---
+
+## 🚀 Features
+
+- **React 19+ hooks** for fetching and updating Figma variables, collections, and modes
+- **Mutation utilities** for creating, updating, and deleting variables
+- **TypeScript-first**: strict, ergonomic types for all API surfaces
+- **Storybook/Next.js ready** for live token dashboards
+- **Experimental/advanced hooks** for power users
+
+---
+
+## 📦 Install
+
+```bash
+npm install figma-vars-hooks
+# or
+yarn add figma-vars-hooks
+# or
+pnpm add figma-vars-hooks
+```
+
+> **Peer dependency:** React 19+
+
+---
+
+## 🛠️ Setup: Figma API Token
+
+Set your Figma Personal Access Token as an environment variable in your app (Vite example):
+
+```env
+VITE_FIGMA_TOKEN=your-figma-token-here
+```
+
+---
+
+## ⚡ Quick Start Example
+
+```tsx
+import { useVariables } from 'figma-vars-hooks'
+
+export function TokenList({ fileKey }: { fileKey: string }) {
+  const { variables, loading, error, refresh } = useVariables(fileKey)
+
+  if (loading) return <div>Loading…</div>
+  if (error) return <div>Error: {error.message}</div>
+
+  return (
+    <ul>
+      {variables?.map((v) => (
+        <li key={v.id}>
+          {v.name}: {v.value}
+        </li>
+      ))}
+      <button onClick={refresh}>Refresh</button>
+    </ul>
+  )
+}
+```
+
+---
+
+## 🧩 API Reference
+
+### Core Hooks
+
+- `useFigmaToken()` – Get the current Figma API token
+- `useVariables(fileKey, options?)` – Fetch variables for a Figma file (with polling/refresh)
+- `useVariableCollections(fileKey)` – Fetch variable collections for a file
+- `useVariableModes(collectionId)` – Fetch variable modes for a collection
+
+### Mutations
+
+- `createVariable(fileKey, variableData)` – Create a new variable
+- `updateVariable(fileKey, variableId, newData)` – Update a variable
+- `deleteVariable(fileKey, variableId)` – Delete a variable
+- `updateVariableValues(variableId, values)` – Update variable values across modes
+
+### Utilities
+
+- `filterVariables(variables, { type?, name? })` – Filter variables by type/name
+- `VariablesCache` – Simple in-memory cache for variable lists
+- `fetchHelpers`, `authHelpers` – Internal helpers (advanced)
+
+### Types
+
+All types are exported from `figma-vars-hooks/types` (see `src/types/`).
+
+---
+
+## 🧪 Experimental/Advanced Hooks
+
+- `useVariableAliases` – Manage local variable aliases (not in Figma API)
+- `useVariableBindings` – Bind variables to UI components (not in Figma API)
+- `usePublishVars`, `useSync` – Placeholders for future publish/sync features
+
+> These are opt-in and may change—see `src/experimental/` for details.
+
+---
+
+## 📚 Storybook & Next.js Integration
+
+Use these hooks in your Storybook stories or Next.js pages to build live design token dashboards. Example:
+
+```tsx
+// In a Storybook story
+import { useVariables } from 'figma-vars-hooks'
+
+export const TokensStory = () => {
+  const { variables } = useVariables('YOUR_FILE_KEY')
+  return <pre>{JSON.stringify(variables, null, 2)}</pre>
+}
+```
+
+---
+
+## 📝 Contributing
+
+PRs and issues welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## 📄 License
+
+MIT
+
+---
+
+## 🙏 Credits
+
+Built by Mark Learst and contributors. Inspired by the Figma community and the need for seamless design token workflows.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@figma-vars/hooks",
+  "version": "1.0.3",
+  "description": "Typed React hooks for managing Figma Variables, modes, tokens, and bindings via API.",
+  "author": "Mark Learst",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "figma",
+    "figma variables",
+    "figma tokens",
+    "react",
+    "react hooks",
+    "design tokens",
+    "theme",
+    "storybook",
+    "vite",
+    "typescript",
+    "design system"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marklearst/figma-vars-hooks"
+  },
+  "bugs": {
+    "url": "https://github.com/marklearst/figma-vars-hooks/issues"
+  },
+  "homepage": "https://github.com/marklearst/figma-vars-hooks#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/marklearst"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "typescript": "~5.8.3",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-tsconfig-paths": "^5.1.4"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  }
+}