UI From Image

Mission

Treat the provided reference image(s) as the visual source of truth.

Accuracy beats speed. Do not stop at "close enough". The task is not finished when the page merely works; it is finished when the rendered result is a close visual match and there are no obvious mismatches left.

Bias toward more verification passes rather than fewer. If there is a realistic chance that text is wrong, a control is crowded, spacing is fragile, or a layout bug is hidden by one viewport, keep iterating.

Do not describe the result as "good enough", "ready to ship", or equivalent unless all mandatory verification and reporting steps in this skill are complete and no known visible mismatch remains beyond clearly stated minor uncertainty.

Default output

Unless the repo already dictates another structure, use:

• index.html
• styles.css
• script.js

If adapting an existing frontend/framework, follow the repo's file structure while keeping markup, styling, and behavior as cleanly separated as the framework allows.

Operating mode

• For standalone work, default to plain HTML/CSS/JS unless the environment already includes a styling system the user wants to keep.
• Reuse the repo's existing Tailwind/DaisyUI setup when present.
• If the repo already has a different established styling system, do not introduce Tailwind/DaisyUI as a competing second system unless the user explicitly asks for it.
• If Tailwind/DaisyUI are already available or explicitly requested, treat them as implementation tools rather than design authority. Override defaults whenever the screenshot differs.
• First achieve fidelity at the exact reference dimensions of the primary screenshot.
• For desktop webpage work, do not treat a narrow mockup or POC screenshot as the final real-page desktop width. After the reference-size pass, prefer adapting the layout to a real desktop viewport around 1900px wide, allowing roughly 1900px rather than 1920px to account for a scrollbar and normal browser chrome.
• Only after the reference-size version is visually close should you derive tablet/mobile behavior.
• When the user supplies a newer or revised screenshot, the latest screenshot becomes the source of truth.

High-fidelity rules

• Match layout, spacing, typography, line height, letter spacing, colours, borders, border opacity, shadows, gradients, border radius, imagery crop/aspect ratio, and visual hierarchy as closely as possible.
• Use explicit values for widths, heights, max-widths, padding, margin, gap, border radius, font size, line height, tracking, and shadow when defaults are not close enough.
• Treat text fidelity as a layout problem as well as a content problem. If text is clipped, crowded, truncated, wrapped incorrectly, or pushes nearby controls out of alignment, the page is not done.
• Treat data visualizations and proportional graphics as layout-critical UI, not decorative approximations. Chart plot areas, axes, legends, segment widths, map regions, funnels, gauges, timelines, and diagram shapes must match the reference proportions and alignment closely enough that a user would read them as the same interface.
• Treat every visible detail as required, including micro-details:
  • small logos and button icons
  • search icons
  • dropdown carets
  • pagination chevrons
  • active nav underlines / glows
  • status dots
  • bullet colours
  • card icons
  • star/favorite icons
  • divider lines
  • subtle corner radii differences
  • text opacity changes
• Missing a small icon or logo inside a control is a fidelity failure, not a minor omission.
• Do not redesign, simplify, embellish, or "improve" the UI unless required for responsiveness or because the reference is genuinely ambiguous.
• Do not silently rely on DaisyUI typography, button styles, input styles, or spacing scale if they do not match the reference.

Existing frontend adaptation mode

When working inside an existing frontend or design system:

• Inspect the current codebase before creating new structures.
• Reuse existing layout shells, shared components, utility patterns, typography tokens, spacing scales, breakpoints, icon conventions, and theme variables wherever they can faithfully express the reference.
• Prefer adapting a nearby existing page or section over creating a parallel implementation from scratch.
• Do not introduce duplicate components, conflicting design tokens, or a second styling system unless the user explicitly asks for it.
• If the screenshot conflicts with the established design system, preserve the screenshot's page-level composition while staying as consistent as possible with the current tokens/components, unless the user explicitly says the screenshot should override the current design language.

Reference intake and breakpoint handling

• Record the exact dimensions of each reference image before coding.
• For the primary fidelity pass, render the page at the exact reference viewport size in CSS pixels whenever possible.
• If the reference desktop image is substantially narrower than a modern desktop viewport, treat that width as a composition/style reference rather than the final real-page desktop width. Preserve the screenshot's structure, hierarchy, spacing intent, and visual language, then expand and validate the actual desktop implementation at about 1900px viewport width.
• If multiple reference images are provided for desktop/tablet/mobile, treat each as authoritative for its breakpoint.
• If only a desktop reference exists, infer tablet/mobile layouts by preserving hierarchy, ordering, and visual balance without inventing new sections or interactions.
• If text is legible, reproduce it exactly, including punctuation and small helper labels.
• If text is unclear, use the closest reasonable approximation and report the uncertainty.
• If the screenshot shows a cropped region of a page rather than a full page, match the visible region first.

Viewport honesty and scaling safety

• Treat browser zoom, OS DPI scaling, and device pixel ratio as environmental factors that the implementation must tolerate, not as excuses to distort the layout.
• When Playwright or similar browser automation is available, treat automation-controlled screenshots captured at an explicit viewport size as the primary fidelity reference for comparison.
• Do not treat a headed browser window as the source of truth for pixel fidelity when OS DPI scaling, browser zoom, window chrome, or desktop compositor behavior may affect what the human sees on screen.
• On Windows in particular, assume non-default desktop scaling or browser zoom can make a headed browser visually misleading even when the underlying page layout is correct in CSS pixels.
• If Playwright reports that it opened a chrome or msedge browser/channel, that is still Playwright-driven verification. Do not describe this as "switching away from Playwright" unless browser automation was actually abandoned.
• Do not use CSS zoom, root-level transform: scale(...), synthetic wrapper scaling, or similar viewport hacks to make the implementation screenshot look closer to the reference.
• Do not "fix" width, crowding, or fold-position mismatches by shrinking the entire page or inflating the canvas.
• Solve screenshot mismatches with real layout changes:
  • correct container widths
  • correct grid and flex sizing
  • correct gaps and paddings
  • correct font sizes and line heights
  • correct control heights and intrinsic widths
  • correct responsive breakpoints
• If a browser-specific mismatch appears, first suspect invalid layout assumptions, overflow, or scaling hacks in the implementation before blaming the user's environment.
• If there is a mismatch between a headed browser window and a Playwright screenshot taken at the calibrated viewport, trust the screenshot first for fidelity work and investigate the implementation with additional screenshot passes before attributing the difference to the user's machine.
• When reporting fidelity status, distinguish between:
  • expected reflow differences caused by user/browser zoom preferences, and
  • genuine layout bugs such as horizontal overflow, incorrect width calculations, broken wrapping, or fragile breakpoint behavior.

Scroll-Resilience Check

For layouts with sticky/fixed sidebars, tool panels, inspectors, menus, or any viewport-height region:

• Verify that every region with content taller than the viewport can be scrolled independently.
• Do not rely on height: 100vh alone for fixed/sticky panels; add appropriate overflow-y: auto where content may exceed available height.
• Test at least one shorter desktop viewport height or zoom-like condition when the design includes a full-height sidebar or tool panel.
• Confirm lower controls, footer actions, account cards, collapse buttons, and secondary navigation remain reachable.
• Treat unreachable panel content as a functional layout bug, not only a visual mismatch.

Persistent Navigation And Panel Width

For persistent navigation, sidebars, rails, inspectors, and tool panels:

• Verify expanded labels fit without internal horizontal scrolling at desktop and wide/zoom-like desktop widths.
• Check horizontal overflow inside the panel itself, not only on document.documentElement.
• Capture a focused crop of the panel when it contains labels, icons, badges, counters, account controls, collapse buttons, or footer actions.
• Prefer sufficient intrinsic panel width, nowrap/ellipsis for labels, independent panel scrolling, and explicit collapsed breakpoints over letting panel content squeeze or create a horizontal scrollbar.
• Verify collapsed or icon-only states do not trigger too early, too late, or only because text no longer fits.
• Treat clipped labels, panel-level horizontal scrollbars, hidden footer controls, and labels colliding with icons/badges as layout failures.

Data Tables And Panel Footers

For cards, panels, data tables, grids, and list modules:

• Check internal scroll containers, not only page-level overflow. A table or grid can have its own horizontal scrollbar even when the document width is fine.
• Verify footer links, CTAs, pagination, summary rows, and secondary actions remain visually inside the card or panel boundary.
• Capture a focused crop of any table/list panel that has many columns, nowrap text, avatars, badges, row menus, pagination, or a footer CTA.
• Prefer explicit column sizing, table layout rules, responsive row-card alternatives, or intentional horizontal scrolling with visible affordance over accidental overflow.
• Treat accidental internal horizontal scrollbars, clipped row-action icons, stray text ellipses from overflowed action cells, and footer links escaping below the panel border as failures.

Preflight checklist

Before implementing, explicitly inspect and inventory:

1. Page sections and their order
2. Grid / column structure and approximate width ratios
3. Major containers and card boundaries
4. All text blocks and labels
5. All visible controls and interactive states
6. All icons, logos, badges, chips, status dots, separators, and decorative marks
7. All image assets and background graphics
8. Typography groupings (hero title, body copy, pills, buttons, table headers, table rows, side cards, notices, etc.)
9. Primary, secondary, muted, success, warning, danger, and accent colours
10. Likely responsive intent
11. Any regions where copy length, chip count, or control density make crowding likely
12. Any rows or panels that must remain on one line at the reference breakpoint
13. Every data visualization, including its card bounds, plot-area bounds, axes, labels, gridlines, legends, controls, marker positions, series shapes, and empty padding
14. Every proportional graphic or diagram, including relative segment sizes, taper direction, alignment, labels, fills, strokes, and surrounding whitespace
15. Every navigation or toolbar icon matched item-by-item against the reference, including active states, badge placement, stroke weight, and whether the glyph itself is the same concept

Do not start coding until you have a working mental map of every visually meaningful element.

Typography audit

Typography is a first-class fidelity target.

• Inspect the repo for existing font sources first:
  • global CSS
  • Tailwind config
  • DaisyUI theme config
  • design tokens
  • existing page components
  • local font files
• If an existing project font matches the reference, use it.
• If the reference appears to use a custom or non-default font and the exact font is unavailable, choose the closest available option and report that limitation explicitly.
• Do not default to generic DaisyUI/body typography without checking.
• Confirm the rendered fallback font, not only the declared font-family. A declared first-choice font may not be installed, and an installed font may be visibly wider, narrower, heavier, or softer than the reference.
• Set typography explicitly for each visual group:
  • logo text
  • nav links
  • pills / badges
  • hero heading
  • lead paragraph
  • stat labels
  • stat values
  • helper text
  • filter chips
  • form labels
  • table headers
  • table rows
  • sidebar headings
  • notifications / timestamps
  • primary and secondary buttons
• Check not only font family, but also:
  • size
  • weight
  • line height
  • letter spacing
  • apparent glyph width / character fit
  • case
  • colour / opacity
• Avoid artificial tracking or wide letter spacing unless the reference clearly shows it. Extra tracking on large numbers, headings, table text, or nav labels can make a UI look zoomed-in and can cause avoidable truncation.
• For dense dashboards, forms, tables, navs, and operational UIs, compare whether common labels and values occupy similar horizontal space to the reference. If text looks too wide, try a closer system font stack, remove unnecessary tracking, reduce weight, or adjust group-specific font sizes before changing layout.
• Validate text wrapping and line breaks at the reference width. If a heading or paragraph wraps differently from the screenshot, fix it.
• Validate text integrity for controls and dense UI:
  • no unintended truncation
  • no clipped ascenders/descenders
  • no vertical squashing from incorrect line height or control height
  • no label/helper text collisions
  • no placeholder text overflowing its field

Iconography and completeness audit

Before declaring the page done, verify that every visually meaningful icon or mark from the reference is represented in the DOM.

This includes:

• logo marks
• sidebar, tab bar, toolbar, and command palette icons
• brand icons inside buttons
• search icons
• dropdown carets
• stat-card icons
• status indicators
• row, table, list, and card action icons
• map / notification bullets
• table favorite icons
• pagination arrows
• close / reset / filter icons
• any subtle inline symbols

Rules:

• Small UI icons count as assets and must not be omitted.
• Navigation icons must be audited item-by-item. A generic placeholder icon is acceptable only when the reference glyph is genuinely unreadable; otherwise match the same visual metaphor, stroke weight, size, and alignment.
• Repeated row-action icons must be audited as a set and individually. Confirm the intended semantics are preserved, such as comment vs edit vs open/external-link vs copy vs delete vs overflow; do not substitute a visually similar control with a different meaning.
• For webpages and web apps, prefer existing repo icons or simple inline SVGs only when the glyph is simple enough to reproduce accurately and a focused visual pass confirms it matches the reference.
• Treat complex icons, detailed pictograms, custom illustrated buttons, branded controls, badges, medals, tabs, toggles, game-like controls, bespoke UI ornaments, textured surfaces, and other visually distinctive UI elements as assets when SVG/code recreation would be fragile or visibly wrong.
• Do not rely on CSS pseudo-elements, borders, or clip-path tricks for icons when the glyph has a recognizable outline, holes, star points, curved arcs, brand-like geometry, or a specific visual metaphor. Use an inline SVG or existing icon component so the icon remains visible and comparable to the reference.
• Do not add a new icon library unless the repo already uses one or the user explicitly asks for it.
• For common brand marks used in UI controls (for example Discord), use a clean inline SVG or existing icon component unless the repo already has an appropriate asset.

Data Visualization and Diagram Fidelity

Charts, diagrams, and dense analytic graphics need their own explicit pass. Do not collapse them into a generic "looks like a chart" implementation.

For every chart-like region, record and match:

• card size and chart-region size separately
• plot-area width, height, and inset from the card edges
• legend position, legend swatch style, and spacing from the title or plot
• axis label count, axis side, tick label positions, and gridline count
• series colour, stroke width, dash pattern, curvature, marker size, and rough point trajectory
• control placement around the chart, such as segmented buttons, dropdowns, zoom controls, range pills, or toolbars
• summary/footer rows below the plot, including column widths and separator lines

For every proportional graphic, record and match:

• overall bounding box and alignment within its card
• number of segments, their relative heights and widths, and whether they taper, expand, overlap, or step
• label placement inside or outside each segment
• colour order, opacity, borders, shadows, and gaps between segments
• companion labels, callout boxes, legends, or side metrics and their distance from the graphic
• whether text is fully contained in the intended segment or intentionally outside it, with no label spillover, clipping, or crowding

For circular charts such as donuts, pies, gauges, and radial progress indicators:

• Audit center labels separately from the chart shape.
• Match the center label's font size, weight, line height, and vertical alignment against the reference.
• Ensure the label fits comfortably inside the inner circle at the reference viewport and responsive breakpoints.
• Prefer explicit flex/grid centering and line heights for center labels.
• If the center label appears crowded, oversized, off-center, or clipped, fix typography and inner radius before declaring the chart matched.

Implementation guidance:

• Use inline SVG for non-rectangular proportional graphics such as funnels, pyramids, gauges, radial charts, maps, node graphs, complex timelines, and icon-like diagrams unless the reference can be matched exactly with normal layout boxes.
• Avoid approximating complex shapes with stacked divs, pseudo-elements, border triangles, or CSS clip-path when segment width, taper angle, separator gaps, or label placement need to be faithful. Those techniques are acceptable only after a screenshot pass proves the geometry and text containment match.
• When an SVG viewBox is used, set explicit width, height, polygon/path coordinates, text anchors, and label positions rather than relying on auto scaling or centered layout alone.

When a chart or diagram looks too narrow, too tall, too centered, too simplified, or visually detached from its surrounding card, treat that as a geometry mismatch. Fix container tracks, plot insets, SVG viewBox/aspect ratio, control widths, and neighbouring column ratios before moving on to responsive work.

Layout fitting and crowding rules

For the reference breakpoint:

• Recreate the screenshot's composition before making responsive adaptations.
• Do not solve crowding by prematurely redesigning, deleting, shrinking, or reflowing major groups.
• Do not solve crowding by scaling the whole page with CSS or by relying on browser zoom assumptions.
• First exhaust fidelity-preserving options:
  • match the reference viewport size
  • correct container widths and side-column widths
  • tighten or loosen gaps to the measured values
  • use the correct font size and line height
  • use correct control widths and min-widths
  • use the correct track sizing for each grid column instead of evenly distributing everything
  • give dense controls the width they actually need before shrinking neighboring elements
  • use wrapping only where the screenshot already implies wrapping
  • inspect whether the reference actually uses multiple rows
• Only move controls to additional rows at the reference breakpoint if:
  • the screenshot explicitly shows multiple rows, or
  • the user provides a revised screenshot showing the updated structure.
• If controls still feel crowded after a pass, assume the proportions are still wrong and continue iterating. Do not normalize crowding as "good enough."
• For narrower breakpoints, reflow cleanly while preserving hierarchy and visual balance.

Colour, surface, and effects audit

• Match primary surfaces, secondary surfaces, muted surfaces, borders, glows, shadows, gradients, and text opacities as closely as possible.
• When possible, sample or estimate colours from the reference instead of inventing new values.
• Pay attention to:
  • background gradients
  • subtle border alpha
  • panel transparency
  • hover/active emphasis that is visible in the reference
  • contrast differences between main content and sidebar cards
  • accent colour consistency across badges, live indicators, buttons, and highlights

Asset handling workflow

Direct image_gen rule

When raster assets are missing and would materially improve the implementation, use the native image_gen tool directly by default. Do not require the separate imagegen or imagen skill to be installed.

After image_gen runs, continue the same turn unless the user explicitly requested image-only output. Briefly identify what was generated, provide the saved file path or asset reference when available, assess whether it matches the request, and continue with saving, integration, and verification.

If image_gen is unavailable or fails, fall back to placeholders plus one standalone generation prompt per missing asset.

Operational rules for direct image_gen:

• Treat generated outputs as project-bound assets when they are used by the implementation. The built-in tool may save under $CODEX_HOME/generated_images/; move or copy the selected final into the workspace before referencing it in code.
• Do not rely on a destination-path argument for the built-in tool. Generate first, then move or copy the selected output.
• Do not overwrite existing assets unless the user explicitly asked for replacement. Otherwise create a sibling filename such as hero-v2.png or card-thumbnail-generated.png.
• For multiple missing raster assets, prefer generating one or more asset sheets rather than one image per asset when the assets are related and can fit cleanly on a single canvas.
• Use multiple asset sheets when the assets are too numerous, visually unrelated, need different styles, need very different aspect ratios, include text-heavy content, or would become too small to extract accurately from one sheet.
• For edits of a local file, inspect it with view_image first so it is visible in the conversation context. Label each input image by role, such as edit target, style reference, composition reference, or supporting insert.
• Shape prompts compactly around asset type, purpose in UI, subject/content, composition/framing, style/medium, lighting/mood, colour palette, exact text if any, constraints, and avoid notes. For edits, repeat invariants such as "change only X; keep Y unchanged."
• Do not treat fallback CLI/API controls such as quality, input fidelity, masks, output format, or output path as built-in image_gen tool arguments.

When transparency is requested, verify the saved PNG has a real alpha channel before finishing. Inspect metadata or pixels with a tool such as Pillow or .NET System.Drawing; a valid transparent PNG should be alpha-capable, such as RGBA or Format32bppArgb, and representative background pixels such as the corners should have alpha 0. If the generated file has a rendered checkerboard or solid background, leave it untouched, create a repaired derivative with a clear name such as *-transparent.png, and re-verify the repaired output.

Asset sheet generation and extraction

When several missing raster assets should be generated, default to an asset-sheet workflow:

1. Group compatible assets into a single sheet prompt. Group by shared style, lighting, perspective, medium, and target use. Keep separate sheets for assets that need incompatible styles, fine text, exact brand marks, very different proportions, or large detail.
2. Ask for a clean contact sheet or sprite sheet: one asset per cell, generous gutters, consistent scale, front-facing or clearly framed subjects, no overlaps, no shadows crossing cell boundaries, no labels unless the UI asset itself requires text, and a flat removable background colour that does not appear in the assets.
3. Prefer a high-contrast flat background such as pure magenta, cyan, or another chroma-key colour when transparency is needed. Do not rely on the image model to produce real transparency, and do not request checkerboard transparency.
4. After generation, copy the selected sheet into the workspace, then extract individual assets with a local script, preferably Python Pillow. Leave the original generated sheet untouched.
5. During extraction, crop each cell or detected object, remove the keyed background or edge-connected neutral background, trim transparent padding, add any needed safe padding, and save each asset with a clear filename in the project asset folder.
6. Verify every extracted transparent PNG has an alpha-capable mode such as RGBA and representative background/corner pixels with alpha 0. Visually inspect extracted assets before integrating them.
7. Integrate the extracted individual files, not the full sheet, unless the implementation intentionally uses a sprite sheet.
8. If extraction damages edges or removes internal details, keep the original sheet, repair the extraction mask, or regenerate with clearer spacing/background before using the asset.

Use one asset sheet when the likely generated assets will remain large and separable. Use more than one sheet when a single sheet would make assets small, ambiguous, hard to crop, or stylistically inconsistent.

First, inventory every visible asset required by the page:

• logos
• hero images
• thumbnails / cards
• maps
• avatars
• icons
• custom buttons and button artwork
• custom controls, toggles, tabs, badges, medals, stickers, cursors, handles, knobs, or UI ornaments
• desktop/game/app-specific chrome, HUD pieces, menu plates, inventory slots, tool icons, or decorative interface parts
• illustrations
• background graphics
• any other non-text visual elements

For each asset, choose exactly one path.

1) User supplied the asset

• Visually inspect it before use.
• Use it where appropriate.
• Crop, resize, pad, trim, or mask it as needed to match the reference composition.
• Preserve aspect ratio; never distort it.
• Use object-fit: cover or contain as appropriate.
• If the asset is low-resolution or otherwise imperfect, get as close as possible and note the limitation.

2) Asset is missing and should be generated

• Use image_gen directly to generate or edit the asset when the tool is available.
• If multiple missing assets can be generated together, use the asset-sheet workflow by default, then extract individual files locally.
• If only one asset is missing, or one asset needs unique composition/detail, generate it individually.
• For webpages and web apps, implement simple UI glyphs as inline SVG or existing repo icons only when they can be matched visually; otherwise generate/extract them as image assets.
• For non-web UI such as desktop apps, game HUDs, menus, inventory screens, launchers, or highly skinned tools, expect many custom UI elements to be image assets unless the code-native recreation is clearly faithful and verified.
• Save generated assets in the repo's existing asset location, or a sensible folder such as assets/generated/ if no convention exists.
• Update the consuming code or markup to reference the generated asset.
• Validate that each extracted or generated asset fits the layout visually and dimensionally.
• Re-crop, regenerate, or iterate if needed until the asset works in context.
• If image_gen is unavailable, generation fails, or extraction cannot be repaired in the current turn, use a clearly labeled placeholder and output one standalone generation prompt for each still-missing asset.

3) Asset is missing but should not be generated

Use this path for proprietary brand marks, assets that require exact real-world source material, or cases where the user explicitly asks not to generate images.

• Use a clearly labeled placeholder with the correct approximate dimensions, aspect ratio, border radius, placement, and visual weight.
• If you create or synthesize a temporary stand-in asset yourself instead of a generic placeholder, still treat that asset as missing for reporting purposes.
• Never silently substitute a stand-in, proxy illustration, or synthetic replacement and then omit it from the final missing-assets report.
• Prepare one separate, ready-to-use generation prompt for each missing asset unless the user explicitly asked not to receive prompts.
• Do not collapse multiple still-missing fallback prompts into one combined prompt in the final response. Asset-sheet prompts are for in-turn generation and extraction, not for the final missing-assets fallback block.
• Each prompt must remain standalone, but in the final response all still-missing asset prompts must be grouped together inside one single fenced text code block for easy copy/paste into another AI/LLM.
• Separate asset prompts inside that block with a clear divider such as ---.
• Each prompt must include:
  • asset name / suggested filename
  • purpose in the UI
  • desired subject/content
  • composition / framing
  • style / mood
  • colours / lighting
  • target aspect ratio or dimensions
  • transparency/background requirements if relevant
  • key "avoid" notes

Asset-specific guidance

• Simple UI icons are not a reason to leave a blank area. For webpages, implement simple glyphs with inline SVG or existing repo icons when they can be visually matched and verified.
• Do not force every icon, button, or custom UI element into inline SVG. Use raster assets when the reference depends on custom illustration, texture, complex geometry, painterly detail, shadows, embossed styling, game/desktop chrome, or another visual treatment that would be unreliable to recreate as code.
• For non-web interfaces, expect custom UI pieces to be generated/extracted image assets more often than inline SVG, unless the existing platform or codebase already provides matching components.
• For repeated icons or shortcut/navigation marks, inspect each rendered icon in screenshot context; a technically present icon that is too faint, clipped, collapsed, or visually unrecognizable still counts as missing.
• For brand logos or proprietary-looking marks that are not provided, use placeholders unless the user explicitly wants a temporary generated stand-in.
• For hero images, thumbnail images, maps, and other prominent visuals, match crop, focal point, aspect ratio, and visual weight as closely as possible.
• If the reference includes repeated thumbnail cards, pay attention to consistent crop and corner radius across all items.

Implementation workflow

1. Inspect the reference image(s) and build the preflight inventory.
2. If an existing codebase is present, inspect the most relevant pages/components/tokens/icons first and decide what to reuse.
3. Build a first pass that is already visually close.
4. Run or preview the page.
5. Capture an implementation screenshot at the exact reference viewport size.
6. Compare the implementation screenshot against the reference.
7. Make a written mismatch list before editing. Focus on the largest visual errors first, then the micro-details.
8. Repeat screenshot, mismatch list, and fixes until there are no obvious mismatches left.
9. For any chart, map, gauge, timeline, funnel, pyramid, tree, graph, or other analytic visual, do a dedicated visual-primitive pass comparing its bounding box, internal proportions, labels, and controls against the reference before declaring the main layout close.
10. For dense, constrained, high-value, or fragile components, capture focused component screenshots/crops and inspect them at larger scale before relying on full-page judgment. This is mandatory for any component where text, icons, badges, controls, charts, legends, tables, avatars, or action rows must fit inside limited space.
11. Before finishing, do at least one explicit "fragility pass" focused only on:

• crowded rows
• clipped or squashed text
• overlapping elements
• text, labels, or values that hug a card/control edge without enough padding
• component boundaries where one card, list, row, popover, or toolbar could grow into the next
• controls that look too narrow for their content
• suspiciously tight spacing that may break at slightly different widths
• fixed-height cards, rows, panels, or sticky regions whose content may overflow, overlap, or become unreachable at higher zoom, DPI scaling, larger fonts, or shorter viewport heights
• center text inside donuts, pies, gauges, badges, counters, and compact chart labels

12. For repeated UI structures such as card grids, table rows, stat tiles, nav items, or repeated buttons, do one explicit alignment pass and verify that shared baselines, footer rows, button positions, chip rows, and media crops are consistent across siblings.

Do not stop at code edits plus lint/build checks when browser verification is available. Build/test results never replace the required screenshot comparison loop for this skill.

Mandatory visual verification workflow

When browser and screenshot tools are available, the following passes are mandatory.

If browser tools are available and you have not yet captured and inspected screenshots yourself, you are not done. Do not present the work as finished, ready, or validated. Instead, continue until the screenshot pass is complete or explicitly report the blocking reason you could not perform it.

When a task only changes one dense or visually important region rather than a full page, still capture at least:

• one screenshot showing the changed region in context
• one close screenshot of the changed region itself when tooling supports element or cropped captures

In your final report, never imply that screenshots were checked unless you actually captured and inspected them during the current turn.

In your final report, list the actual visual verification artifacts by category:

• full-page or viewport screenshots inspected
• focused component crops inspected
• scaling/resilience screenshots inspected
• any required visual pass that could not be performed, with the concrete reason

Do not describe component crops, scaling checks, browser checks, or responsive checks as completed unless those exact artifacts were captured and inspected in the current turn.

If the page is too tall to inspect reliably in a single screenshot, capture segmented screenshots that collectively cover the whole page. Prefer top / middle / bottom coverage or more segments as needed. Do not assume unseen lower sections are correct.

For tall pages, the preferred verification pattern is:

• capture one full-page or tallest-practical screenshot artifact when tooling supports it, to understand overall vertical rhythm, section spacing, and macro composition across the whole document
• also capture segmented viewport screenshots that cover the page from top to bottom with intentional scroll positions
• visually inspect the segmented screenshots yourself; do not rely on the full-page artifact alone for lower sections, because tall captures can hide crowding, clipped text, sticky overlaps, or small alignment errors
• make sure the segmented set covers the entire page without leaving unverified gaps between scroll positions
• when a section is especially dense or fragile, add extra local screenshots for that region rather than assuming the nearest segment is sufficient

Treat the full-page screenshot as a macro-composition aid and the segmented screenshots as the authoritative visual inspection set for tall-page fidelity.

Pass 0 - viewport calibration

• Use the exact primary reference dimensions for the first comparison pass.
• Make sure the page is captured at the correct route/state and comparable scroll position.
• Do not judge fidelity from a different width and then claim a match.
• Keep viewport calibration honest: do not use CSS zoom, wrapper scaling, or screenshot-only transforms to force the composition into place.
• Prefer automation screenshots captured at explicit CSS viewport dimensions over visual judgment from a headed browser window.
• If headed mode is used for convenience, use it for interaction/debugging only; do not treat the live window as the authoritative fidelity check when a direct Playwright screenshot is available.

Pass 1 - macro composition

Check:

• overall page width and margins
• main vs sidebar width ratio
• hero split ratios
• card widths and heights
• chart, diagram, map, media, and table region width ratios inside their cards
• section spacing
• alignment of top nav, hero, filter area, table, and sidebar
• absence of horizontal overflow or suspicious whole-page shrink/stretch behavior
• no rows that appear denser, tighter, or more compressed than the reference

Pass 2 - typography and copy

Check:

• font family choice
• font size
• weight
• line height
• tracking
• text colour / opacity
• exact copy
• exact line breaks / wrapping
• no truncated, clipped, or visibly squashed text
• no copy mismatches in small labels, helper text, timestamps, badge text, placeholders, or table metadata

Pass 3 - iconography and control completeness

Check:

• every icon, logo, caret, bullet, dot, and star
• every navigation, sidebar, toolbar, and tab icon matched to the corresponding reference item
• every repeated table/list/card action icon, including whether each glyph has the same semantic meaning as the reference
• button leading/trailing icons
• search icon presence and placement
• inline helper icons
• stat-card icons
• missing micro-details

Pass 4 - colour and surface treatment

Check:

• gradients
• surface tints
• borders
• border opacity
• shadows
• glows
• pill fills
• badge colours
• table row separators
• muted text tones

Pass 5 - spacing and fine geometry

Check:

• paddings
• margins
• gaps
• border radii
• chip sizes
• input heights
• button heights
• row heights
• image crop framing
• chart plot-area bounds, axis/gridline placement, series shape, marker placement, legend spacing, and chart-footer geometry
• proportional diagram bounds, segment sizes, taper/step geometry, label placement, and adjacent metric spacing
• proportional diagram text containment: labels must not spill outside their intended segment unless the reference does the same
• icon size inside controls
• card and panel heights, especially when adjacent cards in the same row intentionally have different heights
• internal component vertical balance: charts, donuts, legends, footer links, and CTAs should sit at the same relative height as the reference
• no overlapping layers, clipped corners, or compressed control interiors
• no fields/buttons/selects that are narrower than the reference unless the screenshot clearly shows it
• alignment consistency across repeated components
• matched footer/button baselines across peer cards where the refere

…(truncated)