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.

| Old Functionality | New Behavior | |-------------------|--------------| | Text editing via textarea | REMOVED | | Style sliders (fontSize, etc.) | REMOVED | | "Save All to Code" button | REPLACED with screenshot capture | | contentEditable toggle | REMOVED | | edit command | REPLACED with inject command |

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

| Field | Type | Description | |-------|------|-------------| | id | number | Unique identifier | | selector | string | CSS selector for target element | | severity | string | "blocking", "major", or "minor" | | title | string | Short issue title |

Optional Fields

| Field | Type | Description | |-------|------|-------------| | description | string | Detailed explanation | | pillar | string | Design pillar category | | checkId | string | Identifier for the check that found this | | recommendation | string | Suggested fix |

Event API (Canvas Bus)

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

Events Emitted

| Event | Payload | When | |-------|---------|------| | annotation.clicked | {issueId, selector, severity} | User clicks a badge | | screenshot.requested | {directory, filename, issueCount} | Screenshot button clicked | | screenshot.captured | {path, issueCount} | Screenshot saved (Python-side) | | annotations.cleared | {} | Dismiss button clicked | | filter.changed | {severity, pillars} | Filter settings changed |

Events Subscribed

| Event | Action | |-------|--------| | review.started | Show "Scanning..." state | | review.issue_found | Add badge for new issue | | review.completed | Show final count or success message | | capture_mode.changed | Hide/show toolbar for agent-eyes |

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

| State | Display | Trigger | |-------|---------|---------| | Issues Found | "N Issues" + severity badges | Default when issues > 0 | | All Clear | "✓ All looks good!" (randomized) | Zero issues after review completes | | Scanning | "⟳ Analyzing..." with spinner | During review.started |

Success messages rotate randomly:

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

Keyboard Navigation

| Key | Action | |-----|--------| | Tab | Navigate toolbar controls | | 1-9 | Jump to badge by number | | Arrow keys | Navigate between visible badges | | Enter/Space | Activate focused button/badge | | Escape | Close open popover |

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