a27e3b8e43
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
160 lines
6.1 KiB
Markdown
160 lines
6.1 KiB
Markdown
# 设计指南
|
||
|
||
本文档定义页面或元素设计阶段的标准流程、产出规范与质量约束。
|
||
|
||
## 📋 概述
|
||
|
||
设计阶段的核心目标是在编码前完成以下工作：
|
||
- 明确页面功能、内容结构与用户任务
|
||
- 确定布局方案与视觉风格方向
|
||
- 复用现有主题、组件与设计规范
|
||
- 产出可落地的设计规格文档
|
||
|
||
## ✅ 触发条件
|
||
|
||
以下场景需进入设计流程：
|
||
- 新建页面或元素
|
||
- 显式的视觉或布局调整需求
|
||
- 涉及信息架构或交互结构变化
|
||
- 功能或内容范围发生重大调整
|
||
|
||
## 🔍 前置准备
|
||
|
||
### 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` 已产出且包含所有必需章节
|