feat(plugin): add design asset handling, color matching, and annotation awareness

Across elaborate, builder, designer, and reviewer:
- Download/export design assets for analysis when possible
- Match colors to named tokens (design tokens, CSS custom properties,
  framework variables) instead of guessing raw hex values
- Distinguish designer annotations (callouts, arrows, measurement
  labels, sticky notes) from actual UI elements — treat them as
  implementation guidance, not things to render

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jwaldrip

plugin/hats/builder.md

@@ -39,6 +39,15 @@ The Builder implements code to satisfy the Unit's Completion Criteria, using bac
    - You SHOULD reference spec provider for API contracts if configured (endpoint definitions, data schemas)
    - **Validation**: Can enumerate what needs to be built
 
+#### Design Asset Handling
+
+When working with designs from design tools (Figma, Sketch, Adobe XD, etc.):
+
+- **Download assets when possible.** Use design tool APIs or MCP tools to export images, icons, and SVGs for analysis rather than relying on visual inspection alone.
+- **Match colors to named tokens, not raw values.** When extracting colors from designs, do NOT guess hex codes. Instead, match them to the project's existing color system — brand colors, design tokens, CSS custom properties, theme variables, or framework-level color names (e.g., `--color-primary`, `theme.colors.brand.500`, `text-blue-600`). Search the codebase for the color system first.
+- **Legacy tools requiring browser inspection**: If you must use Chrome/browser to inspect a design tool that lacks API access, take extra care with color extraction. Cross-reference every color against the project's defined palette. If a color doesn't match any existing token, flag it — don't invent a new one.
+- **Distinguish design annotations from UI elements.** Designers often annotate mockups with callouts, arrows, measurement labels, sticky notes, and text blocks that describe UX behavior or implementation details. These annotations are **guidance for you, not part of the design to implement.** Look for: redline measurements, numbered callouts, text outside the frame/artboard, comment threads, and annotation layers. Treat them as implementation instructions — extract and follow the guidance, but do not render them as UI elements.
+
 #### Provider Sync — Ticket Status
 - If a `ticket` field exists in the current unit's frontmatter, **SHOULD** update the ticket status to **In Progress** using the ticketing provider's MCP tools
 - If the unit is completed successfully, **SHOULD** update the ticket to **Done**

plugin/hats/designer.md

@@ -64,8 +64,16 @@ The Designer creates visual designs, UI mockups, and user experience flows. This
    - You SHOULD reference design tokens if available
    - You MUST specify accessibility requirements (contrast, labels)
    - You SHOULD include responsive breakpoints
+   - You MUST reference colors by named tokens (design tokens, CSS custom properties, framework variables) — never by raw hex unless defining a new token
    - **Validation**: Specs sufficient for implementation
 
+#### Working with External Designs
+
+When exploring designs in design tools (Figma, Sketch, Adobe XD, etc.):
+
+- **Download assets for analysis.** Use design tool APIs or MCP tools to export images, icons, and SVGs. Analyze downloaded assets rather than relying solely on visual inspection.
+- **Distinguish annotations from design.** Designers annotate mockups with callouts, arrows, measurement labels, sticky notes, and descriptive text that convey UX intent and implementation detail. These annotations are **guidance, not UI elements.** Extract the guidance (spacing rules, interaction notes, state descriptions) and incorporate it into your design specs, but do not treat annotation visuals as part of the design itself.
+
 ## Success Criteria
 
 - [ ] User problem clearly understood

plugin/hats/reviewer.md

@@ -44,7 +44,7 @@ The Reviewer verifies that the Builder's implementation satisfies the Unit's Com
    - You MUST run verification commands, not just read code
    - You MUST NOT assume - verify programmatically
    - You SHOULD cross-reference spec provider for requirement accuracy if configured
-   - You SHOULD cross-reference design provider for visual/UX compliance if configured
+   - You SHOULD cross-reference design provider for visual/UX compliance if configured. When comparing implementation to designs, match colors against the project's named color tokens (design tokens, CSS custom properties, theme variables) — not raw hex values. If the design contains annotations (callouts, arrows, measurement labels, descriptive text), treat them as implementation guidance that should have been followed, not UI elements that should have been rendered.
    - **Validation**: Each criterion marked pass/fail with evidence
 
 3. Review code quality

plugin/skills/elaborate/SKILL.md

@@ -208,7 +208,7 @@ Based on what the user described in Phase 2, identify every relevant technical s
 7. **Configured Providers**: If providers are configured in `.ai-dlc/settings.yml` or discovered via MCP:
    - **Spec providers** (Notion, Confluence, Google Docs): Search for requirements docs, PRDs, or technical specs related to the intent
    - **Ticketing providers** (Jira, Linear): Search for existing tickets, epics, or stories that relate to or duplicate this work
-   - **Design providers** (Figma): Search for design files, component libraries, or mockups relevant to UI work
+   - **Design providers** (Figma, Sketch, Adobe XD): Search for design files, component libraries, or mockups relevant to UI work. When possible, download/export assets (images, icons, SVGs) for analysis rather than relying on visual inspection alone. **Important:** Designers often annotate mockups with callouts, arrows, measurement labels, sticky notes, and descriptive text that convey UX behavior or implementation details. These annotations are **guidance, not part of the design itself** — extract the guidance (interaction notes, spacing rules, state descriptions, edge cases) and incorporate it into unit specs, but do not treat annotation visuals as UI elements to build.
    - **Comms providers** (Slack, Teams): Search for relevant discussions or decisions in channels
    Use `ToolSearch` to discover available MCP tools matching provider types, then use read-only MCP tools for research.
 
@@ -873,6 +873,8 @@ DESIGN_TYPE=$(echo "$PROVIDERS" | jq -r '.design.type // empty')
 
 If a design provider is configured (e.g., Figma), reference component names from the design system in HTML comments (e.g., `<!-- DS: ButtonPrimary -->`) but maintain low-fidelity wireframe aesthetic. Do NOT import actual design system styles.
 
+If design mockups exist, download/export assets when possible for analysis. **Distinguish annotations from design elements** — designers annotate mockups with callouts, arrows, measurement labels, and descriptive text that describe UX behavior and implementation detail. Extract this guidance into the unit specs (interaction notes, edge cases, state descriptions) but do not render annotations as wireframe elements.
+
 ### Step 3: Create mockups directory
 
 ```bash