design-canvas-plugin-github-issues

GitHub Issues plugin for Design Canvas.

Pin design annotations directly to UI elements and automatically sync them as GitHub Issues — bridging the gap between visual design review and actionable development work.

Install

npm install design-canvas-plugin-github-issues

Usage

Add to your .designcanvas.json:

{
  "plugins": {
    "github-issues": { "enabled": true }
  }
}

Features

Element Annotation

• Visual element picker — click "Annotate element" to select any DOM element on the page
• Pin notes to CSS selectors — annotations are anchored to specific elements and persist across reloads
• Numbered markers — pinned annotations display as numbered blue badges on the page, repositioning on scroll/resize
• Click-to-highlight — clicking a note card scrolls to and outlines the target element on the page
• Element screenshots — automatically captures a screenshot of the annotated element (when screenshot service is available)
• Rich element context — captures tag name, classes, ID, dimensions, position, computed styles, DOM path, ARIA attributes, inner text, and outer HTML

GitHub Issues Integration

• Auto-create issues — every annotation is automatically filed as a GitHub Issue with the design-canvas label
• Rich issue body — issues include the annotation text, element screenshot, a full details table (selector, dimensions, DOM path, styles), and HTML snippet
• Metadata embedding — issues contain a hidden <!-- dc-meta --> comment for round-trip sync
• Two-way sync — on activation, fetches existing GitHub Issues and merges them with local notes (remote wins on conflict)
• Manual issue creation — open a detailed issue form with editable title, assignee picker from repo collaborators, and optional Copilot assignment
• Close issues — close a GitHub Issue directly from the more-actions menu
• Assign to me — self-assign an issue from the note card context menu
• Assign Copilot — optionally assign GitHub Copilot to implement the fix when creating an issue

GitHub Repository Connection

• Auto-detect — detects the connected GitHub repo via gh CLI on activation
• Retry detection — re-run auto-detect if the CLI wasn't ready at startup
• Manual connect — enter an owner/repo or full GitHub URL to connect manually
• Create new repo — quick link to create a new GitHub repo when none exists
• Status indicators — clear messaging for missing gh CLI, unauthenticated state, or no repo detected

Copilot AI Integration

• Draft annotations — describe your concern and Copilot expands it into a clear, actionable annotation using full element context (DOM path, styles, dimensions, text content)
• Fix with Copilot — generate a local code fix from any annotation; previews changes in-editor before committing
• Review & revert — accept the Copilot fix and create a Draft PR, or revert the change with one click
• Onboarding modal — shows a setup guide if Copilot is not yet authenticated

Draft PR Workflow

• Create Draft PR — after accepting a Copilot fix, commits changes to a dc-fix/* branch and opens a Draft PR linked to the original issue
• "In Review" tab — notes with linked PRs move to a dedicated tab showing pending reviews
• Auto-cleanup on merge — polls every 60 seconds; when a PR merges, the linked issue is closed and the note is removed automatically

Real-Time Collaboration

• Multi-tab sync — notes sync across browser tabs via SQLite-backed shared notes service
• Remote change listener — merges incoming changes from other connected sessions in real time
• Conflict resolution — uses timestamp-based last-write-wins merging

Panel UI

• Tabbed interface — "Open" tab for active annotations, "In Review" tab for notes awaiting PR merge
• Filter: Mine — toggle to show only notes assigned to the current user
• Author attribution — displays avatar, name, and timestamp on each note card
• Assignee avatars — stacked avatar display for assigned collaborators
• More-actions menu — context menu per note with: Go to GitHub Issue, Assign to me, Fix with Copilot, Close Issue / Delete
• Status bar — shows annotation count and connected repo (or "local only" / "synced" status)
• Dark/light theme — fully themed based on Design Canvas dark mode setting

Export & Sharing

• Export as Markdown — copies all annotations grouped by page URL in a structured Markdown format (with embedded metadata comments for re-import)
• Import from Markdown — parse Markdown back into notes, preserving IDs and timestamps
• Clipboard integration — one-click copy to clipboard via footer button or status bar action

Keyboard Shortcuts

| Shortcut | Action | | --- | --- | | Alt+Shift+N | Start element picker | | Alt+Shift+E | Export annotations as Markdown | | Cmd/Ctrl+Enter | Submit annotation (when compose form is focused) | | Escape | Cancel annotation |

Plugin Commands (Event Bus / MCP)

| Command | Description | | --- | --- | | command:get-notes | Returns all notes with IDs, text, URLs, selectors, timestamps, and issue links | | command:export-markdown | Returns the full Markdown export | | command:add-note | Programmatically add a note (text required, selector and url optional) | | command:delete-note | Delete a note by ID |

Copilot Skills

The plugin registers two skills for natural-language invocation:

• Annotate Page Elements (dc-annotate-page) — triggered by "annotate this", "leave a note", "add a comment on this element", "mark this for review"
• Export Design Annotations (dc-export-annotations) — triggered by "export notes", "share annotations", "generate design review report"

Lifecycle

• activate — initializes GitHub sync, real-time collaboration, markers, PR polling, and renders the panel
• suspend — hides page markers when the plugin panel is collapsed
• deactivate — cleans up event listeners, markers, timers, and subscriptions
• getHandoffContext — provides structured note data for cross-plugin communication

Prerequisites

1. Design Canvas

This plugin requires Design Canvas >=0.1.0 as the host environment.

2. GitHub CLI (gh)

Required for GitHub Issues integration (create, sync, close, assign).

# macOS
brew install gh

# Windows
winget install --id GitHub.cli

# Linux (Debian/Ubuntu)
sudo apt install gh

After installing, authenticate:

gh auth login

3. Copilot CLI Extension (optional)

Required for "Draft with Copilot" and "Fix with Copilot" features.

gh extension install github/gh-copilot
gh auth refresh -s copilot

4. Node.js

Node.js >=18 is required to run Design Canvas and its plugins.

# macOS
brew install node

# Windows
winget install --id OpenJS.NodeJS.LTS

# Or via nvm (any platform)
nvm install --lts

Verify Setup

node --version   # >= 18
gh --version     # >= 2.x
gh auth status   # logged in