Image to UI Skill

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

image2 生图优先规则

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

在这类任务里：

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

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

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

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

• 标题、正文、价格、按钮文案、列表文案、标签、导航文字
• 常规按钮、输入框、卡片、分隔线、底部导航、常规 icon 容器
• 系统状态栏、信号/Wi-Fi/电量、返回/关闭/设置/菜单、加减号、电源、播放控制、底部 tab、quick action、开关、状态点和其它小型 UI glyph
• 需要保持可访问、可翻译、可交互的 UI 文本

image2 调用边界

本 skill 把生图入口分成两类、三种来源，执行和汇报时必须分清：

• native-image2 / source=system-imagegen：当前 Codex 工具面如果暴露内置 image_gen，按 .system/imagegen skill 的 built-in 模式生成普通位图资产。它在本 skill 中算原生 image2。
• native-image2 / source=project-image2：项目显式提供的 image2 命令、IMAGE2_COMMAND，或本 skill 的 scripts/image2_asset.py 成功走原生命令。
• API 备案层：native-image2 不可用或失败时，scripts/image2_asset.py 自动调用本机 Youtoken/OpenRouter ICU 兼容 CLI，模型默认为 gpt-image-2，最终标记为 youtoken-gpt-image-2 或 openrouter-icu-gpt-image-2。

image2-ui doctor 是 shell 诊断命令，只能检测系统 imagegen skill/CLI 文件、项目 image2 命令和 API 备案 CLI/密钥。内置 image_gen 是否在当前会话工具面可直接调用，必须由 agent 根据已暴露工具判断；不要把 shell 检测不到内置工具误判成系统 imagegen 不算 native-image2。

执行时：

• 在任何真实生图前，先按 references/image2-entrypoint.md 确认当前项目的 image2 调用入口和备案通道。
• 如果用户说“找不到 image2”“检索不到 image2 生图”“没有真的生图”，先运行 image2-ui doctor 或 python scripts/image2_asset.py doctor，再决定用 native-image2 还是备案通道。
• 如果当前会话工具面暴露系统内置 image_gen，并且任务只是普通 UI 位图资产生成，可以按 imagegen skill 使用系统 imagegen；生成后必须把最终文件移动或复制到项目资源目录，并标记 native-image2，来源写 source=system-imagegen。
• 对需要可复跑命令、可诊断通道或用户明确说“image2”的任务，优先调用本 skill 的 scripts/image2_asset.py，不要自己重写 API 请求。
• scripts/image2_asset.py 会先尝试原生 image2 命令或 IMAGE2_COMMAND 环境变量；失败后自动发现 youtoken-image 或 OpenRouter ICU 兼容 CLI，模型固定默认为 gpt-image-2。
• 可以把 Youtoken/OpenRouter ICU gpt-image-2 记为“image2 备案通道”或“fallback 通道”，但最终必须说明实际走的是 native-image2、youtoken-gpt-image-2 还是 openrouter-icu-gpt-image-2；如果是 native-image2，同时说明 source=system-imagegen 或 source=project-image2。
• .system/imagegen/scripts/image_gen.py 只在用户明确要求 CLI/API/model path，或系统 imagegen skill 规则允许且用户确认时使用；如果用了它，最终仍可标记为 native-image2，来源写 source=openai-imagegen-cli。
• 不要把其它图片生成插件、随机在线生图服务或手写 SDK 请求当作本 skill 的 image2/fallback 通道，除非用户明确要求作为替代方案。
• 如果 native-image2 来源都不可用或不适合，且备案通道也不可用，再停止并说明缺少可用生图入口；不要声称已经生图。
• 可以继续实现代码 UI 骨架，但必须明确标注“尚未完成真实位图资产生成”，不能把代码近似、CSS/SVG 视觉或其它来源图片写成 image2 结果。

生图命令

需要可复跑、可诊断的项目资产时，使用本 skill wrapper：

文本生图：

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

参考图编辑或多图参考：

python 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 scripts\image2_asset.py generate `
  --prompt "test image" `
  --output output\generated\test.png `
  --prefer image2

强制走备案通道：

python scripts\image2_asset.py generate `
  --prompt "test image" `
  --output output\generated\test.png `
  --prefer fallback

诊断当前入口：

python scripts\image2_asset.py doctor

也可以用全局命令：

image2-ui doctor

Youtoken/OpenRouter ICU fallback 需要 YOUTOKEN_IMAGE_API_KEY、OPENROUTER_ICU_API_KEY、OPENAI_API_KEY 或 ~/.codex/youtoken-image.env 可用。脚本会用当前 Python 运行已安装的兼容 CLI，不使用 py -3。系统 .system/imagegen 的 built-in image_gen 由当前 Codex 工具面决定，不由这个 shell wrapper 直接调用；在本 skill 中它算 native-image2 的 source=system-imagegen。

image2 最小闭环

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

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

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

App 形式触发规则

当用户说“做成 App 形式”“手机 App”“iOS 预览”“App demo”“移动端原型”“可点击 App”或参考图明显是手机应用界面时，默认按 App 原型交付，而不是只生成裸页面。

必须做到：

• 生成一个带 iOS 手机外边框的预览容器，包含圆角黑色机身边框、顶部状态栏、安全区和类似 Dynamic Island 的顶部开孔；参考图如果已经有手机壳/边框，优先保持同类观感。
• App 页面内容放在手机屏幕内部，使用固定设计画布或等比例缩放方案，避免窗口变窄时文字、按钮、插画和状态栏重叠。
• 所有明显按钮、关闭/返回、底部导航、卡片、选项、Next/Continue 等控件都必须可点击；单屏也要有选中态、切换态、反馈态或模拟跳转。
• 提供可在浏览器打开的可点击预览版本，并在完成前用浏览器实际点击主要路径。
• 产出至少一张渲染截图，截图必须能看到完整 iOS 外边框和屏幕内 App 页面；最终说明中写明截图路径或验证方式。
• 最终回复必须直接嵌入渲染截图，并给出本地预览 URL、项目根目录、demo 目录和可打开的 HTML 文件路径；不能只说“已截图”或只给 localhost。
• 外边框、状态栏、电量/Wi-Fi/信号等系统装饰可以用代码实现；不要把可读 App 文案烘焙进图片。
• iOS 状态栏图标必须截图放大检查：信号、Wi-Fi、电量不能画成可读字母、乱码或伪文字。优先用内联 SVG、图标库或明确几何图形，不要用看起来像 U、C、O 的 CSS 边框近似。
• Demo 交付必须能离线打开主要界面；图片、插画和缩略图要落地到项目本地资源目录，不要把远程图片 URL 当作最终资产交付。
• 复杂 App demo 应提供可复跑的验证方式，例如项目内验证脚本或明确的命令，覆盖页面启动、截图生成、主要点击路径和破图检查。

如果没有完成 iOS 外边框、可点击预览和截图验证，不要把结果描述成“已做成 App 形式”。

网页交付默认规则

当用户要求复刻 UI、参考截图做 demo、做 App 形式、做网页预览、可点击预览或高保真还原时，默认最终交付物必须是一个可在浏览器打开的网页/demo，而不是只返回图片、截图、说明文档或生成资产。

执行时：

• 至少创建或更新一个入口 HTML/前端页面，并确保它能本地打开或通过本地 dev server 访问。
• 截图只能作为验收证据，不能替代网页/demo 本身。
• 如果任务里生成了图片资产，必须把图片资产接回网页；不要只把图片留在文件夹里。
• 最终回复必须给出可打开的预览 URL 或入口 HTML 文件路径，并同时给出项目根目录和 demo 目录。
• 如果因为环境限制暂时只能完成截图或资产准备，必须明确说明“尚未完成网页交付闭环”，不能把它描述成已完成可预览 demo。

设计规范、图标与排版

本 skill 吸收 Impeccable 的设计质量思路，但不复刻它的命令体系。目标是让 image-to-UI demo 既像参考图，又不像模板化 AI 页面。执行时先判断页面属于哪种语境：

• 产品 / 工具 / Dashboard / App UI：设计服务任务。优先熟悉、可信、密度稳定、组件一致；少装饰，重状态和可用性。
• 品牌 / 落地页 / Portfolio / 视觉传播页：设计本身是交付。必须有明确视觉立场、图片或强主视觉、节奏变化和非模板化构图。

基础设计约束

• 正文和重要按钮文字必须有足够对比度：普通文字按 4.5:1，较大文字按 3:1 作为底线；浅灰字叠在浅色或彩色背景上通常要加深。
• 不要使用模板化渐变文字、无意义玻璃卡片、紫蓝霓虹默认配色、奶油/沙色整页默认底色、侧边粗色条卡片、英雄区大数字指标模板、反复出现的小号大写 eyebrow 或每节 01/02/03 编号。
• 卡片只用于确实独立、可点击或需要分组的内容；不要把每个区块都包成卡片，不要卡片套卡片。
• 避免“同尺寸 icon + heading + paragraph”的重复卡片网格铺满页面。需要功能列表时，用不同密度、列表、对比布局、分组标题、真实截图或生成图打破单调。
• 产品 UI 默认克制配色，一个主 accent 用于主操作、选中态和状态提示；品牌页可以更大胆，但必须来自参考图、品牌语气或明确的色彩策略。
• 动效只服务状态、层级或叙事：150-250ms 的产品反馈、必要的页面过渡或品牌首屏动效。不要让内容依赖 scroll reveal 才可见；必须支持 prefers-reduced-motion。

图标规则

• 简单功能图标、状态栏 glyph 和 App chrome 必须统一走代码图标系统；不要为了普通关闭、返回、搜索、下载、保存、收藏、播放等图标调用 image2。
• 允许作为统一外部图标库的包只有：@phosphor-icons/react、hugeicons-react、@radix-ui/react-icons、@tabler/icons-react。新 demo、新项目和新写 UI 必须从这四者中选一套。已有项目如果已经固定使用其它主图标库，只在低风险维护任务中作为例外沿用；不能再混入第二套，最终要记录这个例外。
• 在写 UI 前先做 icon inventory：检查 package.json、组件库、src/components、assets/icons、SVG sprite、现有按钮/导航组件，确认项目已经使用哪套 icon。已有一套就沿用；没有时再按 references/icon-system.md 选择一套，不要同时引入第二套图标语言。
• 同一界面只能使用一套图标语言和一个统一调用入口：React 项目建立 UiIcon / IconRegistry，纯 HTML demo 建立 SVG sprite 或 icon() helper。不要在各处散落不同来源的 SVG path。
• 常规图标视觉尺寸通常为 16-24px；底部导航和工具栏可到 24-28px。图标按钮的点击区域必须至少 44x44px，即使图标本体更小。
• 图标按钮必须有 aria-label、可见 tooltip 或旁边可读文本；不要只放一个无语义 SVG。
• 不要把图标放进统一的大圆角彩色方块作为默认套路。只有参考图或设计系统明确需要 icon tile 时才使用；否则让图标直接服务导航、按钮或信息层级。
• 不要手搓复杂 SVG 路径当作图标库替代品；只有库内没有、但必须复刻的极简单系统几何符号，才允许放进同一个 IconRegistry / SVG sprite 作为本地补位，不能散落在业务组件中。
• 自定义品牌符号、复杂插画式徽章、主题贴纸、地图标记、手绘装饰或无法用图标库稳定表达的图形，才进入 image2 资产候选；这些资产也不能承担返回、设置、导航、播放等交互图标职责。
• 区分 设备产品图 / 物体缩略图 和 UI glyph：设备卡片里较大的台灯、摄像头、音箱、电视、空调外机等真实物体展示，应作为 device-product-image 或 object-cutout 图片资产处理，可以用 image2 生成；不要用图标库大图标冒充产品图。只有导航、状态、按钮、开关、tab、quick action 和小尺寸语义标识才属于 code icon。
• 判断图片是不是 icon 时按角色而不是名称：先看它是否在状态栏、导航、按钮、tab、播放器、quick action、开关或小尺寸状态符号中承担交互/语义 glyph；再看它是否是卡片主图、设备外观、商品/人物/物体抠图、照片缩略图或场景图。camera、lamp、speaker 这类词在小按钮里是 code icon，在设备卡片主视觉里是 image2 图片资产。
• 图标要做视觉居中而非机械居中：播放三角、箭头、Wi-Fi、电池、信号等小图要放大检查，避免看起来像字母、乱码或伪文字。

图标系统落地

对 App / 产品 UI，图标完整度来自可复用的代码图标系统，而不是一张张临时画。实现时按这个顺序：

1. 复用已有：如果项目已稳定使用四个允许库之一，优先使用它，并记录实际来源。如果项目混用了多套，选择覆盖 UI glyph 最完整的一套作为主库，逐步把新写 UI 收敛到这一套。
2. 缺省选择一套：没有既有图标集时，为 React/Next 项目从 @phosphor-icons/react、hugeicons-react、@radix-ui/react-icons、@tabler/icons-react 里选一套；纯 HTML/CSS/JS demo 则建立一个小型 Icon/icon() 工具或 SVG sprite，集中定义所有 glyph，不要在每个按钮里随手复制不同风格 SVG。
3. 建立图标 token：统一 size、stroke-width、linecap/linejoin、按钮 hit area、active/disabled/selected 颜色和光学偏移。播放三角通常右移 1px，箭头向指向方向微移，电池/Wi-Fi/信号用明确几何形，不用字母状边框凑。
4. 列 coverage 表：对智能家居、播放器、设置、设备面板等场景，先列出需要的 glyph，再映射到图标库名称或本地 SVG id。缺失的 glyph 用同一图标语言补齐，不交给 image2。

智能家居 / 设备控制 App 至少覆盖这些 code icons：back、more、settings、plus、minus、power、play、previous、next、volume、thermometer、zap、snowflake、flame、wind/fan、droplet、home、lamp、camera、speaker、tv、air-conditioner、battery、wifi、signal。没有同名图标时使用最接近语义，但必须保持同一风格。

UI Glyph 锁定规则

image2 很容易把小图标画成错位、伪字母或乱码。复刻 App、仪表盘、智能家居、音乐播放器、设备控制面板时，必须把 UI glyph 从生图职责里剥离出来。

• 禁止用 image2 生成：iOS/Android 状态栏、电量、Wi-Fi、信号、返回箭头、关闭、设置齿轮、三点菜单、加号/减号、电源、播放/暂停/快进、底部导航图标、分段控件图标、quick action 图标、设备类型小图标、开关、状态点、进度条端点和 icon-only button。
• 必须用代码渲染：上述所有 glyph、icon button、状态栏和导航 chrome。优先用项目图标库；没有合适图标时，用同一套线宽的内联 SVG 几何形或 CSS 几何形，并放大检查视觉居中。
• 必须统一调用：状态栏、返回箭头、菜单、播放器、底部 tab、quick action、开关、设备小图标等 UI glyph 必须从同一个 UiIcon / IconRegistry / SVG sprite 出来，背后只允许使用一套图标库。
• 智能家居参考图拆分：客厅照片、设备产品图、材质背景、真实物体缩略图、产品/物体抠图可以是 image2 候选；温度/电量/功耗文字、状态栏、返回/更多/加号、播放器控制、quick action、底部导航、卡片标签、小型状态符号和开关状态必须是代码。设备卡片里用于展示真实设备外观的大图不是 icon，不能用 glyph 替代，也不能被 validator 当作 raster icon 误报。
• image2 提示词必须显式排除 UI glyph：no icons, no UI symbols, no system status bar, no battery/Wi-Fi/signal glyphs, no arrows, no gear, no menu dots, no plus/minus, no playback controls, no buttons, no labels, no text, no logo, no watermark。
• 最终截图必须放大检查状态栏、底部导航、工具栏、卡片内小图标和 icon-only buttons；如果任何 glyph 像错位字母、乱码、伪文字或模型生成残影，先改成代码渲染再交付。

排版与画面布局

• 建立清晰的空间尺度，优先使用 4pt 系列或项目已有 spacing tokens。相关元素 8-12px 紧密分组，不同组和区块 48-96px 分隔；不要所有间距都一样。
• Flex 用于一维排列，Grid 用于二维结构；响应式卡片网格优先 repeat(auto-fit, minmax(280px, 1fr)) 或内容驱动断点。
• 产品 UI 使用固定 rem 字号尺度，比例通常更紧；品牌/内容页可让标题用有边界的 clamp()，但正文保持稳定可读。
• 正文最小 16px，长文本宽度控制在约 45-75ch；标题使用 text-wrap: balance，长正文可用 text-wrap: pretty。
• App 截图复刻允许缩放后的微型 UI 字号，但卡片、设备 tile、播放器和 quick action 里的可见文本不能小到像伪字。一般不要在 70-90px 高的卡片里同时显示设备数、设备名、房间位置、状态和说明；保留设备名、一个短状态/数量和开关即可。房间位置、楼层、完整说明可以放到 aria-label、title、详情页或 hover/focus 文案里。
• 设备卡片内 8px 以下的可见文字默认视为 dense-micro-text 风险。除非参考图要求且截图放大后仍清晰，否则隐藏非必要元信息或扩大卡片，而不是硬塞多行小字。
• 字体最多 2-3 个家族；产品 UI 通常一个清晰 sans 就够。品牌页选字体要服务语气，避免无理由默认 Inter/Roboto 或一切“高级”都用 display serif。
• 按钮、卡片、标题和导航文字必须能容纳更长文本；给翻译和用户输入预留 30-40% 扩展空间。Flex/Grid 子项需要 min-width: 0 防止溢出。
• 移动端不是缩小桌面：单列优先、44x44px 触摸目标、底部或简化导航、safe area、不要依赖 hover；平板通常需要单独考虑两列或主从布局。
• 用截图做“眯眼测试”：2 秒内能否看出主行动、次级内容和分组；看不出时，先调整空间、字号、字重和位置，而不是加更多装饰。

页面输出巡检闭环

交付可点击 demo 前，要把页面当成“成品”做一次自动巡检和人工复核。这个闭环服务于 image-to-UI 还原，不是通用前端 lint；重点检查页面是否真的可看、可点、可验收。

优先运行本 skill 自带脚本：

image2-ui validate ./demo/my-output --reference ./reference.png

也可以对任意本地 demo 目录运行。image2-ui validate 会调用本 skill 的 scripts/ui_output_audit.mjs：先做静态检查；如果当前环境能加载 Playwright，会自动打开浏览器补充渲染检查。如果命令尚未安装到 PATH，可从 skill 目录运行 node scripts/image2-ui validate ... 或用 npm link 暴露 package.json 里的 bin。不要把这个命令、规则或输出描述成来自其它项目。

如果已经有参考图和当前渲染截图，继续生成对照板：

image2-ui compare --reference ./reference.png --actual ./screenshots/output.png --out ./screenshots/reference-output-compare.png

image2-ui compare 会生成左右对照、半透明 overlay 和人工核对清单。它不替代 validate，而是用来快速看出手机比例、垂直位置、页面间距、状态栏、返回/菜单、播放器、quick action、开关、设备产品图和微型文字与原图的差距。PNG 输出会尝试调用本机 Chrome；没有 Chrome 时保留 HTML 对照板。

巡检至少覆盖：

• 结构与资产：入口 HTML、CSS/JS、本地图片引用、远程资源依赖、空文件、破图和未落地的 image2 资产。
• 渲染稳定性：桌面端和移动端是否有控制台错误、横向滚动、空白首屏、图片未加载和布局跳动。
• 文字与可读性：按钮/卡片内文字是否溢出，正文是否被遮挡，关键文本对比度是否过低。
• 微型伪字风险：设备卡片、tile、播放器和 quick action 内是否有 8px 以下可见文本、过多短标签或多行元信息挤在一起；这类内容在截图里容易变成乱码/伪字，应改成更少、更大的真实文本。
• 审美反模式：明显模板化渐变文字、过度紫蓝/奶油/沙色/灰蓝单一配色、卡片套卡片、重复 icon-card 网格、过重阴影、无意义大圆角、粗侧边色条和背景装饰滥用。
• 图标与控件：SVG/icon button 是否有可访问名称，触摸目标是否过小，导航/工具栏图标是否风格一致，普通 icon 是否被误做成生图资产。
• 图标系统：是否完成 icon inventory、是否混用了多套 icon 技术、是否出现圆角 icon tile 堆在标题上、是否用位图 <img> 当按钮/nav 小图标、是否缺少 44x44px hit area、真实渲染中的 SVG 是否在按钮/导航/状态栏/播放器/quick action/开关容器里视觉居中。
• 交互验收：主要 CTA、返回/关闭、导航、卡片、标签页和末级按钮要有点击反馈、路由变化、选中态变化或内容变化。
• 参考图差距：如果提供 --reference，记录参考图路径，并在截图复核时把当前实现与参考图逐区对照；如果已有输出截图，运行 image2-ui compare 生成可分享的对照 PNG/HTML。

巡检输出要转化为修正动作：fail 先修，warn 视影响修，info 记录取舍。最终汇报里写清楚巡检是否通过、剩余问题和验证命令；不要只说“看起来没问题”。

核心流程

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

确认 image2 调用入口、判断能否真实生图时，读取 references/image2-entrypoint.md。构建资产清单、编写 image-to-ui 提示词、计算输出尺寸、规划抠图/去背景或执行页面输出巡检时，读取 references/asset-manifest-and-prompts.md。规划 App 状态栏、返回箭头、菜单、播放器、底部 tab、quick action、开关、设备小图标等 UI glyph 时，读取 references/icon-system.md。

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

真实生图验真

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

• 实际生成了哪些资产
• 每个资产的落地路径
• 每个资产实际使用的通道：native-image2、youtoken-gpt-image-2 或 openrouter-icu-gpt-image-2；如果通道是 native-image2，同时记录来源 source=system-imagegen、source=project-image2 或 source=openai-imagegen-cli
• 哪些页面区域已经替换为真实位图
• 哪些区域仍然是代码近似
• 用什么截图或页面验证方式确认这些资产已经显示

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

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

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

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

前期审查与确认

当用户先提供 UI 图、首页参考图或视觉参考图时，先交付一份前期审查文档，不要立刻生图，除非用户明确要求直接生成。

前期审查文档必须包含：

• 整体判断：页面类型、主要视觉风格、核心布局、首屏重点和潜在实现风险。
• 好还原元素：适合用代码直接实现的结构，例如文本、按钮、卡片、导航、表单、简单图标、常规阴影和简单背景。
• 中等难度元素：需要结合 CSS、图标库、少量图片或响应式裁剪才能还原的区域。
• 不好还原元素：复杂插画、真实摄影、人物/产品抠图、复杂 3D/材质、品牌专属图形、参考图中难以复刻的视觉质感。
• 字体判断：识别参考图里的标题、正文、数字、按钮和品牌字形气质，判断可用系统字体、项目已有字体、开源 Web 字体，还是必须由用户提供授权字体。
• 图片生成候选：需要 image-to-ui 生成的图片资产，包含位置、用途、预估尺寸、是否需要透明背景和生成风险。
• image2 优先级：标明哪些候选资产属于“必须生图”“建议生图”“可用代码近似”。
• 需要确认的问题：列出继续前必须问用户的问题，例如是否允许风格近似、是否必须保留 logo/产品原图、图片是否可上传外部服务、最终页面尺寸、移动端是否也要还原、是否接受 AI 生成纹理或人物。
• 下一步建议：给出推荐执行顺序，例如先确认品牌资产和页面尺寸，再生成首屏图，再生成抠图资产，最后做页面级审查。

将元素难度分为：

• 容易：用代码或现有图标库稳定实现，几乎不需要生图。
• 中等：可以实现，但需要精细 CSS、响应式处理、局部图片或设计取舍。
• 困难：依赖复杂图片、精确品牌资产、真实摄影/材质/人物、抠图或模型生成质量。
• 不建议直接生成：包含精确 logo、商标、用户专属照片、精确产品截图或必须 100% 还原的版权资产，应优先使用用户提供的原始素材。

如果用户的问题会影响生成结果、版权/品牌准确性、外部 API 使用或最终页面尺寸，先询问并等待确认。不要为了推进任务而自行假设高风险事项。

如果用户已经表达过“你上次没有真的生图”“不要只做代码近似”“必须调用 image2”，把这视为高优先级纠偏信号：后续执行时应默认优先补足真实位图资产，而不是继续只改 CSS。

UI 分析规则

除非用户明确要求生成“截图式整图”，否则所有可读 UI 文字都应该用代码渲染。不要把导航文字、按钮文案、价格、表单标签或动态内容写死进生成图片。

以下内容优先用代码实现：

• 按钮、标签页、分段控件、输入框、菜单、卡片、分割线、徽标、图表、表格和布局网格。
• 当前图标库已经覆盖的简单几何图标，以及状态栏、导航栏、底部 tab、播放器、quick action、设备控制 glyph、开关和 icon-only button。
• CSS 能稳定表达的阴影、发光、模糊、渐变和简单图案背景。

以下内容优先用 image-to-ui 生成：

• 首屏照片、生活方式图片、编辑风插画、产品场景、吉祥物、头像、真实设备样机、复杂背景底图、手工质感纹理、3D 感物体和装饰性位图组合。
• UI 依赖某种特定视觉情绪、主体或参考图风格匹配的区域。
• 产品、人物或物体叠层所需的透明抠图。

如果参考图的关键美术风格来自像素颗粒、半色调、印刷噪点、扫描噪点、摄影纹理或复杂插画，不要把这些关键区域全都归类为“可用代码实现”。这类区域通常应至少生成一个或多个真实位图资产，再用代码承载布局与交互。

如果用户提供的图片看起来是 logo、品牌标识、精确产品截图、用户照片，或用户明确希望保留的版权/商标资产，直接使用原图。除非用户拥有/提供该资产并要求做变体，否则不要用生图模型复刻精确 logo。

字体识别与加载

字体是 UI 还原的一部分。不要把特殊字体做进图片，除非它是不可编辑的品牌海报或用户明确要求生成整张视觉图。

字体处理顺序：

1. 先识别参考图中的字体气质：衬线/无衬线、几何/人文、圆角/方正、压缩/宽体、字重、数字样式、中文/英文混排、标题与正文层级。
2. 检查项目现有字体、设计系统、CSS 变量和主题配置，优先沿用已有字体。
3. 如果需要更接近参考图，选择系统字体或开源 Web 字体作为近似方案，并说明相似点和差异。
4. 如果参考图明显使用品牌专属字体、商业字体或特殊字体，先询问用户是否有授权字体文件或品牌规范。不要擅自下载或嵌入未授权字体。
5. 如果用户允许联网查找字体，优先寻找官方字体源、开源字体仓库或字体厂商页面，并检查授权范围。
6. 加载字体时优先使用 woff2，设置合理的 font-display，并提供 fallback 字体栈，避免字体加载失败后页面崩坏。

集成字体时：

• 使用真实文本和 CSS 字体，不把可编辑 UI 文案烘焙进图片。
• 为标题、正文、按钮、数字和代码/标签分别设定清晰的字体、字重、行高和字间距。
• 中文字体文件可能很大；如果需要自托管，优先子集化、按需加载或使用系统中文 fallback。
• 检查字体加载前后是否造成布局跳动、按钮溢出、行高变化或中文乱码。
• 记录字体来源、授权假设和 fallback。

常见风险与防护

在前期审查、生成、集成和最终验收时，主动识别这些风险：

• 输入信息不完整：只有一张截图、缺少目标屏幕尺寸、缺少移动端参考、缺少 hover/弹窗/下拉等交互状态。先说明缺口，并用低风险假设或向用户确认。
• 还原目标不清楚：用户可能想要“风格类似”，也可能想要“像素级复刻”。在生成前确认可接受的还原精度，尤其是品牌页、产品页和商业落地页。
• 品牌与版权风险：精确 logo、商标、真实产品截图、用户照片、名人肖像、第三方素材不应默认用模型重画。优先要求用户提供原始素材或授权版本。
• 字体授权风险：特殊字体、品牌字体和商业字体不能默认下载或嵌入。没有授权文件时，使用开源/系统近似字体并说明差异。
• 字体加载风险：Web 字体可能导致闪烁、布局跳动、中文缺字、按钮溢出或首屏变慢。使用 fallback、font-display、子集化和实际渲染检查。
• 生图幻觉：模型可能生成伪文字、奇怪 UI、错误 logo、异常手部/人物、错误材质或多余物体。提示词中要明确禁止文字、水印、logo 和无关 UI 元素，验收时逐项检查。
• 多图风格不一致：多个资产分批生成时，容易出现光照、色彩、镜头、线条粗细、材质不统一。为同一页面维护统一风格 token，并在资产清单中复用。
• 尺寸与裁剪失败：桌面端好看但移动端主体被裁掉，或背景图没有给标题留白。提前规划桌面/移动端槽位，必要时生成不同裁剪版本。
• 抠图边缘问题：透明图可能有白边、硬边、残留背景、阴影不自然或 alpha 通道缺失。必须在浅色和深色背景上检查。
• 图片与代码融合不自然：图片透视、阴影、清晰度、饱和度或边缘质感与代码 UI 不匹配。优先调整图片后处理、CSS 阴影、容器背景和裁剪，而不是只改布局。
• 性能问题：首屏大图、透明 PNG、未压缩资产和过多图片会拖慢页面。优先 WebP/AVIF、srcset、懒加载、合理压缩和明确尺寸。
• 可访问性问题：重要图片没有 alt，装饰图片读屏冗余，按钮文字被烘焙进图片导致不可选中、不可翻译、不可读屏。真实 UI 文本必须保留为代码。
• 外部服务和隐私风险：抠图 API 或在线生图工具可能上传用户素材。没有用户许可、没有凭据或素材敏感时，不调用外部 API。
• 构建集成风险：图片路径、打包方式、public 目录、缓存、大小写文件名、远程部署路径可能导致本地可见但线上 404。集成后检查构建和浏览器网络请求。

如果风险会影响版权、安全、隐私、页面尺寸、品牌准确性或最终验收标准，先问用户确认。普通视觉取舍可以记录假设后继续推进。

尺寸规划

根据 UI 参考图推断目标视口和图片槽位：

• 如果截图有明确像素尺寸，先测量图片槽位占截图宽高的比例，再映射到实现视口。
• 如果最终应用是响应式的，定义 CSS 宽高比，并按最大预期展示尺寸生成，通常使用 2x 像素密度。
• 如果复刻的是固定尺寸 App 截图、手机壳、仪表盘卡片或其他强依赖绝对坐标的 UI，不要把固定像素定位直接放进会缩小的响应式容器。优先使用一个固定设计画布（例如 430x870）承载内部元素，再按外层容器宽度整体缩放；或把所有字号、位置、间距统一换算成同一套响应式比例单位，避免窗口变窄后局部文字和插画互相覆盖。
• 优先生成等于或大于目标槽位的图片，再裁剪/缩小。避免把小图强行放大。
• 全宽首屏图在可行时至少按桌面端 2x 宽度生成；如果移动端构图会坏，单独生成移动端裁剪。
• 透明抠图要保留足够留白容纳阴影，避免过度贴边导致主体被裁掉。

image-to-ui 提示词

每个图片资产单独写提示词。提示词聚焦单个资产，不要描述整个页面。

如果用户要的是一整套风格统一的小图，例如 3 张目的地卡片、4 个路线小岛、1 张主视觉和若干装饰纹理，优先考虑：

• 先写统一的风格 token
• 再决定是逐张生成，还是一次生成可切片的资产板
• 如果担心多次生成风格漂移，优先资产板方案

当页面是“代码 UI + 多张统一风格位图”的混合模式时，提示词必须补充这些约束：

• 不要生成任何可读文字、按钮、价格、系统状态栏、图标、UI symbols、UI chrome、箭头、齿轮、三点菜单、加减号、电源符号、播放器控制、底部导航、开关或状态点
• 主体尽量居中或按槽位留白
• 给文案区预留安全留白
• 多资产之间保持同一色板、颗粒密度、光照方向和风格强度

每条提示词应该包含：

• 资产用途和 UI 槽位，例如首屏背景、产品抠图、卡片缩略图或空状态插画。
• 主体、构图、镜头/视角、风格、光照、色彩和背景。
• 宽高比和目标导出尺寸。
• 集成约束：预留文案空间、避免文字/logo/水印、支持时要求透明背景、需要抠图时要求主体独立。
• 会破坏 UI 的负向约束。

多资产页面要复用一致的风格 token：色彩、材质、光照、线条粗细、镜头角度和真实程度。

抠图与去背景

当资产需要透明背景时：

1. 优先使用 image-to-ui/生图模型自带的透明背景、局部编辑、遮罩或独立主体能力。
2. 如果 image-to-ui 不能直接产出干净透明图，或生成结果边缘质量不够，再选择可用的去背景路径：
   • 项目环境中已安装或可安装的本地工具，例如 rembg/Pillow。
   • 用户提供凭据或环境已经配置好的 API。
   • 支持背景移除或遮罩编辑的图片编辑/生图工具。
3. 只有在用户允许、环境已有凭据、且资产不敏感时，才调用外部抠图 API。
4. 不要编造 API key，不要在没有许可的情况下把敏感用户资产上传到外部服务，也不要在未验证 alpha 通道前声称图片已经透明。
5. 检查边缘、阴影、头发/细节，并导出带 alpha 的 PNG 或 WebP。

集成规则

将生成资产放到项目已有的资源目录约定下。如果项目没有约定，使用清晰的生成资产目录，例如 src/assets/generated/ 或 public/generated/。

按角色和尺寸命名文件，例如 hero-product-2880x1440.webp 或 pricing-device-cutout-1200x900.png。

最终 demo 中引用的图片资产必须是项目本地文件。可以在开发中临时参考远程图片，但交付前要下载、生成或重建为本地资产，并修正页面引用；不要让 demo 依赖外网图片加载成功。

集成时：

• 使用明确的宽度、高度、宽高比或容器约束，避免图片加载导致布局跳动。
• 如果创建了多个断点图片，使用 picture/srcset。
• 纯装饰图使用 alt=""；有信息意义的图片提供有用的 alt 文本。
• 按钮、文字和图标保持为真实可访问 UI 元素，可以叠放在图片上或放在图片旁边。
• 除非任务明确是复刻整张图片 mockup，否则避免生成包含 UI 文字的图片。

如果一个页面声称“使用了 image2 生图”，至少要让以下一种情况发生：

• 首屏主视觉来自真实生成图
• 关键插画/缩略图来自真实生成图
• 路线图/地图主体来自真实生成图

如果这些都没有发生，说明任务仍停留在结构复刻阶段，不应宣称已经完成 image2 复刻。

交互与跳转

生成页面不能只是静态截图。除非用户明确要求只交付静态视觉稿，否则要把可识别的交互区做成真实可点击元素，并自动设置合理跳转逻辑。

• 多屏参考图：如果参考图展示多个 App 页面、弹窗状态、步骤页或详情页，默认把它们串成一个可点击原型。主按钮进入下一屏，返回/关闭回到上一屏，底部导航切换对应页面，卡片/列表项进入详情或选中状态。
• 单屏参考图：按钮、链接、开关、标签页、卡片、菜单、输入框和导航仍应可点击或可操作。没有明确目标页面时，使用低风险的视觉反馈、状态切换、锚点滚动或模拟成功态，并在最终说明中记录假设。
• 语义元素：优先使用真实 <button>、<a>、表单控件和 ARIA 状态，不要用不可交互的 div 假装按钮。a 必须有明确 href 或由脚本管理的目标，按钮必须设置 type。
• 跳转假设：根据文案和 UI 常识自动推断跳转，例如 Get Started 到下一屏、Close/Back 到上一屏、Next 到下一步、卡片点击更新选中态。高风险动作（购买、提交真实信息、外部发送、删除、改权限）只做草稿或本地模拟，不实际提交。
• 验证路径：最终至少点击一遍主要 CTA、返回/关闭、一个选择项和一个末级按钮；确认 URL/hash/路由、选中态、按钮反馈、滚动位置或页面内容确实变化，并检查没有死链、无响应按钮或控制台错误。

页面级审查

集成图片后，必须审查完整页面，而不只检查单张图片。优先使用浏览器截图、移动端/桌面端视口和实际渲染结果判断。

审查内容：

• 尺寸正确：图片不被意外拉伸、压扁、裁掉主体；导出尺寸满足最大展示尺寸；首屏、卡片、头像、背景图都有稳定宽高比。
• 无乱码和伪文字：页面真实文案不乱码；生成图片内部没有无法解释的文字、伪字母、logo、水印或与 UI 文案冲突的内容。
• 无生成式 UI glyph：生成图片内部没有状态栏、电量/Wi-Fi/信号、返回箭头、菜单、按钮、底部 tab、播放器或设备控制小图标；这些必须是代码层真实 icon。
• 排版正常：文本不溢出按钮/卡片；导航、按钮、图片、标题和正文之间没有异常重叠；移动端不出现横向滚动或关键内容被裁切。
• 卡片信息密度正常：小设备卡片不要同时塞多行元信息。截图放大后如果房间名、标签或状态读起来像灰色噪点，优先删减可见文本、增大字号或改到详情/辅助语义中。
• 融合自然：图片的光照、透视、边缘、阴影、色彩和清晰度与代码生成的 UI 匹配；抠图没有明显白边、硬边、脏边或悬浮感不合理的问题。
• 层级正确：图片不会遮挡可点击控件；前景图、背景图、文字和按钮的 z-index 与点击区域正常。
• 交互可用：所有显而易见的按钮、链接、导航、卡片和输入控件都能点击或操作；多屏页面有可回退的跳转路径；未知目标有本地反馈而不是静默无效。
• 响应式可靠：至少检查桌面端和移动端；必要时增加移动端专用裁剪图或调整 object-position。
• 窄容器真实可用：如果用户可能在侧边栏、in-app browser、手机预览或小宽度窗口中打开页面，必须额外用接近实际容器宽度的截图验证。不要只用宽桌面视口判断；重点检查标题、正文、按钮、插画、状态栏和卡片是否发生重叠、截断、异常换行或局部放大。
• 局部细节到位：不要只看整页缩略图。必须放大检查关键边角和小元素，包括状态栏、圆角、设备边框、底部导航、图标、手绘线条、卡片边缘、按钮内文字和生成插画局部；如果局部明显不像参考图、像乱码/伪字母、线条断裂或比例失真，先修正再交付。
• 图标对齐到位：状态栏、返回/关闭、菜单、加减号、播放器、底部 tab、quick action 和设备图标必须在真实按钮/导航容器中视觉居中；不能由位图中的残缺图标承担交互含义。
• 生图确实落地：截图里能明确看到生成资产已经出现在正确槽位；不要只验证本地生成文件存在。
• 自动巡检完成：运行 image2-ui validate、scripts/ui_output_audit.mjs 或项目内等价验证命令；重点处理破图、控制台错误、低对比度、文字溢出、卡片套卡片、模板化渐变文字、单一 AI 配色和交互死区。

如果审查发现问题，先判断是图片问题还是代码集成问题：图片主体、风格、边缘或文字错误时重新生成/抠图；尺寸、裁剪、层级或间距错误时修改 CSS/布局。

原图差距核对与迭代

页面级审查通过后，必须把当前实现截图与用户提供的原始参考图进行对照。不要只凭记忆判断效果。

对照方式：

1. 使用与原图尽量一致的视口尺寸截图；如果原图是桌面端和移动端，分别截图对比。
2. 如果原图和实现截图尺寸不同，先按同一宽度缩放后再比较整体比例、间距和视觉重心。
3. 按区域比较：导航、首屏、图片资产、字体、按钮、卡片、背景、色彩、阴影、间距、响应式裁剪。
4. 输出差距清单，给每个差距标注严重程度：必须修、建议修、可接受差异。
5. 对 必须修 和高影响 建议修 进行修改，再重新截图对比。
6. 重复“截图 -> 对比 -> 修正 -> 再截图”，直到没有明显影响还原度的问题，或剩余差异受素材、授权、模型质量、时间或用户选择限制。

如果用户曾指出“没有真正调用 image2”，差距核对时必须单独增加一项：

• 生图替换率：当前参考图中最关键的视觉区域，有多少已经从代码近似替换成真实生成位图。

如果用户要求像素级复刻，优先使用可测量对比：位置、尺寸、颜色、字体、间距和图片裁剪。若只是风格参考，不追求逐像素一致，但仍要说明主要差异和取舍。

差距核对时重点看：

• 布局比例：页面宽度、首屏高度、左右留白、区块间距、网格列宽是否接近原图。
• 字体还原：字重、字号、行高、字间距、标题气质、中文/英文/数字显示是否接近。
• 图片还原：主体、构图、裁剪、风格、光照、清晰度、抠图边缘是否接近原图。
• 局部还原：对参考图里的云朵、头像、贴纸、线稿、状态栏、导航图标、按钮圆角等小区域做局部对比；这些细节不能因为整页看起来接近就忽略。
• 色彩与质感：背景色、按钮色、阴影、边框、透明度、模糊、材质是否偏离。
• 交互和层级：按钮、导航、图标、前景图和背景图的层级是否与参考图一致。
• 响应式差异：移动端是否仍保留原图的视觉重点和内容优先级。

最终交付

完成后报告：

• 哪些区域用代码渲染。
• 生成了哪些图片资产，以及文件路径。
• 哪些资产是通过 native-image2 或 Youtoken/OpenRouter ICU gpt-image-2 备案通道得到的，并标明实际通道；native-image2 要写明来源。
• 使用了什么抠图/去背景方法。
• 关于尺寸、响应式裁剪或生成风格的假设。
• 做过哪些页面级审查和验证，尤其是浏览器截图、移动端/桌面端检查、图片尺寸检查、乱码检查、图片融合检查和主要点击路径检查。
• 页面输出巡检结果，包括是否运行自动脚本、发现了哪些 fail/warn、已经修复哪些、剩余哪些是有意识保留。
• 与原始参考图对比后的主要差距、已修正项、剩余可接受差异，以及迭代了几轮截图核对。
• 如果启动了本地预览服务，必须写清楚本地预览 URL、项目根目录、demo 目录和入口 HTML 文件路径，方便用户直接定位文件。