# Taiyi UI Design

> TaiyiForge 第 4 阶段 — UI/UX 契约，产出 UI-DESIGN.md。四端通用。

- Skill: `dong90/taiyi-ui-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dong90/taiyi-ui-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dong90/taiyi-ui-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dong90 (https://skillmd.com/u/dong90)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dong90/taiyi-ui-design

---


# taiyi-ui-design — UI/UX 设计契约

> 进入本阶段前请优先读 `.taiyi/changes/<slug>/PHASE-CONTEXT.md`（~500 tokens），不要全量加载上游工件。如果 PHASE-CONTEXT 包含 upstream 文档（如 REQUIREMENT.md）的参考节，优先阅读参考节而非完整上游文件。

## 框架集成

本阶段使用以下框架：

| 框架 | 用途 | 何时加载 |
|------|------|---------|
| **Harness** | 阶段门禁与推进（`status` → `continue`；legacy：`npx taiyi complete`） | 全程 |
| **OMO** | 作为前端设计工作流入口 | 全程 |

**Superpowers / GStack / OpenSpec / Spec-Kit** 在本阶段不涉及。

## 前置门禁（Pre-flight）

### 0.1 入口判定
- DESIGN.md 已过关（`engineTruth` 确认）
- UI-DESIGN.md 不应包含后续阶段的实现代码（TASK / DEV / TEST）

### 0.2 Profile 判定

| Profile | UI-DESIGN.md 要求 |
|---------|------------------|
| `full` | 完整：布局原型 + 交互/动效 + UI 组件拆解 + 无障碍 + 状态+异常 + 与 DESIGN.md 差异 |
| `ui` | 同 full |
| `api` | 跳过（无 UI 层） |
| `lite` | 可选。如果有 UI，简化到布局原型 + 组件拆解即可 |
| `spike/micro` | 跳过 |
| `nano` | 跳过 |

### 0.3 前置检查清单
- [ ] design 阶段已过关
- [ ] 项目有 UI 层（如不是跳过）

---

## 步骤

### 工件契约

| 层 | 路径 | 职责 |
|----|------|------|
| **语义真源** | `ui-design.json` | Zod（`src/schemas/ui-design.ts`） |
| **生成视图** | `UI-DESIGN.md` | hbs（`src/templates/ui-design.hbs`） |
| **流程** | 本 Skill | Must/Should/Could、组件拆解、无障碍 |

**工作流**：编辑 json → `scripts/taiyi-forge.sh render <slug> ui-design` → `status` → `continue`。

详见 [`docs/taiyi/artifact-contract.md`](../../docs/taiyi/artifact-contract.md)。

### json 字段（Zod 摘要）

| 字段 | 要求 |
|------|------|
| `title` | 设计标题 |
| `scope` | UI 范围说明 |
| `styling_contract` | 可选；CSS 方案、禁止内联、主题变量规则 |
| `states` | 可选；loading / empty / error 等状态描述 |
| `accessibility` | 可选；键盘 / 焦点 / ARIA / 对比度清单 |
| `links` | 可选；Figma / 设计稿链接 |
| `is_cli_only` | 可选；纯 CLI 无 UI 时标注 |

### 写作指引（填入 json，render 生成 UI-DESIGN.md）

### 1. 确认已有 UI 基础设施

先 grep 项目中的 UI 基础设施（Tailwind / Shadcn / 组件库 / 设计 Token）并记录路径，后续组件拆解直接引用。

```
# grep -r "tailwind" package.json 2>/dev/null && echo "Tailwind found"
# grep -r "shadcn" package.json 2>/dev/null && echo "Shadcn found"
# grep -rn "taiyi-design-tokens" src/ 2>/dev/null || grep -rn "--color-" src/components/ 2>/dev/null | head -5
```

### 2. 产出 UI-DESIGN.md

每段用 Must / Should / Could 标记约束强度。结构如下：

```
# UI-DESIGN: <标题>

## 1. 布局原型
MUST 布局结构描述（文字或用 ASCII / Mermaid 图），不贴最终代码。

### 1.1 接口总览
MUST [以接口为单位描述布局]

### 1.2 页面层级（路由树）
MUST [路由或面板切换逻辑]
```

### 3. 交互与动效

```
## 2. 交互与动效
### 2.1 状态过渡
MUST [加载/空/错误态组件]
### 2.2 微交互
SHOULD [hover / focus / enter / exit 动画描述]
### 2.3 反馈机制
MUST [Toast / 确认弹窗 / 进度指示]
```

### 4. UI 组件拆解

```
## 3. UI 组件拆解
### 3.1 新组件清单
-
### 3.2 受影响已有组件
-
```

### 5. 无障碍

```
## 4. 无障碍
MUST [键盘导航 / 焦点管理 / Aria labels / 色差对比度]
```

### 6. 状态与异常

```
## 5. 状态与异常
### 5.1 正常状态
- [数据加载完成展示]
### 5.2 中间态
- Loading / 骨架屏
- 乐观更新中
### 5.3 空态
- 无数据时的默认 UI
### 5.4 异常
- 网络断开 / API 403 / 400 校验错误
```

### 7. 与 DESIGN.md 的差异（若有）

```
## 6. 与 DESIGN.md 的差异
| 维度 | DESIGN.md | UI-DESIGN.md | 理由 |
|------|-----------|-------------|------|
```
仅在 UI-DESIGN.md 偏离了 DESIGN.md 架构决策时才需要此节。如完全遵循则说明"严格遵循 DESIGN.md"。

---

## 过关（Harness）

1. 逐项检查 `## 质量自检`；有未通过项则不要过关。
2. 预检：`scripts/taiyi-forge.sh status <slug> --json --compact` — 解析 `engineTruth`（`qualityReady` / `blockers`）。
3. 用户确认后过关：`scripts/taiyi-forge.sh continue <slug>`。
4. 过关后再 `status --json --compact`，读 `engineTruth`；若 `currentPhase` 已变为 `task`，切换到 taiyi-task Skill 并通知用户。

Legacy：`npx taiyi complete <slug> ui-design` 仍可用；聊天优先 `/taiyi:continue`。

## 产出

- `.taiyi/changes/<slug>/UI-DESIGN.md`
- `.taiyi/changes/<slug>/ui-design.json`

## 与下游衔接

| 下游 | 需要 |
|------|------|
| `taiyi-task` | 组件拆解 → 开发任务粒度；交互/动效 → 实现复杂度估算 |
| `taiyi-dev` | 布局原型 → 样式实现参考；组件清单 → 需要创建的文件；设计 Token → 颜色/间距变量的统一使用 |

## 异常处理

| 场景 | 处理 |
|------|------|
| 项目无 UI 层 | 跳过本阶段（api profile），说明理由 |
| DESIGN.md 未过关（phase guard） | 展示 DESIGN 未完成，退回完成 DESIGN |
| UI-DESIGN.md 与已有设计 Token 冲突 | 引用已有的设计 Token，不要在 UI-DESIGN 中重新定义 |
| `continue` 被拒 | 检查 6 sections 是否完整、Must/Should/Could 是否标注。修复后 status 再 continue。**最多 1 次自动重试** |
| 误过关本阶段或后续 | `scripts/taiyi-forge.sh undo <slug> ui-design` |

<fatal_constraints>
- NEVER write actual CSS, React components, or implementation code in ui-design.json / rendered UI-DESIGN.md — this is a design contract, not implementation.
- NEVER hardcode hex colors — reference design tokens from Tailwind config or existing DESIGN.md.
- NEVER skip Must/Should/Could strength markers on constraints.
- NEVER add UI concepts not traceable to REQUIREMENT.md or DESIGN.md.
- NEVER skip the 空态/异常/Loading sections — they are part of the design, not optional polish.
</fatal_constraints>

## 质量自检

- [ ] 前置门禁已通过（0.1–0.3）
- [ ] 布局原型已描述（文字/图/ASCII，不是代码）
- [ ] Must/Should/Could 标记已用在每段
- [ ] 组件拆解已列出（新组件 + 受影响已有组件）
- [ ] 无障碍需求已记录
- [ ] 状态与异常已记录（Loading / Empty / Error）
- [ ] 与 DESIGN.md 的差异已记录（或无差异声明）
- [ ] 没有写入实现代码
- [ ] 所有参考的设计 Token 来自项目已有配置

## 引擎门控（自动，无需手动确认）

- **states >= 3**: ui-design.json states 至少 loading/empty/error → 阻止。CLI-only 跳过
- **accessibility >= 1**: accessibility 至少 1 条 WCAG 合规项 → 阻止。CLI-only 跳过