> ## Documentation Index
> Fetch the complete documentation index at: https://velt-claude-ui-customization-docs-review-m7hwcn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<CardGroup cols={2}>
  <Card title="Cursor Plugin" icon="github" href="https://github.com/velt-js/velt-figma-plugin-cursor">
    velt-js/velt-figma-plugin-cursor
  </Card>

  <Card title="Claude Code Plugin" icon="github" href="https://github.com/velt-js/velt-figma-plugin-claude">
    velt-js/velt-figma-plugin-claude
  </Card>
</CardGroup>

## 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](/ui-customization/overview) manually; the plugin currently requires Figma.

<Info>
  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](/get-started/installation-plugin) or [Quickstart](/get-started/quickstart) first.
</Info>

## 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](https://www.figma.com/developers/api#access-tokens) (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

<Tabs>
  <Tab title="Cursor">
    1. Clone the plugin repository and install it:

    ```bash theme={null}
    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):

    ```bash theme={null}
    node scripts/figma-extract.mjs token set
    ```

    3. Install the one screenshot dependency:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="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:

    ```bash theme={null}
    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.
  </Tab>
</Tabs>

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

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

### 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](/ui-customization/layout) and [Primitives](/ui-customization/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](/ui-customization/overview) 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:

<Tabs>
  <Tab title="Cursor">
    ```bash theme={null}
    node /path/to/velt-figma-plugin-cursor/scripts/progress.mjs --watch
    ```
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    node "$CLAUDE_PLUGIN_ROOT/scripts/progress.mjs" --watch
    ```
  </Tab>
</Tabs>

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](/ui-customization/overview): the customization guide the plugin agents read on every run
* [Installation Plugin](/get-started/installation-plugin): Velt SDK knowledge, skills, and MCP servers for your editor
* [Quickstart](/get-started/quickstart): set up Velt in your app first