Files

王冕 a27e3b8e43 feat: sync full workspace including web modules, docs, and configurations to Gitea

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>

2026-06-09 18:12:25 +08:00

6.1 KiB

Raw Blame History

设计指南

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

📋 概述

设计阶段的核心目标是在编码前完成以下工作：

明确页面功能、内容结构与用户任务
确定布局方案与视觉风格方向
复用现有主题、组件与设计规范
产出可落地的设计规格文档

✅ 触发条件

以下场景需进入设计流程：

新建页面或元素
显式的视觉或布局调整需求
涉及信息架构或交互结构变化
功能或内容范围发生重大调整

🔍 前置准备

1. 资料收集

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

用户指定的技能（若有）

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

用户提供的资料（最高优先级）

用户提供的主题、设计规范、业务文档、数据表、参考设计稿等
用户指定的任何参考资料或约束条件

项目原型资产（补充资源）

AGENTS.md：项目名称、简介、总文档、默认主题（如有）
关联页面或元素的实现代码

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

📝 内容与功能规划

1. 功能与内容规划

明确页面或元素的核心职责与内容组织：

用户目标、关键任务与功能模块优先级
交互触发点、反馈机制、数据流转与状态管理
信息层级、模块划分、内容清单与文案语气
数据字段与展示优先级、空状态/加载态/异常处理

2. 数据与内容来源

优先级顺序（用户未提供充分上下文时，必须主动检索以下项目资产）：

用户提供 → 严格按提供的数据/文档组织，保持原有语气与术语
项目数据表 → 使用 src/database/ 中匹配的数据
项目文档 → 引用 src/docs/ 中已定义的业务逻辑与字段
关联原型 → 在 src/prototypes/ 中查找相关页面的 spec.md、prd.md 及实现代码，优先复用已有页面结构和交互约定

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

🎨 视觉设计流程

1. 确定主题

优先级顺序：

用户指定主题 → 严格使用用户提供的主题
项目默认主题 → 使用 AGENTS.md 中定义的默认主题

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

主题设计系统文件含义：

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

2. 确定设计规范

优先级顺序：

用户指定规范 → 严格遵循用户提供的设计规范文档
主题内 DESIGN.md → 使用主题自带的设计规范
内置设计指导 → 根据业务场景选择：
- 基础型界面（管理后台 / 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 已产出且包含所有必需章节

6.1 KiB Raw Blame History Unescape Escape