canvas-ui

canvas-ui

A UI design skill for AI coding agents. It explores three genuinely different design directions, puts them side by side on a live comparison canvas, lets you tune them with real design tokens, and then refines the chosen one against real screenshots until it holds up. Works in Claude Code, Codex, Gemini CLI, Cursor, OpenCode, and any model that can read a prompt (DeepSeek, GPT, Gemini web).

One brief (a field-recording library), three directions from different engines: a tape-log workspace, a single recording as hero, a place-first atlas. Built, linted and captured by the bundled tools. Source in examples/fieldnote.

Live demo → Four example rounds you can open on the real canvas: squint, go blind, tune the dials, and pick.

Why it's different

Most "design skills" are a long style guide. canvas-ui is a workflow plus tools, and every step produces something you can check:

Install

Any agent that supports skills:

npx skills add riz007/canvas-ui

Or from a clone:

git clone https://github.com/riz007/canvas-ui && cd canvas-ui
./install.sh claude            # ~/.claude/skills/canvas-ui
./install.sh agents            # ~/.agents/skills (Codex + Gemini CLI)
./install.sh cursor --project ~/code/my-app
./install.sh all --link        # symlink everything (for hacking on the skill)

./install.sh agents installs once into ~/.agents/skills, which both Codex and Gemini CLI read. Don't also install codex or gemini on top, or the skill is listed twice.

Requirements for the tools: Node 20+ (22+ recommended) and Chrome, Chromium, Edge or Brave. The workflow itself needs nothing.

Use

Just ask:

• "Use canvas-ui to explore three directions for our booking app's home screen."
• "Redesign this dashboard. Show me options on the canvas first."
• "Recreate this screenshot as HTML, then add a mobile layout."
• "Review our pricing page with canvas-ui. Don't change anything."

What happens:

1. Directions in words. The agent names the category and peers, sets the five tone dials with evidence, and writes three direction cards from different engines (a material in a setting, a scene, a character, a movement, another medium's grammar, or rule-breaking). It sends you 3–4 lines each with a recommendation, and asks: build one, or see all three?
2. The canvas. If you want to see them, it builds three first screens on generated tokens and opens the canvas. You compare, squint, tune, take notes, and Pick. Paste the copied text back.
3. Build. Your token tweaks go into the card, and the full UI gets built: real hierarchy, real states, three echoing motions.
4. Evidence. Desktop + mobile screenshots, full page, 200% details, motion frame strips, the lint. Every fix item is fixed; every tell is removed or justified in writing.
5. Independent review. A fresh subagent that never saw the build scores it on a five-line rubric (direction, hierarchy, type & color, craft, specificity), and a blind UX walkthrough checks the main flow without being told the path.
6. Delivery notes: chosen direction and why, what's not done, motions, review scores, copy removed, tells kept and why, where the evidence lives.

Micro-edits ("make the save button green") skip all of this.

Tools

node scripts/tokens.mjs  examples/fieldnote/r1 --specimen       # cards → tokens.css (+ specimen page)
node scripts/canvas.mjs  examples/fieldnote/r1 --open           # build and open the canvas
node scripts/canvas.mjs  examples/fieldnote/r1 --serve 4817     # or serve it for an agent's browser pane
node scripts/shoot.mjs   examples/fieldnote/r1 --sheet --squint # capture all, contact sheet, squint test, lint
node scripts/shoot.mjs   page.html --size desktop,mobile --full
node scripts/shoot.mjs   page.html --steps 'open: click .menu; filled: type #q "rain"' --size mobile
node scripts/shoot.mjs   page.html --compare reference.png --size 1280x800   # recreation diff
node scripts/shoot.mjs   page.html --steps "click .play" --frames 8          # motion strip

Each script has --help. Details: references/tools.md.

What's inside

SKILL.md                    the workflow (what the agent reads)
references/
  direction.md              category & benchmarks, tone dials, engines, color, cards, divergence test
  tokens.md                 the token engine and how to use tokens in Tailwind / CSS / existing systems
  visual-language.md        hierarchy, type, color, controls, subtraction
  layout.md                 persuasion skeletons, workspace layouts, viewports, exact recreation
  motion.md                 three basic motions, feel → springs, durations, scroll
  canvas.md                 building candidates, manifest, reading a pick
  review.md                 reviewer dispatch, /10 rubric, blind UX walkthrough
  slop.md                   lint rules, AI-default tells, tells the lint can't see
  tools.md · workspace.md
scripts/                    tokens.mjs · canvas.mjs · shoot.mjs · lib/ (token engine, CDP, lint)
assets/canvas.html          the canvas template
templates/direction.json    the direction card schema, annotated
adapters/                   Codex · Gemini CLI · Cursor · portable prompt
examples/                   four complete direction rounds, with shots (tidepool is agent-generated)
site/                       the demo site (index.html + build.mjs → _site/)
tests/                      node --test (token guarantees, canvas build, lint on a real browser)

Develop

npm test            # 11 tests; the browser test is skipped if no Chrome is found
npm run example     # regenerate the example's tokens and open its canvas
npm run site        # build the demo site into _site/ (deployed to GitHub Pages from main)

Pro features are planned; see ROADMAP.md. The core skill will stay MIT and complete on its own.

License

MIT