@sarjallab09/figma-intelligence 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +78 -204
  2. package/package.json +13 -2
package/README.md CHANGED
@@ -1,159 +1,110 @@
1
- # Figma Intelligence Layer
1
+ # Figma Intelligence
2
2
 
3
3
  [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
4
+ [![npm](https://img.shields.io/npm/v/@sarjallab09/figma-intelligence)](https://www.npmjs.com/package/@sarjallab09/figma-intelligence)
4
5
  [![License: CC BY-NC-ND 4.0](https://img.shields.io/badge/License-CC%20BY--NC--ND%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-nd/4.0/)
5
- [![MCP Tools](https://img.shields.io/badge/MCP%20tools-64-blue)]()
6
+ [![MCP Tools](https://img.shields.io/badge/MCP%20tools-88-blue)]()
6
7
 
7
- > An AI-powered design assistant that lives inside Figma — connect Claude, OpenAI Codex, or Google Gemini CLI and let AI build, edit, and modify your designs in real time.
8
+ > 88 AI-powered design tools for Figma. Works with your Claude, OpenAI Codex, or Gemini CLI subscription. One command to set up.
8
9
 
9
10
  ```
10
- You (chat in Figma plugin) ◄──► Bridge Relay ◄──► Claude / OpenAI Codex / Gemini CLI
11
+ You (chat in Figma plugin) ◄──► Local Relay ◄──► Claude / OpenAI Codex / Gemini CLI
11
12
  ```
12
13
 
13
14
  ---
14
15
 
15
- ## What does this do?
16
+ ## Quick Start (3 steps)
16
17
 
17
- Type something like *"Make a login screen with a blue button"* and the selected provider will actually create the components and layers in your Figma file — not just describe how to do it.
18
+ ### 1. Install the Figma plugin
18
19
 
19
- The bundled Figma MCP server exposes **64 tools**, including high-level generation tools (`figma_page_architect`, `figma_intent_translator`, `figma_layout_intelligence`, `figma_design_from_ref`, `figma_generate_spec`) and direct editing and inspection tools.
20
+ Search **"Figma Intelligence"** in the Figma Community plugins, or install it from the plugin page.
20
21
 
21
- ---
22
+ > **Note:** Requires Figma Desktop app — the browser version won't work.
22
23
 
23
- ## Before you start — what you need
24
+ ### 2. Install an AI CLI and log in
24
25
 
25
- You need Node.js, Figma Desktop, and at least one supported AI CLI on your computer. If you already have them, skip to Step 1.
26
+ You need at least one. All three use your existing subscription — no extra API costs.
26
27
 
27
- ### 1. Node.js (a programming tool that runs behind the scenes)
28
+ | Provider | Install | Log in |
29
+ |---|---|---|
30
+ | **Claude** | [claude.ai/download](https://claude.ai/download) | `claude login` |
31
+ | **OpenAI Codex** | `npm install -g @openai/codex` | `codex login` |
32
+ | **Google Gemini** | `npm install -g @google/gemini-cli` | `gemini` (opens Google sign-in) |
28
33
 
29
- - Go to [nodejs.org](https://nodejs.org) and download the **LTS** version (the one labelled "Recommended for most users")
30
- - Install it like any normal app (open the downloaded file, click Next/Install)
31
- - To check it worked: open Terminal (Mac) or Command Prompt (Windows), type `node -v`, and press Enter — you should see a version number like `v20.0.0`
34
+ ### 3. Run setup
32
35
 
33
- ### 2. Figma Desktop app
36
+ Open your terminal and run:
34
37
 
35
- - Download from [figma.com/downloads](https://www.figma.com/downloads/)
36
- - This must be the **desktop app** — the browser version won't work
38
+ ```bash
39
+ npx @sarjallab09/figma-intelligence setup
40
+ ```
37
41
 
38
- ### 3. An AI tool
42
+ This will:
43
+ - Install dependencies and build the MCP server
44
+ - Detect which AI CLIs you have and check their login status
45
+ - Ask for your **Figma Personal Access Token** ([how to get one](#figma-personal-access-token))
46
+ - Register the MCP server with your detected providers
47
+ - Start the local relay server
48
+ - Optionally install as a background service (macOS)
39
49
 
40
- Install at least one of these — the setup will detect whichever you have:
50
+ **That's it.** Open the plugin in Figma — it auto-connects.
41
51
 
42
- | Tool | How to install |
43
- |---|---|
44
- | **Claude Code** | Download from claude.ai/download, sign in with `claude login` |
45
- | **VS Code** (GitHub Copilot) | Download from code.visualstudio.com |
46
- | **Cursor** | Download from cursor.com |
47
- | **Windsurf** | Download from codeium.com/windsurf |
48
- | **Zed** | Download from zed.dev |
49
- | **Continue.dev** | Install the VS Code extension from continue.dev |
50
- | **OpenAI Codex CLI** | `npm install -g @openai/codex`, then `codex login` |
51
- | **Google Gemini CLI** | `npm install -g @google/gemini-cli`, then run `gemini` and complete Google sign-in |
52
- | **Kiro** (AWS) | Download from kiro.dev |
53
-
54
- If you install Claude, Codex, and Gemini CLI, `npm run setup` prepares all of them so provider switching does not require restarting the bridge.
52
+ ---
55
53
 
56
- ### 4. A Figma Personal Access Token
54
+ ## Figma Personal Access Token
57
55
 
58
- This is like a password that lets the plugin read and edit your Figma files.
56
+ Required so the plugin can read and edit your Figma files.
59
57
 
60
58
  1. Open Figma Desktop
61
- 2. Click your profile photo (top-left)
62
- 3. Go to **Settings → Security**
63
- 4. Scroll down to **Personal access tokens** → click **Generate new token**
64
- 5. Give it any name (e.g. "Claude Plugin")
65
- 6. **Copy the token and save it somewhere** — you'll need it in Step 2 below and Figma only shows it once
59
+ 2. Click your profile photo (top-left) > **Settings** > **Security**
60
+ 3. Scroll to **Personal access tokens** > **Generate new token**
61
+ 4. Give it any name (e.g. "Figma Intelligence")
62
+ 5. Copy the token — Figma only shows it once
66
63
 
67
64
  ---
68
65
 
69
- ## Setup (one-time, takes about 2 minutes)
70
-
71
- ### Step 1 — Open Terminal in the project folder
72
-
73
- **On Mac:**
74
- 1. Open the **Terminal** app (search for it in Spotlight with Cmd+Space)
75
- 2. Type `cd ` (with a space after), then drag the project folder onto the Terminal window — this fills in the path automatically
76
- 3. Press Enter
66
+ ## Commands
77
67
 
78
- **On Windows:**
79
- 1. Open the project folder in File Explorer
80
- 2. Click the address bar at the top, type `cmd`, press Enter
81
-
82
- ### Step 2 — Run the setup command
68
+ After setup, you can manage the relay with these commands:
83
69
 
84
70
  ```bash
85
- npm run setup
71
+ npx @sarjallab09/figma-intelligence start # Start the relay server
72
+ npx @sarjallab09/figma-intelligence stop # Stop the relay server
73
+ npx @sarjallab09/figma-intelligence status # Show relay + provider status
74
+ npx @sarjallab09/figma-intelligence doctor # Diagnose issues
75
+ npx @sarjallab09/figma-intelligence setup # Full setup (first time or reconfigure)
86
76
  ```
87
77
 
88
- Type exactly that and press Enter. The setup will:
89
- - Install everything needed (you'll see a lot of text scroll by — that's normal)
90
- - Detect your Claude, Codex, and Gemini logins
91
- - Prompt you to sign in to any installed provider that is not ready yet, so both subscriptions can be prepared in one pass
92
- - Register the Figma MCP server for Claude, Codex, Gemini CLI, and VS Code
93
- - If you choose OpenAI in the plugin later, it will use the account currently logged into `codex` without restarting `npm start`
94
- - If you choose Gemini in the plugin later and Gemini CLI is authenticated, it will use Gemini CLI subscription mode with the same Figma MCP server
95
- - Ask you to **paste your Figma token** — paste it and press Enter
96
- - Start the background bridge that lets the plugin talk to Figma
97
-
98
- > If it says "npm: command not found" — Node.js is not installed correctly. Go back and reinstall it from [nodejs.org](https://nodejs.org).
99
-
100
- ### Step 3 — Load the plugin into Figma
101
-
102
- 1. Open **Figma Desktop**
103
- 2. Open any file (or create a new one)
104
- 3. **Right-click** anywhere on the canvas (the blank white area)
105
- 4. In the menu that appears, go to: **Plugins → Development → Import plugin from manifest…**
106
- 5. A file picker opens — navigate to the project folder, then into the `figma-bridge-plugin` folder, and select **manifest.json**
107
- 6. Click **Open**
108
-
109
- ### Step 4 — Start the plugin
78
+ ---
110
79
 
111
- 1. **Right-click** the canvas again
112
- 2. Go to **Plugins → Development → Figma Intelligence Bridge**
113
- 3. A panel will open — click **▶ Start**
114
- 4. You should see **✅ Connected** — you're all set!
80
+ ## Every time you restart your computer
115
81
 
116
- ### Step 5 — Connect any other AI tools (optional)
82
+ If you installed the background service during setup (macOS), the relay starts automatically — no action needed.
117
83
 
118
- Already using Cursor, Windsurf, Zed, Continue.dev, or Kiro? Run:
84
+ Otherwise, just run:
119
85
 
120
86
  ```bash
121
- npm run connect
87
+ npx @sarjallab09/figma-intelligence start
122
88
  ```
123
89
 
124
- It auto-detects which tools you have installed and registers the Figma MCP server with all of them in one go. You can also target a specific tool:
90
+ Then open the Figma plugin — it reconnects automatically.
125
91
 
126
- ```bash
127
- npm run connect -- --tool cursor
128
- npm run connect -- --tool windsurf
129
- npm run connect -- --tool zed
130
- npm run connect -- --tool continue
131
- npm run connect -- --tool vscode
132
- npm run connect -- --tool kiro
133
- npm run connect -- --tool codex
134
- ```
135
-
136
- ### Step 6 — Restart your AI tool
92
+ ---
137
93
 
138
- Restart VS Code, Cursor, Windsurf, Zed, or whichever tool you connected, so it picks up the new MCP server.
94
+ ## What does this do?
139
95
 
140
- ### Step 7 — Quick health check (recommended)
96
+ Type something like *"Make a login screen with a blue button"* and the AI will actually create the components and layers in your Figma file — not just describe how to do it.
141
97
 
142
- Run:
98
+ The plugin exposes **88 MCP tools** across 5 phases:
143
99
 
144
- ```bash
145
- npm run status
146
- ```
147
-
148
- This verifies relay socket state, plugin connection, MCP connection, build output, and token setup in one command.
149
-
150
- If you use OpenAI provider and it reports missing Codex MCP registration, run:
151
-
152
- ```bash
153
- npm run register:codex-mcp
154
- ```
155
-
156
- If you plan to use Gemini subscription mode, verify that `gemini --version` works and that running `gemini` completes Google sign-in before you open the plugin.
100
+ | Phase | Tools | Examples |
101
+ |---|---|---|
102
+ | **Visual Intelligence** | 7 | Screen cloning, visual audit, accessibility audit, sketch-to-design |
103
+ | **Design System Accuracy** | 6 | Intent translation, layout intelligence, variant expansion, linting |
104
+ | **Generation & Scaffolding** | 13 | Page architect, swarm build, prototype wiring, composition builder |
105
+ | **Sync & Bidirectionality** | 9 | Token export (16 formats), component code gen, handoff specs |
106
+ | **Governance & Health** | 15 | Health reports, token docs, design system scaffolding, DTCG validation |
107
+ | **Node Operations** | 38 | Create, read, update, delete nodes, variables, styles, components |
157
108
 
158
109
  ---
159
110
 
@@ -200,114 +151,37 @@ Setup registers the same Figma MCP server for Claude, Codex, and Gemini CLI, so
200
151
 
201
152
  The active provider will show its signed-in email in the auth strip when available.
202
153
 
203
- ## Gemini CLI workflow
204
-
205
- If you want Gemini to use the real Figma MCP tools instead of API-key text mode, use Gemini CLI.
206
-
207
- ### 1. Install Gemini CLI
208
-
209
- ```bash
210
- npm install -g @google/gemini-cli
211
- ```
212
-
213
- ### 2. Sign in with your Google account
214
-
215
- Run either of these:
216
-
217
- ```bash
218
- gemini
219
- ```
220
-
221
- ```bash
222
- gemini auth login
223
- ```
224
-
225
- That opens the Google browser OAuth flow. After it completes, re-run:
226
-
227
- ```bash
228
- npm run setup
229
- ```
230
-
231
- Setup writes the Figma MCP registration into `~/.gemini/settings.json`, so the Gemini CLI subprocess can call the same 64 Figma tools as Claude and Codex.
232
-
233
- ### 3. Use Gemini inside the plugin
234
-
235
- 1. Start the bridge with `npm start`
236
- 2. Open the Figma plugin
237
- 3. Choose the **Gemini** provider
238
- 4. Send a design request
239
-
240
- When Gemini CLI auth is present, the relay uses Gemini CLI subscription mode. If Gemini CLI is not authenticated, the plugin falls back to Gemini API-key mode, which is lower fidelity and does not provide the same MCP-driven tool execution.
241
-
242
- ---
243
-
244
- ## Every time you restart your computer
245
-
246
- If setup completed successfully on macOS, the bridge relay is installed as a background service and should start automatically after login.
247
-
248
- If you ever need to start it manually:
249
-
250
- 1. Open Terminal in the project folder (same as Step 1 above)
251
- 2. Run:
252
-
253
- ```bash
254
- npm start
255
- ```
256
-
257
- 3. Open Figma and click **▶ Start** in the plugin panel
258
-
259
- 4. Run:
260
-
261
- ```bash
262
- npm run status
263
- ```
264
-
265
- That's it — you're connected again.
266
-
267
- ---
268
-
269
154
  ## Troubleshooting
270
155
 
271
156
  | What went wrong | How to fix it |
272
157
  |---|---|
273
158
  | **"npm: command not found"** | Node.js is not installed — download it from [nodejs.org](https://nodejs.org) |
274
- | **Plugin shows "Disconnected"** | Run `npm start` in Terminal first, then click Start in the plugin |
275
- | **Not sure what is broken** | Run `npm run status` for a one-command diagnostic and follow the printed next actions |
276
- | **OpenAI provider can chat but cannot use Figma tools** | Run `npm run register:codex-mcp`, then `npm run status` |
277
- | **Gemini appears to answer but does not build in Figma** | Install Gemini CLI with `npm install -g @google/gemini-cli`, run `gemini` to sign in, then re-run `npm run setup` |
278
- | **Chat does nothing / no response** | Open Terminal and run `claude login` for Claude, `codex login` for OpenAI, or `gemini` for Gemini. Then switch providers once in the plugin or reconnect it — no `npm start` restart needed |
279
- | **`unexpected argument '--approval-mode'` in plugin chat** | Your plugin is using an older Codex CLI invocation. Update to the latest repo version or patch `figma-bridge-plugin/codex-runner.js` to use `codex exec --json` instead of `--approval-mode` / `--quiet` |
280
- | **"dist/index.js not found"** | Run `cd figma-intelligence-layer && npm run build` in Terminal |
281
- | **Wrong Figma token / token expired** | Re-run `npm run setup` and paste your new token when asked |
282
- | **MCP tools missing in VS Code / Cursor / Zed etc.** | Run `npm run connect` then restart the tool |
283
- | **"Design + Code" shows "VS Code not connected"** | Restart VS Code after running `npm run setup` — the bridge extension loads on startup |
284
- | **Port 9001 already in use** | `npm run setup` now handles this automatically — just run it again |
159
+ | **Plugin shows "Server offline"** | Run `npx @sarjallab09/figma-intelligence start` in your terminal |
160
+ | **Plugin shows setup guide** | Follow the on-screen steps — run the setup command in your terminal |
161
+ | **Not sure what is broken** | Run `npx @sarjallab09/figma-intelligence doctor` for full diagnostics |
162
+ | **Chat does nothing / no response** | Run `claude login` / `codex login` / `gemini` to authenticate your AI provider |
163
+ | **Gemini doesn't build in Figma** | Install Gemini CLI: `npm i -g @google/gemini-cli`, run `gemini` to sign in, re-run setup |
164
+ | **Wrong Figma token / token expired** | Re-run `npx @sarjallab09/figma-intelligence setup` and paste your new token |
165
+ | **Port 9001 already in use** | Run `npx @sarjallab09/figma-intelligence stop` then `start` again |
285
166
 
286
167
  ---
287
168
 
288
169
  ## Folder structure (for the curious)
289
170
 
290
171
  ```
291
- setup.sh ← the one-command setup script (does everything)
172
+ bin/cli.js ← CLI entrypoint (npx @sarjallab09/figma-intelligence)
292
173
  figma-bridge-plugin/
293
- manifest.json ← import this file into Figma
294
- bridge-relay.js ← background bridge (npm start runs this)
174
+ manifest.json ← Figma plugin manifest
175
+ bridge-relay.js ← local WebSocket relay server
295
176
  chat-runner.js ← connects Claude to the plugin chat
296
177
  codex-runner.js ← connects OpenAI Codex to the plugin chat
297
178
  gemini-cli-runner.js ← connects Gemini CLI to the plugin chat
298
- shared-prompt-config.js ← system prompts, design systems, dual output prompt
299
- ui.html / code.js ← the plugin's visual panel (Chat / Code / Design+Code)
179
+ ui.html / code.js ← plugin UI panel (Chat / Code / Design+Code)
300
180
  figma-intelligence-layer/
301
- src/ ← source code for the AI tools
302
- dist/index.js ← built/compiled version (created by setup)
303
- vscode-chat-extension/ ← VS Code bridge extension (auto-installed by setup)
304
- src/extension.ts ← background service that writes code files
305
- src/dual-output.ts ← parses code output from AI responses
306
- src/code-generator.ts ← writes component files to workspace
307
- src/preview-server.ts ← Storybook live preview manager
308
- design-bridge/ ← Asset MCP bridge (Stitch, Unsplash, Pexels, Iconify)
309
- ui-components/ ← Generated React component library with Storybook
310
- scripts/ ← Utility scripts (status, connect, cleanup)
181
+ src/tools/ ← 88 MCP tool implementations (5 phases)
182
+ dist/index.js ← built MCP server (created by setup)
183
+ design-bridge/ ← Asset MCP bridge (Unsplash, Pexels, Iconify)
184
+ scripts/ ← Utility scripts (status, connect)
311
185
  ```
312
186
 
313
187
  ---
@@ -315,9 +189,9 @@ scripts/ ← Utility scripts (status, connect, cleanup)
315
189
  ## Contributing
316
190
 
317
191
  1. Fork the repo and create a feature branch
318
- 2. Run `npm run setup` to install all dependencies
192
+ 2. Run `npx @sarjallab09/figma-intelligence setup` to install all dependencies
319
193
  3. Make your changes
320
- 4. Run `npm run status` to verify everything works
194
+ 4. Run `npx @sarjallab09/figma-intelligence doctor` to verify everything works
321
195
  5. Open a pull request
322
196
 
323
197
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sarjallab09/figma-intelligence",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "88 AI-powered design tools for Figma. Works with your Claude, OpenAI Codex, or Gemini CLI subscription. One command to set up.",
5
5
  "author": "Figma Intelligence Contributors",
6
6
  "license": "CC-BY-NC-ND-4.0",
@@ -31,5 +31,16 @@
31
31
  "scripts/",
32
32
  "README.md"
33
33
  ],
34
- "keywords": ["figma", "mcp", "claude", "openai", "codex", "gemini", "ai", "design", "design-system", "figma-plugin"]
34
+ "keywords": [
35
+ "figma",
36
+ "mcp",
37
+ "claude",
38
+ "openai",
39
+ "codex",
40
+ "gemini",
41
+ "ai",
42
+ "design",
43
+ "design-system",
44
+ "figma-plugin"
45
+ ]
35
46
  }