# Rebuilding a UI from a reference image **When to use**: the task is turning a screenshot or design image into a page, component, or application UI in HTML/CSS or the project's existing frontend stack. Checking an existing implementation against its reference is the same workflow entered at Verify. For an isolated icon, logo, or illustration, read `restore-graphic.md`; for Mermaid, Graphviz, or another structured diagram, read `restore-structure.md`. ## Choose the restore mode - Use **fast restore mode** when the user asks for a quick, rough, approximate, prototype, or first-pass reconstruction, explicitly values speed over fidelity, or the reference image itself shows a floating speed-intent control such as "快速还原为 HTML" / "快速生成" / "quick restore" overlay. Its target is a recognizable screenshot in about three minutes when the project already runs. - Use the **standard restore workflow** below when the user asks for close, precise, pixel-level, or production-ready alignment, or does not opt into a faster approximation. ## Fast restore mode: first screenshot in about three minutes Fast mode preserves the page's hierarchy, major regions, visible text, and primary state. It deliberately approximates fine spacing, exact colors, typography, shadows, decorative details, and icon geometry. ### Hard limits 1. Inspect the existing frontend stack, component library, icon set, source assets, and design tokens before writing code, but stop searching as soon as a usable local primitive is found. 2. Run one full-image `vision_detect` pass. Treat its boxes as layout estimates and do not start a region-by-region inventory. 3. After that `vision_detect` pass, use at most **six sequential image-inspection rounds** through `view_image` (or the host's equivalent built-in viewer) and `vision_glance`. Each round may launch up to three independent calls concurrently, so the hard ceiling is 18 calls across six rounds. Batch unrelated regions or questions into the same round instead of waiting for each result before starting the next call. Normally one or two rounds are enough. 4. Do not use `vision_trace`, foreground extraction, repeated color sampling, iterative `vision_pixel_diff` work, or hand-written SVG in fast mode. Those are fidelity tools and will consume the delivery window. Icons and decorative marks stay library-based or screenshot-backed; never hand-write SVG code. ### Build the approximation 1. Implement the largest layout regions first, then visible text, primary controls, and the most important state. Ignore details that are only visible when zoomed in. 2. Reuse the project's existing components and CSS tokens. If its frontend or icon library contains a reasonably similar component or icon, use it directly instead of recreating the reference. Never hand-write SVG in fast mode: use an approximate library icon, or extract the original pixels as a screenshot-backed asset. 3. Use nearby existing palette tokens or visually similar CSS values. Exact sampled hex values, gradients, subtle borders, and shadow opacity are out of scope unless one of them defines the whole composition. 4. Keep text and controls native, selectable, and interactive. Fast mode relaxes visual fidelity, not basic UI behavior. ### Render once, fix once, deliver 1. Render the target viewport with `vision_html_screenshot` or the project's existing browser setup. 2. Inspect the screenshot once. If there is an obvious structural failure such as a missing major region, broken wrapping, or a wildly wrong scale, make one focused correction and render once more. 3. Deliver the screenshot. Stop instead of spending the remaining time on small color, icon, font, shadow, radius, or spacing differences. A practical time box is roughly 30 seconds for project inspection plus `vision_detect`, 90 seconds for implementation, and the remaining minute for startup, rendering, one correction, and screenshot delivery. Dependency installation or a project that does not already run may extend that target; do not compensate by silently switching back to a long precision loop. ## Standard restore workflow ### Core strategy: code-native UI plus screenshot-backed visuals Do not choose one reconstruction mode for the whole page. Classify each element separately. Most finished pages should combine both kinds: | Kind | Build it this way | Typical examples | |---|---|---| | **Code-native component** | Reuse the project's component library or build it with semantic HTML, CSS, and simple SVG primitives | layout, text, buttons, inputs, cards, tabs, dividers, backgrounds, simple geometric badges | | **Screenshot-backed visual** | Extract the original pixels, remove the background when needed, and place the result as an image asset | logos, proprietary icons, illustrations, decorative artwork, textures, complex static marks | Use this decision order for every element: 1. **Reuse an existing component or source asset from the project.** Search before recreating anything. 2. **Use a code-native component** when the element contains text, accepts input, changes state, must respond to layout, or is simple to express with the project's normal primitives. 3. **Use a screenshot-backed visual** when it is static, visually distinctive, expensive to redraw, and no source asset exists. 4. Rebuild a vector only when the user requires SVG/editability, the visual must scale beyond the screenshot resolution, or extraction cannot isolate it cleanly. Follow `restore-graphic.md` for that branch. Never flatten text, controls, or a large layout block into a screenshot. Never redraw extractable brand artwork merely to make the implementation look more "native". For a complex widget, keep the shell, text, and interaction native; use an extracted image only for its static decorative layer. ## Steps ### 1. Preserve the reference and inspect the target project If the reference is in a temporary path, copy it to durable work storage before the first tool call. Inspect the existing stack, component library, fonts, icons, images, and design tokens before writing replacements. ### 2. Establish the coordinate system Record the reference image dimensions and the target viewport. Screenshots may be HiDPI: `vision_detect`, `vision_ground`, and `vision_crop` report image pixels, while CSS uses logical pixels. Derive the scale from the actual image and viewport dimensions; do not assume a fixed 2x ratio. ### 3. Inventory the UI outside-in 1. Run one full-image `vision_detect` pass for the initial element list and boxes. 2. Call `vision_detect` with `region` on dense layout blocks; a full-screen pass is only a scaffold. 3. Use `vision_glance` for hierarchy, component type, visual state, and styling. 4. Use OCR for visible text and `vision_ground` for a specific element that remains ambiguous. Treat model boxes as approximate handles. Use them to organize the page, but do not mistake their final few pixels for measured boundaries. ### 4. Classify before implementing Make a short element list with one of these decisions: reuse existing source, code-native, screenshot-backed, or hybrid. This prevents two costly mistakes: rebuilding complex artwork from scratch and turning functional UI into static image patches. ### 5. Extract screenshot-backed visuals Use a padded crop only to inspect and center the target. Before foreground extraction, tighten the final region to the visual's own ink; adjacent text or rules inside the region can become foreground components too. ```json {"image":"shot.png","region":"X1,Y1,X2,Y2","scale":4,"output":"icon4x.png"} {"image":"","output":"icon.clean.png"} {"image":"shot.png","region":"X1,Y1,X2,Y2","output":"icon.png"} {"image":"shot.png","region":"X1,Y1,X2,Y2","mode":"dark","output":"logo.png"} ``` Inspect the transparent result before use. Confirm that the whole visual is present, no neighboring text or border leaked in, and the alpha edge remains clean. When extracting several assets, inspect them together in a contact sheet instead of checking them from filenames alone. ### 6. Implement the native frame - Follow the project's existing framework and component patterns. - Build content, interaction, responsive layout, borders, shadows, and simple shapes natively. - Use `vision_dominant_colors` for important background, text, and accent values; use `vision_glance` to name a color, not to invent its numeric value. - Place extracted assets with explicit logical dimensions. Preserve their aspect ratio and avoid baking surrounding whitespace into the asset. - Match structure and proportions before tuning small spacing. ## Verify and converge by impact For an existing implementation, start here. 1. Render at the same logical viewport with `vision_html_screenshot` or the project's browser test setup. 2. Compare the render and reference at the same dimensions. Inspect them side by side; use `vision_pixel_diff` to locate differences that are hard to spot or explain. 3. Fix material discrepancies: missing or wrong content, incorrect hierarchy, broken wrapping, visibly wrong alignment or scale, wrong component state, distorted assets, and clearly different primary colors. 4. Re-render after a meaningful fix. Continue while the comparison exposes a user-visible defect; stop when the remaining difference is font rasterization, antialiasing, subpixel placement, or another imperceptible rendering detail. `vision_pixel_diff` is a locator, not the acceptance target. Do not keep iterating only to lower its aggregate percentage, and do not promise zero-difference output from a screenshot without a separately scoped browser, font, viewport, and rendering environment. ## Boundaries - Do not ship a screenshot of the whole page as the implementation. - Do not use screenshot-backed text or controls that must remain selectable, accessible, interactive, localized, or responsive. - Do not stretch an extracted bitmap beyond the resolution supported by the reference. Obtain a source asset or rebuild a vector when it must scale. - Always compare against the original reference, never only against an earlier version of your own render.