cavekit-design-system

设计系统：面向 AI Agent 的 DESIGN.md

核心原则：DESIGN.md 描述外观，而非构建方式

DESIGN.md 是 kits 的视觉对应文档。它定义项目的视觉语言——颜色、字体排印、间距、组件、响应式行为——采用 AI Agent 可读取并一致应用的格式。它是所有 Hunt 阶段都会参考的并行约束层。

文档	定义内容	适用对象
CLAUDE.md	如何构建项目	编码 Agent
Kits	必须满足的条件（行为）	所有 Agent
DESIGN.md	外观（视觉）	构建 UI 的 Agent
Plans	如何构建（任务）	构建 Agent

为什么需要专门的设计系统文档？

没有 DESIGN.md，视觉决策就会分散在 kits、plans 和代码中：

• 各组件的颜色硬编码方式不一致
• 不同 Agent 和会话所选的字体排印各不相同
• 整个 UI 的间距变得不一致
• 新组件重复设计已有模式

DESIGN.md 将这些决策集中管理。每个 Agent 在编写 UI 代码前都会先阅读它。

---

9 部分 Stitch 格式

DESIGN.md 遵循 Google Stitch 格式——由 9 个部分共同定义完整的视觉语言。每个 DESIGN.md 都必须包含全部 9 个部分。

第 1 部分：视觉主题与氛围

设计理念、情绪和整体美感。使用生动、具体的语言，而不是“简洁现代”之类的笼统说法。

## 1. Visual Theme & Atmosphere

This is a warm editorial experience built on natural materials. Think: a well-curated
bookshop with soft overhead lighting and carefully chosen display shelves. The density
is low — generous whitespace signals confidence and clarity. Every element earns its
place; nothing decorative exists without functional purpose.

**Key attributes:** Warm, unhurried, editorial, confident
**Density:** Low — generous whitespace, single-column focus
**Personality:** Thoughtful librarian, not flashy storefront

好的效果： 新设计师阅读本部分后，即使没看过其他部分，也能画出粗略的布局草图。

反面示例：“简洁、现代、专业”——这没有描述任何具体内容。

第 2 部分：调色板与用途

每种颜色都需要包含三项内容：语义化名称、十六进制值和功能用途。

## 2. Color Palette & Roles

### Primary
| Name | Hex | Role |
|------|-----|------|
| Terracotta Brand | #c96442 | Primary CTA, active states, brand anchors |
| Terracotta Hover | #b85838 | Hover/pressed state for primary actions |

### Neutral
| Name | Hex | Role |
|------|-----|------|
| Near Black | #141413 | Primary text, headings |
| Olive Gray | #5e5d59 | Secondary text, captions |
| Parchment | #f5f4ed | Page background, default canvas |
| Ivory White | #ffffff | Card surfaces, overlays |

### Semantic
| Name | Hex | Role |
|------|-----|------|
| Success Green | #2d7d46 | Confirmation, success states |
| Warning Amber | #c27217 | Warnings, attention needed |
| Error Red | #c24132 | Errors, destructive actions |
| Info Blue | #3b6fb5 | Informational states, links |

### Dark Mode (if applicable)
| Light Name | Dark Equivalent | Hex |
|------------|----------------|-----|
| Parchment | Deep Charcoal | #1a1a1a |
| Near Black | Off White | #e8e8e8 |

规则：

• 每个十六进制值都必须根据实际设计或线上网站进行核实
• 每种颜色都必须有明确的功能用途——不能有无明确用途的颜色
• 按语义（用途）而非色相命名颜色（使用“主要 CTA”，而不是“橙色”）
• 如果存在深色模式，必须为每种浅色指定对应的深色

第 3 部分：字体排印规则

完整的字体层级，并提供具体数值——不能写“大约 16px”或“中等字重”。

## 3. Typography Rules

### Font Stack
- **Display/Heading:** "Anthropic Serif", Georgia, "Times New Roman", serif
- **Body:** "Anthropic Sans", -apple-system, BlinkMacSystemFont, sans-serif
- **Code:** "Anthropic Mono", "SF Mono", "Fira Code", monospace

### Type Scale
| Level | Size | Weight | Line Height | Letter Spacing | Font |
|-------|------|--------|-------------|----------------|------|
| H1 | 48px / 3rem | 500 | 1.10 | -0.02em | Serif |
| H2 | 36px / 2.25rem | 500 | 1.15 | -0.01em | Serif |
| H3 | 24px / 1.5rem | 500 | 1.25 | 0 | Serif |
| H4 | 20px / 1.25rem | 600 | 1.30 | 0 | Sans |
| Body | 16px / 1rem | 400 | 1.60 | 0 | Sans |
| Small | 14px / 0.875rem | 400 | 1.50 | 0.01em | Sans |
| Caption | 12px / 0.75rem | 500 | 1.40 | 0.02em | Sans |

### Principles
- Headings use serif for warmth and authority
- Body text uses sans-serif for readability at small sizes
- Maximum line length: 65ch for body text
- Minimum font size: 14px (never go below)

规则：

• 字号阶梯中的每个级别都必须包含全部 5 个值（字号、字重、行高、字间距、字体）
• 为保证无障碍，除 px 外还要使用 rem
• 包含字体栈回退选项

第 4 部分：组件样式

为常见组件指定具体样式，包括交互状态。

## 4. Component Stylings

### Buttons
**Primary:**
- Background: Terracotta Brand (#c96442)
- Text: Ivory White (#ffffff), 16px Sans, weight 500
- Padding: 12px 24px
- Border radius: 8px
- Hover: Terracotta Hover (#b85838), translateY(-1px), shadow-sm
- Active: translateY(0), shadow-none
- Disabled: opacity 0.5, cursor not-allowed
- Transition: all 150ms ease-out

**Secondary:**
- Background: transparent
- Border: 1px solid Olive Gray (#5e5d59)
- Text: Near Black (#141413)
- Hover: background Parchment (#f5f4ed)

### Cards
- Background: Ivory White (#ffffff)
- Border: 1px solid rgba(0,0,0,0.06)
- Border radius: 12px
- Padding: 24px
- Shadow: 0 1px 3px rgba(0,0,0,0.04)
- Hover: shadow 0 4px 12px rgba(0,0,0,0.08), translateY(-2px)

### Inputs
- Border: 1px solid #d0d0d0
- Border radius: 8px
- Padding: 10px 14px
- Focus: border Terracotta Brand, ring 2px rgba(201,100,66,0.2)
- Error: border Error Red, ring 2px rgba(194,65,50,0.2)

### Navigation
...

规则：

• 包含悬停、焦点、激活和禁用状态
• 指定过渡时长和缓动方式
• 包含触控目标的最小尺寸（44x44px）

第 5 部分：布局原则

间距系统、网格、容器和留白理念。

## 5. Layout Principles

### Spacing Scale (base: 4px)
| Token | Value | Usage |
|-------|-------|-------|
| space-1 | 4px | Tight gaps, icon margins |
| space-2 | 8px | Related element spacing |
| space-3 | 12px | Component internal padding |
| space-4 | 16px | Standard gap between elements |
| space-6 | 24px | Section padding, card padding |
| space-8 | 32px | Between major sections |
| space-12 | 48px | Page-level vertical rhythm |
| space-16 | 64px | Hero/banner spacing |

### Grid
- Max content width: 1200px
- Column count: 12
- Gutter: 24px (space-6)
- Margin: 16px mobile, 24px tablet, auto desktop

### Border Radius Scale
| Token | Value | Usage |
|-------|-------|-------|
| radius-sm | 4px | Badges, tags |
| radius-md | 8px | Buttons, inputs |
| radius-lg | 12px | Cards, panels |
| radius-xl | 16px | Modals, dialogs |
| radius-full | 9999px | Avatars, pills |

第 6 部分：深度与层级

阴影系统和视觉分层。

## 6. Depth & Elevation

### Shadow Scale
| Level | Value | Usage |
|-------|-------|-------|
| shadow-none | none | Flat elements |
| shadow-sm | 0 1px 2px rgba(0,0,0,0.04) | Subtle lift (cards at rest) |
| shadow-md | 0 4px 12px rgba(0,0,0,0.08) | Hover states, active cards |
| shadow-lg | 0 8px 24px rgba(0,0,0,0.12) | Dropdowns, popovers |
| shadow-xl | 0 16px 48px rgba(0,0,0,0.16) | Modals, dialogs |

### Surface Hierarchy
1. **Base** — page background (Parchment)
2. **Raised** — cards, panels (Ivory White + shadow-sm)
3. **Floating** — dropdowns, tooltips (Ivory White + shadow-lg)
4. **Overlay** — modals, dialogs (Ivory White + shadow-xl + scrim)

第 7 部分：该做与不该做

使用代码提供具体示例，而不只是文字规则。

## 7. Do's and Don'ts

### DO: Use semantic color names
```css
/* Good */
.button-primary { background: var(--color-terracotta-brand); }

不该做：硬编码颜色值

/* Bad */
.button-primary { background: #c96442; }

该做：遵循间距阶梯

/* Good — uses scale */
.card { padding: var(--space-6); margin-bottom: var(--space-8); }

不该做：使用任意间距

/* Bad — 19px is not on the scale */
.card { padding: 19px; margin-bottom: 37px; }

该做：包含所有交互状态

不该做：省略交互元素的悬停／焦点状态

该做：所有文本都使用字号阶梯

不该做：引入字号阶梯中没有的新字号

### Section 8: Responsive Behavior

Breakpoints, mobile patterns, and adaptation rules.

```markdown
## 8. Responsive Behavior

### Breakpoints
| Name | Width | Target |
|------|-------|--------|
| mobile | < 640px | Phones |
| tablet | 640–1024px | Tablets, small laptops |
| desktop | > 1024px | Laptops, monitors |

### Touch Targets
- Minimum interactive element size: 44x44px
- Minimum spacing between targets: 8px

### Mobile Adaptations
- Navigation collapses to hamburger menu below 640px
- Cards stack single-column below 640px
- Font sizes: H1 reduces to 32px on mobile, H2 to 28px
- Side padding: 16px on mobile, 24px tablet, auto-center desktop

### Behavior Patterns
- Horizontal scrolling: never (use stacking or truncation)
- Images: responsive with srcset, max-width: 100%
- Tables: horizontal scroll wrapper below tablet breakpoint

第 9 部分：Agent 提示词指南

说明 AI Agent 在生成 UI 时应如何使用本文档。

## 9. Agent Prompt Guide

### Quick Reference
- Primary CTA color: Terracotta Brand (#c96442)
- Background: Parchment (#f5f4ed)
- Heading font: Serif, weight 500
- Body font: Sans, weight 400
- Standard spacing: 24px (space-6)
- Card radius: 12px (radius-lg)

### How to Use This Document
1. Before writing any UI code, read the full DESIGN.md
2. Reference specific section names when implementing: "Following Section 4: Buttons"
3. Use design token names in CSS (var(--color-terracotta-brand)), not raw hex values
4. Check Section 7 (Do's and Don'ts) before submitting
5. If a component is not covered, create it following existing patterns and flag for DESIGN.md update

### Example Component Prompt
"Create a hero section on Parchment (#f5f4ed) with a headline at H1 scale
(48px Serif weight 500, line-height 1.10). Use Near Black (#141413) text.
Add a subtitle in Olive Gray (#5e5d59) at Body scale (16px Sans, line-height 1.60).
Place a Terracotta Brand (#c96442) primary button with Ivory text, radius-md (8px)."

### Iteration Guide
- Change one component at a time
- Reference specific color names and token values
- Describe the component's state (default, hover, active, disabled)
- Specify responsive behavior for the component

---

设计令牌约定

令牌是 DESIGN.md 与代码之间的桥梁。统一的命名方式可确保 Agent 将设计规范转换为 CSS/Tailwind 变量。

命名模式

--{category}-{name}[-{modifier}]

类别	示例
color-	--color-terracotta-brand、--color-near-black、--color-success-green
space-	--space-1、--space-4、--space-8
text-	--text-h1、--text-body、--text-caption
radius-	--radius-sm、--radius-md、--radius-lg
shadow-	--shadow-sm、--shadow-md、--shadow-lg
font-	--font-serif、--font-sans、--font-mono

映射到 CSS 自定义属性

DESIGN.md 令牌直接映射到 CSS 自定义属性：

:root {
  --color-terracotta-brand: #c96442;
  --space-6: 24px;
  --radius-lg: 12px;
  --shadow-sm: 0 1px 2px rgba(0,0,0,0.04);
}

映射到 Tailwind

使用 Tailwind 时，DESIGN.md 令牌会映射到 tailwind.config.js 扩展项。构建 Agent 应配置一次，并在后续过程中引用。

---

与套件集成

当 DESIGN.md 存在且套件包含 UI 要求时，验收标准应按章节和名称引用设计令牌。这样可以形成可追踪的链路：

DESIGN.md → Cavekit acceptance criterion → Plan task → Implementation

如何引用

Cavekit 验收标准	设计引用
“CTA 按钮使用品牌主色样式”	DESIGN.md 第 4 节：按钮，主样式
“标题遵循字体层级”	DESIGN.md 第 3 节：字体比例
“卡片具有细微的默认阴影”	DESIGN.md 第 6 节：shadow-sm
“布局使用标准网格”	DESIGN.md 第 5 节：网格
“颜色适配深色模式”	DESIGN.md 第 2 节：深色模式映射

不要将 DESIGN.md 内容复制到套件中。 只按章节／令牌名称引用。如果 DESIGN.md 中的颜色发生变化，套件无需更新。

没有设计引用时

如果 cavekit 需要 DESIGN.md 中未定义的视觉模式，验收标准应注明：

- [ ] Component uses a card-like container [DESIGN.md: pattern not yet defined — flag for design update]

这会提示 inspect 阶段检查 DESIGN.md 是否需要添加新模式。

---

与计划集成（架构师阶段）

当架构师为 UI 工作生成任务描述时，每项任务都应包含：

**Design Reference:** DESIGN.md Section {N} — {section name}

这会告知任务构建器在实现前需要阅读 DESIGN.md 的哪些章节。

---

与构建阶段集成

任务构建 Agent 按以下流程处理 UI 工作：

1. 实现前： 阅读 DESIGN.md（或任务中引用的特定章节）
2. 实现期间： 使用设计令牌，而非硬编码值
3. 提交说明中： 注明遵循了 DESIGN.md 的哪些章节
4. 需要新模式时： 遵循现有 DESIGN.md 规范实现，并标记以便更新设计

---

修订模式

在 Hunt 循环之外手动进行视觉修复时，/ck:revise 会追溯这些修复与 DESIGN.md 的对应关系：

视觉修复分类

修复类型	DESIGN.md 操作
应全局应用的颜色更改	在 DESIGN.md 第 2 节中更新正确的值
DESIGN.md 中未定义的新组件模式	添加到 DESIGN.md 第 4 节
暴露比例错误的间距调整	更新 DESIGN.md 第 5 节中的比例
字体排版修复	更新 DESIGN.md 第 3 节中的字体比例
响应式行为更改	更新 DESIGN.md 第 8 节

修订流程

1. 在差异中识别视觉更改
2. 检查 DESIGN.md 是否涵盖此模式
3. 如果未涵盖：将该模式添加到相应章节
4. 如果已涵盖但有误：更新令牌／值
5. 将更改记录到 context/designs/design-changelog.md

---

导入集合

awesome-design-md 仓库包含 54+ 个从真实产品中提取的精选设计系统，可作为起点。

导入工作流

1. 选择模板： vercel、claude、stripe、github、linear 等
2. 从集合中获取原始 DESIGN.md
3. 向用户展示，作为起点，而非成品
4. 逐一检查各章节，进行自定义（品牌颜色、字体排版、特定组件需求）
5. 将自定义版本写入项目根目录

导入后

导入的 DESIGN.md 将成为项目自身的文档。后续更新直接在其中进行——导入内容是起点，而非依赖项。

---

质量标准

完整性检查清单

• 包含全部 9 个章节，且内容非空
• 每种颜色均包含：语义名称 + 十六进制值 + 功能角色
• 字体排版表完整（每个级别包含全部 5 个值）
• 组件样式包含悬停、焦点、激活、禁用状态
• 间距刻度已定义，并使用一致的基准单位
• 阴影/层级刻度已定义
• 断点包含具体像素值
• Agent 提示词指南包含快速参考和示例提示词

具体性要求

DESIGN.md 中的每个值都必须具体且明确：

过于模糊	足够具体
“暖蓝色”	#3b6fb5（信息蓝）
“中等间距”	24px（space-6）
“略微圆角”	8px（radius-md）
“柔和阴影”	0 1px 2px rgba(0,0,0,0.04)（shadow-sm）
“大号标题”	48px / 3rem, weight 500, line-height 1.10

一致性规则

• 第 4 节（组件）中使用的令牌必须存在于第 2、3、5、6 节
• 深色模式映射必须涵盖组件中使用的每种颜色
• 响应式变更必须引用已定义的断点
• 所有间距值都必须是基准单位的倍数

---

反模式

1. 泛泛的氛围描述——“简洁、现代、专业”可以描述所有 SaaS 应用，却无法具体描述任何一个
2. 缺少交互状态——没有悬停/焦点状态的按钮是不完整的
3. 孤立的颜色——调色板中定义了颜色，却从未在组件中使用
4. 随意的间距——不遵循间距刻度的值
5. 缺少深色模式——如果应用支持深色模式，每种浅色都需要对应的映射
6. 组件中只引用十六进制值——使用语义名称，而非原始值
7. 没有 Agent 提示词指南——第 9 节是让 DESIGN.md 能为 AI Agent 提供可执行指引的关键
8. 在工具包中重复 DESIGN.md——只按章节/令牌名称引用