design-canvas-plugin-checks

A Design Canvas plugin for running project quality checks, binding them to lifecycle hooks, and managing a shared check library across projects.

Features

Core

• Run checks — Execute bash-based validation scripts against your project (type checking, lint, security, etc.)
• Hook bindings — Bind checks to lifecycle events (postToolUse, preToolUse, sessionStart, userPromptSubmitted, stop) so they run automatically
• Enable/disable — Toggle individual checks on/off without removing them
• Severity levels — Categorize checks as critical, warning, or info with visual indicators
• Dependencies — Define check ordering with dependsOn — dependent checks are skipped when prerequisites fail
• Debounced triggers — Hook-bound checks are debounced (2.5s) to avoid running on every keystroke

AI-Powered

• ✨ Suggest Checks — Copilot analyzes your project context and suggests tailored checks across six domains:
  • Visual Design — color contrast, typography scale, spacing consistency, token coverage
  • Accessibility — WCAG 2.2 compliance, ARIA correctness, focus management, motion safety
  • UX Heuristics — Nielsen's 10 mapped to deterministic signals (vague labels, missing loading states, competing CTAs)
  • Cognitive Load — Miller's Law (nav grouping), Hick's Law (choice reduction), progressive disclosure
  • Security — OWASP Top 10 signals (hardcoded secrets, XSS vectors, dependency vulnerabilities, CORS)
  • Privacy — GDPR/CCPA compliance (PII in logs, consent gating, data minimization, fingerprinting)
• ✨ Explain failures — Copilot analyzes error output and suggests fixes
• ✨ Fix PR — Generate a draft PR that addresses a failing check

Collaboration

• 📚 Shared Library — Publish checks to a team library and install them into any project
• 📦 Check Packs — Curated bundles (a11y, ux-heuristics, data-viz, security, etc.) — install an entire category at once
• ↑ Share / ↓ Import — Export check definitions as JSON to clipboard; import from clipboard into another project
• ⚑ File Issues — Create GitHub issues from failures with screenshots, assign Copilot for automated fixes
• Batch issue filing — File issues for all failed checks at once

UX

• Filter by tag — Focus on specific check categories
• Show failed only — Toggle to see only failing checks
• Severity grouping — Collapsible groups sorted critical → warning → info
• Run history & deltas — "↑ fixed" / "↓ regressed" indicators show what changed since last run
• Progress bar — Visual progress during "Run All"
• Keyboard navigation — Arrow keys + Enter to navigate and run checks
• Copy output — One-click copy of check output
• Export results — Full results as JSON for CI integration
• 30s timeout — Automatic timeout with visual indicator for hung checks
• Watch mode — Re-runs hook-bound checks on file changes
• SSE live updates — Real-time refresh when checks change on the server (with reconnection backoff)

Installation

npm install design-canvas-plugin-checks

Peer dependency

npm install @design-canvas/toolbox

Usage

Register the plugin in your Design Canvas configuration:

import { checksPlugin } from 'design-canvas-plugin-checks';

export default {
  plugins: [checksPlugin],
};

The plugin will appear in the Design Canvas toolbar with the ✓ icon.

Check Format

Checks are bash scripts stored on the DC server. Each check receives the project root as $1 and exits 0 on pass, non-zero on fail.

#!/usr/bin/env bash
set -euo pipefail
PROJECT_DIR="$1"
cd "$PROJECT_DIR"

# Your validation logic here
# stdout/stderr is captured and shown to the user

echo "✅ Check passed"

Check Schema

| Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | Unique kebab-case identifier | | description | string | Yes | What the check validates (shown in UI) | | command | string | Yes | Full bash script content | | severity | "critical" \| "warning" \| "info" | No | Default: "warning" | | triggers | string[] | No | ["manual"] and/or hook events | | tags | string[] | No | Categorization tags | | enabled | boolean | No | Default: true | | dependsOn | string[] | No | Check IDs that must pass first |

API Endpoints

The plugin communicates with the Design Canvas server:

| Endpoint | Method | Description | |----------|--------|-------------| | /__dc/checks | GET | List all checks | | /__dc/checks | POST | Create a new check | | /__dc/checks/:id/run | POST | Run a specific check | | /__dc/checks/:id | PATCH | Update check (e.g., toggle enabled) | | /__dc/checks/:id | DELETE | Delete a check | | /__dc/checks/events | GET (SSE) | Server-sent events for live updates | | /__dc/library/checks | GET | Browse shared library | | /__dc/library/checks | POST | Publish a check to library | | /__dc/library/packs | GET | List available check packs | | /__dc/context | GET | Project context (file tree, deps) | | /__dc/design-tokens | GET | Active design tokens | | /__dc/components | GET | Registered components |

Plugin Commands (MCP / postMessage)

Available for external automation:

| Command | Args | Returns | |---------|------|---------| | run-all | none | Array of { id, passed, output, timestamp, duration } | | run-check | { id: string } | Single result object or null | | export-results | none | Array of all current results |

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Alt+Shift+C | Run All checks | | ↑ / ↓ | Navigate check cards | | Enter | Run focused check |

Sharing Checks Across Projects

Option 1: Shared Library (via DC server)

1. Click ↑ on any check card to publish it to the shared library
2. In another project, click 📚 → browse and ↓ Install individual checks
3. Use Check Packs tab to install curated bundles

Option 2: Export/Import (clipboard JSON)

1. Click ↑ Share in the footer to copy all check definitions as JSON
2. In another project, copy the JSON to clipboard and click ↓ Import

Option 3: Copilot Suggestions

Click ✨ Suggest in any project — Copilot will generate checks tailored to that specific codebase based on its dependencies, file structure, and patterns.

Skills (Copilot Integration)

The plugin registers three skills for natural language interaction:

| Skill | Trigger phrases | |-------|----------------| | dc-run-checks | "run checks", "validate the project", "check for errors" | | dc-check-hooks | "set up check hooks", "run checks after edits", "automate validation" | | dc-create-check | "create a check", "add validation for", "I want a check that verifies" |

Development

# Install dependencies
npm install

# Build
npm run build

# Type check + build + verify (all 7 sections)
npm run verify

Project Structure

src/
  index.ts       # Plugin source (activate, deactivate, skills, render)
  svg.d.ts       # SVG module declarations
tsup.config.ts   # Build config with import rewriting
dist/
  index.js       # Built ESM output
  index.d.ts     # Type declarations

Architecture

• Shadow DOM safe — All styles are inline; no document.head injection
• ESM — Built as ES module with @design-canvas/toolbox as external
• Strict TypeScript — strict: true with full type coverage
• AbortController — All fetches are cancellable; cleanup on deactivate
• SSE reconnection — Exponential backoff with jitter (3-30s)
• Debounced hooks — 2.5s trailing debounce prevents check spam

License

MIT

Install

npm install design-canvas-plugin-checks

Usage

Add to your .designcanvas.json:

{
  "plugins": {
    "checks": { "enabled": true }
  }
}