从代码生成UI规范
视频会重建产品界面的HTML和CSS,而不是录制真实窗口,因此界面的真实度完全取决于构建它的规范。近似值会被发现:在开发这些技能的生产环境中,审核人员在第一次审核时就拒绝了手绘图标和徽标,而一个尺寸和名称错误的手工徽章让他愤怒不已。修复方法来自阅读代码,而代码中隐藏了肉眼无法察觉的陷阱:根字体大小由应用外壳在运行时设置(14 px,而非样式表声明的10 px),多个CSS变量在生产环境中不存在而使用了回退值,某个组件在两个月前的提交中丢失了强调条,两个“对话框”是自定义弹出框而非库的对话框。
因此,规范中的每一个值都是字面量并带有引用,无法引用的值会被标记,绝不猜测。
输入
videos/<video>/SOURCES.md来自 source-recon:每个屏幕、其路由、组件和状态。如果缺少,请先运行 source-recon。sources/<role>/和sources.lock。每个引用都使用锁定的 SHA。product.yaml:app_canvas.logical(UI 重建时的视口)、app_canvas.theme、app_canvas.rem_px、sources[].framework。- 框架的适配器:
references/adapters/<framework>.md。在编写子代理提示之前先阅读它;它说明了该栈中值隐藏的位置。
| product.yaml 中的框架 | 适配器 | 状态 |
|---|---|---|
angular-primeng | references/adapters/angular-primeng.md | 在生产中已验证 |
react | references/adapters/react.md | 未验证 |
vue | references/adapters/vue.md | 未验证 |
| 任何使用 Tailwind 的栈 | references/adapters/tailwind.md(与框架自身的适配器一起) | 未验证 |
html、other、服务端模板 | references/adapters/html.md | 未验证 |
对于未验证的适配器,请告知用户它尚未验证,遵循它,并在最后添加您学到的东西(一个简短的“在 上学到的”部分),以便下一个产品可以更进一步。
1. 全局渲染事实(每个产品一次)
在任何屏幕之前,建立每个屏幕都依赖的事实,并将其写入 kit/render-facts.md 并附带引用:
- 运行时根字体大小(搜索应用外壳中设置它的代码,而不仅仅是 CSS),以便 rem 正确转换。如果不同,则更新
product.yaml中的app_canvas.rem_px。 - 主题:哪个选择器启用了视频的主题,以及它是否默认启用。
- Token 文件、CSS 层或导入顺序(哪些规则胜出),以及来自锁定文件的组件库及其确切版本和主题预设。
- 实际加载的字体(link 标签、
@font-face、字体包),而不仅仅是 CSS 中声明的字体。声明但从未加载的字体在生产环境中会呈现为回退字体。 - 桌面断点,以确认
app_canvas.logical显示桌面布局。
然后写入令牌,解析为视频主题的字面量:
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/ui-spec-from-code/scripts/resolve_tokens.py" <product_dir> \
[--role frontend] [--theme-selector "html.dark"] [--files src/styles/tokens.css ...]
它读取 CSS 自定义属性、顶层 SCSS 变量以及来自 sources/<role>/ 的 Tailwind v3 主题(静态),解析每个 var() 和 $variable,并写入 kit/tokens.css,每行都带有 /* role/path:line@sha */ 引用。标记为 UNDEFINED 的行是生产环境未定义的变量(可能的故障);标记为 needs a Sass compile 的行是使用 Sass 函数构建的值,子代理必须根据函数及其输入手动解析。当导出包含不相关的样式表(文档站点、电子邮件模板、供应商 CSS)时,请使用 --files。
2. 每个屏幕一个子代理
为每个屏幕(或大屏幕的每个面板)启动一个只读子代理,所有子代理并行运行,填充 references/ui-spec-prompt.md 并附加适配器的“值隐藏位置”列表。将每个子代理指向 sources/<role>/(而不是用户的检出目录),并提供渲染上下文:逻辑画布大小、主题、rem、渲染事实、令牌以及已重建部分的 CSS,以便新部分与之匹配。
每个子代理返回:画布内的几何信息、每个状态的静态 HTML(无框架语法)、一个包含字面值和每个值引用的 CSS 块、作为额外类的悬停/聚焦/激活/禁用/加载状态、具有确切持续时间和缓动函数的过渡和关键帧、按库和名称组织的图标(或逐字内联 SVG)、每个可见字符串,以及一个明确的“未验证”列表。
协调器(您)本身不会提取规范:真实应用的一个屏幕可能需要数十千字节的调查结果,而一个上下文在视频中间填满的协调器会丢失整个构建的跟踪。
3. 图标和图像
图标来自产品自身的图标集和资源,永不手绘,也绝不来自浏览器配置文件或扩展文件夹。每个产品运行一次 references/icon-extraction-prompt.md(并在添加新屏幕时再次运行),将视频需要的每个图标映射到其库和名称,然后将名称交给 product-kit 的 collect_icons.py,该脚本将 SVG 复制到 kit/icons/ 并附带引用。对于没有 SVG 文件的图标字体,构建会从库自身的 CSS 中写入码点,并且必须在遇到未知名称时失败,而不是渲染一个空框。
4. 编写规范
对于每个屏幕,videos/<video>/specs/<screen>.md 和 specs/<screen>.html:
# 规范:<screen>
来源:frontend@1a2b3c4(参见 SOURCES.md)。画布 1440x810,主题 light,rem 16。
## 几何
| 元素 | x | y | w | h | 引用 |
## 状态
S1 <name>:<显示的内容,虚构数据>。HTML 在 <screen>.html 中,第 S1 节。
## CSS
<一个代码块,字面量值,每行都带有 /* role/path:line@sha */>
## 动画
| 内容 | 属性 | 起始值 | 结束值 | 时长 | 缓动函数 | 延迟 | 引用 |
## 图标
| 键 | 库 | 名称 | kit/icons 中的文件 | 引用 |
## 字符串
| 键 | 文本 | 引用 |
## 修复(视频中修复的生产故障)
| 内容 | 生产环境表现 | 视频表现 | 原因 |
## 未验证
- <值或行为,原因,以及最佳可用参考>
保持外观,修复故障
一比一重建布局、令牌和行为,包括使其感觉像真实产品的动画、悬停、打字和加载状态。但修复可见的生产缺陷,因为视频展示了产品的最佳状态,审核人员会问为什么屏幕上显示了一个错误:缺少内边距、溢出、文本被截断、原生的浏览器控件(一个灰色的默认音频播放器)出现在产品原本设计的位置、未定义的变量绘制回退值、点击后的聚焦环残留。在规范的“修复”表和 BRIEF 注释中列出每个修复。保留设计决策中的异常(覆盖字段的粘性页脚、随内容滚动的侧边栏);改变这些属于重新设计,而非修复。
规范还应用并记录了两种转换:
- 规范名称。 即使实时 UI 仍显示旧名称,也将
product.yaml names中的遗留字符串替换为规范名称,并保留该元素的其他所有内容。 - 禁止术语。 如果真实屏幕显示了供应商或
banned_terms中的术语(模型选择器、集成卡片),请将该部分排除在画面之外。它不能看起来空荡荡或破损;选择一个它自然缺席的取景或状态。
数据
规范仅携带来自 product.yaml cast 的虚构数据。仓库中的夹具、种子和截图可以包含真实姓名;使用它们的形状,绝不使用它们的值。
将规范交给构建之前的检查清单
- 引用了锁定的提交;写入了渲染事实;令牌已针对视频主题解析
- 画布大小超过桌面断点;rem 与运行时匹配
- 每个
var()已解析;未定义的值及其回退已列出(或作为故障修复) - 每个字符串来自 i18n 文件或模板;已应用规范名称
- 每个图标来自应用的库;构建在缺少字形时失败
- 徽标和图像来自仓库资源
- 默认状态(标签页、手风琴、切换开关)与代码匹配
- 覆盖、弹出和过渡时序具有精确的缓动函数
- 滚动范围在真实内容内;没有文本在边缘被剪裁
- 画面中无供应商、禁止术语、内部 ID 或真实客户数据
- 列出了修复和保留的异常;为审核人员列出了未验证的值