# Change Request: CR-003

> Created: 02-15-2026
> Status: Approved
> Classification: Modification to FEATURE-030-B-MOCKUP
> Related Feature: FEATURE-030-B-MOCKUP

## Request Details

**Requestor:** User (via feedback on TASK-457)
**Date Received:** 02-15-2026
**Priority:** High

## Description

Update FEATURE-030-B-MOCKUP analysis workflow to implement 4 improvements based on lessons learned LL-012 through LL-015:

1. **Structured folder output (LL-012):** The analysis step must produce the complete `uiux-references/` folder structure including `page-element-references/`, `summarized-uiux-reference.md`, `mimic-strategy.md`, `full-page.png`, and per-area resource files.

2. **Area semantics (LL-013):** The DOM snap via `findSem()` is kept as the initial selection anchor (good UX). However, the snapped DOM element is just ONE of the related elements within the selected area. During analysis, the agent must discover ALL DOM elements whose `getBoundingClientRect()` intersects the area's bounding_box. The area is a rectangular region, not a single DOM element.

3. **Exact area screenshots (LL-014):** Screenshots must match the user's selected `bounding_box` coordinates exactly (x, y, width, height), not a DOM element's dimensions. The agent should use coordinate-based cropping instead of element UID-based screenshots.

4. **Resource auto-download (LL-015):** During analysis, the agent must detect and download ALL static resources within the selected area: images (`<img>` src, srcset, background-image), SVGs (inline or external), canvas content, video poster/src, fonts (@font-face), and icon resources. Resources are downloaded to the `resources/` folder with systematic naming.

## Business Justification

These changes are critical for achieving pixel-perfect mockup generation. The current analysis step only captures the snapped DOM element's styles/HTML and does not download actual resources, resulting in mockups that lack images, fonts, and other visual assets. Exact area screenshots ensure the reference image matches what the user selected, not what the DOM hierarchy dictates.

## Impact Analysis

### Classification

**Type:** Modification to FEATURE-030-B-MOCKUP

**Reasoning:**
- All 4 changes enhance the existing analysis step (Step 3) within the current 4-step wizard flow
- Same users, same toolbar, same UI screens
- Builds upon existing user stories (US-M4 analysis, US-M10 auto-collection, US-M11 screenshot validation)
- Extends existing ACs (AC-M27..AC-M30 auto-collection) with resource download
- No new API endpoints or data models — extends `__xipeRefData.areas[]` with additional fields

### Comparison Matrix

| Aspect | CR Requirement | Existing Feature |
|--------|---------------|-----------------|
| Users | Same — designers/developers using toolbar | Same |
| Workflow | Same 4-step wizard. Analysis step enriched | 4-step wizard: Select → Instruct → Analyze → Generate |
| Data Model | `area.snap_element` (anchor ref), `area.related_elements[]` (all elements in bounding_box) | `areas[]` with single selector/bounding_box |
| UI Elements | No new UI. Same toolbar wizard | Same toolbar wizard |
| API Endpoints | No change. save_uiux_reference already supports structured output | save_uiux_reference MCP tool |

### Affected Components

| Component | Impact Level | Details |
|-----------|--------------|---------|
| SKILL.md (x-ipe-tool-uiux-reference) | High | Update analysis procedure: area element discovery, resource download, structured folder output, exact screenshots |
| xipe-toolbar-mockup.js | Low | Store `snap_element` reference alongside bounding_box (minor data model change) |
| xipe-toolbar-core.js | Low | Deep capture may need to support multi-element capture within bounding_box |
| Specification (this feature) | Medium | New ACs for area semantics, resource download, structured output, exact screenshots |

### Dependencies

- FEATURE-033 (save_uiux_reference MCP) — already supports structured folder output (TASK-454)
- Chrome DevTools MCP — evaluate_script for element enumeration, fetch for resource download
- No new external dependencies

## Proposed Approach

### Change 1: Structured Folder Output
- Add explicit SKILL.md step: after analysis, agent MUST call `save_uiux_reference` with complete data (outer_html, computed_styles) to trigger structured output generation
- Add verification step: confirm `page-element-references/`, `mimic-strategy.md`, and `full-page.png` exist after save
- Take full-page screenshot as part of analysis (not just area screenshots)

### Change 2: Area Semantics
- Keep `findSem()` for initial DOM snap — good UX
- Store snapped element as `area.snap_element` (reference/anchor)
- During analysis: use `evaluate_script` to enumerate ALL elements within `bounding_box` via `getBoundingClientRect()` intersection
- Capture computed styles and HTML for ALL discovered elements, not just the snap target
- The area's content = union of all elements within the bounding_box

### Change 3: Exact Area Screenshots
- Use bounding_box coordinates (x, y, width, height) for screenshot cropping
- Scroll to ensure area is in viewport, take viewport screenshot, crop to exact coordinates
- Validate screenshot dimensions match bounding_box within 1px (existing AC-M24..AC-M26)
- Remove dependency on finding a matching DOM element UID in the a11y snapshot

### Change 4: Resource Auto-Download
- During analysis, for each area:
  - Enumerate all DOM elements within bounding_box
  - Classify: `<img>`, `<svg>`, `<canvas>`, `<video>`, background-image, @font-face
  - Extract resource URLs from elements and computed styles
  - Download each resource via `evaluate_script` fetch or network request capture
  - Save to `resources/` folder: `{area-id}-img-{N}.{ext}`, `{area-id}-svg-{N}.svg`, etc.
  - Reference downloaded resources in `summarized-uiux-reference.md`

## Mockup Impact

**UI/UX Change:** No (toolbar UI unchanged)
**Existing Mockups Referenced:** N/A — changes are to agent analysis behavior, not toolbar UI

## Approval

- [x] Classification approved by human
- [x] Approach approved by human
- [x] Ready for execution

## Execution

**Classification Result:** modification

**Actions Taken:**
- [x] CR document created in feature folder (CR-003.md)
- [x] Specification Version History updated with CR link
- [ ] Specification ACs updated (→ Feature Refinement)
- [x] Next task type set: x-ipe-task-based-feature-refinement

## Links

- Feature Specification: [specification.md](x-ipe-docs/requirements/EPIC-030/FEATURE-030-B-MOCKUP/specification.md)
- Lesson Learned: [x-ipe-meta-lesson-learned.md](../../skill-meta/x-ipe-tool-uiux-reference/x-ipe-meta-lesson-learned.md) (LL-012..LL-015)
- Requirement Details: [Part 8](../requirement-details-part-8.md)

---

## Change History

| Date | Change | By |
|------|--------|----|
| 02-15-2026 | CR created from LL-012..LL-015 feedback | Nova (agent) |
