mockup-canvas

# mockup-canvas

> mockup-canvas is a free, open-source (MIT) Claude Code plugin by chrisjo-dev, also usable from OpenAI Codex, made of three skills that cover plan, review, and build. mockup-canvas has your AI agent draw screen mockups as plain HTML files and lays them out on a local, Figma-like canvas where you pan, zoom, arrange, link with flow arrows, and approve them. mockup-review has an agent review those screens and leave severity-tagged findings as comments on the exact artboards. mockup-to-code turns approved screens into real code in your app and visually compares each running route with its mockup (pixel diff with side-by-side and diff images) until only intentional differences remain. It runs on the Python standard library with no pip dependencies and uses Google Chrome (or Chromium/Edge) only to render and capture PNGs.

## Key facts

- Live demo (read-only, pan and zoom only): https://chrisjo-dev.github.io/mockup-canvas/ shows the six-screen TrailMate example canvas, exported with `canvas export`.
- Three skills, one CLI: `mockup-canvas` (draw mockups and record approvals), `mockup-review` (review boards with `[must]`, `[should]`, `[could]` comments and a `review.md` report; never edits boards or sets status), `mockup-to-code` (build approved boards in the app, compare each route with its board, record the route and files). Flow: draw, review, approve, build, compare. Only boards the user approved are built.
- Install as a Claude Code plugin: `/plugin marketplace add chrisjo-dev/mockup-canvas`, then `/plugin install mockup-canvas@mockup-canvas`.
- Manual install for Claude Code and Codex: `git clone https://github.com/chrisjo-dev/mockup-canvas.git`, then `./install.sh` (links every skill into `~/.claude/skills` and `~/.codex/skills`; `--claude`, `--codex`, `--dry-run` are available). `install.sh` needs a POSIX shell.
- In Codex, call the skills with `$mockup-canvas`, `$mockup-review`, or `$mockup-to-code`, for example `Use $mockup-canvas to draw the sign-up flow.`
- The CLI is one Python 3 file of about 5,100 lines (Python 3.8+, standard library only) with 19 commands: serve, roots, new, add, group, render, check, overview, export, link, status, artifact, snap, compare, impl, comment, trash, restore, pins.
- `snap <url> --out FILE.png [--size ...] [--wait MS] [--full-page]` screenshots a running app page (http or https) at an exact size. `render --full-page` captures a board's whole scroll height. `add` with a new `--size` resizes a registered board.
- `compare <idea dir> <file> (--url URL | --png FILE)` renders the board at its registered size, captures the app at the same size, and writes `board.png`, `app.png`, `diff.png`, `side.png`, and `report.json` (with `mismatch_percent`) to `<idea>/compare/<board id>/`. A pixel differs when any channel differs by more than `--threshold` (default 24 of 255). `--ignore-top N`, `--ignore-bottom N`, and `--align-top N` handle fake status bars and home indicators drawn on boards; `--wait MS` defaults to 3000. The percentage is a guide; the images are the evidence.
- `impl <idea dir> <file> --route PATH --file PATH` records which route and files implement a board; `impl <idea dir> [--strict]` lists approved boards and whether each is implemented (`--strict` exits 1 when one is missing). `comment <idea dir> <file> TEXT [--by NAME]` adds a review comment (`--clear` removes them, no text lists them); `--at x,y[,w,h]` or `--el SELECTOR` pins it to a spot or an element. `pins <idea dir> [file] [--json] [--all]` lists open pins with the element each points at (CSS selector, text, short HTML) and a cropped PNG; `--resolve N --note TEXT` closes one.
- The canvas shows a violet `built` badge on implemented boards and a comment count that opens a comment panel. Pins: press `C` (or Point in the toolbar), click a spot or drag an area on a board, and write a note; the server finds the element under it with its own headless Chrome, crops that spot, and moves the pin with its element when the board changes. Copy for AI copies a line naming the board, pin, and element. Pins are local only (not in share mode). With many boards it keeps live pages only near the view, shows cached PNG thumbnails when zoomed out (below about 30 to 40%) when served, never shows a board it has painted as a blank card again, and batches updates once per animation frame.
- `canvas serve` binds to `127.0.0.1` on port 4400 by default. `http://localhost:4400/` is a dashboard of every registered project: idea cards with board thumbnails, a status meter, comment, built, and `N new` counts, status filters (needs decision, has comments, approved but not built, built), search and a command palette (`/` or `Cmd+K`), adding, finding, renaming, and removing projects, missing folder warnings, light and dark themes, and a phone layout. `/<project>/<idea>/` is one idea's canvas, and `#<board>` fits one board. `serve <design dir>` serves one design folder at `/<idea>/`; `--port N` picks another port. In the background: `nohup python3 <skill-dir>/scripts/canvas.py serve > /tmp/mockup-canvas.log 2>&1 &`, stopped with `lsof -ti tcp:4400 -sTCP:LISTEN | xargs kill`. The tool itself makes no outbound requests; artboards may load Google Fonts, the only external resource the skill allows.
- Share mode (`serve <design dir> --share`) is opt-in: it binds to the local network, requires a random token, is read-only unless `--share-edit` is passed, and stops after `--minutes` (1 to 240, default 30). In registry mode, `serve --share --project NAME` shares one project; a registry share is frozen to the projects registered at start and hides folder paths. Traffic is plain HTTP.
- Server hardening: requests whose `Host` header is not this server get 421 (DNS rebinding); layout saves and registry changes need a same-origin `Origin` and exactly `application/json`; artboards are served with `Content-Security-Policy: sandbox` and shown in sandboxed iframes; connections time out after 15 s and are capped at 64.
- `export <idea dir> <output dir>` refuses an output folder that is, is inside, or contains the idea folder, and skips symlinks pointing outside the idea folder.
- Idea folder layout: `<project>/design/<idea>/` with `canvas.json` (layout, groups, flow arrows, status and notes, impl records, comments), `boards/*.html` (one screen per file), `shared/tokens.css`, `assets/`, `render/` (generated PNGs), `compare/` (compare output), and `review.md` (the mockup-review report).
- Artboard size presets: mobile 390x844, tablet 768x1024, desktop 1440x900, or any `WxH`.
- Approvals are recorded with `canvas status <idea dir> <file> approved --note "..."`; old screens are kept in an `old drafts` group as rejected instead of being deleted. When the user asks for a delete, `canvas trash` moves an idea or a board to `design/.trash/` (the dashboard and canvas do the same, with Undo), and `canvas restore` puts it back.
- App code comes only after approval: mockup-to-code implements approved boards in the app's own framework and tokens and reports what it verified versus what it could not.

## Docs

- [README](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/README.md): overview, dashboard, quick start, running the server, CLI reference, security model, FAQ
- [Skill guide](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/docs/skill.md): every workflow step of the three skills with commands, rules, and customization
- [mockup-canvas SKILL.md](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/skills/mockup-canvas/SKILL.md): the instructions the agent loads to draw mockups
- [mockup-review SKILL.md](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/skills/mockup-review/SKILL.md): the instructions for reviewing mockups
- [mockup-to-code SKILL.md](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/skills/mockup-to-code/SKILL.md): the instructions for building approved mockups and comparing them with the app
- [CHANGELOG.md](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/CHANGELOG.md): changes per release
- [CONTRIBUTING.md](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/CONTRIBUTING.md): setup, tests, design rules, commit style, and how to propose UI changes
- [SECURITY.md](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/SECURITY.md): threat model and vulnerability reporting

## Code

- [canvas.py](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/skills/mockup-canvas/scripts/canvas.py): the CLI and local canvas server
- [install.sh](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/install.sh): manual installer for Claude Code and Codex
- [plugin.json](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/.claude-plugin/plugin.json): Claude Code plugin manifest

## Examples

- [TrailMate example](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/examples/trailmate/canvas.json): a six-screen sample idea with shared tokens, flow arrows, and approval marks. From the repository root, run `python3 skills/mockup-canvas/scripts/canvas.py serve examples` and open `http://127.0.0.1:4400/trailmate/`.

## Translations

- [README in Korean](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/README.ko.md)
- [README in Simplified Chinese](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/README.zh-CN.md)
- [README in Japanese](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/README.ja.md)
- Skill guide: [Korean](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/docs/skill.ko.md), [Simplified Chinese](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/docs/skill.zh-CN.md), [Japanese](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/docs/skill.ja.md)

## Optional

- [CITATION.cff](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/CITATION.cff): how to cite mockup-canvas
- [lessons.md](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/skills/mockup-canvas/references/lessons.md): log of approved skill improvements (mockup-review and mockup-to-code keep their own under `references/`)
- [LICENSE](https://raw.githubusercontent.com/chrisjo-dev/mockup-canvas/main/LICENSE): MIT License, Copyright (c) 2026 chrisjo-dev