# Change Request: CR-002

> Created: 02-14-2026
> Status: Proposed
> Classification: Major Revision (v1.1 → v2.0)
> Related Feature: FEATURE-030-B (UIUX Reference Agent Skill & Toolbar)
> Source: IDEA-019 (CR-UIUX Reference)

---

## Request Details

- **Requestor:** Human (via IDEA-019 ideation)
- **Date Received:** 02-14-2026
- **Priority:** High

## Description

Complete redesign of the UIUX Reference toolbar from standalone tools to a two-mode wizard system:

1. **Replace entire toolbar with hamburger-menu wizard** — Remove standalone Color Picker and Element Highlighter. The hamburger menu becomes the sole entry point, offering two guided workflows.

2. **Catch Design Theme mode** — Step-by-step wizard to pick colors from the page using an offscreen canvas with circular magnifier (120px, 10x zoom, crosshair), annotate color roles (primary/secondary/accent/custom), and trigger `brand-theme-creator` skill to generate a design system.

3. **Copy Design as Mockup mode** — Step-by-step wizard to select page components via smart-snap to semantic containers, add per-component text instructions, trigger agent analysis (5-dimension rubric), and generate a pixel-perfect mockup with iterative validation (max 3 auto-iterations).

4. **Auto-collapse behavior** — Toolbar defaults collapsed (hamburger icon only). Expands on hover. Auto-collapses 2 seconds after mouse leaves panel, leaving space for color picking or area selection. Draggable position (default: right side).

5. **Bi-directional communication** — New `__xipeRefCommand` queue enables agent→toolbar requests during analysis loop, complementing existing `__xipeRefReady` toolbar→agent signal.

6. **New data schema** — Replace `elements[]` with `components[]` (including `html_css`, `instruction`, `agent_analysis`). Add `role` field to `colors[]`. Clean break — new schema only, no backward compatibility with v1.x format.

7. **Injection performance optimization** — Current v1.1 injects an 830-line unminified IIFE via CDP `evaluate_script`, which is noticeably slow. The v2.0 toolbar (which will be larger due to wizard UI, magnifier, smart-snap) must use a more efficient injection strategy. Explore: minification, chunked/staged injection, lazy font loading, deferred non-critical UI. Target: perceptibly faster than v1.1 despite larger feature set.

## Business Justification

- Current toolbar captures raw data but provides no guided workflow to produce actionable artifacts
- Users must manually assemble captured colors/elements into themes or mockups
- The agent lacks enough structured context to generate high-fidelity mockups
- Two purpose-driven modes replace scatter-shot tools with focused outcomes
- Absorbs FEATURE-031 (cancelled) and FEATURE-032 (cancelled), simplifying the feature roadmap

## Impact Analysis

### Classification

- **Type:** Major Revision — complete toolbar rewrite
- **Reasoning:** All 13 user stories (US-1 through US-13) and all 37 functional requirements (FR-1 through FR-37) from v1.1 are deprecated and replaced. The UI paradigm shifts from standalone tools to guided wizards.

### Comparison Matrix

| Aspect | v1.1 (Current) | v2.0 (CR-002) |
|--------|----------------|---------------|
| Entry point | Draggable floating panel, always expanded | Hamburger icon, auto-collapse on mouseleave (2s delay) |
| Color picking | `getComputedStyle` + canvas sampling | Offscreen canvas rendering + circular magnifier (120px, 10x zoom) |
| Element capture | Click → bounding box + CSS selector + screenshot | Smart-snap to semantic containers + drag-handle resize + agent rubric analysis |
| Data format | `colors[]` + `elements[]` | `colors[]` (with `role`) + `components[]` (with `html_css`, `instruction`, `agent_analysis`) |
| Workflow | Manual: pick colors, highlight elements, send | Guided wizard: step-by-step per mode |
| Send action | Single "Send References" button | Per-mode action: "Create Theme" / "Generate Mockup" |
| Agent communication | `__xipeRefReady` (toolbar→agent only) | `__xipeRefReady` + `__xipeRefCommand` (bi-directional) |
| Mode switching | N/A (single mode) | Two modes, switchable mid-session, shared data store |
| Auth flow | Auth prerequisite URL flow | Unchanged (kept as-is from v1.1) |
| Position | Top-right, draggable | Right side default, draggable |
| Keyboard shortcuts | None | None (mouse-only) |

### Affected Components

| Component | Impact Level | Details |
|-----------|-------------|---------|
| `xipe-toolbar.js` | 🔴 Full rewrite | Entire IIFE replaced with new wizard-based toolbar |
| `toolbar-template.md` | 🔴 Full rewrite | Skill reference updated for new toolbar code |
| FEATURE-033 MCP schema | 🟡 Update | `save_uiux_reference` accepts new schema (new schema only, clean break) |
| FEATURE-030-B spec | 🔴 Full rewrite | All user stories and FRs replaced |
| FEATURE-030-B tech design | 🔴 Full rewrite | Architecture redesigned for wizard system |
| Tests | 🔴 Full rewrite | Test suite rewritten for new toolbar behavior |

### Dependencies

- **FEATURE-030-A** (Tab & Console Integration) — unchanged, still the entry point
- **FEATURE-033** (App-Agent Interaction MCP) — schema update for new data format
- **brand-theme-creator skill** — invoked by "Catch Design Theme" mode (already exists)
- **Mockup creation skill** — invoked by "Copy Design as Mockup" mode (may need creation/extension — out of scope for this CR)

## Proposed Approach

### CR-002-A: Toolbar Shell & Auto-Collapse

Replace the toolbar IIFE with new panel shell:
- Hamburger icon as sole visible element when collapsed
- Expand on hover, auto-collapse 2s after mouseleave
- Draggable position (default: right side)
- Mode switcher tabs: "Catch Theme" / "Copy Mockup"
- Inline toast notifications at bottom of panel

### CR-002-B: Catch Design Theme Mode

3-step wizard:
- **Step 1 — Pick Colors**: Offscreen canvas rendering of viewport, circular magnifier (120px, 10x zoom, crosshair), click to sample pixel. Store hex/rgb/hsl/source.
- **Step 2 — Annotate Roles**: Assign role per color (primary/secondary/accent/custom text). Editable list with color swatches.
- **Step 3 — Create Theme**: Send annotated colors via `__xipeRefReady`, agent invokes `brand-theme-creator` skill. Toast on completion.

### CR-002-C: Copy Design as Mockup Mode

4-step wizard:
- **Step 1 — Select Components**: Click to smart-snap to nearest semantic container (`section`, `nav`, `article`, etc.). Fallback: nearest `div` with width>50px and height>50px (within 5 ancestor levels). Drag handles for resize. Capture bounding box + screenshot crop + minimal computed styles.
- **Step 2 — Add Instructions**: Free-text box per component for context notes.
- **Step 3 — Analyze**: Send captured data to agent. Agent evaluates 5-dimension rubric (layout, typography, color, spacing, visual effects). If any dimension is "missing", agent requests deeper capture via `__xipeRefCommand`.
- **Step 4 — Generate**: 4a: Persist metadata via MCP. 4b: Agent generates mockup. Screenshot comparison (method TBD). Below threshold → re-analyze (max 3 iterations). After 3 failures → human approval.

### CR-002-D: Data Schema & Communication

- New `window.__xipeRefData` schema with `mode`, `colors[]` (with `role`), `components[]` (with `html_css`, `instruction`, `agent_analysis`), `design_tokens`
- `__xipeRefCommand` queue for agent→toolbar requests
- Both modes share same data session (colors from Theme mode available in Mockup mode)
- Clean break — new schema only

## Mockup Impact

### UI/UX Changes

The entire toolbar UI is replaced. The mockup demonstrates:
- Collapsed hamburger state → expanded panel with mode tabs
- Theme mode: magnifier, color list with role chips, "Create Theme" button
- Mockup mode: smart-snap overlay, component list, 4-step wizard
- Toast notifications at panel bottom

### Affected Mockups

| Mockup | Status | Link |
|--------|--------|------|
| v2.0 Toolbar (new) | ✅ Created | [toolbar-v2-v1.html](../../ideas/019.%20CR-UIUX%20Reference/mockups/toolbar-v2-v1.html) |
| v1.1 Toolbar (current) | ⚠️ Superseded | [injected-toolbar-v3.html](mockups/injected-toolbar-v3.html) |

## Approval

- [x] Impact analysis reviewed
- [ ] Human approved CR scope
- [ ] Feature specification updated to v2.0
- [ ] Technical design updated

## Execution

- **Classification Result:** Major Revision — bump FEATURE-030-B to v2.0
- **Actions:**
  - [ ] Deprecate all v1.x user stories (US-1 through US-13) and FRs (FR-1 through FR-37)
  - [ ] Write new v2.0 specification with wizard-based user stories and FRs
  - [ ] Update technical design for new architecture
  - [ ] Rewrite test suite
  - [ ] Update FEATURE-033 MCP schema

## Links

- [IDEA-019 Summary v3.0](../../ideas/019.%20CR-UIUX%20Reference/idea-summary-v3.md)
- [IDEA-019 Mockup](../../ideas/019.%20CR-UIUX%20Reference/mockups/toolbar-v2-v1.html)
- [FEATURE-030-B Specification v1.1](x-ipe-docs/requirements/EPIC-030/FEATURE-030-B/specification.md)
- [CR-001](x-ipe-docs/requirements/EPIC-030/FEATURE-030-B/CR-001.md)

## Clarifications

| Question | Answer |
|----------|--------|
| Backward compatibility with v1.x saved data? | New schema only (clean break). Old saved data stays as-is. |
| Auth flow? | Keep as-is from v1.1 (auth prerequisite URL unchanged). |
| Mode switching mid-session? | Yes — both modes available simultaneously, shared data store. Colors from Theme mode persist when switching to Mockup mode and vice versa. |
| Send/trigger behavior? | Each mode has its own action button. User must follow steps to the end within each mode to send. |
| Toolbar position? | Right side by default, user can drag to reposition. |
| Initial toolbar state? | Collapsed (hamburger icon only). Expand on hover. Auto-collapse 2s after mouseleave. |
| Keyboard shortcuts? | No — mouse-only interaction. |
| Injection performance? | Current 830-line unminified IIFE is slow to inject via CDP `evaluate_script`. Technical design should explore more efficient injection strategies (minification, chunked injection, lazy loading, font optimization). |

## Change History

| Date | Change | By |
|------|--------|------|
| 02-14-2026 | CR-002 created from IDEA-019 ideation + brainstorming | Cipher (agent) |
