frontend-docs

フロントエンドドキュメント

コードの根拠に基づいて、フロントエンドアプリケーションの客観的な Markdown ドキュメントを作成します。ユーザーが選択した種類のドキュメントのみを作成し、明示的に依頼されない限り、ドキュメント一式は作成しないでください。

ドキュメントの選択

ユーザーがドキュメントの種類を指定していない場合は、次から1つ以上を選ぶように尋ねてください。

ユーザーのニーズ	テンプレート
フロントエンドのアーキテクチャと設計	templates/architecture-design.md
開発者のオンボーディング	templates/developer-onboarding.md
ギャップ分析と改善の機会	templates/gap-analysis.md
ルート、データ、状態のコントラクト	templates/route-data-contracts.md
コンポーネントシステムとデザインシステムのマップ	templates/component-system-map.md

ユーザーが出力先のパスを指定せずに「frontend docs」と依頼した場合は、選択したファイルをテンプレート名をファイル名として docs/frontend/ に作成してください。リポジトリにより明確なドキュメント規約がある場合は、そちらに従ってください。

引数のルール：

• --mode は、選択されたドキュメントの種類として扱います。
• --frontendPath は、調査対象のフロントエンドのパス、アプリ、ルートグループ、ドメインシステム、コンポーネントツリー、またはスコープとして扱います。
• --outputPath は、指定された Markdown の出力先として扱います。
• --mode が指定されていない場合は、ユーザーの表現からドキュメントの種類を推測するか、選択するように尋ねてください。

選択ルール：

• 依頼にコンポーネント、UI システム、デザインシステム、コンポーネント一覧、画面、状態、アクセシビリティ、または視覚的パターンが含まれる場合は、component-system-map.md を選択してください。
• 依頼にルート、ナビゲーション、ローダー、クエリキー、ミューテーション、アダプター、API 呼び出し、フォーム、状態のコントラクト、またはフロントエンドとバックエンドの統合動作が含まれる場合は、route-data-contracts.md を選択してください。
• 主な成果がリスク、問題のあるコード、違反、技術的負債、アクセシビリティの問題、デザインシステムの乖離、テストの不足、または改善の機会である場合は、gap-analysis.md を選択してください。
• 主な成果が、フロントエンドの構成やその設計理由の説明である場合は、architecture-design.md を選択してください。
• 2種類のドキュメントで出力が大きく異なり、プロンプトから読み手のニーズを明確に判断できない場合に限り、確認の質問をしてください。

ワークフロー

ステップ 1：スコープの確認

対象となるフロントエンドアプリ、パッケージ、ルートグループ、ドメインシステム、コンポーネントセット、状態レイヤー、またはデザインシステムの領域を特定します。依頼の範囲が広い場合は、まず最も価値の高い範囲だけをドキュメント化し、対象外として残る範囲を記してください。

次の項目を把握します。

• ドキュメントの種類と対象読者。
• 対象パスまたはドキュメント規約。
• 判明した場合は、フロントエンドの技術スタックとランタイム。
• ドキュメントで現状、提案する設計、またはその両方を説明するか。

ステップ 2：ルールと既存ドキュメントを確認する

references/discovery-workflow.md を読み、実装の詳細を調べる前にプロジェクトのルールを確認します。

優先順位：

1. プロジェクトの指示：AGENTS.md、CLAUDE.md、DESIGN.md、.cursor/rules/、.windsurf/rules/、CONTRIBUTING.md。
2. 既存ドキュメント：docs/、アーキテクチャに関するメモ、デザインシステムのドキュメント、オンボーディングドキュメント、Storybook のドキュメント、ADR、RFC。
3. コード上の契約：ルート定義、ローダー、クエリーオプション、API アダプター、スキーマ、ストア、コンテキスト、コンポーネント、テスト、ストーリー、生成されたルートツリー、トークンファイル。

プロジェクトのルールとこのスキルが矛盾する場合は、プロジェクトのルールを優先します。

DESIGN.md が次の 2 か所にあるか確認します。リポジトリのルートと docs/references/DESIGN.md です。両方を確認し、両方ある場合はルートのファイルを優先し、内容の相違を指摘事項として記録します。解決したパスを記録し、ドキュメントがデザインルールを参照する箇所には必ずそのパスを記載します。

いずれかの場所に DESIGN.md がある場合は、規範的なフロントエンドの契約として扱います。UI、TSX、CSS、Tailwind、トークン、アイコン、余白、タイポグラフィ、モーション、コピー、アクセシビリティ、コンポーネントのパターンを評価する前に読み込みます。

リポジトリが systems/<domain>/ を使用している場合は、ドキュメントを書く前に references/feature-system-contracts.md を読み込みます。機能／ドメインのドキュメントでは、app-renderer-systems を主要なローカルアーキテクチャの視点として扱います。

--mode gap-analysis が選択されている場合、バンドルされた UI 品質リファレンスと、baseline-ui、frontend-design、interface-design、interaction-design、web-design-guidelines を、ユーザーが目にするプロダクト画面の既定の情報源として扱います。これらを使って、使いやすさ、コンポーネントの状態、トークンの規律、アクセシビリティ、視覚的な階層、マイクロコピー、モーション、ダークモード、レスポンシブな挙動、既定パターンからの逸脱に関するギャップを特定します。ユーザーから依頼されない限り、独立した UI 監査は作成しません。

ステップ 3：コードから根拠を集める

エントリーポイントからユーザーが操作する機能まで、フロントエンドを追跡します。コードを大量に貼り付ける代わりに、ファイルへの参照を使用します。

確認する項目：

• アプリのブートストラップ、ルーターの設定、プロバイダー、レイアウトシェル、テーマ／デザインシステムの統合、グローバルスタイル。
• Vite の設定、React プラグイン、Tailwind プラグイン、TanStack Router のプラグイン順序、生成されたルートツリーの処理、エイリアス、環境変数の公開、ビルド／プレビューのスクリプト。
• ルート、ローダー、ルートガード、検索パラメーター、ナビゲーション、遅延読み込みされるルート、エラーコンポーネント、読み込み中コンポーネント。
• ドメインシステム、systems/<domain>/ の境界、アダプター、クエリーキー、クエリーオプション、フック、ミューテーション、フォーム、スキーマ、ストア、コンテキスト、ガード、公開用バレルファイル。
• コンポーネント、プリミティブ、バリアント、状態マトリクス、アクセシビリティのパターン、デザイントークン、レスポンシブな挙動、ダークモード。
• TSX／CSS における DESIGN.md の遵守状況：生の hex/rgb/hsl カラー、ハードコードされた Tailwind カラー、インラインスタイル、固定値の余白／角丸／サイズ、アイコンファミリーの使用状況、タイポグラフィのユーティリティ／クラス、トークンファイル、CSS 変数、文書化された例外。
• ユーザーが目にする画面の UI 品質に関するギャップ：画面の目的が不明瞭、状態マトリクスの欠如、階層が弱い、テキストのオーバーフロー、見せかけのインタラクティブ性、汎用的な CTA、プレースホルダーのコピー、アイコン代わりの絵文字、ありきたりな SaaS／AI のビジュアル、未検証のコントラスト、フォーカス可視化の挙動の欠如、動きを抑える設定への対応不足、未テストのダークモード、パフォーマンスに影響するビジュアルパターン。
• テスト、ストーリー、ビジュアル検証、Playwright のカバレッジ、モック／フェイク、既知のテストギャップ。
• パフォーマンスに影響する領域：大規模なテーブル、グラフ、仮想化リスト、画像、バンドルの境界、Suspense／遅延読み込み、不要なクライアント側状態。

コードやドキュメントに直接記載されている事実は「確認事項」として記述し、直接示されていない結論には「推測」とラベルを付けます。

Step 4: 関連するリファレンスのみを読み込む

段階的開示を活用します。

• ドキュメントの構成と簡潔さについては、references/documentation-principles.md を読みます。
• フロントエンドのエビデンス収集とソーススキルの振り分けについては、references/source-skill-map.md を読みます。
• systems/<domain>/ の機能アーキテクチャ、アダプター、クエリーオプション、フック、ストア、コンテキスト、ガード、バレルについては、references/feature-system-contracts.md を読みます。
• いずれかの場所に DESIGN.md がある場合は、references/design-system-compliance.md を読みます。
• --mode gap-analysis が選択され、スコープに可視 UI が含まれる場合は、references/ui-quality-gap-lens.md を読みます。
• React、systems、route/data、UI、アクセシビリティ、デザインシステム、テスト、品質チェックについては、references/frontend-quality-lenses.md を読みます。
• React、TanStack Router/Query、Zustand、Storybook、shadcn/Radix、Tailwind、アクセシビリティ、デザインシステムの詳細については、references/framework-contract-notes.md を読みます。
• UI 品質の指摘に再現可能なエビデンスが必要な場合は、このスキルのルートから読み取り専用のヘルパーを実行します。生のカラーの逸脱には node scripts/detect-token-drift.mjs <source-dir>、コントラストの組み合わせには node scripts/check-contrast.mjs --fg <color> --bg <color> または --json <file> を使用します。
• 選択したドキュメント形式については、templates/ 内の該当するテンプレートのみを読みます。

Step 5: Markdown ドキュメントを作成する

選択したテンプレートを構成として使用します。対象読者にとって簡潔で役立つドキュメントにしてください。

生成する各ドキュメントでは、次の点を守ります。

• スコープ、対象読者、最終確認日から始めます。
• 可能な場合は、ファイルパスと行番号を付けて、具体的なコードやドキュメントのエビデンスを示します。
• 現状と推奨事項を分けます。
• インベントリ、ルート、契約、状態、ギャップ、次のアクションには表を優先します。
• 所有関係、ルーティング、データフロー、コンポーネント間の関係を明確にする場合に限り、図を含めます。
• 詳細が不明な場合は、内容を作り上げず、不明点や前提として明記します。
• ドキュメントを更新すべきタイミングを説明する、短いメンテナンス注記で締めくくります。

Step 6: 完了前に検証する

最終回答の前に、次の点を確認します。

• 作成または編集したドキュメントを読み直します。
• 選択したテンプレートに従っていることを確認します。
• 自明でない主張すべてにエビデンスがあるか、推論であると明記されていることを確認します。
• 無関係なテンプレートが生成されていないことを確認します。
• リンクとファイルパスを確認します。
• systems/<domain>/ のコードベースが、一般的な React のフォルダー構成に関する助言ではなく、機能システムの契約に照らして評価されていることを確認します。
• リポジトリのルートまたは docs/references/ に DESIGN.md がある場合、フロントエンドの TSX、CSS、トークンファイル、文書化された例外に照らして評価されていることを確認します。ギャップ分析ドキュメントでは、このスキャンについて、指摘事項または「問題なし」を明示した行のいずれかを記載する必要があります。
• 可視 UI を対象とするギャップ分析ドキュメントには、状態マトリクス、アクセシビリティの最低基準、トークンの適切な使用、マイクロコピー、モーション／ダークモード／レスポンシブ動作、デフォルトパターンの回避について、UI 品質の合否行または指摘事項が含まれていることを確認します。
• React、Vite、TanStack Router、TanStack Query、Tailwind CSS、プロジェクトのデザインシステムに関する主張が、プロジェクトのエビデンス、ローカルスキル、または最新のドキュメントに基づいていることを確認します。
• ドキュメントのフォーマットや Markdown の lint に使える検証コマンドがある場合は、プロジェクトで推奨されているコマンドを実行します。

出力ルール

• リポジトリでドキュメントの言語が定められている場合を除き、ユーザーの言語で記述してください。
• 簡潔で技術的な文章を使用してください。宣伝的な表現や一般的な主張は避けてください。
• 大きなソースコードブロックを重複して記載しないでください。代わりにソースへのパスをリンクしてください。
• ユーザーがその形式を選択した場合、またはリポジトリの慣例で必要な場合を除き、ADR、RFC、PRD、設計仕様書を独断で作成しないでください。
• ドキュメントの作成中にフロントエンドを変更しないでください。ギャップが見つかった場合は、推奨事項として記録してください。
• コードから根拠を確認できる場合、スクリーンショットだけで UI の品質を説明しないでください。コード、ドキュメント、ストーリー、またはレンダリング検証の情報源を引用してください。
• 出力を React、Vite、Tailwind、TanStack のチュートリアルにしないでください。プロジェクト固有の所見、契約、またはオンボーディング手順に影響する場合に限り、フレームワークの動作を説明してください。
• リポジトリ内の systems/<domain>/ やルートの規約に反するフォルダー移動を推奨しないでください。
• TSX と CSS の根拠に照らして DESIGN.md のルールを確認し、トークンの使用状況と例外を検証していない場合、フロントエンドがデザインシステムに準拠していると述べないでください。
• ギャップ分析の対象となる UI を健全と判定する前に、ソースの根拠、テスト／ストーリー、レンダリング検証を使って UI 品質のリスクを確認してください。確認できない場合は、その旨を明記してください。

例

アーキテクチャと設計

ユーザーの依頼：「ダッシュボードアプリのフロントエンドアーキテクチャをドキュメント化してください。」

対応：templates/architecture-design.md を選択し、プロジェクトのルールとフロントエンドアプリのコードを調査して、アプリの起動処理、ルート、システム、状態管理、デザインシステムとの統合、テスト、リスクを整理します。

オンボーディング

ユーザーの依頼：「新しいフロントエンド開発者がこのアプリを理解できるよう、オンボーディング資料を作成してください。」

対応：templates/developer-onboarding.md を選択し、セットアップコマンド、アプリのエントリーポイント、ルートとデータの流れ、コンポーネントの規約、デザインシステムのルール、安全に着手できる変更箇所を特定します。

ギャップ分析

ユーザーの依頼：「このシステムにおけるフロントエンドアーキテクチャの問題点とドキュメントの不足を見つけてください。」

対応：templates/gap-analysis.md を選択し、プロジェクトのルールに加え、React、ルーティング、サーバー状態、クライアント状態、コンポーネント、デザインシステム、UI 品質、アクセシビリティ、パフォーマンス、テストの観点から調査します。

ルートとデータの契約

ユーザーの依頼：「請求 UI のルートローダー、クエリーキー、ミューテーション、API アダプターをドキュメント化してください。」

対応：templates/route-data-contracts.md を選択し、ルートの所有範囲、ローダーとクエリーの契約、アダプターの呼び出し、フォーム、ミューテーション、キャッシュの無効化、エラー、副作用をたどります。

機能システムのドキュメント

ユーザーの依頼：「accounts システムをドキュメント化し、フロントエンドのシステムパターンに準拠しているか教えてください。」

対応：依頼の目的に応じて templates/architecture-design.md または templates/gap-analysis.md を選択し、references/feature-system-contracts.md を読み込んで、systems/accounts/ のディレクトリ構成、依存関係の流れ、クエリーオプション、アダプターの契約、フック、ストア、コンテキスト、ガード、公開バレルを評価します。

コンポーネントシステムのマップ

ユーザーの依頼：「アカウント設定のコンポーネントと、デザインシステムへの依存関係を整理してください。」

対応：templates/component-system-map.md を選択し、コンポーネント、バリエーション、状態、プリミティブ、トークン、アクセシビリティの動作、ストーリー／テスト、おすすめのドキュメントを一覧化します。