# 设计指南

本文档定义页面或元素设计阶段的标准流程、产出规范与质量约束。

## 📋 概述

设计阶段的核心目标是在编码前完成以下工作：
- 明确页面功能、内容结构与用户任务
- 确定布局方案与视觉风格方向
- 复用现有主题、组件与设计规范
- 产出可落地的设计规格文档

## ✅ 触发条件

以下场景需进入设计流程：
- 新建页面或元素
- 显式的视觉或布局调整需求
- 涉及信息架构或交互结构变化
- 功能或内容范围发生重大调整

## 🔍 前置准备

### 1. 资料收集

按优先级依次阅读以下资料：

**用户指定的技能（若有）**
- 优先阅读并执行该 Skill 的流程（可能会产出**主题 tokens / 设计规范**等）
- 如果 Skill 的设计流程和本指导冲突时，以 Skill 为准

**用户提供的资料（最高优先级）**
- 用户提供的主题、设计规范、业务文档、数据表、参考设计稿等
- 用户指定的任何参考资料或约束条件

**项目原型资产（补充资源）**
- `AGENTS.md`：项目名称、简介、总文档、默认主题（如有）
- 关联页面或元素的实现代码

**优先级原则**：用户提供 > 项目资产 > 默认推荐（详见「默认资源分流」）

## 📝 内容与功能规划


### 1. 功能与内容规划

明确页面或元素的核心职责与内容组织：
- 用户目标、关键任务与功能模块优先级
- 交互触发点、反馈机制、数据流转与状态管理
- 信息层级、模块划分、内容清单与文案语气
- 数据字段与展示优先级、空状态/加载态/异常处理

### 2. 数据与内容来源

**优先级顺序**（用户未提供充分上下文时，**必须主动检索**以下项目资产）：
1. **用户提供** → 严格按提供的数据/文档组织，保持原有语气与术语
2. **项目数据表** → 使用 `src/database/` 中匹配的数据
3. **项目文档** → 引用 `src/docs/` 中已定义的业务逻辑与字段
4. **关联原型** → 在 `src/prototypes/` 中查找相关页面的 `spec.md`、`prd.md` 及实现代码，优先复用已有页面结构和交互约定

> **原则**：已有文档中的定义优先于推测。

## 🎨 视觉设计流程

### 1. 确定主题

**优先级顺序**：
1. **用户指定主题** → 严格使用用户提供的主题
2. **项目默认主题** → 使用 `AGENTS.md` 中定义的默认主题

**注意**：禁止使用非用户指定，或项目默认主题以外的主题，包括资产库中的主题。

**主题设计系统文件含义**：
- `DESIGN.md`：设计规范（不一定存在）
- `designToken.json` 或 `globals.css`：设计令牌定义（支持 Tailwind CSS V4 或标准 CSS 变量），通常仅使用一个，以主题内实际存在的文件为准。

### 2. 确定设计规范

**优先级顺序**：
1. **用户指定规范** → 严格遵循用户提供的设计规范文档
2. **主题内 `DESIGN.md`** → 使用主题自带的设计规范
3. **内置设计指导** → 根据业务场景选择：
   - **基础型界面**（管理后台 / ToB / 工具 / 设置 / 数据工作台）→ `/skills/third-party/interface-design/SKILL.md`
   - **风格化界面**（落地页 / ToC / 品牌展示 / 营销页 / 强视觉 App）→ `/skills/third-party/frontend-design/SKILL.md`
   - **混合场景** → 以核心任务区优先套用基础型界面规范，品牌展示区再补充风格化规范

### 3. 弥补缺失事项

按需补充主题或当前设计缺失的资源。

**仅在触发条件满足时查阅对应文档**：

| 资源类型 | 触发条件 | 参考文档或内容 |
|---------|---------|---------|
| **图表库** | 需要数据可视化 且 用户未指定图表库 且 项目中无现有图表方案 | `/skills/default-resource-recommendations/references/default-chart-libraries.md` |
| **图标库** | 需要图标 且 用户未指定图标库 且 主题中无自定义图标系统 | `/skills/default-resource-recommendations/references/default-icon-libraries.md` |
| **字体** | 需要自定义字体 且 用户未提供字体方案 且 主题中无字体定义 | `/skills/default-resource-recommendations/references/default-font-combinations.md` |
| **动画库** | 页面动画处数 > 5 且 用户未指定动画方案 且 主题中无自定义动画系统 | `/skills/default-resource-recommendations/references/default-animation-libraries.md` |
| **图片** | 需要图片/插图 且 用户未提供图片资源 且 Agent 无法生成 | 优先级：Unsplash → Pexels → Pixabay → Picsum |

**重要**：不要一次性加载所有默认推荐文档，严格按触发条件按需查阅。

### 4. 布局结构

确定页面框架与信息组织：
- 整体布局模式（单栏、双栏、网格、自由）
- 模块尺寸与比例约束
- 响应式断点与适配策略
- 信息密度与留白处理

## 📄 规格文档产出

### 1. 生成时机

- 设计方案确认后，立即产出 `spec.md`
- 使用模板：`src/docs/templates/spec-template.md`

### 2. 文档内容

规格文档必须包含以下部分：

**业务与功能**
- 页面/元素定位与核心目标
- 功能清单
- 交互要点

**内容规划**
- 信息架构与模块划分
- 数据来源与关键字段说明
- 示例内容（如适用，包含文案语气与术语规范）

**布局与结构**
- 整体布局（布局模式、关键尺寸、模块比例）
- 响应式适配（如适用）

**视觉规范**
- 设计规范来源（用户规范/主题设计系统/内置设计指导）
- 自定义设计要点（如适用）
- 组件状态定义（默认/悬停/聚焦/禁用/加载）

## 🛠️ 样式实现规范

### 1. 技术栈选择

- 默认：Tailwind CSS V4

### 2. 可访问性要求

- 色彩对比度符合 WCAG 2.1 AA 标准（特别是文本与背景的对比度）

## ✨ 质量检查点

设计阶段完成前，确认以下检查点：

- [ ] 已明确业务场景并匹配对应设计规范
- [ ] 已确定数据来源或兜底方案
- [ ] 功能清单与内容结构已规划
- [ ] 布局方案清晰且符合设计规范
- [ ] Design Tokens 引用正确
- [ ] `spec.md` 已产出且包含所有必需章节