Ui Designer

---
name: ui-designer
description: 设计界面视觉方案——从需求描述或交互设计文档出发，产出界面布局方案文档（页面结构、布局栅格、组件状态、配色、字体、间距/圆角/阴影规范、响应式规则），并负责 HTML demo 的设计编写（可运行的 HTML/CSS/原生 JS 原型，零构建直接预览）。适用于"设计这个界面"、"这个页面怎么布局"、"帮我画个页面设计"、"出个 UI 设计"、"页面原型"、"写个 HTML demo"、"做个 demo 页面"、"给这个页面改版"、"重设计一下" 等场景。定位在设计链路 interaction-design（交互逻辑）→ ui-designer（视觉层，本 skill）→ design-craft（技术设计）之间，只管视觉不管交互逻辑与架构。
---

# UI 设计师（UI Designer）

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

## 📖 概述

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

**功能**：
- 从交互设计文档（interaction-design 产出）或需求描述出发，设计界面视觉方案
- 产出界面布局方案文档：页面结构、布局栅格、组件清单与状态、配色、字体、间距/圆角/阴影 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 视觉设计             技术设计        代码骨架
```

- **输入**：交互设计文档（首选）或需求描述
- **输出**：界面布局方案文档 + 可运行 HTML demo
- **边界**：只管**视觉层**（布局、组件、配色、字体、样式规范）；交互逻辑交给 interaction-design，技术架构交给 design-craft
- **与 ui-to-ascii 区分**：ui-to-ascii 是"已有设计稿 → ASCII 存档"（转换/存储）；本 skill 是"需求/交互 → 视觉方案 + HTML demo"（从零设计）
- **与 demo-verify 区分**：demo-verify 针对设计中的风险点构建技术验证原型（"这方案可行吗"）；本 skill 的 HTML demo 呈现已定的视觉方案（"界面长这样"），目标不同

## 📐 核心原则

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

## 🔀 工作流总览

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

**每个阶段输出后等用户确认再进入下一阶段；用户未确认时默认保留"待确认"标注继续，不静默推翻已确认内容。**

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

### 0.1 识别输入类型

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

### 0.2 信息收集清单

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

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

### 0.3 输出格式

```text
🎯 输入与范围
━━━━━━━━━━━━━━━━

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

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

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

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

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

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

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

```bash
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. **导航关系**：页面间跳转关系（来自交互文档的流程）

### 输出格式

```text
🗂️ 页面清单
━━━━━━━━━━━━━━━━

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

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

## 📊 阶段 2：布局设计

对每个页面：

1. **选布局模式**：从布局模式库选型（见 [reference.md](reference.md#布局模式库)），如单列、双栏、侧边栏导航、卡片网格、master-detail 等
2. **定栅格**：12 列栅格下各区块的列占比
3. **画区块结构**：用简洁 ASCII 框线画出各区块（顶栏 / 主内容 / 侧栏 / 底栏 / 弹层）
4. **响应式策略**：桌面 / 平板 / 移动的布局变化（如侧边栏 → 抽屉）

### 输出格式

```text
📊 布局设计
━━━━━━━━━━━━━━━━

【登录页】
布局模式：单列居中卡片
```
┌────────────────────────┐
│        Logo            │
│  [ 账号输入框 ]        │
│  [ 密码输入框 ]        │
│  [ 登录按钮 ]          │
│  注册入口 · 忘记密码    │
└────────────────────────┘
```
响应式：桌面卡片宽 400px 居中；移动端卡片占满屏宽、上下留白 16px。

请确认布局。
```

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

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

### 输出格式

```text
🧩 组件状态
━━━━━━━━━━━━━━━━

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

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

请确认组件与状态。
```

## 🎨 阶段 4：视觉风格设计

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

若阶段 0.4 检测到风格工具库，按 [reference.md](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](reference.md#配色体系)）：

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

### 输出格式

```text
🎨 视觉风格
━━━━━━━━━━━━━━━━

【配色 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](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 编写

按 [reference.md](reference.md#html-demo-规范) 规范编写可运行 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](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：质量自检

复制此清单核对：

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

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

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

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

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

## 🚫 反模式

- ❌ 不产出方案直接写代码，或方案未确认就进入 demo
- ❌ 把设计写成像素级视觉稿（要 token 化、可落地给 design-craft 与前端）
- ❌ 脱离交互设计文档凭空发明页面流程
- ❌ 只画默认态，忽略悬停/禁用/加载/错误/空状态
- ❌ demo 引入框架、构建工具、CDN 依赖（违背零构建）
- ❌ demo 里的 CSS 变量与方案文档 token 不一致
- ❌ 用"好看一点"、"醒目一点"等模糊词代替具体规格
- ❌ 与 ui-to-ascii 混淆：本 skill 不负责把已有设计稿转 ASCII
- ❌ 工具库已安装却不做场景匹配，直接套用内置默认风格（浪费工具库）
- ❌ 工具库缺失时不安装、跳过阶段 0.4 直接设计（违反"必须安装"约束）

## 📚 更多资源

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