# Design Spec

> 対話的にデザイン仕様書を作成・既存ドキュメントに追記する

- Skill: `ousiass/design-spec` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ousiass/design-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ousiass/design-spec/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ousiass (https://skillmd.com/u/ousiass)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ousiass/design-spec

---


# design-spec

UI/UX・システム設計の両面をカバーするデザイン仕様書を、おすすめを提示しながらヒアリングして作成する。既存ドキュメントへの追記にも対応。

## 前提条件

- Claude Code 環境
- `gh` CLI（GitHub 連携モード時）

## 引数

- **引数なし**: 新規デザイン仕様書を作成
- **パス指定**: 既存のデザイン仕様書に追記・更新
- **テキスト**: 初期情報として扱い、不足分をヒアリング

## 生成するドキュメント（デフォルトパス）

| ドキュメント | デフォルトファイル | 内容 |
|------------|---------|------|
| **画面設計** | `docs/design/screens.md` | 画面一覧、ワイヤーフレーム（ASCII/Mermaid）、画面遷移図 |
| **コンポーネント仕様** | `docs/design/components.md` | コンポーネント一覧、Props/状態定義、バリアント |
| **デザイントークン** | `docs/design/tokens.md` | カラー、タイポグラフィ、スペーシング、その他トークン |
| **インタラクション仕様** | `docs/design/interactions.md` | ユーザー操作、状態遷移図、アニメーション、エラー/ローディング状態 |

- **上記はデフォルトパス。既存の仕様書ディレクトリが見つかった場合はそちらを使う（下記「探索」参照）**

## フェーズ1: 現状把握と方針決定

#### 1-0: 既存ドキュメントの探索（必須・最初に実行）

**引数でパスが指定されている場合:**
- そのパスのファイル/ディレクトリを直接読み込む
- 同じディレクトリ内の関連ファイルも確認する

**引数なしの場合:**
以下のパターンで既存ドキュメントを検索する（Glob を使用）:
```
**/spec/**/*.md
**/specs/**/*.md
**/docs/**/*.md
**/design/**/*.md
**/specifications/**/*.md
```

**探索結果に基づく判定:**
- **既存ドキュメントが見つかった場合**: そのディレクトリ構造を記録し、デザイン仕様書もこの構造に合わせて配置する。デフォルトパスは使わない
- **見つからなかった場合**: デフォルトパス（`docs/design/` 配下）を使用する

**重要: 探索で見つけたドキュメントは必ず Read で読み込み、現在の仕様を把握してからフェーズを進める。**

#### 1-1: プロジェクトのスキャン

デザイン仕様に必要な情報を収集する：

- **フレームワーク・UIライブラリ**: React/Vue/Svelte, Tailwind/MUI/shadcn 等
- **既存デザイン基盤**: `tailwind.config.*`, `theme.ts`, `tokens.*`, `variables.css` 等
- **画面・ページ構成**: `pages/`, `views/`, `routes/`, `app/` 等
- **コンポーネント構成**: `components/` 配下の構造

スキャン結果はヒアリングの選択肢生成に使う。

#### 1-2: 対象と方針のヒアリング

`AskUserQuestion` で以下を確認（引数から判明済みの情報はスキップ）：

1. **対象**: 新規画面 or 既存画面のリデザイン（スキャン結果から画面一覧を選択肢に含める）
2. **範囲**: 作成するドキュメントの選択（4種すべて or 必要なもののみ）
3. **デザインの方向性**: 選択肢で提示
   - 既存デザイン基盤に合わせる / 新しい方向性を定義する / 参考デザインがある

#### 1-3: 出力先の選択

`AskUserQuestion` で確認：
- **GitHub Issue + ブランチ + PR**: feat Issue を作成し作業ブランチで作業、完了後 PR 作成
- **GitHub Issue + ブランチ**: feat Issue を作成し作業ブランチで作業。PR は手動
- **コミットまで**: 現在のブランチでファイル作成・コミットのみ
- **ファイル作成のみ**: ファイル生成のみ。git 操作なし

**GitHub Issue モード選択時:**
- ベースブランチ記録 → feat Issue 作成 → `feat/#<Issue番号>` ブランチ作成 → Issue にブランチ名追記
- **Issue タイトルは「デザインする対象」を記述する**（例: `feat: ダッシュボード画面のデザイン仕様`）
- **ブランチ作成前に同名ブランチの存在を確認する。既存の場合はサフィックス付与またはユーザーに確認**

TaskCreate でタスク化。

## フェーズ2: ドキュメント作成サイクル（各ドキュメントで繰り返し）

#### 2-1: ヒアリング

当該ドキュメントに必要な情報を `AskUserQuestion` **1回**にまとめて質問（4問以内）。
選択肢の `description` に**おすすめ理由やメリット・デメリット**を記載する。

**ドキュメント別のヒアリング指針:**

| ドキュメント | 聞くべきこと | おすすめの出し方 |
|------------|------------|---------------|
| 画面設計 | 主要画面、画面遷移、レスポンシブ要件 | 類似サービスのパターンを選択肢で提示 |
| コンポーネント仕様 | 粒度、バリアント、共有コンポーネント | 既存UIライブラリのコンポーネントを提案 |
| デザイントークン | ブランドカラー、フォント、スペーシング規則 | 業界標準のスケール（4px/8px等）を提案 |
| インタラクション | 主要操作、遷移アニメーション、エラー表示 | 一般的なUXパターンを選択肢で提示 |

**曖昧な回答への対応（`references/clarification-patterns.md` 参照）**

#### 2-2: 執筆

- ヒアリング内容に基づき作成
- 図表は Mermaid 記法（`references/diagram-guide.md` 参照）
- 画面モックアップは ASCII アートまたは Mermaid で表現
- 改訂履歴を末尾に記載（`references/diagram-guide.md` 末尾のフォーマット参照）

#### 2-3: レビュー

ユーザーに提示し `AskUserQuestion` で確認（「問題なし」選択肢を含める）。

#### 2-4: 改善サイクル

フィードバックあり → 修正 → 改訂履歴更新 → 再確認 → なくなるまで繰り返す。

#### 2-5: Format & Lint

設定があれば実行。なければスキップ。

#### 2-6: Commit

CLAUDE.md の規約に従いコミット（コミットモード以上の場合）。

## フェーズ3: 完了

1. 全ドキュメントの完了確認
2. ドキュメント間の整合性チェック（画面設計とコンポーネント、トークンとコンポーネント等）
3. 出力モードに応じた処理：
   - **Issue + Branch + PR**: push → PR 作成 → Issue に仕様書リンク追記 → サマリー報告
   - **Issue + Branch**: push → Issue に仕様書リンク追記 → サマリー報告
   - **コミットまで**: サマリー報告（パス一覧）
   - **ファイル作成のみ**: サマリー報告（パス一覧）

## ルール

- 不明点は推測せず必ずユーザーに確認する
- **質問には必ず `AskUserQuestion` を使い選択式で提示する。** テキストだけで質問しない
- 1回あたり4問以内にまとめる
- 各選択肢の `description` に**おすすめ理由やメリット・デメリット**を記載する
- 既存ドキュメントへの追記時は既存構造・スタイルとの整合性を優先
- ドキュメント更新時は必ず改訂履歴を追記する
- TaskCreate/TaskUpdate で進捗を管理する
- **既存の仕様書ディレクトリが見つかった場合、デフォルトパスではなく既存パスにファイルを配置する**
- **既存ファイルを更新する場合は Edit で直接編集する。同じ内容の新規ファイルを別の場所に作成しない**
- プロジェクトに存在しないコンポーネントや画面を選択肢に含めない