---
name: iris-verify-ui
description: "Reproduce and verify web interfaces against reference screenshots or acceptance criteria using Iris vision, OCR, capture, grounding and pixel comparison. 用于对照参考图检查界面、还原设计、定位视觉偏差与验证前端修改；单步图片理解或媒体创作用 iris-use / iris-compose-media。"
---

# Verify UI with Iris

Use vision models to understand and locate problems. Use deterministic pixel tools to measure them. Establish comparable capture conditions before editing, then recheck under the same conditions. Do not declare success from visual impression alone.

Choose checks that answer the actual acceptance criteria. Read the relevant part of the [shared capability and artifact contract](../iris-use/references/media-contract.md) when an input or handoff is unclear; a standalone description or image generation belongs to `iris-use`.

## Choose the shortest path

Select a path from the evidence provided:

- Current and reference screenshots are both available: compare them directly; do not recapture.
- Raw HTML and a reference screenshot are available: capture the current version with `iris_html_screenshot`.
- Editable page source is available but no current screenshot exists: use the project's browser or screenshot workflow first. `iris_html_screenshot` accepts an HTML string; it cannot navigate an arbitrary URL.
- Only one screenshot is available and no reference or acceptance criteria exist: perform a semantic review and state that comparative pixel verification is not possible.
- The request is only to describe, OCR, or generate media: do not use this skill. Use the matching Iris tool or a media-composition skill.

Ask one concise question only when a missing reference, target state, theme, or viewport would materially change the result. Make conservative assumptions otherwise and record them in the verdict.

## Prepare the inputs

1. Identify each image source:
   - Existing Core image: pass `artifact_id` to look/locate/OCR. Agent crop/diff need a path or attachment; CLI `run crop` and `media diff` accept Core IDs directly. Use the shared contract's examples, or export only when the chosen consumer needs a file.
   - Host absolute path: pass `image_path`.
   - Current-session or Iris-produced attachment: pass `attachment_id`.
   - Browser-local path, `content://` URI, or ordinary web URL: do not assume the host can read it. Ask for an upload or a host-accessible file.
2. Record the comparison conditions: viewport, screenshot dimensions, device pixel ratio, theme, fonts, zoom, scroll position, and dynamic-content state.
3. Freeze time, animation, cursor, random content, loading state, and scrollbars where practical.
4. Require matching image dimensions for reliable UI comparison. If dimensions differ, recapture before comparing; do not let automatic stretching hide a layout error.

## Run the verification loop

### 1. Establish the baseline

State the current image, reference image, target area, and acceptance criteria. Follow a threshold supplied by the user. If no threshold exists, do not invent a universal passing percentage.

When raw HTML needs capture, call `iris_html_screenshot` with the same HTML wrapper, `fullPage` value, and size parameters for every iteration. Account for these constraints:

- `width` and `height` set a minimum container size; they do not control the browser viewport.
- The page runs in an opaque-origin CSP sandbox. Scripts, external network access, form submission, and remote resources are unavailable.
- Inline required styles, fonts, and images, or use data URLs.
- The shared browser may briefly show the temporary tab.
- `iris_html_screenshot` is not concurrency-safe. Capture multiple states sequentially.

### 2. Inspect semantics

When semantic interpretation is needed, inspect the current and reference images separately. Call `iris_look_at_image` for a Core Artifact ID or host path and `iris_relook_attachment` for an attachment. Use `iris_long_ocr` when exact interface text matters; preserve its partial-result status.

Each vision call sees only one image. Ask the same structured questions for both images:

- List visible components, relative positions, and hierarchy by top, middle, and bottom regions.
- Identify clipping, overflow, misalignment, unusual spacing, typography, and color issues.
- Record the target element's position relative to its container and neighboring elements.

Compare the two observation sets and prioritize the differences. Treat vision answers as diagnostic leads, not pixel evidence.

### 3. Measure the whole image

When quantitative screenshot comparison serves the criteria, call `iris_pixel_diff` with the current and reference images, or CLI `media diff` for Core IDs. Record:

- diff ratio
- changed-pixel count and normalized dimensions
- worst grid regions
- heatmap attachment ID

Use the result as UI regression evidence only when image dimensions and render conditions match. The tool ignores alpha and counts RGB differences above its noise threshold. It stretches mismatched images to the smaller dimensions and downsizes when the longest side exceeds 1024 pixels. A low normalized diff therefore does not prove that the original large images are pixel-identical.

### 4. Locate and verify local regions

When a component must be located, call `iris_locate` separately on the current and reference images:

- Compare the two bounding boxes to detect position and size changes.
- If it returns `found=false`, retry once with a more specific target. If it still fails, report uncertain location; never fabricate coordinates.
- Treat the model-generated bounding box as a hypothesis and cross-check it against the screenshots and heatmap.

Use `iris_crop` when local evidence is needed:

- For a same-coordinate comparison, use identical `left`, `top`, `width`, and `height` on both images.
- When an element moved, report bounding-box geometry first. Do not crop different shapes and then use a stretched diff to hide the movement.
- Keep any added margin within image boundaries.

Run `iris_pixel_diff` on the two crop attachments to verify whether the problem is concentrated in the expected component.

### 5. Modify and recheck

Edit source files only when the task authorizes changes. Fix the highest-impact deterministic issue first, keep the patch focused, and preserve existing user changes.

After an authorized modification, repeat the relevant checks under the same conditions:

1. Capture again under the baseline conditions.
2. Rerun the whole-image diff.
3. Recheck the previous worst regions.
4. Record before-and-after diff ratios and bounding-box changes.
5. Confirm that the fix did not move the difference elsewhere.

Use the task's revision scope and budget. Stop when the criteria pass; if progress stops, capture conditions cannot be aligned, or differences come from the environment, report that limit instead of repeating the same loop. Visual checks do not prove browser interactions or application behavior; verify those with the project's actual browser/test workflow when required.

## Assign a verdict and degrade safely

Read [references/verdict-and-degradation.md](references/verdict-and-degradation.md) when assigning the final verdict or when Browser, vision, location, offline HTML, or comparable capture conditions are unavailable. Use **Pass**, **Partial pass**, **Fail**, or **Indeterminate** according to the evidence. Confirmed unmet requirements are Fail; missing evidence is Indeterminate.

## Report the result

Use the five-field report in [references/verdict-and-degradation.md](references/verdict-and-degradation.md). Keep conditions, changes, evidence, one verdict, and remaining work distinct. Do not finish with only “looks correct” or report precision the evidence cannot support.