Canvas Edit - Live Annotation Toolbar

Floating toolbar that overlays design review findings directly on web pages in real-time. Displays numbered badges on problematic elements with severity-colored borders, hover popovers for issue details, and one-click screenshot capture.

Key features:

• Live annotations - Numbered badges appear on elements as issues are found
• Severity indicators - Color-coded badges (red/orange/blue) with counts
• Issue popovers - Click badges to see full issue details and recommendations
• Screenshot capture - Capture annotated page (toolbar hidden, annotations visible)
• Shadow DOM - Toolbar is invisible to agent-eyes screenshots
• Filtering - Filter by severity or pillar category

Breaking Changes from v1

This is a complete redesign. Canvas-edit is now a viewing tool, not an editing tool.

For live editing, use agent-canvas --with-edit instead.

Prerequisites

• Python 3.10+
• uv package manager
• Playwright browsers: playwright install chromium

Commands

bash
1SKILL_DIR=".claude/skills/canvas-edit/scripts"

Inject Annotations onto Page

bash
1# Inject toolbar with issues from JSON file
2uv run $SKILL_DIR/canvas_edit.py inject http://localhost:3000 --issues issues.json
3
4# Inject with issues from stdin
5echo '[{"id": 1, "selector": "h1", "severity": "major", "title": "Contrast issue"}]' | \
6  uv run $SKILL_DIR/canvas_edit.py inject http://localhost:3000 --issues -
7
8# Auto-screenshot on load
9uv run $SKILL_DIR/canvas_edit.py inject http://localhost:3000 --issues issues.json --screenshot

Typical Workflow: Design Review + Annotations

bash
1# 1. Run design review to find issues
2uv run .claude/skills/design-review/scripts/design_review.py review http://localhost:3000 \
3  --output-json issues.json
4
5# 2. Inject annotations onto the page
6uv run $SKILL_DIR/canvas_edit.py inject http://localhost:3000 --issues issues.json
7
8# 3. User interacts with annotations, takes screenshots, closes browser

Toolbar Controls

The floating toolbar (top-right by default) provides:

Status Display

• Issue count ("5 Issues" or "All looks good!")
• Severity badges: 🔴 blocking, 🟡 major, 🔵 minor

Actions

• 👁 Visibility: Show/hide all annotations
• ⚙ Filter: Filter by severity or pillar category
• 📸 Screenshot: Capture page with annotations (toolbar hidden)
• ↕/↔ Orientation: Toggle vertical/horizontal toolbar
• ✕ Dismiss: Remove toolbar and all annotations

Dragging

• Grab the ☰ handle to drag toolbar anywhere on screen
• Position persists during session

Annotation Badges

Each issue appears as a numbered badge on its target element:

• Position: Top-right of target element (auto-adjusts at screen edges)
• Color: Border matches severity (red/orange/blue)
• Click: Opens popover with full issue details
• Hover: Highlights the target element

Badge Popover Contents

┌─────────────────────────────────────┐
│ #3  Contrast issue         [major] │
├─────────────────────────────────────┤
│ Color contrast ratio 3.2:1 fails   │
│ WCAG AA requirement of 4.5:1       │
│                                     │
│ Pillar: Quality Craft               │
│ Check: color-contrast               │
├─────────────────────────────────────┤
│ Recommendation:                     │
│ Change text color to #1a1a1a or    │
│ background to #ffffff              │
└─────────────────────────────────────┘

Issue JSON Format

Issues can come from design-review output or be manually constructed:

json
1[
2  {
3    "id": 1,
4    "selector": ".hero-title",
5    "severity": "major",
6    "title": "Contrast ratio insufficient",
7    "description": "Text contrast 3.2:1 fails WCAG AA (4.5:1 required)",
8    "pillar": "Quality Craft",
9    "checkId": "color-contrast",
10    "recommendation": "Use darker text (#1a1a1a) or lighter background"
11  },
12  {
13    "id": 2,
14    "selector": "button.submit",
15    "severity": "minor",
16    "title": "Touch target too small",
17    "description": "Button is 36x28px, minimum is 44x44px",
18    "pillar": "Quality Craft",
19    "checkId": "touch-target-size"
20  }
21]

Required Fields

Optional Fields

Event API (Canvas Bus)

Canvas-edit integrates with other skills via the canvas bus event system.

Events Emitted

Events Subscribed

Integration Example

javascript
1// In another skill's JavaScript
2const bus = window.__canvasBus;
3
4// Listen for annotation clicks
5bus.subscribe('annotation.clicked', (payload) => {
6  console.log(`Issue ${payload.issueId} clicked: ${payload.selector}`);
7});
8
9// Add an issue programmatically
10window.__annotationLayer.addIssue({
11  id: 99,
12  selector: '.problematic-element',
13  severity: 'major',
14  title: 'New issue found'
15});

Screenshot Output

Screenshots are saved to .canvas/screenshots/ with timestamp filenames:

.canvas/screenshots/
├── 2026-01-23T15-30-45_5-issues.png
└── 2026-01-23T15-45-12_0-issues.png

Filename format: YYYY-MM-DDTHH-MM-SS_N-issues.png

Screenshots capture:

• Full page content
• All visible annotation badges
• Element highlights (if active)
• NOT the toolbar (hidden during capture)

Toolbar States

Success messages rotate randomly:

• "All looks good!"
• "Ship it!"
• "Pixel perfect"
• "Zero issues found"
• "Looking sharp!"

Keyboard Navigation

Shadow DOM Isolation

The toolbar is rendered inside a closed Shadow DOM:

• Invisible to document.querySelector()
• Excluded from agent-eyes DOM snapshots
• Hidden from screenshots (annotations remain visible)
• Page styles cannot affect toolbar appearance

Notes

• Toolbar auto-repositions to stay on screen when dragged or resized
• Badges reposition when window resizes or scrolls
• Multiple badges on the same element stack with offset
• Orphaned badges (element removed) are automatically cleaned up
• Filter state persists during session but resets on page reload