UI 设计师（UI Designer）

从需求或交互设计文档出发，设计界面视觉方案，并产出可运行的 HTML demo。

📖 概述

目的：补齐设计链路"交互逻辑 → 视觉层"之间的界面视觉设计环节，把"用户怎么操作"转译为"界面长什么样"，并直接产出可运行的 HTML demo，让设计可预览、可评审、可交付。

功能：

• 从交互设计文档（interaction-design 产出）或需求描述出发，设计界面视觉方案
• 按页面产出 ASCII 布局图并定稿——demo 的前置闸门（绘制规范对齐 ui-to-ascii，结构复杂时调用其描述生成模式）
• 产出界面布局方案文档：页面结构、布局栅格、组件清单与状态、配色、字体、间距/圆角/阴影 token、响应式规则
• 设计 token 化（CSS 变量），方案与 demo 一一对应
• 编写零构建、可直接浏览器打开的 HTML demo（HTML + CSS + 原生 JS）
• 按场景加载外部风格工具库（taste-skill）：检测 ui-tools/skills/，匹配并加载对应风格指令

使用场景：

• 用户说"设计这个界面"、"这个页面怎么布局"、"帮我画个页面设计"
• 用户说"出个 UI 设计"、"页面原型"、"写个 HTML demo"、"做个 demo 页面"
• interaction-design 完成交互设计后，需要视觉层设计

📍 定位

requirement-mining → interaction-design → ui-designer（本 skill）→ design-craft → design-to-code
     需求挖掘            交互逻辑设计           UI 视觉设计             技术设计        代码骨架

• 输入：交互设计文档（首选）或需求描述
• 输出：ASCII 布局图（定稿，demo 前置闸门）+ 界面布局方案文档 + 可运行 HTML demo
• 边界：只管视觉层（布局、组件、配色、字体、样式规范）；交互逻辑交给 interaction-design，技术架构交给 design-craft
• 与 ui-to-ascii 分工：从零设计的布局 ASCII 图由本 skill 产出（绘制规范以 ui-to-ascii 为准，复杂页面调用其描述生成模式）；"已有设计稿 → ASCII 存档"归 ui-to-ascii（模式 A）；什么算界面改动、什么可不出图（触发与豁免）以其「界面确认闸门」为准
• 与 demo-verify 区分：demo-verify 针对设计中的风险点构建技术验证原型（"这方案可行吗"）；本 skill 的 HTML demo 呈现已定的视觉方案（"界面长这样"），目标不同

📐 核心原则

1. 布局图先于 demo：先产出经确认的 ASCII 布局图与布局方案文档，确认后再写 HTML demo，不边想边写；ASCII 布局图未定稿，不得开始编写 demo
2. token 化设计：颜色/字号/间距/圆角/阴影一律用 design token（CSS 变量）承载，杜绝散落硬编码
3. 状态不可缺：组件不只画默认态，悬停/聚焦/禁用/加载/错误/空状态都要定义
4. 与交互文档对齐：页面的流程、反馈、异常必须来自交互设计文档，不自行发明
5. 移动优先响应式：先定小屏布局，再扩展到大屏；断点规则明确
6. demo 零构建：单文件 HTML，双击即开，不引入框架/构建工具/包管理
7. 可落地：方案是给 design-craft 和前端实现用的，规格要具体（具体色值、具体字号、具体间距），不用模糊词
8. 分阶段确认：页面清单、ASCII 布局图、视觉风格、demo 均为确认点，未经确认不进入下一步
9. 风格工具必须安装：设计前检查当前工作区根目录 ui-tools/skills/ 风格工具库；缺失时必须先安装（见阶段 0.4），再按场景匹配加载对应风格 skill 作为视觉指令

🔀 工作流总览

阶段 0：输入识别与信息收集 → 确定输入类型（交互文档 / 需求描述），收集设备/技术栈/品牌约束，检查并确保风格工具库已安装
阶段 1：页面与结构设计     → 页面清单 + 信息层级 + 每页目的
阶段 2：布局设计           → 布局模式 + 栅格 + ASCII 布局图（demo 前置闸门）+ 响应式策略
阶段 3：组件与状态设计     → 组件清单 + 各状态视觉定义
阶段 4：视觉风格设计       → 场景匹配加载风格工具 + 配色 + 字体 + 间距/圆角/阴影 token + 图标 + 暗色（按需）
阶段 5：产出界面布局方案文档 → 落盘 docs/ui-design/{slug}.md
阶段 6：HTML demo 编写     → 前置：ASCII 布局图已定稿；落盘 demo/{slug}/index.html，实现方案并验证
阶段 6.5：体验计划与报告   → 体验前产出体验计划、体验后产出体验报告，均关联代码 commit 追溯
阶段 7：质量自检           → 对照自检清单核对

每个阶段输出后等用户确认再进入下一阶段；用户未确认时默认保留"待确认"标注继续后续设计阶段，不静默推翻已确认内容；但阶段 6 demo 不适用"未确认继续"——ASCII 布局图未定稿（且未获明确豁免）不得开始编写 demo。

🚦 阶段 0：输入识别与信息收集

0.1 识别输入类型

输入	处理
交互设计文档（interaction-design 产出）	直接作为主输入：页面清单、操作流程、反馈状态、异常路径都来自它
仅有需求描述	先提取页面与功能点，列出初步页面清单请用户确认；必要时提示先走 interaction-design
两者都有	以交互文档为准，需求描述用于补充上下文

0.2 信息收集清单

向用户确认以下信息（可从上下文推断，缺省时做合理假设并注明）：

1. 目标设备：桌面优先 / 移动优先 / 自适应（影响断点与布局策略）
2. 技术栈约束：是否有既定前端框架（影响 HTML demo 是否用原生实现，demo 默认纯原生）
3. 品牌与设计系统：品牌色、Logo、已有组件库规范；没有则本阶段 4 从零设计
4. 设计范围：全部页面还是某几个关键页面（页面多时先设计 2-3 个关键页面示范）
5. 参考偏好：用户提到的风格关键词（简约/活泼/商务/科技感）或参照产品

0.3 输出格式

🎯 输入与范围
━━━━━━━━━━━━━━━━

【输入类型】交互设计文档 / 需求描述 / 两者
【目标设备】桌面优先 / 移动优先 / 自适应
【技术栈约束】（若有）
【设计范围】页面清单：
- P1：登录页
- P2：仪表盘
- ...

【待确认】
- 品牌色/设计系统：未提供，将在阶段 4 从零设计（默认取主色 #1677FF）
- ...

请确认页面清单与设计范围。

0.4 风格工具库检查（必须安装）

风格工具库是必须组件，目录固定为当前工作区根目录 ui-tools/skills/。检测结果处理：

状态	处理
存在	列出可用工具 skill（design-taste-frontend / minimalist-ui / frontend-design …），供阶段 4 按场景选择
缺失	必须安装：在当前工作区根目录执行下方安装命令，确认安装完成后再继续后续阶段；不得跳过、不得降级
安装失败	重试 1 次；仍失败则暂停并向用户报告原因（如 Node/npx 缺失、网络不可达），待用户处理后继续

在当前工作区根目录安装：

mkdir -p ui-tools && cd ui-tools
npx skills add https://github.com/Leonxlnx/taste-skill --agent openclaw -y
npx skills add https://github.com/anthropics/skills --skill frontend-design theme-factory --agent openclaw -y

安装完成后列出 ui-tools/skills/ 下的 skill 清单。

🗂️ 阶段 1：页面与结构设计

对确认的每个页面：

1. 页面目的：一句话说明该页面达成什么（对应交互文档的场景目标）
2. 信息优先级：划分首要 / 次要 / 辅助三级信息，决定视觉权重
3. 导航关系：页面间跳转关系（来自交互文档的流程）

输出格式

🗂️ 页面清单
━━━━━━━━━━━━━━━━

| 页面 | 目的 | 首要信息 | 次要信息 | 来源场景 |
|------|------|----------|----------|----------|
| 登录页 | 完成身份认证 | 账号密码表单 | 注册入口、忘记密码 | S-01 |

请确认页面清单与信息优先级。

📊 阶段 2：布局设计

对每个页面：

1. 选布局模式：从布局模式库选型（见 reference.md），如单列、双栏、侧边栏导航、卡片网格、master-detail 等
2. 定栅格：12 列栅格下各区块的列占比
3. 画 ASCII 布局图：产出布局定稿物——绘制规范以 ui-to-ascii 为准（字符集 / 宽度 / 中文全角对齐 / 编号锚点，见 reference.md）；结构复杂（多区域嵌套 / 多屏 / 单图放不下）时调用 use_skill("ui-to-ascii") 描述生成模式（骨架 + 局部放大）
4. 响应式策略：桌面 / 平板 / 移动的布局变化（如侧边栏 → 抽屉）

ASCII 布局图是 demo 的前置闸门：经用户确认定稿（或用户明确豁免）后，才可进入阶段 6 编写 demo——布局未定就写代码，返工必然连带 demo 重写。上游（如 PM 报告）传来的界面示意图只作设计输入，不能当作定稿图——定稿图必须在本阶段产出并经用户确认。

输出格式

📊 布局设计
━━━━━━━━━━━━━━━━

【登录页】
布局模式：单列居中卡片

┌────────────────────────┐ │ Logo │ │ [ 账号输入框 ] │ │ [ 密码输入框 ] │ │ [ 登录按钮 ] │ │ 注册入口 · 忘记密码 │ └────────────────────────┘

响应式：桌面卡片宽 400px 居中；移动端卡片占满屏宽、上下留白 16px。

请确认 ASCII 布局图（定稿后 demo 才启动）。

🧩 阶段 3：组件与状态设计

1. 组件清单：页面用到的组件（按钮、输入框、表格、卡片、弹窗、下拉、标签等）
2. 状态定义：每个组件的状态视觉——默认 / 悬停 / 聚焦 / 禁用 / 加载 / 错误
3. 对齐交互文档：交互文档里的"成功/失败/等待/空"反馈 → 对应视觉呈现（成功提示条、错误红字、加载 spinner、空状态插画文案）

输出格式

🧩 组件状态
━━━━━━━━━━━━━━━━

【主按钮】
| 状态 | 视觉 |
|------|------|
| 默认 | 主色底 #1677FF + 白字 + 圆角 6px |
| 悬停 | 加深 #0958d9 |
| 禁用 | 灰底 #f5f5f5 + 灰字 #bfbfbf |
| 加载 | spinner 替代图标 + 禁用态 |

【表单校验错误】输入框红边框 #ff4d4f + 红字提示
【空状态】插图占位 + 引导文案 + 主按钮

请确认组件与状态。

🎨 阶段 4：视觉风格设计

4.0 风格场景匹配（工具库优先）

若阶段 0.4 检测到风格工具库，按 reference.md 的场景路由表匹配本次设计场景并加载对应风格 skill：

1. 选风格：从路由表选定候选风格 skill（如新 landing 页 → design-taste-frontend；用户要极简风 → minimalist-ui；改造现有项目 → redesign-existing-projects）
2. 加载指令：读取 ui-tools/skills/{name}/SKILL.md，提炼其关键设计准则（排版/配色/动效/间距/禁用的默认模式），作为本设计的风格基调——不全文照搬，控制 token 成本；拿不准的准则可在加载后回看原文
3. 交叉偏好：用户明确偏好优先于路由默认；冲突时以用户为准并说明
4. 冲突裁决：风格工具指令与内置参考 token（4.1 起）冲突时，以风格工具为准（用户加载它就是想要该风格）；内置 token 仅作为无匹配场景时的基线兜底
5. 兜底：仅当无匹配场景时使用内置参考色板与 token（见下方 4.1 起），继续正常流程（工具库已由阶段 0.4 保证存在）

风格指令只影响"长什么样"，不改变页面结构（阶段 1-2 已确认）与交互流程（来自交互文档）。

4.1 视觉 token 定义

定义全站视觉 token（详细规范库见 reference.md）：

1. 配色：主色 / 辅助色 / 功能色（成功·警告·错误）/ 中性色（文本、背景、边框），给出具体 hex 值
2. 字体：字体栈（含中文字体）、字号阶梯、字重、行高
3. 间距 token：4px 或 8px 基准的间距档位
4. 圆角 / 阴影：token 档位
5. 图标风格：统一线型或面型、描边粗细
6. 暗色模式（按需）

输出格式

🎨 视觉风格
━━━━━━━━━━━━━━━━

【配色 token】
| token | 值 | 用途 |
|-------|-----|------|
| --color-primary | #1677FF | 主操作 |
| --color-success | #52c41a | 成功反馈 |
| --color-error | #ff4d4f | 错误反馈 |
| --color-text | #1f1f1f | 正文 |

【字体】font-family: -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif
【字号】12 / 14 / 16 / 20 / 24 / 32
【间距】4 / 8 / 12 / 16 / 24 / 32
【圆角】4 / 6 / 8 / 12
【阴影】sm / md / lg 三档

请确认视觉风格。

📄 阶段 5：产出界面布局方案文档

将阶段 1-4 确认的内容合并为界面布局方案文档，按 reference.md 的模板写入：

• 默认路径：docs/ui-design/{slug}.md（slug 取功能名 kebab-case，如 login-page、dashboard）
• 需求管理集成：项目存在 .requirements/config 时，改用 .requirements/design/ui-design.md 存储，并调用 req update {REQ-NNN} --docs add design/ui-design.md,design --changelog "完成 UI 设计" 注册文档关联（与 interaction-design 的存储体系保持一致，保证设计链路文档统一管理）；需求 ID 不存在或 req 命令不可用时跳过集成，按默认路径落盘
• 无法写入或用户另有指定时遵循用户指定路径

文档应包含：概述与输入来源 / 页面清单 / 各页面布局与结构 / 组件状态表 / 视觉 token 总表 / 响应式规则 / 待确认项。

落盘后向用户简述：设计了几个页面、定义了多少 token、有几项待确认。

🖥️ 阶段 6：HTML demo 编写

前置闸门（硬性）：开工前逐个核对 demo 将要实现的每个页面（含状态视图）的 ASCII 布局图是否已定稿（用户已确认，或明确豁免）；存在未定稿页面 → 回阶段 2 补齐，不得先写 demo。

按 reference.md 规范编写可运行 demo，写入 demo/{slug}/index.html：

1. 实现方案：按方案文档的布局、组件、token 实现，CSS 变量名与方案文档 token 一一对应
2. 覆盖状态：至少展示默认态 + 关键状态（如登录错误提示、按钮禁用/加载）
3. 响应式验证：按断点调整视口检查布局变化
4. 交互演示：用原生 JS 实现 demo 所需的最小交互（表单校验、Tab 切换、弹窗开关），仅演示不接真实后端

框架约束：默认纯原生零构建；若用户在阶段 0 明确指定框架（如 React/Vue），遵循用户约束——demo 用单文件 CDN 引入或用户提供的构建环境实现，并在方案文档记录偏离默认规范的说明。

完成后在回复中给出预览方式（如 demo/{slug}/index.html 浏览器打开）并说明 demo 覆盖了哪些状态。

🧪 阶段 6.5：体验计划与体验报告

HTML demo 产出后进入体验验证闭环，双文档均须记录对应代码 commit 信息用于追溯（模板与 commit 获取方式见 reference.md）。用户要求体验验证、需要追溯产物对应代码版本时执行；否则可跳过并标注。

6.5.1 体验前：产出体验计划

1. 关联 commit：记录当前代码 commit（git rev-parse --short HEAD 取 hash + git log -1 --format=%s 取 message）；未提交则标注 [工作区未提交] 及变更文件清单，不编造 commit
2. 体验目标：本次体验要验证什么（如登录流程顺畅、移动端适配正确、风格统一）
3. 体验项清单：对照交互文档的流程/反馈/状态逐项列出（页面流、表单校验、错误/空/加载态、响应式断点、风格一致性）
4. 体验方法：浏览器走查 / 多设备视口 / 用户试玩
5. 验收标准：每项给出可判定的通过标准

6.5.2 体验后：产出体验报告

1. 关联 commit：记录体验时对应代码 commit（与 6.5.1 同法），保证可回溯到"这个版本体验出这个结果"
2. 体验结果：体验项逐项记录（✅ 通过 / ⚠️ 存疑 / ❌ 失败），附证据（截图/视口/描述）
3. 发现问题：问题清单 + 严重度 + 建议修复方向 + 关联体验项
4. 结论：通过 / 有条件通过 / 不通过；不通过则回到对应阶段修正，修正后更新报告并标注新 commit

与 design-craft 的衔接

方案文档产出后，design-craft（技术设计）可以：

• 页面与组件：直接引用方案文档的页面结构、组件清单作为前端实现的输入
• 接口设计：参考方案文档确认页面所需数据（列表、详情字段），对照交互设计的反馈状态
• 数据模型：参考页面展示的信息层级确定数据结构
• demo 复用：HTML demo 可作为 design-craft 阶段的原型参照，供技术选型与接口设计对表

✅ 阶段 7：质量自检

复制此清单核对：

方案质量：
- [ ] 页面清单与交互文档/需求一致，无凭空发明的页面
- [ ] 每页信息优先级明确（首要/次要/辅助）
- [ ] 布局模式选型合理，有响应式策略
- [ ] demo 涉及的每页 ASCII 布局图已产出且已处置（已定稿或用户明确豁免，无悬空页面）
- [ ] 组件覆盖全部状态（默认/悬停/聚焦/禁用/加载/错误/空）
- [ ] 交互文档的成功/失败/等待/空反馈都有视觉呈现
- [ ] 配色/字体/间距/圆角/阴影均为 token，无散落硬编码
- [ ] 色值具体（hex），无模糊描述

风格工具库：
- [ ] 工具库已安装（当前工作区 ui-tools/skills/），按场景匹配正确风格 skill
- [ ] 加载的风格指令已体现在设计输出中，非只读不用
- [ ] 工具库缺失时已先完成安装（阶段 0.4），未硬编不存在的风格

demo 质量：
- [ ] 与已定稿的 ASCII 布局图一致（结构无偏）
- [ ] 单文件、零构建、浏览器直接打开可运行
- [ ] CSS 变量名与方案文档 token 一致
- [ ] 语义化 HTML 标签
- [ ] 移动优先响应式，关键断点布局正确
- [ ] 关键状态已演示（默认态必达，错误/空/加载按需）
- [ ] 无真实后端依赖，交互均为演示性质

体验闭环（如执行了阶段 6.5）：
- [ ] 体验计划已产出（体验项覆盖交互文档流程/反馈/状态）
- [ ] 体验报告已记录逐项结果与问题
- [ ] 体验计划与报告均记录了对应代码 commit（未提交已标注）

任一项不通过 → 回到对应阶段修正后重新核对。

🚫 反模式

• ❌ 不产出方案直接写代码，或方案未确认就进入 demo
• ❌ 把设计写成像素级视觉稿（要 token 化、可落地给 design-craft 与前端）
• ❌ 脱离交互设计文档凭空发明页面流程
• ❌ 只画默认态，忽略悬停/禁用/加载/错误/空状态
• ❌ demo 引入框架、构建工具、CDN 依赖（违背零构建）
• ❌ demo 里的 CSS 变量与方案文档 token 不一致
• ❌ 用"好看一点"、"醒目一点"等模糊词代替具体规格
• ❌ 与 ui-to-ascii 混淆：把"已有设计稿 → ASCII 存档"当本 skill 职责（那是 ui-to-ascii 模式 A）；本 skill 的布局 ASCII 图绘制遵循其规范
• ❌ ASCII 布局图未定稿就写 demo：布局还没确认先写 HTML，布局一改 demo 全部返工
• ❌ ASCII 图不按规范画：字符集 / 宽度 / 对齐随意，中文错位、右框线歪斜 → 绘制规范以 ui-to-ascii 为准
• ❌ 工具库已安装却不做场景匹配，直接套用内置默认风格（浪费工具库）
• ❌ 工具库缺失时不安装、跳过阶段 0.4 直接设计（违反"必须安装"约束）

📚 更多资源

• 布局模式库、ASCII 布局图规范、栅格、配色体系、字体系统、间距/圆角/阴影 token、响应式断点、方案文档模板、HTML demo 规范与骨架模板，参见 reference.md
• 风格工具库（taste-skill）场景路由表、安装与加载/兜底机制，参见 reference.md
• 完整设计流程示例（输入 → 方案 → demo），参见 examples.md