| name | design-rail-ui |
| description | 用于会影响产品一致性的前端 UI 任务,包括 app 界面、可见组件、布局、样式、导航、弹窗、卡片、设置、列表、表单、颜色、字体、截图参考界面、组件库复用和其他 renderer-facing surface。 |
Design Rail UI
Design Rail UI 是一套给 coding agent 和开发者共用的前端 UI 工作流。
它的目标不是让 agent 自由发挥设计,而是让 UI 修改保持同一套产品语言:先读图,先确认,再按最小范围实现。
什么时候使用
只要任务会影响可见 UI,就使用这个 skill:
- 页面、模块、组件
- 间距、排版、颜色、字体、表面处理
- 导航、弹窗、菜单、popover
- 卡片、列表、设置、表单
- 参考截图、当前截图、视觉风格调整
- 组件库复用、组件替换、组件封装
- 任何 renderer-facing surface
以下情况不用:
- 后端-only 修改
- 不影响 UI 的内部重构
- 不改变渲染结果的纯技术修复
必读文件
提出 UI 改法前必须读:
references/design.md
references/workflow.md
references/component-rules.md
references/ui-communication-glossary.md
references/screenshot-reading.md
涉及代码实现时还必须读:
references/implementation-rules.md
需要更多页面模式、颜色家族、结构术语时再读:
references/ui-glossary.md
硬门槛
识别到 UI 任务后,不允许直接实现。
只要任务涉及截图、参考图、视觉风格、布局、层级、密度、颜色、组件处理或组件库复用,确认就是必需步骤。
实现前必须完成:
- 识别当前
surface
- 识别目标
module
- 说清主要
issues
- 提出计划中的
adjustments
- 提出聚焦的设计决策问题
- 等待用户明确确认后再改代码
以下情况必须先确认:
module change
new module
- 用户提供了当前截图或参考截图
- 小改动但影响布局、层级、颜色、字体、模式选择、密度、组件库使用
没有确认,就不能实现。
如果用户提供截图,必须先返回截图差异报告和改法选项,然后停下来等待用户确认。
截图任务必须输出
当用户提供当前截图、参考截图或模糊视觉反馈时,先输出:
当前 surface(Current surface):
目标 module(Target module):
参考图阅读(Reference reading):
当前差异(Current mismatch):
可能原因(Likely cause):
推荐改法路径(Recommended adjustment paths):
需要你确认(Need your decision on):
然后停止,等待用户确认。
不能在第一次截图分析的同一轮里直接改文件,除非用户已经明确确认了改法。
组件库复用协议
Design Rail 不绑定某一个组件库。每个项目可以使用自己的组件库,例如 HeroUI、shadcn/ui、Radix、Headless UI 或内部组件系统。
进入实现前,agent 必须先检查当前项目的组件环境:
- 查看
package.json 是否已有 UI 组件库
- 查看项目组件入口,例如
src/components/ui、src/renderer/components/ui、components/ui
- 查看目标页面附近是否已有相似组件、卡片、行、弹窗、输入区、toolbar
- 先复用项目已有组件,再考虑直接使用已安装组件库
- 新增组件库或新造基础控件前必须问用户
实现优先级:
- 项目已有业务组件
- 项目已有
components/ui 或类似 UI 入口
- 已安装组件库的 primitives
- 基于已有组件的小封装
- 自定义组件,且必须说明为什么不能复用
禁止默认重写:
- Button
- Input
- Select
- Dialog / Modal
- Tabs
- Dropdown
- Tooltip
- Card
- Badge
- Switch / Checkbox
- Table / List primitives
执行流程
1. 分类改动
先把任务分类:
small change
module change
new module
然后识别:
- 当前 surface
- 目标 module
- 最近的已有模式
- app shell 和层级约束
- 可复用组件和组件库入口
完整流程见 references/workflow.md。
2. 运行确认循环
实现前必须返回结构化 UI reading:
当前 surface(Current surface):
目标 module(Target module):
观察到的问题(Observed issues):
建议改法(Proposed improvements):
模式方向(Pattern direction):
颜色方向(Color direction):
密度方向(Density direction):
组件复用(Component reuse):
需要你确认(Need your decision on):
最低必须包含:
当前 surface(Current surface)
目标 module(Target module)
观察到的问题(Observed issues)
建议改法(Proposed improvements)
如果涉及截图,还必须包含:
参考图阅读(Reference reading)
当前差异(Current mismatch)
可能原因(Likely cause)
推荐改法路径(Recommended adjustment paths)
需要你确认(Need your decision on)
然后停下来等待用户确认。
3. 只在方向明确后实现
用户确认后:
- 写一句简短的
Design direction
- 遵守
workflow.md
- 遵守
component-rules.md
- 涉及代码时遵守
implementation-rules.md
- 优先复用当前项目组件和已安装组件库
不要静默创造新的局部 UI 模式。
沟通规则
讨论 UI 时不要停留在模糊词:
必须翻译成:
surface
module
issue
adjustment
decision
非平凡 UI 任务还要确认:
pattern direction
color direction
density direction
component reuse
术语路由
使用 references/ui-communication-glossary.md 处理:
- 页面名
- 模块名
- 组件名
- 问题名
- 调整动词
- 确认模板
- 模糊反馈翻译
使用 references/screenshot-reading.md 处理:
- 截图阅读顺序
- 当前截图和参考截图对比
- visual contrast pairs
- screenshot-to-decision prompts
使用 references/ui-glossary.md 处理:
- 更广泛的 pattern family
- surface 和结构术语
- 视觉和交互词汇
- 中性颜色方向
完成标准
UI 任务完成必须同时满足:
- 功能可用
- surface 仍然像同一个产品
- 没有引入不必要的新模式
- 代码结构合理
- 已检查关键状态
- 实现前设计方向已被确认
- 已按 skeleton、hierarchy、surface treatment、density、control language、product consistency 做最终 review
- 视觉验收由用户更新截图确认,或明确标记为
pending user review
详细验收流程见 references/workflow.md。