How KY Design-to-HTML Skill Turns a UI Screenshot into Precise HTML/CSS

Introduction

KY Design-to-HTML Skill is an AI skill for Codex and Claude that takes a UI screenshot or design mockup and generates a matching HTML/CSS page.

Demo: the author uploaded a screenshot (Figure 1) and the tool produced a page (Figure 2) using the gpt‑5.3 model, showing good visual fidelity.

Why Direct Screenshot‑to‑Page Fails

Attempting to make an LLM do three tasks at once leads to poor quality:

Understanding layout logic – grid, alignment, nesting.

Reproducing visual details – colors, fonts, spacing, shadows.

Creating complex assets – drawing logos, adjusting illustrations.

Doing all three simultaneously usually degrades results.

Solution: Task Decomposition

KY Design-to-HTML splits the work into a pipeline:

识别结构 → 分类素材 → 定义画布 → 写代码 → 验证效果 → 循环改进

Core Workflow

Step 1: Page Decomposition

AI scans the design and produces a skeleton map of regions, components, and color schemes.

Step 2: Asset Classification

AI decides whether each element (e.g., a logo) should be rendered with CSS or kept as an image, based on whether CSS can faithfully reproduce it.

Step 3: Canvas Adaptation

Define reference dimensions (e.g., original 2048×1243 px) and display mode (scale vs. stretch) to avoid distortion on different screens.

Step 4: Code Generation

AI writes HTML and CSS for the elements identified in previous steps, avoiding unnecessary token usage on image generation.

Step 5: Screenshot Verification

Run the generated code in a real browser, capture a screenshot, and compare it with the original design to spot mismatches.

Step 6: Iterative Fixes

Identify discrepancies (e.g., font size, spacing), let the AI adjust the code, re‑capture, and repeat until the result matches the design.

Most AI design tools stop after step 4; KY Design-to-HTML forces steps 5‑6, providing quality assurance.

File Structure

ky-design-to-html/
├── SKILL.md                # Main skill definition
├── agents/
│   └── openai.yaml         # OpenAI agent config
├── references/
│   ├── asset-handling.md  # Asset handling guide
│   └── visual-error-taxonomy.md
└── scripts/
    └── screenshot_page.py # Screenshot verification script

Installation & Usage

Codex Installation

git clone https://github.com/KyrieCheungYep/ky-design-to-html-skill && cd ky-design-to-html-skill
cp -r ky-design-to-html ~/.codex/skills/ky-design-to-html

Claude Installation

git clone https://github.com/KyrieCheungYep/ky-design-to-html-skill && cd ky-design-to-html-skill
cp -r ky-design-to-html ~/.claude/skills/ky-design-to-html

Running the Skill

In Codex or Claude send a prompt such as:

使用 ky-design-to-html，把这张 UI 截图还原成一个 HTML/CSS 页面。 截图见：你的图片路径

Attach the design screenshot and the skill returns the generated page.

Practical Scenarios

Scenario 1: Rapid Marketing Landing Page

Traditional workflow requires designer hand‑off, manual slicing, multiple CSS revisions, often taking two days. With the skill the flow becomes design → upload → code → tweak → publish.

Scenario 2: SaaS Backend Page Reconstruction

When an internal system has UI mockups but no front‑end code, the skill can quickly generate a functional base, saving repetitive work.

Limitations & Considerations

Requires a visual reference; pure text descriptions are unsupported.

Runs with low permissions; it does not install dependencies or modify global settings.

Screenshot verification needs a browser or Playwright.

Complex logos or illustrations must be supplied as assets; the tool does not generate them.

Responsive support defaults to desktop unless mobile adaptation is requested.

Conclusion

KY Design-to-HTML provides a quality‑managed AI design pipeline: clear step‑by‑step process, enforced screenshot verification, and automatic correction loops, making it valuable for anyone who frequently needs to turn design mockups into production‑ready HTML/CSS.

Reference

GitHub: https://github.com/KyrieCheungYep/ky-design-to-html-skill