visual-replication

name

visual-replication

description

Reconstruct or repair a web UI from a live reference URL, screenshots, or an existing implementation with measurable visual fidelity. Use for pixel-accurate cloning, screenshot-to-code, responsive page matching, visual regression repair, or requests such as “match this website,” “make this look exactly like the reference,” and “compare and iterate with Playwright.” Do not use for inspiration-only redesigns or ordinary frontend work without a visual source of truth.

Visual Replication

Reproduce the reference as an engineered UI, not as an approximation and not as a screenshot.

Treat:

• The reference URL or approved screenshots as the visual source of truth.
• Repository instructions, architecture, and design-system conventions as the engineering source of truth.
• Captured evidence and measured diffs as the completion source of truth.

Never claim “100%,” “pixel perfect,” or “exact” without measured evidence. State remaining uncertainty explicitly.

Required operating mode

Use an evidence-driven loop:

contract → stabilize → inspect → specify → implement → compare → diagnose → correct → verify

Do not jump directly from opening the reference to writing the whole page.

For complex pages, work one bounded region and one interaction state at a time.

1. Establish the task contract

Before editing application code:

1. Read repository instructions and discover:
   • package manager;
   • start, build, lint, unit-test, and browser-test commands;
   • framework and version;
   • component, styling, asset, routing, state, and accessibility conventions;
   • existing design tokens and reusable primitives.
2. Identify:
   • reference URL or screenshots;
   • target local route;
   • exact page regions in scope;
   • required viewport matrix;
   • required interaction/state matrix;
   • approved asset sources;
   • content that must be real versus deterministic fixtures.
3. Create artifacts/visual-replication/<task-slug>/task-contract.md from assets/task-contract.template.md.
4. Record observations separately from assumptions. Never silently convert an unknown into a fact.
5. Confirm the work is authorized. Do not bypass access controls, bot protections, authentication, or licensing restrictions.

When scope is not explicit, choose the smallest coherent region that delivers visible progress and record that scope decision.

2. Build a deterministic reference baseline

Read references/visual-validation.md before capturing baselines.

Use the same rendering environment for reference and local captures:

• Playwright/browser version;
• browser engine;
• operating system or container image;
• viewport and screen dimensions;
• device scale factor;
• locale and timezone;
• color scheme and reduced-motion preference;
• font files and font-loading state;
• authentication, cookies, country, currency, and language;
• scroll position and interaction state.

Capture the reference at least twice before implementation.

Compare the reference captures with each other:

• If they differ materially, the baseline is unstable.
• Identify the cause before comparing local output.
• Freeze time or deterministic data when supported.
• Hide or mask only genuinely volatile, out-of-scope content.
• Document every stabilization rule.

Do not hide stable mismatches to improve the score.

Do not use networkidle as the only readiness signal. Wait for explicit UI readiness, required fonts, required images, and stable layout.

Store:

• screenshots;
• environment metadata;
• stabilization CSS;
• state preparation steps;
• self-diff/noise measurement.

If the reference cannot be stabilized, use region-level captures or user-approved screenshots and document the limitation.

3. Reverse-engineer before implementing

Read references/reference-inspection.md.

Inspect every required viewport independently. Do not infer mobile behavior from desktop alone.

Create artifacts/visual-replication/<task-slug>/visual-spec.md from assets/visual-spec.template.md.

Measure and record:

Structure

• page landmarks and section order;
• repeated patterns;
• desktop/mobile variants;
• overlays, drawers, menus, carousels, sticky regions, and scroll behavior;
• visible, hidden, loading, empty, hover, focus, selected, and expanded states.

Geometry

• viewport-relative and container-relative positions;
• widths, heights, min/max constraints;
• page/container gutters;
• grid columns, tracks, spans, and gaps;
• flex alignment, wrapping, and distribution;
• margins, padding, borders, and radii;
• aspect ratios, object fit, object position, and clipping;
• fixed, sticky, absolute, and stacking behavior.

Typography

• actual font family and fallback chain;
• font source and load status;
• size, weight, style, line height, letter spacing, text transform;
• wrapping width, line count, truncation, and alignment.

Visual tokens

• foreground/background colors;
• borders, shadows, gradients, opacity, filters, and blend modes;
• icon source, dimensions, stroke width, and alignment.

Assets and data

• image URLs or approved local equivalents;
• intrinsic image dimensions;
• product/content ordering;
• deterministic content needed to preserve wrapping and card heights.

Use browser evaluation and computed styles for measurable values. Use screenshots for appearance that computed styles do not fully explain.

Inspect the reference DOM only as evidence. Do not copy its production JavaScript or blindly transplant generated markup and CSS.

4. Plan the reconstruction

Create an implementation sequence that minimizes compounding error:

1. fonts, reset, and global rendering assumptions;
2. page shell, max-widths, gutters, and major vertical rhythm;
3. shared primitives;
4. one region at a time from top to bottom;
5. responsive variants;
6. interaction states;
7. motion only after static fidelity passes;
8. full-page integration.

Prefer a thin vertical slice that can be fully verified over a broad partial implementation.

For Angular repositories, read references/angular-adapter.md.

5. Implement without approximation drift

Follow the repository’s current conventions unless they conflict with the explicit task contract.

Required rules:

• Reuse canonical tokens and components when they can produce the reference faithfully.
• Add narrowly scoped tokens when the reference requires values that do not exist.
• Do not force an inaccurate design-system primitive merely to claim reuse.
• Do not introduce a parallel styling system.
• Do not use an iframe, canvas screenshot, full-page background image, or rasterized text as the implementation.
• Do not replace approved assets with visually unrelated placeholders.
• Do not modify unrelated features.
• Do not perform broad refactors during replication.
• Preserve semantic HTML, keyboard behavior, focus treatment, and accessible names.
• Keep dynamic behavior deterministic in tests.
• Prefer measured CSS values over arbitrary guesses.
• Keep repeated structures data-driven only when doing so does not change layout behavior.

When a reference technique is fragile or inaccessible, reproduce the visual result with a maintainable equivalent and record the deviation.

6. Run the visual correction loop

After each bounded region or state:

1. Start the local application using the repository’s command.
2. Capture reference and local output under identical conditions.
3. Compare:
   • functional/semantic state;
   • region geometry;
   • typography and wrapping;
   • pixel output.
4. Save expected/reference, actual, diff, and metrics.
5. Identify the three largest discrepancies.
6. Fix only the highest-impact causes.
7. Re-capture and compare.
8. Continue until the acceptance gate passes or a documented blocker remains.

Diagnose in this order:

1. wrong reference variant, viewport, zoom, DPR, locale, currency, or fonts;
2. page shell and container geometry;
3. section dimensions and layout algorithm;
4. typography and line wrapping;
5. image dimensions, crop, and positioning;
6. spacing;
7. colors, borders, shadows, and decorative details;
8. animation timing and transient effects.

Do not “pixel-push” child elements while a parent geometry error remains.

Use region-level screenshots during iteration. Use full-page screenshots only after regions are stable.

When available, run scripts/run-visual-audit.mjs with a project-specific config based on assets/visual-audit.config.template.mjs.

7. Verify responsive behavior and interactions

For each viewport/state pair in the task contract:

• inspect the reference state directly;
• reproduce navigation, drawer, modal, carousel, hover, focus, selected, and loading behavior in scope;
• verify content order and visibility;
• verify text wrapping and image crop;
• check sticky/fixed behavior at meaningful scroll positions;
• detect horizontal overflow;
• verify keyboard navigation and focus restoration where applicable.

Use user-facing locators for functional tests. Use explicit region selectors only for visual measurement.

8. Apply completion gates

Do not report completion until:

Engineering

• build passes;
• relevant lint and type checks pass;
• relevant unit and browser tests pass;
• no unrelated regressions are introduced.

Evidence

• reference, actual, and diff images exist for every required case;
• baseline stability/self-diff is recorded;
• environment metadata is recorded;
• visual metrics and geometry metrics are recorded;
• hidden or masked content is documented.

Visual quality

• every required case meets its agreed tolerance;
• there is no unexplained horizontal overflow;
• typography and line wrapping match;
• major region geometry matches;
• remaining differences are classified and explained.

Create the final report from assets/visual-audit.template.md.

Report:

• scope completed;
• files changed;
• commands run;
• viewport/state matrix;
• baseline noise;
• local-versus-reference diff;
• geometry deviations;
• remaining discrepancies;
• blockers or assumptions.

Use evidence-based language:

• “Passed the configured gate at …”
• “Remaining difference is …”
• “Could not verify … because …”

Never use unsupported completion language.

9. Handle blockers honestly

Stop visual scoring and document the blocker when:

• the reference variant changes by geolocation, account, experiment, or session;
• required fonts or assets are unavailable;
• the reference is actively changing;
• anti-bot or access controls prevent authorized inspection;
• third-party content cannot be made deterministic;
• the local route cannot represent the same data/state;
• browser environments differ materially.

Continue with stable regions when possible. Do not fabricate measurements.

Additional resources

Load only what the current phase requires:

• references/reference-inspection.md — DOM, computed-style, geometry, typography, asset, and responsive inspection.
• references/visual-validation.md — deterministic capture, stability calibration, pixel/geometry comparison, thresholds, and artifact rules.
• references/angular-adapter.md — Angular-specific implementation and testing guidance.
• references/dynamic-content.md — decision tree for volatile reference content.
• references/failure-modes.md — common agent mistakes and corrective actions.
• references/skill-evaluation.md — fresh-session eval prompts and scoring rubric.
• assets/task-contract.template.md — task inputs and acceptance matrix.
• assets/visual-spec.template.md — measured reconstruction specification.
• assets/visual-audit.template.md — final evidence report.
• assets/visual-audit.config.template.mjs — executable audit configuration starter.
• scripts/run-visual-audit.mjs — capture, baseline calibration, geometry extraction, PNG diff, and report generation.