UI Customization Plugin

Install the velt-customize plugin in Cursor or Claude Code to turn a Figma design into clean Velt UI customization (comments + notifications) on your React app.

Turn a Figma design into working Velt UI customization directly in your AI coding editor. The velt-customize plugin reads your design from Figma, plans the customization surface by surface, builds it in your app, and verifies each result against the design in a real browser, or honestly reports what the Velt SDK can’t do yet.

Cursor Plugin

velt-js/velt-figma-plugin-cursor

Claude Code Plugin

velt-js/velt-figma-plugin-claude

When to Use

• You have a Figma design for how Velt comments or notifications should look in your product
• You want your AI agent to build the customization for you (CSS, wireframes, or primitives) instead of hand-writing it
• You want every result verified against the design in a live browser, not just generated and hoped for

No Figma design? Follow the UI Customization guide manually; the plugin currently requires Figma.

This plugin customizes Velt’s UI on an app where Velt is already installed and working. If you haven’t set up Velt yet, start with the Installation Plugin or Quickstart first.

Prerequisites

• Node.js 18+
• A React app with @veltdev/react installed, authenticated, and rendering Velt’s default UI
• A Figma design of your desired Velt UI, plus a Figma personal access token (figma.com → Settings → Security → Personal access tokens)
• Chrome with the Claude in Chrome extension (Claude Code), or Cursor’s built-in browser, to verify results against the design
• playwright-core (Cursor install step below) for device-resolution screenshot capture

Quickstart

Cursor

1. Clone the plugin repository and install it:

git clone https://github.com/velt-js/velt-figma-plugin-cursor.git
cd velt-figma-plugin-cursor
npm run all

This validates the plugin and copies its skills, rules, commands, and agents into ~/.cursor/. Fully restart Cursor afterwards. If you later move the repo or pull updates, run npm run all again.

2. Store your Figma token (kept in your OS keychain, never in a file):

node scripts/figma-extract.mjs token set

3. Install the one screenshot dependency:

npm i -g playwright-core

4. Open your app’s repo in Cursor (not the plugin repo), make sure the app is running, and start a run:

/velt-customize-run <figma-loop-node-url> <app-url> --mode "wireframes + primitives" --budget balanced

<app-url> is the exact page where Velt renders in your running app (e.g. http://localhost:3000/inline-comments?documentId=my-run-1). Include a run-unique documentId so runs never pollute each other’s comment data.

Claude Code

1. Inside Claude Code, install the plugin and restart:

/plugin marketplace add velt-js/velt-figma-plugin-claude
/plugin install velt-customize@velt-customize

Then restart Claude Code (or run /reload-plugins).

2. Store your Figma token (kept in your OS keychain, never in a file). Run this inside Claude Code ($CLAUDE_PLUGIN_ROOT only exists there), or just ask Claude to run it:

node "$CLAUDE_PLUGIN_ROOT/scripts/figma-extract.mjs" token set

3. Connect the Claude in Chrome extension. The plugin uses Chrome to check your running app against the design.

4. Open your app’s folder in Claude Code, make sure your dev server can run, and start a run:

/velt-customize:run <figma-loop-node-url> <app-url> --mode "wireframes + primitives" --budget balanced

<app-url> is the exact page where Velt renders in your running app (e.g. http://localhost:3000/inline-comments?documentId=my-run-1). Include a run-unique documentId so runs never pollute each other’s comment data.

A Loop is just a Figma section or frame that groups the design frames you want built, in order. The Figma URL must point at one Loop node in your file (right-click the Loop → Copy link), not the whole file. Keep a Loop to 8 frames or fewer; split bigger designs into several Loops and run them one at a time. The app URL is required too; without it the run halts and asks for it. Preflight verifies that Velt actually renders at that URL.

A full customization run can take up to about 4 hours, depending on Loop size, --budget, and how many fix iterations the verification agent (the Judge) needs. Plan to leave the editor and app running until the handoff report finishes.

Run Options

Flag	Values	Description
--mode	strictly wireframe, strictly primitives, wireframes + primitives, freeform	How the plugin is allowed to build; these correspond to the Wireframes and Primitives approaches. Leave it out and it asks you, with a recommendation
--budget	strict, balanced, thorough	How much polish effort per design frame/surface, also caps fix iterations per defect (6 / 8 / 12)
--auto	-	Fully unattended run (CI/cloud): no questions asked. Requires --mode; reads the Figma token from the FIGMA_TOKEN environment variable. --cloud is a legacy alias

What’s Included

Resource	Count	Description
Commands	5	Run, fix, replay, clear, and memory (see below)
Agents	6	velt-orchestrator (drives the run), velt-planner-structure and velt-planner-style (plan structure, then styles against the real rendered DOM), velt-builder (builds), velt-judge-2 (independently verifies), velt-judge (legacy)
Skills	14	Customization approaches (CSS, wireframes, primitives), extraction, verification, comments, notifications, references, and rules
Guide	1	A bundled customization knowledge base: the single source of truth the agents read on every run (same content as the UI Customization docs)

Available Commands

Cursor	Claude Code	Description
/velt-customize-run <url> <app-url>	/velt-customize:run <url> <app-url>	Start a customization run from a Figma Loop node URL and live app page
/velt-customize-fix "<issue>"	/velt-customize:fix "<issue>"	Surgically fix one described mismatch, then re-verify the affected area
/velt-customize-replay	/velt-customize:replay	Open the session-replay player for every stage, measurement, and fix of a run, with screenshots
/velt-customize-clear	/velt-customize:clear	Wipe run state and start fresh (does not touch generated code)
/velt-customize-memory	/velt-customize:memory	Inspect what the plugin has learned across runs

How It Works

Each run follows a plan → approve → two-phase build → verify loop:

1. Plan structure: reads your Figma Loop via the Figma REST API, recognizes which Velt component each design element is, and picks the cheapest viable approach per surface
2. Approach gate: shows you a per-surface coverage matrix with a recommendation and waits for your confirmation before building anything
3. Structure build: mounts a bare wireframe skeleton (no cosmetic CSS) family by family
4. DOM snapshot → style plan → style build: snapshots the real rendered DOM, maps the design’s exact values onto real selectors, then applies styles
5. Judge → fix: an independent fresh-context Judge (velt-judge-2) verifies the whole design in a live browser with screenshot evidence. Each defect is fixed and re-measured until it’s clean, or documented as a blocker or SDK gap
6. Report: coverage achieved, screenshots, any SDK gaps, and the generated code under components/velt/ui-customization/

You can watch progress live from a second terminal:

Cursor

node /path/to/velt-figma-plugin-cursor/scripts/progress.mjs --watch

Claude Code

node "$CLAUDE_PLUGIN_ROOT/scripts/progress.mjs" --watch

After a run, /velt-customize-replay (Cursor) or /velt-customize:replay (Claude Code) opens a session-replay player over every stage, measurement, and fix, with screenshots, so you can scrub to where something drifted.

Troubleshooting

The run halts at preflight

Preflight checks every prerequisite (Figma token, browser, target app URL, Node version) and halts with the exact fix if any is missing. Follow the printed instruction and re-run the command.

”No Figma token” error

Design intake uses the Figma REST API and requires a token. There is no Figma desktop fallback. Store one with figma-extract.mjs token set, or set the FIGMA_TOKEN environment variable in CI/cloud environments. Verify with figma-extract.mjs token status.

Commands don’t appear after install

Restart your editor fully. Cursor loads plugin files from ~/.cursor/ (re-run npm run all after moving or updating the repo), and Claude Code registers plugin commands at startup (or use /reload-plugins).

App URL doesn’t render Velt

Pass the exact page where Velt comments or notifications are mounted, not just the app origin. Preflight verifies that URL; if Velt isn’t there, fix the URL and re-run. Include a unique documentId query param so concurrent runs don’t share comment data.

---

Next Steps

• UI Customization: the customization guide the plugin agents read on every run
• Installation Plugin: Velt SDK knowledge, skills, and MCP servers for your editor
• Quickstart: set up Velt in your app first