image-to-ui-skill

name	image-to-ui-skill
description	将 UI 截图或设计稿复刻为可点击前端/App demo，区分代码 UI 与真实位图资产。Use for image-to-UI, screenshot-to-code, clickable app/iOS prototypes, or faithful recreation; exclude image-only generation and reference-free UI polish.
category	developer-tools-integrations
tags	["image-to-ui","codex","frontend","prototype","image2"]
version	0.1.0
argument-hint	[ui-reference-image]
allowed-tools	Read, Write, Edit, Bash, Glob, Grep

Image to UI Skill

使用这个 skill，把 UI 参考图转成可执行的图片资产方案：先分析哪些区域需要生成图片，再生成、后处理，并集成回 UI。

本文件保留路由、核心生图边界与主流程；App/网页交付、UI 分析、字体、尺寸、提示词写法、抠图、集成、交互、审查、差距核对与最终交付报告等细则已下沉到 references/，按需读取(见文末「详细规则索引」)。

image2 生图优先规则

当用户明确要求“调用 image2 生图”“用 image2 复刻”“参考图片做高保真 UI”，或参考图的效果明显依赖摄影、插画、颗粒、半色调、像素噪点、复杂纹理、景深、真实材质、复杂岛屿/地图/角色等位图质感时，必须优先走真实的 image2 位图生成流程，而不是只用 HTML/CSS/SVG 做近似。

在这类任务里：

• 必须先判断哪些区域属于 必须真实生图，哪些区域属于 必须代码实现。
• 必须至少生成并落地一批真实位图资产后，才能声称“已经调用 image2”。
• 不要把“用 CSS 画了一个相似背景”“用 SVG 拼了插画”“用渐变和噪点近似了风格”描述成已经完成 image2 生图。
• 如果只是先做代码骨架，必须明确说明“当前仅完成结构 UI，还未真正调用 image2 生成资产”。
• 如果用户要的是高保真复刻，优先生成主视觉、路线插画、卡片缩略图、复杂背景纹理等高影响位图资产，再做 CSS 微调。

以下内容默认视为 应优先调用 image2：

• 首屏主视觉海景、人物、产品、摄影感场景
• 带颗粒、半色调、像素噪点、蓝晒/丝网印刷、扫描感的复杂插画
• 跳岛路线图中的岛屿插画、装饰地图、复杂海岸线和非标准装饰物
• 卡片缩略图、场景图、带统一美术风格的多张主题图
• 用代码实现会显著降低质感或极难逼近参考图的区域

以下内容默认 不要交给 image2：

• 标题、正文、价格、按钮文案、列表文案、标签、导航文字
• 常规按钮、输入框、卡片、分隔线、底部导航、常规 icon 容器
• 需要保持可访问、可翻译、可交互的 UI 文本

image2 调用边界

本 skill 里的 image2 指项目指定的 image2 调用入口，不等同于任意图片生成工具。当前 skill 也包含一个备案通道：当原生 image2 命令不可用或失败时，scripts/image2_asset.py 会在备案前置条件满足时自动转到 OpenRouter ICU gpt-image-2(前置条件见下方「备案通道前置条件」)。若前置条件不满足，脚本会以非零码明确报错，此时必须如实说明尚未生图，不得声称已落地位图。

执行时：

• 在任何真实生图前，先按 references/image2-entrypoint.md 确认当前项目的 image2 调用入口和备案通道。
• 优先调用本 skill 的 scripts/image2_asset.py，不要自己重写 API 请求。
• scripts/image2_asset.py 会先尝试原生 image2 命令或 IMAGE2_COMMAND 环境变量；失败后自动调用 openrouter-icu-image/scripts/openrouter_icu_image.py，模型固定默认为 gpt-image-2。
• 可以把 OpenRouter ICU gpt-image-2 记为“image2 备案通道”或“fallback 通道”，但最终必须说明实际走的是 native-image2 还是 openrouter-icu-gpt-image-2。
• 不要把 imagegen skill、其它图片生成插件、随机在线生图服务或手写 SDK 请求当作本 skill 的 image2/fallback 通道。
• 如果原生 image2 和 OpenRouter ICU fallback 都不可用，再停止并说明缺少可用生图入口；不要声称已经生图。
• 可以继续实现代码 UI 骨架，但必须明确标注“尚未完成真实位图资产生成”，不能把代码近似、CSS/SVG 视觉或其它来源图片写成 image2 结果。

备案通道前置条件

OpenRouter ICU gpt-image-2 备案通道并非无条件可用。scripts/image2_asset.py 走 fallback 需要同时满足：

• 能定位 OpenRouter ICU CLI:在本 skill 同级目录安装 openrouter-icu-image skill(脚本默认查找 openrouter-icu-image/scripts/openrouter_icu_image.py),或显式设置 OPENROUTER_ICU_IMAGE_CLI 指向该脚本。本仓库默认不附带该兄弟 skill，需要时另行安装或配置。
• 凭据可用:设置 OPENROUTER_ICU_API_KEY 或 OPENAI_API_KEY。

任一前置条件不满足时，脚本会以非零码报错(例如 OpenRouter ICU fallback CLI not found，或提示需要配置 API key),不会产出位图。此时按下文「真实生图验真」与 references/image2-entrypoint.md 的「找不到入口时怎么办」处理:完成 UI 拆解、资产清单、提示词与代码骨架，明确标注“尚未完成真实位图资产生成”,不得用 CSS/SVG 代码近似冒充 image2 结果。

生图命令

下列命令中的 <skill-dir> 是 skill 加载时公布的实际根目录。请替换为字面路径；它不是环境变量。Git Bash 使用 python，Windows PowerShell 找不到 python 时将其替换为 py -3。

文本生图：

python "<skill-dir>/scripts/image2_asset.py" generate \
  --prompt "为 App 首屏生成一张无文字、无 logo 的高级时尚产品主视觉，留出左侧文案空间，柔和自然光，4:3" \
  --output "public/generated/hero-main.png" \
  --size 1536x1024 \
  --quality medium \
  --output-format png

参考图编辑或多图参考：

python "<skill-dir>/scripts/image2_asset.py" edit \
  --image "reference.png" \
  --prompt "保留参考图主体轮廓和色彩气质，生成无文字、无 logo 的 UI 卡片缩略图，适合 3:2 裁切" \
  --output "public/generated/card-visual.png" \
  --size 1536x1024 \
  --quality medium \
  --output-format png

强制只测试原生 image2：

python "<skill-dir>/scripts/image2_asset.py" generate \
  --prompt "test image" \
  --output "output/generated/test.png" \
  --prefer image2

强制走备案通道：

python "<skill-dir>/scripts/image2_asset.py" generate \
  --prompt "test image" \
  --output "output/generated/test.png" \
  --prefer fallback

OpenRouter ICU fallback 需要 OPENROUTER_ICU_API_KEY 或 OPENAI_API_KEY 可用。脚本会用当前 Python 运行已安装的 OpenRouter ICU CLI，不使用 py -3。

image2 最小闭环

当任务触发 image2 流程时，至少完成这个闭环：

1. 从参考图中拆出必须生图的资产类别。
2. 为每个资产或同风格资产组编写可执行提示词。
3. 实际调用 scripts/image2_asset.py，优先原生 image2，必要时自动备案 OpenRouter ICU gpt-image-2，产出真实位图文件。
4. 必要时做裁切、切片、透明化、尺寸修正或导出不同槽位版本。
5. 将生成结果接回前端页面，而不是只停留在“生成了一张图”。
6. 打开真实页面截图，验证这些资产已经被渲染，而不是停留在本地文件夹。
7. 在最终汇报里列出生成资产路径，并明确说明哪些视觉区域已经改为真实生图。

如果上述 1-7 没完成，不要把任务描述成“已用 image2 完成复刻”；应准确描述为“已完成部分生图”或“仅完成生图准备”。

核心流程

1. 在编辑代码或生成图片之前，先检查用户提供的每一张 UI 参考图。
2. 将 UI 拆分为：
   • 代码渲染 UI：布局、文字、按钮、卡片、简单渐变、边框、阴影、开关、表单、图表和重复组件。
   • 图标资产：优先使用项目已有图标库或 lucide 风格矢量图标。只有当图标是自定义插画式标记，且设计系统无法表达时，才生成图标。
   • image-to-ui 图片资产：照片、插画、产品渲染图、角色、复杂纹理、复杂首屏背景、真实物体、App 展示图、装饰性位图，以及用代码复刻会脆弱或低质的视觉内容。
   • 抠图资产：需要透明 PNG/WebP、遮罩或去背景的前景人物、产品、物体。
3. 先输出前期审查文档，说明哪些元素好还原、哪些元素不好还原、哪些需要生成图片、哪些需要用户确认；如果用户已经明确要求“直接做”或“直接复刻”，可以跳过等待，但仍要先在内部完成这一步拆解。
4. 等用户确认关键问题后，再进入生图；如果用户明确要求“直接继续”，可以用合理假设继续，但要记录假设。
5. 生成前输出资产清单。清单要包含资产 id、UI 位置、目标槽位尺寸、导出尺寸、宽高比、生成提示词、后处理需求、集成目标，以及“是否必须真实 image2 生图”的判断。
6. 只生成真正需要位图生成的资产。结构性 UI、可读文字和普通控件继续用代码实现。
7. 对需要统一风格的一组资产，优先考虑“一次生成统一资产板，再切片导出”的方案，减少风格漂移。
8. 按需做后处理：裁剪、缩放、去背景、添加 alpha、压缩和尺寸验证。
9. 将生成资产集成到 UI 中，使用稳定尺寸、object-fit、响应式约束、alt 文本和必要的懒加载。
10. 给页面补齐可点击行为和跳转逻辑：明显的按钮、链接、返回/关闭、卡片、标签、导航项都要有真实交互；多屏参考图要自动串成可流转原型。
11. 对完整页面做最终审查：检查尺寸、乱码、排版、响应式、图片嵌入、代码 UI 的融合和交互跳转是否自然。
12. 将最终页面截图与原始 UI 参考图做差距核对，列出差异，修正后再次截图对比。
13. 如果目标是前端应用，最后用渲染截图和点击路径验证效果，并确认截图里真实出现了 image2 资产。

确认 image2 调用入口、判断能否真实生图时，读取 references/image2-entrypoint.md。构建资产清单、编写 image-to-ui 提示词、计算输出尺寸或规划抠图/去背景时，读取 references/asset-manifest-and-prompts.md。

当用户要把社媒视觉热点、INS/Pinterest 小趋势或图像创作工具做成可用网页，并关心上线验证、传播数据或技术社区案例时，可读取 references/hicolor-case-study.md 作为真实项目参考。

真实生图验真

如果任务涉及 image2，最终必须输出一段“生图验真”信息，至少包含：

• 实际生成了哪些资产
• 每个资产的落地路径
• 每个资产实际使用的通道：native-image2 或 openrouter-icu-gpt-image-2
• 哪些页面区域已经替换为真实位图
• 哪些区域仍然是代码近似
• 用什么截图或页面验证方式确认这些资产已经显示

禁止出现以下误导性表述：

• “已按 image2 流程完成”，但没有任何新生成位图文件
• “已经生图”，但图片没有接入页面
• “已经高保真复刻”，但复杂视觉仍全部由 CSS/SVG 临摹

如果页面仍主要依赖代码近似，必须明确写成：

• “当前为结构复刻版，尚未完成真实 image2 资产替换”
• 或 “当前仅首页主视觉已接入生图，其余区域仍待补齐”

详细规则索引

以下细则均从本 skill 下沉到 references/，内容与此前 SKILL.md 一致，按需读取：

• references/image2-entrypoint.md — 确认 image2 调用入口、备案通道与生图后的验真记录。
• references/asset-manifest-and-prompts.md — 前期审查模板、资产清单模板、image2 提示词模板、页面级检查清单。
• references/delivery-app-and-web.md — App 形式触发规则(iOS 外边框、Dynamic Island、可点击预览、截图验真)与网页交付默认规则。
• references/integration-rules.md — UI 分析规则、字体识别与加载、尺寸规划、image-to-ui 提示词写法、抠图与去背景、集成规则、交互与跳转。
• references/review-and-gap-check.md — 前期审查与确认、常见风险与防护、页面级审查、原图差距核对与迭代、最终交付报告。
• references/hicolor-case-study.md — 把社媒视觉趋势做成可上线网页的真实项目案例。
• references/fashion-shopping-app-case-study.md — 女装购物 App 的风格参考、多屏复刻与展示 mockup 案例。
• references/museum-app-case-study.md — 博物馆多屏移动端 UI 的还原、串联与交付案例。