Canvas Edit - Live Annotation Toolbar

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

SKILL_DIR=".claude/​skills/​canvas-edit/​scripts"

Inject Annotations onto Page

# Inject toolbar with issues from JSON file
uv run $SKILL_DIR/​canvas_edit.py inject http://localhost:3000 --issues issues.json

# Inject with issues from stdin
echo '[{"id": 1, "selector": "h1", "severity": "major", "title": "Contrast issue"}]' | \
  uv run $SKILL_DIR/​canvas_edit.py inject http://localhost:3000 --issues -

# Auto-screenshot on load
uv run $SKILL_DIR/​canvas_edit.py inject http://localhost:3000 --issues issues.json --screenshot

Typical Workflow: Design Review + Annotations

# 1. Run design review to find issues
uv run .claude/​skills/​design-review/​scripts/​design_review.py review http://localhost:3000 \
  --output-json issues.json

# 2. Inject annotations onto the page
uv run $SKILL_DIR/​canvas_edit.py inject http://localhost:3000 --issues issues.json

# 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:

[
  {
    "id": 1,
    "selector": ".hero-title",
    "severity": "major",
    "title": "Contrast ratio insufficient",
    "description": "Text contrast 3.2:1 fails WCAG AA (4.5:1 required)",
    "pillar": "Quality Craft",
    "checkId": "color-contrast",
    "recommendation": "Use darker text (#1a1a1a) or lighter background"
  },
  {
    "id": 2,
    "selector": "button.submit",
    "severity": "minor",
    "title": "Touch target too small",
    "description": "Button is 36x28px, minimum is 44x44px",
    "pillar": "Quality Craft",
    "checkId": "touch-target-size"
  }
]

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

// In another skill's JavaScript
const bus = window.__canvasBus;

// Listen for annotation clicks
bus.subscribe('annotation.clicked', (payload) => {
  console.log(`Issue ${payload.issueId} clicked: ${payload.selector}`);
});

// Add an issue programmatically
window.__annotationLayer.addIssue({
  id: 99,
  selector: '.problematic-element',
  severity: 'major',
  title: 'New issue found'
});

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