Gen UI Mockup Tool (L1)

Fast, low-token UI wireframing and design iteration with Claude.

Normally, asking Claude to mock up a UI means one of two things: bad ASCII art, or an entire HTML/JSX page hand-written from scratch — hundreds of lines, thousands of output tokens, tens of seconds of streaming, every single time, even for a layout it's "drawn" a dozen times before.

This tool takes a different approach. Claude composes the mockup in a compact, line-oriented language (OpenUI Lang) that references a fixed, pre-registered palette of 42 real shadcn/ui primitives — buttons, cards, tables, forms, plus page-level layout primitives like Container/PageHeader/AppShell. It isn't your design system or a general-purpose exporter — it's one specific, registered shadcn/ui palette this tool ships with. A full page comes out to roughly 15–40 lines instead of hundreds, renders live in a connected browser in well under a second, and — because the model can only reference primitives that are actually registered — never contains invented markup.

What it's like to use

Ask Claude (through the MCP tools below) to mock something up — "a pricing page," "a settings screen," "a dashboard with a sidebar." It renders live in the browser tab you have open, typically in tens of milliseconds. Ask for a tweak and only the changed lines get re-sent, not the whole page, so iterating stays cheap and fast. Every version is auto-saved under a stable id, so you can rename it, switch between saved designs instantly in the sidebar, come back to one later, or delete the ones you don't want. Once you like something, ask Claude to write the actual React/shadcn code for it — see Getting code out below.

Key features

• Live, in-browser rendering — ask, watch it render in well under a second.
• Low-token by design — a full page is ~15–40 lines of a compact language, not hundreds of lines of hand-written markup.
• Always real components — every element comes from the registered shadcn/ui palette; nothing invented, nothing off-system.
• Assemblies persist automatically — rename, revisit, switch between, or delete saved designs without a separate save step.
• Code on demand — ask for the code once you're happy with something; no export button, no separate build step.

See the full design rationale and roadmap in docs/superpowers/specs/2026-07-11-genui-mockup-tool-design.md.

Setup

Prerequisites

• Node.js >=24 (see root package.json engines)

Install & build

npm install
npm run build

npm run build runs build in every workspace (packages/*, apps/*) via npm run build --workspaces --if-present — this compiles @genui/core → @genui/mcp → @genui/preview in turn.

Running it

1. Start the preview

npm run dev:preview

This root script first builds @genui/core (npm run build -w @genui/core) and then starts the preview's Vite dev server (npm run dev -w @genui/preview). The core build is required up front because the preview imports @genui/core/browser from its compiled dist/ output, not from source. Open the URL Vite prints (typically http://localhost:5173).

2. Register the MCP server with Claude

The MCP server isn't started manually — it's launched by the MCP client (Claude). Local stdio servers like this one are configured via JSON, not a URL — this is a project-scoped dev tool (paired to this repo's live preview and its data/assemblies folder), not a hosted/remote capability, so JSON config is the correct mechanism, not a legacy one.

Claude Code picks this up automatically from the root .mcp.json (relative paths are fine — Claude Code runs from the repo root):

{
  "mcpServers": {
    "genui-mockup": {
      "command": "node",
      "args": ["packages/mcp/dist/server.js"],
      "env": { "WS_PORT": "7337", "DATA_DIR": "./data/assemblies" }
    }
  }
}

Claude Desktop requires an entry in claude_desktop_config.json — but Desktop does not run from this repo's directory, so paths must be absolute, not the relative ones above:

{
  "mcpServers": {
    "genui-mockup": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/this/repo/packages/mcp/dist/server.js"],
      "env": {
        "WS_PORT": "7337",
        "DATA_DIR": "/absolute/path/to/this/repo/data/assemblies"
      }
    }
  }
}

Find your node path with which node. The config file lives at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Fully quit and relaunch Claude Desktop (not just close the window) after editing it.

Either way, a Claude session gets the five genui-mockup tools below once connected. The server spawns a WebSocket bridge on WS_PORT (7337) that the preview connects to, and persists assemblies as JSON files under DATA_DIR.

Only run the server from one client at a time — it's a single process binding port 7337, so starting it from both Claude Code and Claude Desktop simultaneously will fail on the second one.

Operational note — reload the preview after (re)starting the server

The preview's WS client connects once on mount and does not auto-reconnect. Each new MCP client session spawns a fresh packages/mcp/dist/server.js process — i.e. a fresh bridge on port 7337 — so if the server restarts after the preview tab is already open, reload the preview tab once the server is back up to pick up the new bridge connection. The preview must be open and connected for render_assembly to succeed; otherwise it correctly reports "No preview connected."

The five MCP tools

• list_primitives — returns the shadcn primitive list, param signatures, and the OpenUI Lang system prompt Claude must follow (including the lang→shadcn code mappings — see below).
• render_assembly(lang, id?, name?) — renders an OpenUI Lang assembly live in the connected web preview. Every render is auto-persisted. Omit id to start a new assembly (its id is returned — reuse it on later calls to keep editing the same design in place instead of creating a duplicate). Pass id to update that existing assembly's tree (and optionally rename it) in place. name is optional and can be set/changed on any call — that's how naming/"saving" works, there's no separate save tool.
• list_assemblies() — lists saved assemblies (id, name, createdAt, updatedAt). If a user references an existing design ambiguously by name, call this first and ask them to clarify rather than guessing which one they mean.
• get_assembly(id) — fetches a saved assembly's OpenUI Lang source by id (used for Way 2 code generation — see below).
• delete_assembly(id) — deletes a saved assembly by id. Deleting something already gone isn't an error.

Getting code out (Way 2)

There's no export button. To get real source for a saved assembly, ask Claude to get_assembly <id> and write the corresponding React/shadcn code from the returned OpenUI Lang.

The non-obvious lang→shadcn translations (e.g. OpenUI's Button variant "primary" mapping to shadcn's variant="default", since shadcn has no "primary" variant; the Table row pipe encoding; the CardHeader → CardTitle/CardDescription split) are documented directly in the system prompt returned by list_primitives, so this works even for a Claude session with only the MCP tools and no repo file access. When Claude does have repo access (e.g. Claude Code running inside this repo), it can additionally cross-check against apps/preview/src/library/renderers.tsx and apps/preview/src/library/layout-renderers.tsx directly for full fidelity.

Repo layout

• packages/core — library/palette definitions (42 primitives), OpenUI Lang parsing, the assembly store.
• packages/mcp — the MCP server (server.ts) exposing the five tools, plus the WS bridge to the preview.
• apps/preview — the Vite/React web preview that renders assemblies live via the shadcn library (atom renderers in library/renderers.tsx, page-level layout renderers in library/layout-renderers.tsx).
• docs/ — the design spec and supporting verification notes.