DESIGN.md フォーマット仕様

DESIGN.md は 9つのセクション で構成されるデザインシステム文書です。各セクションが AI エージェントに対して明確な指示を提供し、一貫した UI 実装を可能にします。

全体構造

markdown

# DESIGN.md — {プロジェクト名}

## 1. Visual Theme & Atmosphere
## 2. Color Palette & Roles
## 3. Typography Rules
## 4. Component Stylings
## 5. Layout Principles
## 6. Depth & Elevation
## 7. Do's and Don'ts
## 8. Responsive Behavior
## 9. Agent Prompt Guide

記述の原則

すべてのセクションは AI エージェントが解釈しやすい 形式で記述する
曖昧な表現を避け、具体的な値（HEX、px、rem）を明記する
判断に迷うケースのためにガードレール（Do's and Don'ts）を設ける

1. Visual Theme & Atmosphere

デザインの全体的なムード・哲学・方向性を記述するセクションです。AI エージェントがプロジェクト全体のトーンを把握するための基盤となります。

記述内容

項目	説明	例
設計哲学	デザインの根本思想	「情報密度と視認性の両立」
視覚的印象	ユーザーが受ける第一印象	「プロフェッショナルかつ遊び心のある」
密度バランス	情報の詰め具合の方針	「データリッチだが圧迫感がない」
特徴的視覚要素	プロジェクト固有の視覚要素	「グラデーション、グロー効果」

記述例

markdown

## 1. Visual Theme & Atmosphere

**Design Philosophy**: Premium dark interface that evokes the feel of 
a high-end card collector's workshop — rich, immersive, and data-dense 
without feeling cluttered.

**Visual Impression**: Professional yet playful. Users should feel like 
they're using a tool built by MTG players, for MTG players.

**Density Balance**: Data-rich layouts with generous spacing. 
Cards and decks are the primary visual anchors.

**Signature Visual Elements**:
- Subtle glow effects on interactive elements
- Card-inspired rounded corners and shadows
- Mana color accents woven into the UI fabric

ベストプラクティス

比喩や例えを活用する

AI エージェントは具体的なイメージがあると正確に実装できます。「高級カードショップのショーケースのような」といった比喩が効果的です。

何であるか だけでなく 何でないか も記述する
- 良い例: 「ゲーミング寄りだが、ネオンが過剰なサイバーパンクではない」
- 悪い例: 「かっこいい感じ」
既存のプロダクトやデザインへの参照があれば記述する

2. Color Palette & Roles

セマンティックカラーを HEX 値と機能的役割で定義するセクションです。AI エージェントがどの場面でどの色を使うかを明確に判断できるようにします。

カテゴリ別テーブル構造

Background Surfaces

markdown

### Background Surfaces

| Token           | HEX       | Role                      |
|-----------------|-----------|---------------------------|
| bg-primary      | `#0F0F0F` | メインの背景色             |
| bg-secondary    | `#1A1A2E` | カードやセクションの背景   |
| bg-tertiary     | `#16213E` | ホバー状態・アクティブ領域 |
| bg-elevated     | `#1E293B` | モーダル・ドロップダウン   |

Text & Content

markdown

### Text & Content

| Token           | HEX       | Role                      |
|-----------------|-----------|---------------------------|
| text-primary    | `#F8FAFC` | 見出し・重要テキスト       |
| text-secondary  | `#94A3B8` | 説明文・補助テキスト       |
| text-muted      | `#64748B` | プレースホルダ・無効テキスト|
| text-inverse    | `#0F172A` | 明るい背景上のテキスト     |

Brand & Accent

markdown

### Brand & Accent

| Token           | HEX       | Role                      |
|-----------------|-----------|---------------------------|
| brand-primary   | `#7C3AED` | メインアクション・CTA      |
| brand-hover     | `#6D28D9` | プライマリのホバー状態     |
| brand-subtle    | `#7C3AED1A` | ブランドカラーの薄い背景 |
| accent          | `#F59E0B` | 注意・ハイライト           |

Semantic

markdown

### Semantic

| Token           | HEX       | Role                      |
|-----------------|-----------|---------------------------|
| success         | `#10B981` | 成功・完了                 |
| warning         | `#F59E0B` | 警告・注意                 |
| error           | `#EF4444` | エラー・削除               |
| info            | `#0EA5E9` | 情報・ヒント               |

Borders

markdown

### Borders

| Token           | HEX       | Role                      |
|-----------------|-----------|---------------------------|
| border-default  | `#1E293B` | 通常のボーダー             |
| border-hover    | `#334155` | ホバー時のボーダー         |
| border-focus    | `#7C3AED` | フォーカスリング           |

ベストプラクティス

セマンティックトークン名 を必ず使う（brand-primary は良い、purple-500 は避ける）
RGBA / HSLA を使う場合は 目的を明記 する（例: #7C3AED1A → 「ブランドカラーの10%透過、背景ティント用」）
ダークモード / ライトモード両対応の場合は、それぞれのパレットを明記する

3. Typography Rules

フォントファミリー・ウェイト・サイズ階層を定義するセクションです。

Font Families

markdown

## 3. Typography Rules

### Font Families

| Role      | Family                          | Fallback                |
|-----------|---------------------------------|-------------------------|
| Heading   | `"Inter", sans-serif`           | `system-ui, sans-serif` |
| Body      | `"Inter", sans-serif`           | `system-ui, sans-serif` |
| Monospace | `"JetBrains Mono", monospace`   | `"Courier New", monospace` |
| Display   | `"Clash Display", sans-serif`   | `"Inter", sans-serif`   |

Hierarchy Table

markdown

### Type Scale

| Level  | Size   | Weight | Line Height | Letter Spacing | Usage            |
|--------|--------|--------|-------------|----------------|------------------|
| h1     | 2.5rem | 700    | 1.2         | -0.02em        | ページタイトル    |
| h2     | 2rem   | 600    | 1.25        | -0.01em        | セクション見出し  |
| h3     | 1.5rem | 600    | 1.3         | 0              | サブセクション    |
| h4     | 1.25rem| 500    | 1.4         | 0              | カードタイトル    |
| body   | 1rem   | 400    | 1.6         | 0              | 本文             |
| small  | 0.875rem| 400   | 1.5         | 0.01em         | 補助テキスト     |
| caption| 0.75rem| 500    | 1.4         | 0.02em         | ラベル・キャプション|

Principles

markdown

### Typography Principles

- 見出しは常に **Semi-Bold (600)** 以上を使用する
- 本文では **Regular (400)** を基本とする
- **Thin (100)** および **Extra Light (200)** は使用禁止（視認性確保）
- 日本語テキストには line-height: 1.8 以上を推奨
- 数値表示（価格・統計）には **Monospace** フォントを使用する

ベストプラクティス

すべてのテキスト役割 を網羅する（見落としがちなもの: ツールチップ、バッジ、エラーメッセージ）
禁止ウェイト も明示的に記述する（AI エージェントが誤って使わないように）
rem ベースのサイズ指定を推奨（レスポンシブ対応のため）

4. Component Stylings

ボタン、カード、入力フィールド等の主要コンポーネントを 状態別 に定義するセクションです。

対象コンポーネント（7種）

Buttons -- プライマリ / セカンダリ / ゴースト / デストラクティブ
Cards -- デフォルト / ホバー / 選択中
Inputs -- テキスト / セレクト / チェックボックス
Navigation -- サイドバー / タブ / ブレッドクラム
Badges -- ステータス / カテゴリ / カウント
Modals -- ダイアログ / シート / コマンドパレット
Tables -- データテーブル / リストビュー

記述フォーマット

各コンポーネントは以下のフォーマットで記述します:

markdown

### Buttons

#### Primary Button
- **Background**: `brand-primary` (#7C3AED)
- **Text**: `text-inverse` (#FFFFFF)
- **Border**: none
- **Border Radius**: 8px
- **Padding**: 10px 20px
- **Font**: body weight 500
- **States**:
  - Hover: background `brand-hover` (#6D28D9), 
    transform scale(1.02)
  - Active: background #5B21B6, transform scale(0.98)
  - Disabled: opacity 0.5, cursor not-allowed
  - Loading: spinner icon, text "処理中..."

#### Secondary Button
- **Background**: transparent
- **Text**: `brand-primary` (#7C3AED)
- **Border**: 1px solid `brand-primary`
- **States**:
  - Hover: background `brand-subtle` (#7C3AED1A)
  - Active: background `brand-subtle` opacity 0.3

markdown

### Cards

#### Default Card
- **Background**: `bg-secondary` (#1A1A2E)
- **Border**: 1px solid `border-default` (#1E293B)
- **Border Radius**: 12px
- **Padding**: 24px
- **Shadow**: elevation-low
- **States**:
  - Hover: border-color `border-hover`, shadow elevation-mid
  - Selected: border-color `brand-primary`, 
    shadow 0 0 0 1px `brand-primary`

markdown

### Inputs

#### Text Input
- **Background**: `bg-primary` (#0F0F0F)
- **Border**: 1px solid `border-default` (#1E293B)
- **Border Radius**: 8px
- **Padding**: 10px 14px
- **Text**: `text-primary`
- **Placeholder**: `text-muted`
- **States**:
  - Focus: border-color `border-focus`, 
    box-shadow 0 0 0 3px `brand-subtle`
  - Error: border-color `error`, 
    box-shadow 0 0 0 3px #EF44441A
  - Disabled: background `bg-tertiary`, opacity 0.6

状態の網羅性

すべてのインタラクティブコンポーネントについて、最低限 Default / Hover / Active / Focus / Disabled の5状態を定義してください。

5. Layout Principles

スペーシングスケール、グリッドシステム、余白ルールを定義するセクションです。

記述例

markdown

## 5. Layout Principles

### Base Unit
- **Base**: 4px
- すべてのスペーシングは 4px の倍数で統一

### Spacing Scale

| Token | Value | Usage                        |
|-------|-------|------------------------------|
| xs    | 4px   | アイコンとテキストの間       |
| sm    | 8px   | 関連要素間                   |
| md    | 16px  | セクション内の要素間         |
| lg    | 24px  | セクション間                 |
| xl    | 32px  | 大きなセクション間           |
| 2xl   | 48px  | ページセクション間           |
| 3xl   | 64px  | ヒーロー領域のパディング     |

### Max Widths

| Context          | Max Width |
|------------------|-----------|
| Content area     | 1280px    |
| Text block       | 720px     |
| Modal (small)    | 480px     |
| Modal (large)    | 720px     |
| Full bleed       | 100%      |

### Grid Structure
- **Desktop**: 12カラムグリッド、gap 24px
- **Tablet**: 8カラムグリッド、gap 16px
- **Mobile**: 4カラムグリッド、gap 16px
- **Side padding**: Desktop 48px / Tablet 32px / Mobile 16px

Border Radius Scale

markdown

### Border Radius Scale

| Token      | Value | Usage                    |
|------------|-------|--------------------------|
| none       | 0     | シャープなエッジが必要な場合|
| sm         | 4px   | バッジ、小さなタグ        |
| md         | 8px   | ボタン、入力フィールド    |
| lg         | 12px  | カード、パネル            |
| xl         | 16px  | モーダル、大きなカード    |
| full       | 9999px| ピル型ボタン、アバター    |

6. Depth & Elevation

シャドウシステムとサーフェス階層を定義するセクションです。

5レベルの深度テーブル

markdown

## 6. Depth & Elevation

### Shadow System

| Level     | Token          | CSS Value                                    | Usage              |
|-----------|----------------|----------------------------------------------|--------------------|
| Flat      | elevation-none | none                                         | 背景と同一面の要素  |
| Low       | elevation-low  | `0 1px 3px rgba(0,0,0,0.3)`                 | カード、セクション  |
| Mid       | elevation-mid  | `0 4px 12px rgba(0,0,0,0.4)`                | ホバー中のカード    |
| High      | elevation-high | `0 8px 24px rgba(0,0,0,0.5)`                | ドロップダウン、ポップオーバー |
| Dialog    | elevation-dialog| `0 16px 48px rgba(0,0,0,0.6)`              | モーダル、ダイアログ |

### Surface Hierarchy

| Layer | Surface          | Background   | Border       |
|-------|------------------|-------------|--------------|
| 0     | Page background  | `bg-primary`| なし          |
| 1     | Card / Section   | `bg-secondary`| `border-default` |
| 2     | Elevated panel   | `bg-elevated`| `border-hover`  |
| 3     | Dropdown / Popup | `bg-elevated`| `border-hover`  |
| 4     | Modal overlay    | `bg-elevated`| なし（シャドウで区別） |

ダークモード対応の代替手法

ダークモードでのシャドウ

ダークテーマではシャドウが見えにくくなります。以下の代替手法を組み合わせてください:

markdown

### Dark Mode Elevation Alternatives

- **ボーダーの明度差**: 上位レイヤーほどボーダーを明るくする
- **背景の明度差**: 上位レイヤーほど背景を僅かに明るくする
- **グロー効果**: 重要な要素に微弱な発光ボーダーを付与
- **オーバーレイ**: モーダル背後に `rgba(0,0,0,0.7)` のスクリム

7. Do's and Don'ts

デザイン判断のガードレールを定義するセクションです。AI エージェントが迷った際の判断基準になります。

記述フォーマット

markdown

## 7. Do's and Don'ts

### Do ✅
- カードコンポーネントには必ず `elevation-low` 以上のシャドウを付与する
- インタラクティブ要素には hover / focus 状態を必ず実装する
- 色だけに依存せず、アイコンやテキストでも状態を伝える（アクセシビリティ）
- 数値データにはモノスペースフォントを使用する
- 画像の読み込み中はスケルトンスクリーンを表示する

### Don't ❌
- `text-primary` を `bg-primary` の上で直接使わない場合、
  コントラスト比 4.5:1 を下回る組み合わせは禁止
- ボーダーラディウスを要素ごとにバラバラにしない
  （Scale テーブルの値のみ使用）
- 3色以上のグラデーションを使用しない
- テキストに text-shadow を使わない
- z-index を 100 より大きい値にしない
  （モーダルは 50、ドロップダウンは 40）

プロジェクト固有の制約

プロジェクト固有のルールもこのセクションに含めます:

markdown

### Project-Specific Rules
- MTGの5色（White/Blue/Black/Red/Green）はマナシンボルの
  表示にのみ使用し、UIのアクセントカラーとしては使わない
- カード画像は Scryfall API から取得し、ローカルに保存しない
- アニメーションの duration は最大 300ms に制限する

8. Responsive Behavior

ブレークポイント、レイアウト変化、タッチターゲットを定義するセクションです。

Breakpoints テーブル

markdown

## 8. Responsive Behavior

### Breakpoints

| Name    | Min Width | Columns | Side Padding | Typical Devices      |
|---------|-----------|---------|--------------|----------------------|
| mobile  | 0px       | 4       | 16px         | スマートフォン        |
| tablet  | 768px     | 8       | 32px         | タブレット            |
| desktop | 1024px    | 12      | 48px         | ノートPC              |
| wide    | 1440px    | 12      | auto (centered) | デスクトップモニタ |

### Touch Targets
- 最小タッチターゲット: **44px x 44px**
- ボタン間の最小間隔: **8px**
- モバイルでのフォントサイズ下限: **14px**

Collapsing Strategy

markdown

### Collapsing Strategy

| Component         | Desktop           | Tablet             | Mobile             |
|-------------------|-------------------|--------------------|--------------------|
| Navigation        | サイドバー (固定)  | サイドバー (折畳)   | ボトムナビ          |
| Data Table        | フルテーブル       | 横スクロール        | カードリスト        |
| Grid (cards)      | 4列               | 2列                | 1列                |
| Modal             | センターダイアログ  | センターダイアログ   | フルスクリーンシート |
| Search            | インライン展開     | インライン展開      | フルスクリーン検索  |
| Sidebar + Content | 横並び            | オーバーレイ        | フルスクリーン遷移  |

タッチ操作の考慮事項

スワイプでカードを削除・アーカイブする機能は 確認ダイアログ を必ず挟む
ドラッグ&ドロップはデスクトップのみとし、モバイルでは代替UIを提供する
ピンチズームはカード画像の拡大にのみ許可する

9. Agent Prompt Guide

AI エージェント向けのクイックリファレンスセクションです。エージェントがコーディング中に素早く参照できるよう、要点をまとめます。

Quick Color Reference

markdown

## 9. Agent Prompt Guide

### Quick Color Reference

Background: #0F0F0F → #1A1A2E → #1E293B (layer progression)
Text: #F8FAFC (primary) → #94A3B8 (secondary) → #64748B (muted)
Brand: #7C3AED (actions) → #6D28D9 (hover)
Success/Warning/Error: #10B981 / #F59E0B / #EF4444

Example Prompts

markdown

### When Building a New Page

"Create a [page name] page following DESIGN.md. 
Use bg-primary for the page background, bg-secondary for cards.
All interactive elements need hover/focus states.
Use the spacing scale (multiples of 4px).
Apply elevation-low shadow to cards."

### When Building a Component

"Build a [component name] component per DESIGN.md Section 4.
Match the exact border-radius from the scale (sm/md/lg).
Include all 5 interaction states.
Use semantic color tokens, never raw HEX values."

### When Fixing Styles

"Audit this component against DESIGN.md:
- Check color tokens match Section 2
- Verify spacing uses the 4px grid (Section 5)
- Confirm elevation matches surface layer (Section 6)
- Validate responsive behavior (Section 8)"

Iteration Guide

markdown

### Iteration Guide

1. **First pass**: レイアウトとスペーシングに集中
2. **Second pass**: カラートークンとタイポグラフィを適用
3. **Third pass**: インタラクション状態（hover/focus/active）を追加
4. **Fourth pass**: レスポンシブ対応とアクセシビリティ確認
5. **Final pass**: Do's and Don'ts に照らして最終チェック

まとめ

セクション	主な役割	AI エージェントへの効果
1. Visual Theme	トーン設定	デザインの方向性を正しく理解
2. Color Palette	色の定義	正確な色選択
3. Typography	文字の定義	フォント・サイズの統一
4. Components	部品の定義	状態を含む正確な実装
5. Layout	配置の定義	一貫したスペーシング
6. Depth	深度の定義	正しい重なり表現
7. Do's/Don'ts	ガードレール	誤った判断の防止
8. Responsive	レスポンシブ	デバイス対応
9. Agent Guide	クイックリファレンス	実装速度の向上

次のステップ

DESIGN.md のフォーマットを理解したら、Stitch 連携ガイドで実践的なワークフローを学びましょう。

DESIGN.md フォーマット仕様 ​

全体構造 ​

1. Visual Theme & Atmosphere ​

記述内容 ​

記述例 ​

ベストプラクティス ​

2. Color Palette & Roles ​

カテゴリ別テーブル構造 ​

Background Surfaces ​

Text & Content ​

Brand & Accent ​

Semantic ​

Borders ​

ベストプラクティス ​

3. Typography Rules ​

Font Families ​

Hierarchy Table ​

Principles ​

ベストプラクティス ​

4. Component Stylings ​

対象コンポーネント（7種） ​

記述フォーマット ​

5. Layout Principles ​

記述例 ​

Border Radius Scale ​

6. Depth & Elevation ​

5レベルの深度テーブル ​

ダークモード対応の代替手法 ​

7. Do's and Don'ts ​

記述フォーマット ​

プロジェクト固有の制約 ​

8. Responsive Behavior ​

Breakpoints テーブル ​

Collapsing Strategy ​

9. Agent Prompt Guide ​

Quick Color Reference ​

Example Prompts ​

Iteration Guide ​

まとめ ​

DESIGN.md フォーマット仕様

全体構造

1. Visual Theme & Atmosphere

記述内容

記述例

ベストプラクティス

2. Color Palette & Roles

カテゴリ別テーブル構造

Background Surfaces

Text & Content

Brand & Accent

Semantic

Borders

ベストプラクティス

3. Typography Rules

Font Families

Hierarchy Table

Principles

ベストプラクティス

4. Component Stylings

対象コンポーネント（7種）

記述フォーマット

5. Layout Principles

記述例

Border Radius Scale

6. Depth & Elevation

5レベルの深度テーブル

ダークモード対応の代替手法

7. Do's and Don'ts

記述フォーマット

プロジェクト固有の制約

8. Responsive Behavior

Breakpoints テーブル

Collapsing Strategy

9. Agent Prompt Guide

Quick Color Reference

Example Prompts

Iteration Guide

まとめ