Agent Canvas

Spec-driven design QA for AI agents

Review UI implementations against design specs, generate annotated screenshots with issues marked, and create actionable fix lists. Works with any AI agent that supports skills (Copilot, Claude Desktop, Cursor, etc.) on any web page.

---

Quick Start

Copy and paste this into your AI agent:

Install Agent Canvas for design review. Run these commands:

# Download skills from GitHub (sparse clone - only .claude/skills/)
git clone --depth 1 --filter=blob:none --sparse https://github.com/edrouhardmicrosoft/canvas-cli-demo.git /tmp/agent-canvas-install
git -C /tmp/agent-canvas-install sparse-checkout set .claude/skills

# Copy to your project
mkdir -p .claude/skills
cp -r /tmp/agent-canvas-install/.claude/skills/* .claude/skills/
rm -rf /tmp/agent-canvas-install

# Install dependencies (use "temporary" scope - minimal footprint)
uv run .claude/skills/agent-canvas-setup/scripts/check_setup.py install --scope temporary

Want multi-agent support? Add --agents to install for Copilot, Cursor, etc:

uv run .claude/skills/agent-canvas-setup/scripts/check_setup.py install --scope temporary --agents claude,copilot

Supported agents: claude (default), codex, copilot, cursor, windsurf, aider

Once setup completes, try:

Review the design at http://localhost:3000

---

Customizing Your Reviews (CRITICAL)

By default, Agent Canvas reviews against generic design principles. For meaningful reviews, give it YOUR design context:

Option 1: Custom Design Spec (Recommended)

Create a DESIGN-SPEC.md in your project root:

your-project/
├── DESIGN-SPEC.md    ← Agent Canvas auto-detects this
├── src/
└── ...

Your spec can define brand colors, typography rules, spacing standards, component patterns—anything your team cares about. See specs/README.md for the full format.

Example DESIGN-SPEC.md:

---
name: My Project Design Spec
version: "1.0"
extends: default.md
---

# My Project Design Spec

## Brand Guidelines

### Checks

#### brand-colors
- **Severity**: major
- **Description**: Uses approved brand colors only
- **Approved colors**:
  - `#0078D4` - Primary Blue
  - `#1B1B1B` - Text Black
  - `#FFFFFF` - White
- **How to check**: Extract colors from elements, compare against approved list

#### typography
- **Severity**: minor
- **Description**: Uses approved font families
- **Approved fonts**:
  - Inter
  - SF Pro
- **How to check**: Check computed font-family on text elements

Option 2: Visual References

Drop reference images (exported from Figma, screenshots from prod, etc.) into:

.claude/skills/design-review/imgs/
├── homepage.png
├── settings-page.png
└── mobile-nav.png

Then ask your agent:

Compare http://localhost:3000 against the homepage.png reference

Option 3: Figma MCP (If Connected)

If your agent has Figma MCP connected, it will automatically use it for comparisons:

Compare http://localhost:3000 against the Homepage frame in our Figma file

Note: Without Figma MCP, export frames as PNG and use Option 2.

---

What You Can Do

Ask your agent...	What happens
"Check http://localhost:3000"	Interactive mode (default) - Opens browser with auto-scan and badges
"Review the design at [url]"	Headless review - checks against spec, lists issues by severity
"Audit [url] and create a task list"	Creates DESIGN-REVIEW-TASKS.md with fix priorities
"Compare [url] to homepage.png"	Visual diff against reference image
"Create an issue for this bug"	GitHub Issue - Click "Create Issue" button to file bugs with context

---

Example Queries

Different phrases trigger different modes. Use the one that fits your workflow:

Interactive Mode (Default)

Opens a browser with automatic issue scanning and visual badges on elements with problems. Press N to navigate through issues.

This is the default mode — any query that doesn't explicitly say "review", "audit", or "compare" will open the browser.

Check http://localhost:3000
Show me http://localhost:3000
Open http://localhost:3000
Look at the design at http://localhost:3000
http://localhost:3000

Review Mode (Headless, for CI/Automation)

Runs in the background without opening a browser. Use explicit keywords to trigger.

Review http://localhost:3000 against spec
Audit http://localhost:3000
Run compliance check on http://localhost:3000
Generate task list for http://localhost:3000

Compare Mode (Visual Diff)

Compares current page against a reference image or Figma frame.

Compare http://localhost:3000 to homepage.png
Check http://localhost:3000 against the mockup
Compare the current design to the reference
Diff http://localhost:3000 against settings.png

---

Workflows

REVIEW ──▶ FIX ──▶ VERIFY          (Design QA)
PICK ──▶ EDIT ──▶ APPLY ──▶ VERIFY (Live Editing)

Design QA Workflow

1. Review - Find issues:

   Review http://localhost:3000 and generate a task list
   

2. Fix - Your agent (or you) fixes the issues

3. Verify - Re-run review to confirm:

   Review http://localhost:3000 again
   

Live Editing Workflow

Pick an element on http://localhost:3000 to edit

1. Browser opens → click elements to select
2. Edit in floating panel → changes apply live
3. Click "Save All to Code" → agent updates your source files

GitHub Issue Creation

Create GitHub issues directly from the browser with full context:

Check http://localhost:3000

1. Browser opens with picker overlay
2. Select elements related to the bug/issue
3. Click "Create Issue" button (bottom-left)
4. First time: Enter your GitHub repo (owner/repo format)
5. Fill in title and description
6. Click Create → Issue created with:
   • Selected element details
   • Page URL
   • Screenshots (uploaded to Gist)

Requirements:

• GitHub CLI (gh) installed and authenticated
• Or: Falls back to opening GitHub web interface

Disable issue button: Use --no-issue flag:

uv run .claude/skills/agent-canvas/scripts/agent_canvas.py pick http://localhost:3000 --no-issue

---

Skills Reference

Skill	What it does
design-review	Reviews UI against specs, generates annotated screenshots
agent-canvas-setup	Installs dependencies (Python, Playwright, etc.)
agent-eyes	Takes screenshots, runs accessibility scans
agent-canvas	Interactive element picker
canvas-issue	GitHub issue creation with element context and screenshots
canvas-edit	Annotation toolbar overlay
canvas-apply	Converts visual edits to code changes
canvas-verify	Before/after visual comparison

---

Default Review Criteria

Without a custom spec, Agent Canvas checks these pillars:

Pillar	Focus
Frictionless Insight to Action	Task efficiency, clear navigation, single primary actions
Progressive Clarity	Smart defaults, progressive disclosure, contextual help
Quality Craft	Accessibility, contrast, keyboard navigation, touch targets
Trustworthy Building	AI disclaimers, error handling, secure defaults

See the full default spec: specs/default.md

---

Session Artifacts

Reviews are saved to .canvas/reviews/<sessionId>/:

session.json       # Full event log
report.json        # Structured issue data
screenshot.png     # Original screenshot
annotated.png      # Screenshot with issues marked
diff.png           # Visual diff (compare mode)

---

Troubleshooting

Browser doesn't open?

Run agent-canvas-setup to check dependencies

"uv not found" or "Python not found"? Your agent will guide you through installing prerequisites.

Reviews too generic? Add a DESIGN-SPEC.md to your project root with your actual design standards.

---

Project Structure

.claude/skills/
├── design-review/         # Main review skill
│   ├── specs/             # Design spec files
│   │   └── default.md     # Default review criteria
│   └── imgs/              # Reference images go here
├── agent-canvas-setup/    # Dependency installer
├── agent-eyes/            # Screenshots & a11y
├── agent-canvas/          # Element picker
├── canvas-issue/          # GitHub issue creation
├── canvas-edit/           # Annotation overlay
├── canvas-apply/          # Code generator
├── canvas-verify/         # Verification
└── shared/                # Shared utilities

---

For AI Agent Developers

See docs/AGENTS.md for:

• Skill trigger phrases
• Command reference
• Output parsing
• Error handling