人们往往是在看过具体画面之后，才真正知道自己在意什么。
所以 UI Skill Lab 先让团队看到 UI 长什么样，再让 Codex / Claude Code 按定稿实现、验收和修复。
English · 简体中文
UI Skill Lab 提出并开源一套 "视觉稿 + 规格合同"驱动的 AI 前端实现工作流。
它的核心想法很简单：
人对画面的判断力远强于对文字的描述力。看到具体 UI 之前，人们往往说不清自己要什么；看到之后，才真正知道在意什么、哪里不对、该往哪个方向改。
所以 UI Skill Lab 把流程反过来：先把 PRD 变成一张可以看的 UI 视觉稿，让团队在看到画面后做出真正的判断；再把定稿转成 visual spec、tokens、layout、component tree 和 design rules，作为 Agent 的规格合同，让 Codex / Claude Code 按这份合同实现、验收和修复。
传统 AI 写前端，通常是把 PRD 直接交给 Agent，让它生成代码。
问题是：PRD 是文字，团队很难提前判断页面最终长什么样，也很难建立一致的视觉体感。Agent 在缺少明确视觉目标和实现规格时，容易套用通用页面结构，写出一个"能跑但不对"的 UI。
UI Skill Lab 把这个过程拆成三步：
- 先可视化目标：把 PRD 转成可讨论、可迭代的 UI 视觉稿，让团队先建立页面体感和视觉共识；
- 再规格化目标：把定稿视觉稿拆成 visual spec、tokens、layout、component tree 和 design rules，让主观视觉尽量变成可执行的客观规格；
- 最后按规格实现：让 Codex / Claude Code 按规格合同写页面，再通过截图验收和 diff fix 逐轮修正。
对于强依赖人物、产品图、插画、3D 主视觉或复杂切图的页面，最终效果主要取决于是否准备了 clean assets。相关能力会先放到后续 Asset Workflow Planning 中探索。
当前状态： 这是一个早期开源的 AI 前端工作流参考项目，适合用于学习、拆解、迁移，也可以接入 Codex / Claude Code / 自研 Agentic Coding 流程。
这张图展示的是 UI Skill Lab 的完整闭环：
先用视觉稿建立团队共识，再用规格合同约束 Agent 实现，最后通过截图验收和差异修复让页面逐轮收敛。
| 📝 PRD 变视觉稿 | 👀 建立团队视觉共识 | 📐 视觉稿变规格合同 | 🧑💻 Agent 按规格实现 | 🧪 截图验收与定向修复 |
|---|---|---|---|---|
| 把文字需求转成可讨论的 UI 画面 | 先判断页面体感、风格和布局方向 | 拆成 spec / tokens / layout / component tree | Codex / Claude Code 不再凭感觉写 UI | 用 screenshot 和 fix-tasks.json 逐轮收敛 |
Codex / Claude Code 已经能很快生成一版页面。
但在真实产品协作里，AI 写 UI 经常卡在这些地方。这些问题的根因是同一个：文字 PRD 无法触发人对画面的直觉判断——人需要看到具体产出，才能做出有效的设计决策。
- 目标看不见：PRD 是文字，团队很难提前判断页面最终长什么样，也很难建立一致的视觉体感；
- 视觉共识难建立：产品、设计、研发、业务方对"页面应该是什么感觉"可能各自想象不同；
- Agent 容易跑偏：缺少明确视觉目标时，它可能默认套用 dashboard、sidebar、KPI cards 等通用结构；
- 截图缺少结构：视觉稿对人很直观，但不能直接告诉 Codex / Claude Code 颜色、间距、组件层级和响应式规则；
- 验收靠人眼：像不像、哪里不像，往往只能靠主观判断；
- 修复靠口头描述：每次都是"再调好看一点"，很难定位到具体模块和改动范围；
- 修复容易漂移：修一个 spacing，可能顺手改坏整体 layout、视觉风格或组件结构。
UI Skill Lab 补上的就是这层中间工作流：
PRD
→ UI 视觉稿
→ 视觉规格合同
→ 设计系统
→ Agent 实现
→ 截图验收
→ 差异修复
它保留人的关键判断：产品目标、视觉方向、最终验收。 同时把重复的规格化、审查、截图验收和差异修复，交给一套可复用的 workflow 管理。
| 传统方式 | UI Skill Lab |
|---|---|
| PRD 直接交给 Agent 写代码 | 先把 PRD 转成可讨论的 UI 视觉稿 |
| 团队只能想象页面长什么样 | 先通过视觉稿建立团队共识 |
| Agent 容易套用通用页面结构 | 定稿视觉稿成为唯一视觉事实源（source of truth） |
| 靠一句 prompt 控制视觉方向 | 用 prompt pack、negative prompt、variant briefs 控制视觉生成 |
| 截图对人直观，但对 Agent 不够结构化 | 用 visual-to-spec 转成 tokens、layout、component tree |
| AI 抽出来的 spec 也可能出错 | visual-spec-review 先做规格门禁 |
| 静态截图缺少状态和响应式 | design-system-governor 补齐产品级设计规则 |
| 代码能跑就算完成 | spec-compliance-review 检查代码是否服从视觉合同 |
| 像不像靠人眼判断 | visual-acceptance-review 做浏览器截图验收 |
| 修复靠"再调好看一点" | visual-diff-fix 生成结构化 fix-tasks.json |
| 修一处坏一处 | 每轮修复后重新截图验收，形成闭环 |
UI Skill Lab 把这条链路拆成 7 个主流程 Skill，每个 Skill 都负责控制一个容易漂移的环节。
| Skill | 它解决的问题 | 关键价值 | 主要产物 |
|---|---|---|---|
🪄 image2-prompt-pack |
PRD 到 reference 图不稳定 | 让视觉生成可复用、可比较 | ui/01_prompt_pack/ |
📐 visual-to-spec |
图片不能直接指导实现 | 把图变成前端视觉合同 | ui/03_visual_spec/ |
🛡️ visual-spec-review |
Agent 抽规格也会抽错 | 阻止错误 spec 进入开发 | ui/04_visual_spec_review/ |
🎛️ design-system-governor |
静态图缺少状态和响应式 | 补齐产品级设计规则 | ui/05_design_system/ |
🔍 spec-compliance-review |
代码不一定按 spec 写 | 检查代码是否服从视觉合同 | ui/06_spec_review/ |
🖼️ visual-acceptance-review |
页面跑出来未必像 reference | 用截图做验收并生成差异 | ui/07_validation/ |
🔧 visual-diff-fix |
修复时容易重新设计 | 用 fix-tasks.json 定向修复 |
ui/08_diff_fix/ |
ui-ux-pro-max-skill 是辅助设计参考 Skill，主要在 design-system-governor 阶段提供 UI/UX 模式、风格、配色、字体和设计建议，不是主链路必经步骤。
适合： 产品经理、创业团队、业务负责人、需要快速对齐视觉方向的项目团队。
你有 PRD，但团队还不知道页面最终大概长什么样。
使用方式：
PRD
→ image2-prompt-pack
→ Image Model
→ 多轮视觉确认
→ Final Reference
价值：
- 写代码前先看到 UI 方向
- 产品、设计、研发、决策者可以提前讨论
- 减少"实现完才发现方向不对"
适合： 正在使用 Codex / Claude Code 做前端实现的开发者或 AI Coding 用户。
你已经定稿了一张 UI 视觉图，希望 Agent 按这个目标实现前端。
使用方式：
reference.png
→ visual-to-spec
→ visual-spec-review
→ design-system-governor
→ Codex / Claude Code Implementation
价值：
- 把图像变成 Agent 能执行的视觉合同
- 限制 Agent 自由发挥
- 防止默认套 dashboard、sidebar、KPI cards
- 让前端实现围绕
reference.png和 visual spec 展开
适合： 需要做 UI 还原、视觉验收、前端修复和回归检查的团队。
你已经有代码和浏览器效果，但和参考图还有差异。
使用方式：
spec-compliance-review
→ visual-acceptance-review
→ visual-diff-fix
→ Re-check
价值：
- 用 spec 和 screenshot 双向校验
- 把差异定位到模块和修复任务
- 让 Agent 定向修复，而不是重写整个页面
- 每一轮修复后都能重新验收
这个仓库不是一个完整 UI 生成产品，而是一套可以拆解、借鉴、迁移的 AI 前端工作流参考骨架。
你可以直接参考：
- 一套视觉目标驱动的 AI 前端实现流程
- 一套把 PRD 转成 UI visual target 的 prompt pack 方法
- 一套把 UI 截图转成 visual spec / tokens / component tree 的结构
- 一套防止 Agent 幻觉组件的审查规则：bbox evidence、Prohibited Components、Rejected Assumptions
- 一套
source / confidence / strictness的质量标注体系 - 一套
Pass / Conditional Pass / Fail的门禁设计 - 一套
screenshot acceptance → fix-tasks.json → diff fix的修复闭环 - 一套可以迁移到 Codex、Claude Code 或自研 Agent Workflow 的目录与文档骨架
如果你也在尝试用 Codex / Claude Code 做前端 UI，经常遇到"方向不清、Agent 乱改、修完又回归"的问题，可以先收藏这个 repo，后续按自己的项目需要，逐步迁移其中的 Skill。
UI Skill Lab 更适合 代码可实现为主的 UI，例如 Dashboard、SaaS、管理后台、移动端页面和普通 landing page。
| 场景 | 适配度 | 说明 |
|---|---|---|
| Dashboard / SaaS / 管理后台 | ✅ 高 | 大部分元素可用 HTML / CSS / 组件实现，适合完整 workflow |
| Mobile app screen | ✅ 高 | 适合做布局、tokens、组件结构和响应式规格 |
| 普通 landing page | ✅ 中高 | 有 clean hero / product assets 时效果更好 |
| Image-led landing | 可定义 image layer 和 overlay strategy，但不自动切图 | |
| Panorama / 3D 展厅 / 展台 UI | 可定义场景层、控件层和验收规则，主视觉需要 clean assets | |
| 海报 / 强视觉合成页面 | 没有独立素材时，只能做截图级规格和验收建议 | |
| 自动切图 / 抠图 / Figma 导出 | 🚧 未来探索 | 会先进入 Asset Workflow Planning，不代表已经支持生产级自动导出 |
当前暂不覆盖的能力
UI Skill Lab 当前不会自动完成：
- 从整张图里切出背景、产品图、人物、图标或 logo
- 生成透明 PNG / WebP / SVG
- 导出 @1x / @2x / @3x 多倍率资源
- 从 Figma / PSD / Sketch 图层导出素材
- 自动抠图、分割图层或重建照片级主视觉
如果页面强依赖切图，当前推荐：
先准备 clean assets
再使用 UI Skill Lab 做：
visual spec → asset strategy → code audit → screenshot acceptance → diff fix
当 Agent 进入 UI 生产流程后，真正需要控制的是：每一轮输出都不要偏离已确认的视觉目标。
UI Skill Lab 本质上是一套 anti-drift workflow：
| Drift 类型 | 对应 Skill |
|---|---|
| 生图漂移 | image2-prompt-pack |
| 规格漂移 | visual-to-spec + visual-spec-review |
| 设计系统漂移 | design-system-governor |
| 代码实现漂移 | spec-compliance-review |
| 视觉验收漂移 | visual-acceptance-review |
| 修复漂移 | visual-diff-fix |
它让 Agent 参与 UI 生产时，每一步都有：
- source of truth
- evidence
- confidence
- strictness
- review gate
- fix task
- re-check loop
项目包含三层质量门禁：
| 层级 | 工具 | 验证内容 |
|---|---|---|
| Skill 源契约 | validate-skill-source-contracts.mjs |
SKILL.md 格式、引用文件存在性、示例 JSON 合法性 |
| E2E Pipeline Gate | validate-ui-skill-e2e.mjs |
每个 pipeline 阶段的输出完整性、token schema、bbox evidence、gate enforcement |
| 视觉重建基准 | compare-visual-reconstruction.py |
对测试样例计算 MAE、RMSE、SSIM，并进行 anti-cheat 检测 |
tests/real-runs/是 workflow validation artifacts，用于验证 pipeline 输出结构和流程完整性。它们不是像素级重建质量的证明。像素级重建质量应在tests/visual-reconstruction/下通过 anti-cheat 检查来评估。
当前 CI 默认验证 Skill 契约、E2E pipeline gate 和 visual benchmark 配置。完整截图采集与视觉对比建议在本地或 scheduled workflow 中安装 Playwright 浏览器后运行。
# Browse available skills
npx skills add Jason904/ui-skill-lab --list
# Install all skills at once
npx skills add Jason904/ui-skill-lab --all
# Install a single skill
npx skills add Jason904/ui-skill-lab --skill visual-to-spec你不需要复制整个仓库。最小用法是把 7 个核心 Skill 复制到你的项目：
your-project/
└── .codex/
└── skills/
├── image2-prompt-pack/
├── visual-to-spec/
├── visual-spec-review/
├── design-system-governor/
├── spec-compliance-review/
├── visual-acceptance-review/
└── visual-diff-fix/
完整迁移说明见：Using Skills in Your Project
git clone https://github.com/Jason904/ui-skill-lab.git
cd ui-skill-lab
pip install -r requirements.txt
npx playwright install chromium
npm run check-prereqs
npm run fixtures:seed
npm test
npm run visual:seed
npm run visual:check-config详见 Getting Started。
UI Skill Lab 会围绕一个核心方向持续迭代：
把 UI 的主观视觉目标，逐步转成 Agent 可以执行、检查和修复的客观规格。
当前版本优先覆盖 非切图场景：
适合 Dashboard、SaaS、管理后台、移动端页面、普通 landing page 等主要由 HTML / CSS / 组件实现的 UI。
后续会逐步扩展到 asset-heavy 页面：
例如产品图、人物图、插画、3D 主视觉、展厅背景、海报式页面、sprite 动效等更依赖图片资产和切图资源的场景。
目标：让 UI 复现过程更可评估、更可回归、更不容易越修越乱。
计划方向：
- 增强截图验收报告，让差异更容易定位
- 增加区域级对比，例如 header、hero、card、form、navigation
- 优化 blocking / warning / suggestion 分级
- 让
fix-tasks.json更适合 Agent 做定向修复 - 增加更多真实页面样例，完善 visual benchmark
- 明确哪些检查适合 CI，哪些适合本地或 scheduled workflow
目标：让 UI Skill Lab 更好地处理包含图片资产的页面。
适合场景：
- landing page 里的产品图、人物图、插画
- 3D 展台、展厅、展示页背景
- 大面积 image-led hero 区域
- background image + overlay UI 页面
计划方向：
- 在 visual spec 中增加 asset strategy
- 区分哪些内容适合代码实现，哪些内容应该作为图片资产保留
- 设计
asset-manifest.proposed.json - 输出建议的 asset list，例如 background、hero image、logo、icon、illustration
- 增加 clean assets checklist
- 在验收阶段区分 code-rendered layer 和 image asset layer
目标：探索从完整视觉图中规划切图资源，让复杂视觉页面也能进入 UI Skill Lab 的规格化流程。
计划方向：
- 新增
asset-slicing-plannerSkill - 从 reference image 中识别潜在切图区域
- 输出候选切图清单，例如 background、hero image、product image、character image、icon、decorative element
- 生成 proposed asset manifest，包括 asset name、asset type、bounding box、recommended format、density suggestion、usage layer
- 标记哪些资产适合自动建议，哪些需要人工确认
- 与
visual-to-spec、design-system-governor、visual-acceptance-review串联
这一阶段会优先沉淀 切图规划、资产命名、资源规格和人工确认流程，让带图片资产的页面有更清晰的实现路径。
目标：探索从更可靠的设计源读取图层和资产，减少单张截图反推带来的不确定性。
计划方向：
- 探索 Figma / PSD / design-layer export adapter
- 读取图层命名、尺寸、位置和资产类型
- 将设计源图层转换为 asset manifest
- 将 design layer 与 visual spec 对齐
- 支持从设计源导出的 clean assets 接入前端实现流程
目标：支持更复杂的 UI 资产和动效场景。
计划方向：
- 探索 sprite sheet / icon sheet / raster asset workflow
- 支持简单动效资产的规格描述
- 描述 hover、transition、loading、micro-interaction 等状态
- 支持 sprite frame manifest
- 将动效资源与 design system rules、visual acceptance 结合
- 为角色、展台、交互式页面等复杂场景提供 asset + UI workflow
UI Skill Lab 的长期目标是持续沉淀一套 AI 前端实现方法：
PRD
→ UI 视觉稿
→ 视觉规格合同
→ 设计系统
→ Agent 实现
→ 截图验收
→ 差异修复
→ 资产工作流
这个方向会持续围绕三个目标推进：
- 让视觉目标更容易被团队确认；
- 让实现规格更容易被 Agent 执行；
- 让最终结果更容易被验收、修复和回归。
MIT