[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-85117":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":12,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":13,"stars30d":13,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":14,"rankGlobal":9,"rankLanguage":9,"license":15,"archived":16,"fork":16,"defaultBranch":17,"hasWiki":16,"hasPages":16,"topics":18,"createdAt":9,"pushedAt":9,"updatedAt":19,"readmeContent":20,"aiSummary":9,"trendingCount":13,"starSnapshotCount":13,"syncStatus":21,"lastSyncTime":22,"discoverSource":23},85117,"ui-skill-lab","Jason904\u002Fui-skill-lab","Jason904","AI-driven UI development skill pipeline — test lab for Codex skills covering PRD-to-pixel workflow",null,"Python",61,3,0,37.81,"MIT License",false,"main",[],"2026-06-15 10:04:29","\u003Cdiv align=\"center\">\n\n\u003Ch1>UI Skill Lab\u003C\u002Fh1>\n\n\u003Cp>\n  \u003Cstrong>人们往往是在看过具体画面之后，才真正知道自己在意什么。\u003C\u002Fstrong>\u003Cbr\u002F>\n  \u003Cstrong>所以 UI Skill Lab 先让团队看到 UI 长什么样，再让 Codex \u002F Claude Code 按定稿实现、验收和修复。\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp>\n  \u003Ca href=\"README.en.md\">English\u003C\u002Fa> · 简体中文\n\u003C\u002Fp>\n\n\u003Cp>\n  \u003Cimg alt=\"Workflow\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fworkflow-Visual--first%20Frontend-7c3aed\">\n  \u003Cimg alt=\"Agent\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fagent-Codex%20%2F%20Claude%20Code-2563eb\">\n  \u003Cimg alt=\"Status\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fstatus-Workflow%20Reference-f59e0b\">\n  \u003Cimg alt=\"License\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-10b981\">\n\u003C\u002Fp>\n\n\u003C\u002Fdiv>\n\nUI Skill Lab 提出并开源一套 **\"视觉稿 + 规格合同\"驱动的 AI 前端实现工作流**。\n\n它的核心想法很简单：\n\n人对画面的判断力远强于对文字的描述力。看到具体 UI 之前，人们往往说不清自己要什么；看到之后，才真正知道在意什么、哪里不对、该往哪个方向改。\n\n所以 UI Skill Lab 把流程反过来：**先把 PRD 变成一张可以看的 UI 视觉稿，让团队在看到画面后做出真正的判断；再把定稿转成 visual spec、tokens、layout、component tree 和 design rules，作为 Agent 的规格合同，让 Codex \u002F Claude Code 按这份合同实现、验收和修复。**\n\n传统 AI 写前端，通常是把 PRD 直接交给 Agent，让它生成代码。\n\n问题是：PRD 是文字，团队很难提前判断页面最终长什么样，也很难建立一致的视觉体感。Agent 在缺少明确视觉目标和实现规格时，容易套用通用页面结构，写出一个\"能跑但不对\"的 UI。\n\nUI Skill Lab 把这个过程拆成三步：\n\n1. **先可视化目标**：把 PRD 转成可讨论、可迭代的 UI 视觉稿，让团队先建立页面体感和视觉共识；\n2. **再规格化目标**：把定稿视觉稿拆成 visual spec、tokens、layout、component tree 和 design rules，让主观视觉尽量变成可执行的客观规格；\n3. **最后按规格实现**：让 Codex \u002F Claude Code 按规格合同写页面，再通过截图验收和 diff fix 逐轮修正。\n\n对于强依赖人物、产品图、插画、3D 主视觉或复杂切图的页面，最终效果主要取决于是否准备了 clean assets。相关能力会先放到后续 Asset Workflow Planning 中探索。\n\n> **当前状态：** 这是一个早期开源的 AI 前端工作流参考项目，适合用于学习、拆解、迁移，也可以接入 Codex \u002F Claude Code \u002F 自研 Agentic Coding 流程。\n\n---\n\n## 🗺️ 一图看懂\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Ffrom-prd-to-acceptable-page.zh.png\" alt=\"从 PRD 到可验收页面\" width=\"100%\">\n\u003C\u002Fp>\n\n这张图展示的是 UI Skill Lab 的完整闭环：  \n**先用视觉稿建立团队共识，再用规格合同约束 Agent 实现，最后通过截图验收和差异修复让页面逐轮收敛。**\n\n---\n\n## ✨ 核心价值\n\n| 📝 PRD 变视觉稿 | 👀 建立团队视觉共识 | 📐 视觉稿变规格合同 | 🧑‍💻 Agent 按规格实现 | 🧪 截图验收与定向修复 |\n|---|---|---|---|---|\n| 把文字需求转成可讨论的 UI 画面 | 先判断页面体感、风格和布局方向 | 拆成 spec \u002F tokens \u002F layout \u002F component tree | Codex \u002F Claude Code 不再凭感觉写 UI | 用 screenshot 和 `fix-tasks.json` 逐轮收敛 |\n\n---\n\n## 🧭 为什么会有这个项目？\n\nCodex \u002F Claude Code 已经能很快生成一版页面。\n\n但在真实产品协作里，AI 写 UI 经常卡在这些地方。这些问题的根因是同一个：**文字 PRD 无法触发人对画面的直觉判断**——人需要看到具体产出，才能做出有效的设计决策。\n\n- **目标看不见**：PRD 是文字，团队很难提前判断页面最终长什么样，也很难建立一致的视觉体感；\n- **视觉共识难建立**：产品、设计、研发、业务方对\"页面应该是什么感觉\"可能各自想象不同；\n- **Agent 容易跑偏**：缺少明确视觉目标时，它可能默认套用 dashboard、sidebar、KPI cards 等通用结构；\n- **截图缺少结构**：视觉稿对人很直观，但不能直接告诉 Codex \u002F Claude Code 颜色、间距、组件层级和响应式规则；\n- **验收靠人眼**：像不像、哪里不像，往往只能靠主观判断；\n- **修复靠口头描述**：每次都是\"再调好看一点\"，很难定位到具体模块和改动范围；\n- **修复容易漂移**：修一个 spacing，可能顺手改坏整体 layout、视觉风格或组件结构。\n\nUI Skill Lab 补上的就是这层中间工作流：\n\n```text\nPRD\n→ UI 视觉稿\n→ 视觉规格合同\n→ 设计系统\n→ Agent 实现\n→ 截图验收\n→ 差异修复\n```\n\n它保留人的关键判断：产品目标、视觉方向、最终验收。\n同时把重复的规格化、审查、截图验收和差异修复，交给一套可复用的 workflow 管理。\n\n---\n\n## 🔁 传统方式 vs UI Skill Lab\n\n| 传统方式 | UI Skill Lab |\n|---|---|\n| PRD 直接交给 Agent 写代码 | 先把 PRD 转成可讨论的 UI 视觉稿 |\n| 团队只能想象页面长什么样 | 先通过视觉稿建立团队共识 |\n| Agent 容易套用通用页面结构 | 定稿视觉稿成为唯一视觉事实源（source of truth） |\n| 靠一句 prompt 控制视觉方向 | 用 prompt pack、negative prompt、variant briefs 控制视觉生成 |\n| 截图对人直观，但对 Agent 不够结构化 | 用 `visual-to-spec` 转成 tokens、layout、component tree |\n| AI 抽出来的 spec 也可能出错 | `visual-spec-review` 先做规格门禁 |\n| 静态截图缺少状态和响应式 | `design-system-governor` 补齐产品级设计规则 |\n| 代码能跑就算完成 | `spec-compliance-review` 检查代码是否服从视觉合同 |\n| 像不像靠人眼判断 | `visual-acceptance-review` 做浏览器截图验收 |\n| 修复靠\"再调好看一点\" | `visual-diff-fix` 生成结构化 `fix-tasks.json` |\n| 修一处坏一处 | 每轮修复后重新截图验收，形成闭环 |\n\n---\n\n## 🧩 7 个主流程 Skill 分别解决什么问题？\n\nUI Skill Lab 把这条链路拆成 7 个主流程 Skill，每个 Skill 都负责控制一个容易漂移的环节。\n\n| Skill | 它解决的问题 | 关键价值 | 主要产物 |\n|---|---|---|---|\n| 🪄 `image2-prompt-pack` | PRD 到 reference 图不稳定 | 让视觉生成可复用、可比较 | `ui\u002F01_prompt_pack\u002F` |\n| 📐 `visual-to-spec` | 图片不能直接指导实现 | 把图变成前端视觉合同 | `ui\u002F03_visual_spec\u002F` |\n| 🛡️ `visual-spec-review` | Agent 抽规格也会抽错 | 阻止错误 spec 进入开发 | `ui\u002F04_visual_spec_review\u002F` |\n| 🎛️ `design-system-governor` | 静态图缺少状态和响应式 | 补齐产品级设计规则 | `ui\u002F05_design_system\u002F` |\n| 🔍 `spec-compliance-review` | 代码不一定按 spec 写 | 检查代码是否服从视觉合同 | `ui\u002F06_spec_review\u002F` |\n| 🖼️ `visual-acceptance-review` | 页面跑出来未必像 reference | 用截图做验收并生成差异 | `ui\u002F07_validation\u002F` |\n| 🔧 `visual-diff-fix` | 修复时容易重新设计 | 用 `fix-tasks.json` 定向修复 | `ui\u002F08_diff_fix\u002F` |\n\n`ui-ux-pro-max-skill` 是辅助设计参考 Skill，主要在 `design-system-governor` 阶段提供 UI\u002FUX 模式、风格、配色、字体和设计建议，不是主链路必经步骤。\n\n---\n\n## 🎯 什么时候适合用？\n\n### 场景 1：PRD 还没变成 UI，团队需要先看方向\n\n**适合：** 产品经理、创业团队、业务负责人、需要快速对齐视觉方向的项目团队。\n\n你有 PRD，但团队还不知道页面最终大概长什么样。\n\n使用方式：\n\n```text\nPRD\n→ image2-prompt-pack\n→ Image Model\n→ 多轮视觉确认\n→ Final Reference\n```\n\n价值：\n\n- 写代码前先看到 UI 方向\n- 产品、设计、研发、决策者可以提前讨论\n- 减少\"实现完才发现方向不对\"\n\n---\n\n### 场景 2：已经有参考图，要让 Codex \u002F Claude Code 按目标写前端\n\n**适合：** 正在使用 Codex \u002F Claude Code 做前端实现的开发者或 AI Coding 用户。\n\n你已经定稿了一张 UI 视觉图，希望 Agent 按这个目标实现前端。\n\n使用方式：\n\n```text\nreference.png\n→ visual-to-spec\n→ visual-spec-review\n→ design-system-governor\n→ Codex \u002F Claude Code Implementation\n```\n\n价值：\n\n- 把图像变成 Agent 能执行的视觉合同\n- 限制 Agent 自由发挥\n- 防止默认套 dashboard、sidebar、KPI cards\n- 让前端实现围绕 `reference.png` 和 visual spec 展开\n\n---\n\n### 场景 3：页面已经跑起来，但和参考图不够接近\n\n**适合：** 需要做 UI 还原、视觉验收、前端修复和回归检查的团队。\n\n你已经有代码和浏览器效果，但和参考图还有差异。\n\n使用方式：\n\n```text\nspec-compliance-review\n→ visual-acceptance-review\n→ visual-diff-fix\n→ Re-check\n```\n\n价值：\n\n- 用 spec 和 screenshot 双向校验\n- 把差异定位到模块和修复任务\n- 让 Agent 定向修复，而不是重写整个页面\n- 每一轮修复后都能重新验收\n\n---\n\n## 📦 你可以从这个项目拿走什么？\n\n这个仓库不是一个完整 UI 生成产品，而是一套可以拆解、借鉴、迁移的 AI 前端工作流参考骨架。\n\n你可以直接参考：\n\n- 一套视觉目标驱动的 AI 前端实现流程\n- 一套把 PRD 转成 UI visual target 的 prompt pack 方法\n- 一套把 UI 截图转成 visual spec \u002F tokens \u002F component tree 的结构\n- 一套防止 Agent 幻觉组件的审查规则：bbox evidence、Prohibited Components、Rejected Assumptions\n- 一套 `source \u002F confidence \u002F strictness` 的质量标注体系\n- 一套 `Pass \u002F Conditional Pass \u002F Fail` 的门禁设计\n- 一套 `screenshot acceptance → fix-tasks.json → diff fix` 的修复闭环\n- 一套可以迁移到 Codex、Claude Code 或自研 Agent Workflow 的目录与文档骨架\n\n如果你也在尝试用 Codex \u002F Claude Code 做前端 UI，经常遇到\"方向不清、Agent 乱改、修完又回归\"的问题，可以先收藏这个 repo，后续按自己的项目需要，逐步迁移其中的 Skill。\n\n---\n\n## ✅ 适合场景与当前边界\n\nUI Skill Lab 更适合 **代码可实现为主的 UI**，例如 Dashboard、SaaS、管理后台、移动端页面和普通 landing page。\n\n| 场景 | 适配度 | 说明 |\n|---|---|---|\n| Dashboard \u002F SaaS \u002F 管理后台 | ✅ 高 | 大部分元素可用 HTML \u002F CSS \u002F 组件实现，适合完整 workflow |\n| Mobile app screen | ✅ 高 | 适合做布局、tokens、组件结构和响应式规格 |\n| 普通 landing page | ✅ 中高 | 有 clean hero \u002F product assets 时效果更好 |\n| Image-led landing | ⚠️ 中 | 可定义 image layer 和 overlay strategy，但不自动切图 |\n| Panorama \u002F 3D 展厅 \u002F 展台 UI | ⚠️ 中 | 可定义场景层、控件层和验收规则，主视觉需要 clean assets |\n| 海报 \u002F 强视觉合成页面 | ⚠️ 较低 | 没有独立素材时，只能做截图级规格和验收建议 |\n| 自动切图 \u002F 抠图 \u002F Figma 导出 | 🚧 未来探索 | 会先进入 Asset Workflow Planning，不代表已经支持生产级自动导出 |\n\n\u003Cdetails>\n\u003Csummary>当前暂不覆盖的能力\u003C\u002Fsummary>\n\nUI Skill Lab 当前不会自动完成：\n\n- 从整张图里切出背景、产品图、人物、图标或 logo\n- 生成透明 PNG \u002F WebP \u002F SVG\n- 导出 @1x \u002F @2x \u002F @3x 多倍率资源\n- 从 Figma \u002F PSD \u002F Sketch 图层导出素材\n- 自动抠图、分割图层或重建照片级主视觉\n\n如果页面强依赖切图，当前推荐：\n\n```text\n先准备 clean assets\n再使用 UI Skill Lab 做：\nvisual spec → asset strategy → code audit → screenshot acceptance → diff fix\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 🧷 它真正控制的是什么？\n\n当 Agent 进入 UI 生产流程后，真正需要控制的是：每一轮输出都不要偏离已确认的视觉目标。\n\nUI Skill Lab 本质上是一套 anti-drift workflow：\n\n| Drift 类型 | 对应 Skill |\n|---|---|\n| 生图漂移 | `image2-prompt-pack` |\n| 规格漂移 | `visual-to-spec` + `visual-spec-review` |\n| 设计系统漂移 | `design-system-governor` |\n| 代码实现漂移 | `spec-compliance-review` |\n| 视觉验收漂移 | `visual-acceptance-review` |\n| 修复漂移 | `visual-diff-fix` |\n\n它让 Agent 参与 UI 生产时，每一步都有：\n\n- source of truth\n- evidence\n- confidence\n- strictness\n- review gate\n- fix task\n- re-check loop\n\n---\n\n## 🛡️ Quality Gates & 测试基础设施\n\n项目包含三层质量门禁：\n\n| 层级 | 工具 | 验证内容 |\n|---|---|---|\n| Skill 源契约 | `validate-skill-source-contracts.mjs` | `SKILL.md` 格式、引用文件存在性、示例 JSON 合法性 |\n| E2E Pipeline Gate | `validate-ui-skill-e2e.mjs` | 每个 pipeline 阶段的输出完整性、token schema、bbox evidence、gate enforcement |\n| 视觉重建基准 | `compare-visual-reconstruction.py` | 对测试样例计算 MAE、RMSE、SSIM，并进行 anti-cheat 检测 |\n\n> `tests\u002Freal-runs\u002F` 是 workflow validation artifacts，用于验证 pipeline 输出结构和流程完整性。它们不是像素级重建质量的证明。像素级重建质量应在 `tests\u002Fvisual-reconstruction\u002F` 下通过 anti-cheat 检查来评估。\n\n> 当前 CI 默认验证 Skill 契约、E2E pipeline gate 和 visual benchmark 配置。完整截图采集与视觉对比建议在本地或 scheduled workflow 中安装 Playwright 浏览器后运行。\n\n---\n\n## 🚀 在自己的项目中使用\n\n你不需要复制整个仓库。\n\n最小用法是把 7 个核心 Skill 复制到你的项目：\n\n```text\nyour-project\u002F\n└── .codex\u002F\n    └── skills\u002F\n        ├── image2-prompt-pack\u002F\n        ├── visual-to-spec\u002F\n        ├── visual-spec-review\u002F\n        ├── design-system-governor\u002F\n        ├── spec-compliance-review\u002F\n        ├── visual-acceptance-review\u002F\n        └── visual-diff-fix\u002F\n```\n\n完整迁移说明见：[Using Skills in Your Project](docs\u002Fusing-skills-in-your-project.md)\n\n---\n\n## ⚡ Quick Start\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FJason904\u002Fui-skill-lab.git\ncd ui-skill-lab\n\npip install -r requirements.txt\nnpx playwright install chromium\n\nnpm run check-prereqs\nnpm run fixtures:seed\nnpm test\n\nnpm run visual:seed\nnpm run visual:check-config\n```\n\n详见 [Getting Started](docs\u002Fgetting-started.md)。\n\n---\n\n## 🗺️ Roadmap\n\nUI Skill Lab 会围绕一个核心方向持续迭代：\n\n> 把 UI 的主观视觉目标，逐步转成 Agent 可以执行、检查和修复的客观规格。\n\n当前版本优先覆盖 **非切图场景**：  \n适合 Dashboard、SaaS、管理后台、移动端页面、普通 landing page 等主要由 HTML \u002F CSS \u002F 组件实现的 UI。\n\n后续会逐步扩展到 **asset-heavy 页面**：  \n例如产品图、人物图、插画、3D 主视觉、展厅背景、海报式页面、sprite 动效等更依赖图片资产和切图资源的场景。\n\n---\n\n### 阶段 1 — 质量门禁增强\n\n目标：让 UI 复现过程更可评估、更可回归、更不容易越修越乱。\n\n计划方向：\n\n- 增强截图验收报告，让差异更容易定位\n- 增加区域级对比，例如 header、hero、card、form、navigation\n- 优化 blocking \u002F warning \u002F suggestion 分级\n- 让 `fix-tasks.json` 更适合 Agent 做定向修复\n- 增加更多真实页面样例，完善 visual benchmark\n- 明确哪些检查适合 CI，哪些适合本地或 scheduled workflow\n\n---\n\n### 阶段 2 — Asset-aware Workflow\n\n目标：让 UI Skill Lab 更好地处理包含图片资产的页面。\n\n适合场景：\n\n- landing page 里的产品图、人物图、插画\n- 3D 展台、展厅、展示页背景\n- 大面积 image-led hero 区域\n- background image + overlay UI 页面\n\n计划方向：\n\n- 在 visual spec 中增加 asset strategy\n- 区分哪些内容适合代码实现，哪些内容应该作为图片资产保留\n- 设计 `asset-manifest.proposed.json`\n- 输出建议的 asset list，例如 background、hero image、logo、icon、illustration\n- 增加 clean assets checklist\n- 在验收阶段区分 code-rendered layer 和 image asset layer\n\n---\n\n### 阶段 3 — Asset Slicing Planner\n\n目标：探索从完整视觉图中规划切图资源，让复杂视觉页面也能进入 UI Skill Lab 的规格化流程。\n\n计划方向：\n\n- 新增 `asset-slicing-planner` Skill\n- 从 reference image 中识别潜在切图区域\n- 输出候选切图清单，例如 background、hero image、product image、character image、icon、decorative element\n- 生成 proposed asset manifest，包括 asset name、asset type、bounding box、recommended format、density suggestion、usage layer\n- 标记哪些资产适合自动建议，哪些需要人工确认\n- 与 `visual-to-spec`、`design-system-governor`、`visual-acceptance-review` 串联\n\n这一阶段会优先沉淀 **切图规划、资产命名、资源规格和人工确认流程**，让带图片资产的页面有更清晰的实现路径。\n\n---\n\n### 阶段 4 — Design Source Adapter\n\n目标：探索从更可靠的设计源读取图层和资产，减少单张截图反推带来的不确定性。\n\n计划方向：\n\n- 探索 Figma \u002F PSD \u002F design-layer export adapter\n- 读取图层命名、尺寸、位置和资产类型\n- 将设计源图层转换为 asset manifest\n- 将 design layer 与 visual spec 对齐\n- 支持从设计源导出的 clean assets 接入前端实现流程\n\n---\n\n### 阶段 5 — Sprite \u002F Motion \u002F Interactive Asset Workflow\n\n目标：支持更复杂的 UI 资产和动效场景。\n\n计划方向：\n\n- 探索 sprite sheet \u002F icon sheet \u002F raster asset workflow\n- 支持简单动效资产的规格描述\n- 描述 hover、transition、loading、micro-interaction 等状态\n- 支持 sprite frame manifest\n- 将动效资源与 design system rules、visual acceptance 结合\n- 为角色、展台、交互式页面等复杂场景提供 asset + UI workflow\n\n---\n\n### 长期方向\n\nUI Skill Lab 的长期目标是持续沉淀一套 AI 前端实现方法：\n\n```text\nPRD\n→ UI 视觉稿\n→ 视觉规格合同\n→ 设计系统\n→ Agent 实现\n→ 截图验收\n→ 差异修复\n→ 资产工作流\n```\n这个方向会持续围绕三个目标推进：\n- 让视觉目标更容易被团队确认；\n- 让实现规格更容易被 Agent 执行；\n- 让最终结果更容易被验收、修复和回归。\n---\n\n## License\n\nMIT\n",2,"2026-06-15 02:30:05","CREATED_QUERY"]