component-architecture

コンポーネントアーキテクチャ

場当たり的なコンポーネントが絡み合った状態を、組み合わせ可能なシステムへと変えます。既存の構成を監査し、アトミックなレベルに分類してから、問題の大きいコンポーネントを、小さく、型付けされ、ドキュメントが整った部品にリファクタリングします。**最優先の原則：コンポーネントが存在する価値は、責務が1つであり、無効な状態を表現できないプロパティインターフェースを備えていることによって決まります。**動作するリファクタリング済みコードと、ユーザーが次のアクションを取れる監査結果を必ず提供してください。助言だけで終わらせてはいけません。

使用する場合／使用しない場合

次の用途に使用します：コンポーネントの分割、プロパティインターフェースの設計、バリアントシステム、共有ライブラリの切り出し、制御コンポーネントと非制御コンポーネントの選定、コンポーネントのドキュメント作成。

実際のニーズが次の場合は、代わりに引き継いでください：

• ビジュアルトークン（間隔、色、文字サイズのスケール） → skills/frontend-design/design-foundation
• コンポーネント内のアニメーション／フィードバック → skills/frontend-design/interaction-physics
• コンポーネントのキーボード／ARIA 動作 → skills/frontend-design/accessibility-excellence
• レンダリングパフォーマンス（メモ化、再レンダリング） → skills/frontend-design/performance-optimization
• フロントエンド全体のどこから着手すべきか不明 → skills/frontend-design/frontend-orchestrator

ステップ 0 — コードベースを調べてから、未解決の点だけを質問する

何かを提案する前に、実際のコードからコンポーネントの一覧を作成します：

1. コンポーネントのディレクトリ（components/、ui/、src/app/**、lib/）を見つけます。フレームワークとスタイリング手法（Tailwind、CSS Modules、CSS-in-JS、vanilla）を確認し、それに合わせてください。依頼されていないスタイリングシステムを新たに導入してはいけません。
2. コンポーネント数を数え、次の項目に注意します：およそ200行を超えるファイル、データ取得と詳細なマークアップのレンダリングを両方行うコンポーネント、重複した UI（複数のボタン／入力／カードの実装）、同じ値を繰り返すインラインスタイル、クラスベースの継承。
3. 既存のデザインシステムや UI キット（shadcn/ui、MUI、Chakra、社内パッケージ）があるか確認します。ある場合は、その規約を拡張し、並行する別のシステムを構築しないでください。

ユーザーには、コードから分からなかったことだけをまとめて一度に質問します：対象範囲（アプリ全体、1つの機能、または問題のある1つのコンポーネントか）と、共有ライブラリ／パッケージを作ることが目標か、ローカルな構成を整理するだけか。依頼内容から対象範囲がすでに明らかな場合（「このファイルをリファクタリングして」など）は質問せず、前提を明示して作業を進めます。

ワークフロー

1. 一覧をアトミックなレベルに分類する

• アトム — 分割できず、ほかのコンポーネントに依存しないもの：Button、Input、Label、Icon、Badge、Spinner。
• 分子 — 1つの目的を持つ、アトムの小さな組み合わせ：FormInput（Label+Input+Error）、SearchBar。
• 有機体 — ビジネス上の目的を持ち、多くの場合は状態も扱うセクション：NavBar、Card、Modal、Form。
• テンプレート — 有機体を配置したページレイアウト。異なる種類のページ間では再利用しません。
• ページ — 実際のデータを持つテンプレート。エッジケースを見つけるために使用します。

判断基準：コンポーネントを分類できない場合、責務が多すぎます。これは分類上の問題ではなく、リファクタリングの候補です。

2. 効果の大きさに基づいてリファクタリングの優先順位を決める

順序：(1) 重複したアトム（最初に統合します。他のすべてはそれを土台にするためです）、(2) 単一責務に違反する巨大なコンポーネント、(3) 無効な状態を許すプロパティインターフェース、(4) コピー＆ペーストを強いるバリアントの不足。効果をそれぞれ一文で示し、優先度の高いリファクタリングを3〜5件提案してから、広範な書き換えを始める前にユーザーに対象範囲を確認します。単一コンポーネントの依頼では、確認を省略してリファクタリングします。

3. 次の判断基準に従ってリファクタリングします

• 分割ルール： データの取得、フォームの状態管理、詳細なマークアップのレンダリングをすべて担うコンポーネントは、オーケストレーターと責務を絞った子コンポーネントに分割します。分割の基準は行数ではなく、責務です。
• 常に継承よりコンポジションを優先します。 バリエーションは props（variant、size）で表現し、プリセットは薄いラッパーにします。サブクラスは作りません。
• 制御コンポーネントと非制御コンポーネント： 編集中の値に他の UI が反応する必要がある場合（リアルタイムのバリデーション、連動するフィールド、文字数カウントなど）は、制御コンポーネントにします。送信時に一度だけ読み取る、結果を返さない入力であれば、非制御コンポーネントでも問題ありません。1つのコンポーネントで両方の方式を混在させてはいけません。
• props インターフェースのルール： 競合し得るブール値の代わりにユニオン型を使います（isPrimary と isDanger ではなく、variant: 'primary' | 'danger'）。有効な選択肢に制限し、className と ARIA 属性を引き継ぎ、コールバックには on<Event> という名前を付けます。2つのブール値 props の組み合わせで無効な状態になり得る場合は、インターフェースを再設計します。
• 抽出の基準： コピーが本当に同じ概念である場合に限り、2〜3回目の重複で共通コンポーネントを抽出します。見た目が似ていても異なる理由で変更されるものは分けたままにします。誤った抽象化は、重複よりも大きなコストになります。

アトムの標準的な形（完全な一覧は references/patterns.md にあります）：

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  onClick?: () => void;
  children: React.ReactNode;
}

export const Button = ({ variant = 'primary', size = 'md', disabled, loading, ...rest }: ButtonProps) => (
  <button
    className={`button button--${variant} button--${size}`}
    disabled={disabled || loading}
    {...rest}
  />
);

4. 作成したものをドキュメント化します

抽出またはリファクタリングしたすべての共通コンポーネントに、目的、props の表、バリエーションとその用途、状態、アクセシビリティに関する注意点、エッジケースを記載したドキュメントを用意します。references/patterns.md のテンプレートを使用してください。チームの目に触れる場所にドキュメントを配置します（Storybook があれば Storybook のストーリー、なければ同じディレクトリの README.md または JSDoc）。

必須の出力形式

次の2つを提出してください。

1. コード — プロジェクトの既存のスタイルと命名規則に従って、リファクタリングまたは新規作成したコンポーネントファイルを適切に編集します。すべての呼び出し元を更新し、アプリが引き続きコンパイルできることを確認してください。

2. コンポーネントアーキテクチャ監査（Markdown）：

## Component Inventory
| Component | File | Level | Verdict | Issue |
| Button (x3 impls) | src/... | atom | consolidate | 3 duplicate implementations |
| UserProfile | src/... | ??? | split | fetches + validates + renders (412 lines) |
| Card | src/... | organism | keep | — |

## Refactors applied
1. [name] — what changed, files touched, why (one line each)

## Refactors recommended (not applied)
1. [name] — payoff, estimated blast radius

## Conventions going forward
- Directory structure: [atoms/molecules/organisms or project's own scheme]
- Prop rules adopted: [union variants, no conflicting booleans, ...]
- When to extract: [the 2–3 rule as applied to this codebase]

品質基準（提出前に確認してください）

• リファクタリングしたすべてのコンポーネントについて、1文で説明できる責務がちょうど1つある
• 無効な状態を許す props インターフェースがない（競合するブール値や、バリエーションに対する制約のない文字列がない）
• 提出するコードのどこにも、バリエーションに継承を使っていない
• 各共通コンポーネントが、制御コンポーネントか非制御コンポーネントのどちらか一方に明確に定まっており、両方ではない
• インタラクティブなコンポーネントがキーボード操作に対応し、フォーカスを視覚的に示している（既存の対応を削除しない）
• すべての呼び出し元が更新され、インポートが解決し、既存のスタイリングシステムを尊重している
• 新しい共通コンポーネントすべてにドキュメント（目的、props、バリエーション、状態）がある
• 監査表が、変更したファイルだけでなく、調査した範囲全体をカバーしている

厳禁事項：破壊的変更になることを明示せずに、ユーザー向けのコンポーネント API の名前を変更しないでください。副作用として新しい状態管理ライブラリやスタイリングライブラリを導入しないでください。早まって細分化しないでください。まとまりのある40行のコンポーネントを分割する必要はありません。

連携

• skills/frontend-design/design-foundation → コンポーネントが使用するトークン（間隔／色／文字の変数）をこのスキルに提供します。
• skills/frontend-design/interaction-physics ← このスキルが提供するコンポーネントの状態（hover／active／loading）を受け取り、アニメーションを適用します。
• skills/frontend-design/loading-states と skills/frontend-design/error-handling-recovery ← このスキルが提供するコンポーネント一覧を受け取り、loading／error バリエーションを体系的に追加します。
• skills/frontend-design/accessibility-excellence ← 作成したコンポーネントを監査します。修正が必要な箇所を減らせるよう、セマンティックな要素を使ってください。

参考資料

• references/patterns.md — アトムレベルごとの完全なコード例、単一責務のリファクタリング前後の例、制御／非制御の実装、コンポーネントドキュメントのテンプレート、サイズの規約を掲載しています。リファクタリングしたコードやドキュメントを実際に作成する際に読んでください。