cavekit-design-system

デザインシステム：AI エージェント向け DESIGN.md

基本原則：DESIGN.md が記述するのは「見た目」であり、「構築方法」ではありません

DESIGN.md はキットの視覚的な相当物です。色、タイポグラフィ、余白、コンポーネント、レスポンシブな動作など、プロジェクトの視覚言語を定義し、AI エージェントが読み取って一貫して適用できる形式で記述します。これは、Hunt のすべてのフェーズで参照する並行した制約レイヤーです。

ドキュメント	定義する内容	対象
CLAUDE.md	プロジェクトの構築方法	コーディングエージェント
キット	満たすべき条件（動作）	すべてのエージェント
DESIGN.md	見た目（視覚面）	UI 構築エージェント
計画	構築方法（タスク）	ビルダーエージェント

専用のデザインシステムドキュメントが必要な理由

DESIGN.md がないと、視覚に関する決定がキット、計画、コードに分散してしまいます。

• コンポーネントごとに異なる色がハードコードされる
• エージェントやセッションによってタイポグラフィの選択が異なる
• UI 全体で余白に一貫性がなくなる
• 新しいコンポーネントで、すでにあるパターンが再び作られる

DESIGN.md は、こうした決定を一元化します。すべてのエージェントは、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：カラーパレットと役割

すべての色には、意味を示す名前、16 進数値、機能上の役割の 3 つが必要です。

## 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 |

ルール：

• すべての 16 進数値は、実際のデザインまたは稼働中のサイトと照合して確認する
• すべての色に明確な機能上の役割を持たせる。孤立した色を作らない
• 色相ではなく役割に基づいて意味のある名前を付ける（「オレンジ」ではなく「プライマリ 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：エージェント向けプロンプトガイド

UI を生成する際に、AI エージェントがこのドキュメントをどう使うべきかを説明します。

## 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 とコードをつなぐ橋渡しです。一貫した命名により、エージェントはデザイン仕様を 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 の拡張にマッピングされます。ビルダーエージェントはこれを一度設定し、以降は参照して使用します。

---

キットとの統合

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 に新しいパターンが必要かどうかを確認できます。

---

プランとの統合（Architect フェーズ）

architect が UI 作業のタスク説明を生成するとき、各タスクには次の内容を含める必要があります。

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

これにより、task-builder は実装前に読むべき DESIGN.md のセクションを把握できます。

---

Build フェーズとの統合

task-builder エージェントは、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 つのセクションがすべて存在し、空ではない
• すべての色に、意味的な名前、16 進数値、機能上の役割がある
• 完全なタイポグラフィの表（各レベルに 5 つの値すべてを記載）
• コンポーネントのスタイルに、ホバー、フォーカス、アクティブ、無効の各状態が含まれている
• 一貫した基本単位でスペーシングスケールが定義されている
• シャドウ／エレベーションのスケールが定義されている
• ブレークポイントに具体的なピクセル値が設定されている
• エージェントプロンプトガイドにクイックリファレンスとプロンプト例がある

具体性の要件

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. コンポーネント内での 16 進数値のみの参照 — 生の値ではなく、意味的な名前を使用します
7. エージェントプロンプトガイドがない — セクション 9 が、DESIGN.md を AI エージェントにとって実用的なものにします
8. DESIGN.md の内容をキットに複製する — セクション名／トークン名だけで参照します