| name | hello-ui |
|---|---|
| description | 从前端页面参考或现有项目建立一份可维护的 DESIGN.md；开发多页面或单页多模块时统一风格与组件、复用逻辑、适配手机与桌面，并对比页面截图发现视觉漂移。 |
helloUI
面向依靠可运行 demo 与用户需求持续迭代的前端项目，无需原型图。目标依次是多页面/多模块的风格与组件一致、共享逻辑复用、同一页面在手机与桌面可用。不同 HTML 文件表示不同功能页面；同一功能页面使用同一份 HTML/路由。项目根目录的 DESIGN.md 是已确认规则的简明入口。当前用户需求决定本次变化，源码和实际页面是现状证据，自动生成的候选报告不是设计规范。
从页面参考开始
用户给出已有前端 demo 页面 ZIP 时，先检查压缩包内容、入口文件、资源和运行方式，再在目标项目中建立可运行基线；保留原件，避免覆盖用户已有文件。把页面作为设计与实现证据，不把每个页面机械地当成独立产品规则。先盘点页面/模块、共享样式和组件、重复的 JS 行为与数据处理，再决定哪些应统一、哪些是有意差异。若压缩包不是完整可运行项目，说明缺少什么，并在现有材料范围内继续。
接入进行中的项目
直接在现有项目中工作。没有 DESIGN.md 时，从当前源码、实际页面和已确认的用户需求提炼规则，建立简短文档，标出冲突与待确认项；不要为建文档大规模改写功能。已有 DESIGN.md 时先阅读并对照实现，判断差异是新需求带来的规范变更、实现漂移还是有意例外。完成需求并检查可运行 demo；只有项目级规则变化才更新受影响的内容，不重写整份文档。
建立或更新设计规则
- 先读现有
DESIGN.md（如有）、用户要求、模板页面、共享 CSS/变量和组件。已有明确决策优先于出现次数；单页偶然样式不能自动升级为全站规则。 - 对静态 HTML/CSS 项目运行
python <skill>/scripts/extract_design.py --project-root <项目>。脚本生成.hello-ui/evidence.json与.hello-ui/proposals.md：记录页面、CSS 变量、重复声明、共享类名、媒体查询和可能的漂移。它不创建或覆盖DESIGN.md，也不调用浏览器。脚本看不到的 CSS-in-JS、构建结果或动态状态，由 Agent 另行检查。 - 阅读候选报告及其文件、行号证据。在手机窄屏、桌面宽屏和实际布局转换附近渲染相关页面，检查计算后的样式、内容顺序、导航、溢出和交互。没有渲染能力时，标明仅凭源码的结论及未验证项；不要声称完成视觉验证。
- 区分共享规则、页面例外与历史漂移。按 设计文档契约 用一份
DESIGN.md覆盖页面目标、业务语义（适用时）、体验、视觉、组件和页面类型这六个视角，并指出共享逻辑的实际入口。只写有依据的当前规则；不确定的意图标[待确认]，冲突列出具体证据。不要把自动报告整段复制进正式规范。
开发页面与模块
先读 DESIGN.md 和受影响的现有页面，再实现新功能。新页面沿用共享导航、排版、语义颜色、间距和组件状态；同页新模块遵守标题层级、内容节奏与基础组件样式。比较旧页面与新页面、相邻模块的导航、边距、同义按钮/卡片/表单及其状态；有意差异要说明适用范围和原因。优先复用项目已有共享 CSS、变量或组件，不为纯 HTML demo 引入用户未要求的框架。
对相同的交互流程、校验、格式化和数据处理，优先查找现有实现；确有重复时抽取小而稳定的共享函数/模块，并让各页面调用它。保持业务含义和状态一致，避免把相似外观但职责不同的逻辑强行合并。源码提取脚本主要分析 HTML/CSS，不会自动判断 JS 逻辑能否复用。
同一页面在手机和桌面宽度下保留核心内容与操作；用流式布局、媒体查询或项目已有机制调整栏位、顺序、导航呈现。用内容碰撞而非设备名称解释断点。检查至少一个手机和一个桌面宽度，特别留意导航、内容顺序、主操作、溢出和交互状态；中间宽度、横屏、长文案或虚拟键盘影响任务时补测。
截图对比
新增页面、较大模块或共享样式变化时，如项目已有 ui-baseline/manifest.json 且具备可选截图依赖，运行 python <skill>/scripts/visual_compare.py --project-root <项目> --mode compare。脚本按基线中的页面和视口截整页图，写入 .hello-ui/visual-report/ 的当前图、红色差异图和报告，发现超阈值变化时返回非零状态。检查差异是否由本次用户需求引起，同时对照新旧页面的共享风格；新页面还没有基线，须直接检查并在确认后加入基线。像素差异只能指出变化，不能判断设计是否正确。
项目尚无基线时，先运行和查看代表性页面，确认当前状态可作为比较起点，再用 --mode baseline --pages ... 建立基线。用户需求引起的变化经核对后，才用 --mode baseline --replace-baseline --pages ... 更新基线；compare 不会覆盖它。截图工具未安装或页面无法运行时，按前述方式人工检查并说明未做自动对比。不要为普通文案小改强制安装依赖。详细命令见 README。
普通文案和局部样式调整无需重新提炼规则。新增共享组件、改变视觉语言或发现跨页漂移时再提炼并更新 DESIGN.md。重要选择的理由可简记在受影响的规则旁，无需默认增加文档。
交付边界
说明提炼了哪些候选、接受或拒绝的依据、实际修改的规则、验证的视口与未验证项。不要安装钩子、修改项目配置、提交代码或自动发布，除非当前任务授权。生成物不加署名或推广文字。