设计决策记录
本文档采用 ADR (Architecture Decision Record) 格式记录关键设计决策。
ADR-001: 选择 VitePress 作为文档框架
状态
已采纳 (2024-01)
背景
项目需要一个静态站点生成器来展示 Cursor Rules 规则集合。主要需求：
- 双语支持（中/英文）
- 快速的开发体验
- 良好的 SEO
- 可扩展的主题系统
- Markdown 增强（代码高亮、图表）
决策
选择 VitePress 作为文档框架。
理由
| 框架 | 优点 | 缺点 |
|---|---|---|
| VitePress | Vue 生态、Vite 极速、简洁配置 | 社区小于 Docusaurus |
| Docusaurus | React 生态、功能丰富 | 构建较慢、配置复杂 |
| Nextra | Next.js 集成、RSC 支持 | 较新、稳定性待验证 |
| Docsify | 无构建、简单 | SEO 差、功能有限 |
关键因素：
- Vue 3 组合式 API 适合组件开发
- Vite HMR 提供极佳开发体验
- 内置 i18n 支持满足双语需求
- 轻量级，构建快速
后果
- 正向：开发效率高，构建速度快，Vue 组件开发灵活
- 负向：部分 React 生态工具不可用，社区资源相对较少
ADR-002: 采用 OKLCH 色彩空间
状态
已采纳 (2024-02)
背景
设计系统需要一套科学的色彩管理方案，支持：
- 深浅色模式完美适配
- 可感知均匀的颜色渐变
- 易于维护的色彩变量
决策
采用 OKLCH 色彩空间定义品牌色。
理由
| 色彩空间 | 感知均匀性 | 浏览器支持 | 可访问性 |
|---|---|---|---|
| OKLCH | ⭐⭐⭐ | 现代浏览器 | 优秀 |
| HSL | ⭐ | 全部 | 一般 |
| RGB | ⭐ | 全部 | 差 |
| P3 | ⭐⭐ | 部分 | 优秀 |
OKLCH 优势：
- 感知均匀 - 相同亮度变化视觉效果一致
- 色域宽广 - 支持比 sRGB 更广的色彩范围
- 易于创建色阶 - 固定 L/C，调整 H 即可
示例
css
/* 品牌色阶（11 级） */
--vp-c-brand-50: oklch(0.98 0.02 269); /* 最亮 */
--vp-c-brand-500: oklch(0.62 0.18 269); /* 基准 */
--vp-c-brand-950: oklch(0.20 0.05 269); /* 最暗 */后果
- 正向：色彩系统科学、一致，深浅色适配简单
- 负向：旧版浏览器需要 fallback（已通过 CSS 变量解决）
ADR-003: 四层架构设计
状态
已采纳 (2024-02)
背景
项目需要清晰的内容组织结构，让不同角色的读者快速找到所需信息。
决策
采用四层系统架构：
资产层 → 同步层 → 叙事层 → 发布层理由
参考 The Architecture of Open Source Applications 的理念：
- 资产层：规则文件是唯一权威源
- 同步层：构建前自动提取站点事实
- 叙事层：白皮书式内容组织
- 发布层：主题组件与 GitHub Pages
收益：
- 数据源唯一，避免不一致
- 内容与展示分离
- 可追溯的构建流程
后果
- 正向：数据一致性有保障，内容结构清晰
- 负向：构建流程增加同步步骤
ADR-004: CSS Cascade Layers 架构
状态
已采纳 (2024-02)
背景
传统 CSS 存在样式优先级问题，导致：
- 大量
!important使用 - 样式覆盖困难
- 维护成本高
决策
采用 CSS Cascade Layers 组织样式：
css
@layer reset, tokens, fonts, base, layout, components, utilities, overrides;理由
| 方案 | 优先级控制 | 维护性 | 兼容性 |
|---|---|---|---|
| Layers | ⭐⭐⭐ | ⭐⭐⭐ | 现代浏览器 |
| ITCSS | ⭐⭐ | ⭐⭐ | 全部 |
| BEM | ⭐ | ⭐ | 全部 |
| CSS-in-JS | ⭐⭐ | ⭐ | 需要 JS |
优势：
- 明确的优先级顺序
- 无需
!important - 组件样式解耦
后果
- 正向：样式可预测，维护简单
- 负向：需要现代浏览器（> 2022）
ADR-005: 引入 UnoCSS
状态
已采纳 (2025-05)
背景
项目需要：
- 快速开发 UI 组件
- 一致的设计令牌使用
- 减少重复 CSS 代码
决策
引入 UnoCSS 原子化 CSS 框架。
理由
| 框架 | 性能 | 定制性 | 学习成本 |
|---|---|---|---|
| UnoCSS | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| Tailwind | ⭐⭐ | ⭐⭐ | ⭐⭐ |
| WindiCSS | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
| 纯 CSS | ⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
选择理由：
- 即时按需生成 - 无构建开销
- 高度可定制 - 支持自定义 shortcuts
- 兼容 Tailwind 语法 - 学习成本低
后果
- 正向：开发效率提升，CSS 体积减少
- 负向：团队需要学习原子化 CSS 约定