dong90 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。
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）
- 逐项检查
## 质量自检；有未通过项则不要过关。 - 预检：
scripts/taiyi-forge.sh status <slug> --json --compact— 解析engineTruth（qualityReady/blockers）。 - 用户确认后过关：
scripts/taiyi-forge.sh continue <slug>。 - 过关后再
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 |
质量自检
- 前置门禁已通过（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 跳过