UI From Image

ui-from-image is a Codex skill for turning one or more concept images into a high-fidelity frontend implementation.

In the common workflow, the input image is a UI concept generated by ChatGPT or GPT-Image. That generated image is then treated as the visual source of truth for building the real webpage in HTML, CSS, and JavaScript, or for adapting the design inside an existing frontend codebase.

The skill is designed for cases where "roughly similar" is not enough and the goal is to reproduce layout, typography, spacing, iconography, colour, and responsive behavior as closely as possible.

What This Skill Does

• recreates a webpage or app UI from screenshot references
• works for standalone pages or adaptation inside an existing frontend codebase
• prioritizes exact reference-viewport matching before responsive refinements
• requires explicit verification passes for typography, spacing, iconography, and layout fragility
• handles missing assets with supplied files, direct image_gen generation for missing raster assets when available, or placeholders plus standalone asset-generation prompts

Repository Contents

• SKILL.md: the main skill instructions and definition of done
• AGENTS.md.template: repo-specific setup template for projects that use this skill
• agents/openai.yaml: agent registration metadata
• references/visual-qa.md: screenshot-based QA checklist
• references/asset-prompts.md: rules for placeholder handling and asset-generation prompts
• scripts/compare_screenshots.py: helper script for producing screenshot diff artifacts

Dependencies And Tooling

The skill instructions themselves do not require the separate playwright Codex skill to be installed. ui-from-image can still be used to inspect references, implement UI, perform manual visual comparison, and report any verification limits.

For high-fidelity browser verification, some way to capture deterministic screenshots is strongly recommended. Suitable options include:

• the separate Codex playwright skill, when installed
• Playwright CLI or another Playwright setup already available in the target project
• another headless browser/screenshot workflow provided by the environment
• manual screenshots as a fallback, with any limitations reported clearly

The bundled screenshot diff helper is optional. It requires Python plus Pillow:

pip install pillow

If Pillow is unavailable, the skill still works; compare screenshots manually or use another available image-diff tool.

Core Workflow

1. Inspect the reference image and inventory all meaningful visual elements before coding.
2. Reuse existing components, tokens, fonts, and layout patterns when adapting an existing project.
3. Build the first pass to match the primary reference viewport as closely as possible.
4. Capture an implementation screenshot at the same dimensions as the reference.
5. Compare the screenshots, write down mismatches, and iterate.
6. Verify responsive behavior only after the reference-size implementation is visually close.
7. Do not stop until remaining differences are minor and explainable.

Example Prompts

This skill is useful both for the initial implementation pass and for follow-up asset planning after the page exists.

Examples:

• $ui-from-image Implement the attached image to be an actual homepage for the website
• $ui-from-image Recreate this screenshot as a responsive landing page in the current project
• $ui-from-image Use the attached desktop mockup as the source of truth and build the real webpage from it
• $ui-from-image Are there any other assets we should make for this website?
• $ui-from-image Audit this implemented page against the mockup and tell me which additional images, logos, icons, or social assets would improve it
• $ui-from-image Based on this screenshot implementation, list the missing or optional assets we should create next, with filenames and dimensions

Example Assets

The repo can also hold a simple before-and-after example pair under examples/:

• concept-source.png: the original ChatGPT or GPT-Image concept image used as the source of truth
• implementation-full-page.png: the final full-height webpage screenshot created from that concept

This gives readers one concrete input example and one concrete output example for the skill.

Verification Standard

The skill expects explicit checks for:

• macro layout and composition
• typography and exact copy
• icon and control completeness
• colours, borders, shadows, and surface treatment
• spacing, radii, control sizing, and image framing
• responsive behavior across desktop, tablet, and mobile

The intent is to catch both major layout errors and small fidelity misses such as missing carets, clipped helper text, incorrect line breaks, or overly narrow controls.

Asset Handling

For each visible asset in the reference, the skill expects one of three paths:

• use the supplied asset and fit it accurately into the layout
• generate or edit missing raster assets with direct image_gen when the tool is available
• use a clearly labeled placeholder and provide a standalone generation prompt when generation is unavailable, fails, or the asset should not be invented

When image_gen is used, the skill instructs Codex to continue the same turn after generation, move or copy project-bound outputs from the default generated-images location into the workspace, integrate them into the implementation, and verify that they fit the layout. It does not require the separate imagegen or imagen skill to be installed. If image_gen is unavailable or fails, the fallback remains placeholders plus standalone asset-generation prompts.

Small UI icons are treated as part of fidelity, not optional decoration.

Standalone vs Existing Projects

For standalone work, the skill defaults to plain index.html, styles.css, and script.js unless the environment already includes a styling system the user wants to keep.

For existing applications, the skill is intended to adapt the current stack instead of introducing a parallel one. If Tailwind or DaisyUI already exist, they can be reused, but they are implementation tools rather than design authority.

Screenshot Diff Helper

The helper script can be used after capturing a reference screenshot and an implementation screenshot at the same dimensions:

python <path-to-codex-home>/skills/ui-from-image/scripts/compare_screenshots.py reference.png candidate.png --out-dir .codex-artifacts/ui-diff

Notes:

• compare same-size screenshots whenever possible
• use --fit only as a fallback diagnostic when dimensions are slightly off
• use the generated images and metrics to find mismatch hot spots, but rely on visual judgment for final decisions
• changed_pixel_pct uses a thresholded comparison so tiny anti-aliasing differences do not dominate the result

Run python <path-to-codex-home>/skills/ui-from-image/scripts/compare_screenshots.py --help to see all options, including --pixel-threshold.

Using This Skill In Another Repo

If you want a target project to provide better repo-specific guidance, copy or adapt AGENTS.md.template into that repo and fill in:

• package manager and standard commands
• framework and styling system
• component, icon, font, and asset locations
• reference viewport sizes
• screenshot capture workflow
• done criteria specific to that project

Intended Outcome

This skill is for high-precision UI recreation work. It is deliberately opinionated about verification because most failures in screenshot recreation are not functional bugs; they are small visual inaccuracies that accumulate into an obviously wrong result.