frontend-component-build

フロントエンドコンポーネントの構築

本番環境に対応できるコンポーネントを構築します。スタックに依存しない原則です。ほとんどのパターンは React、Vue、Svelte、またはバニラの Web コンポーネントに応用できます。

このスキルでは、コンポーネントを適切に実装する方法を扱います。より広範なシステム設計については design-system を参照してください。日々のビジュアル面の判断については design-standards を参照してください。

---

使用する場合

• コンポーネントをゼロから新しく構築するとき
• 既存のコンポーネントをリファクタリングするとき
• コンポーネント API（props、slots、events）を設計するとき
• 既存のコンポーネントにアクセシビリティを追加するとき
• デザインをもとにコンポーネントを実装するとき

使用しない場合

• デザインシステム全体を構築するとき（design-system を使用）
• ページレベルのデザインを決めるとき（design-standards を使用）
• バックエンドやデータを扱うとき（code-review-web を使用）
• パフォーマンスのみを最適化するとき（performance-optimization を使用）

---

必要な入力

• コンポーネントの目的（どのような UI ニーズに応えるか）
• デザイン（またはデザインする意思）
• フレームワークまたは技術的なコンテキスト
• コンポーネントがサポートする必要のある状態
• アクセシビリティ要件

---

フレームワーク：6 つの側面

完全なコンポーネントは、6 つの側面に対応します。どれか 1 つでも省略すると、コンポーネントは不完全です。

1. 構成要素

マークアップを書く前に、コンポーネントを構成するパーツを特定します。

一般的な構成：

• ボタン：コンテナ + ラベル + （任意の）アイコン + （任意の）ローディングインジケーター
• モーダル：背景オーバーレイ + コンテナ + ヘッダー + 本文 + フッター + 閉じるための操作部
• フォーム入力：ラベル + 入力欄 + （任意の）ヘルプテキスト + （任意の）エラーメッセージ
• カード：コンテナ + （任意の）ヘッダー + 本文 + （任意の）フッター + （任意の）メディア

パーツにあらかじめ名前を付けておくと、API が明確になります。

2. バリエーション

コンポーネントはどのようなバリエーションに対応しますか？

• ビジュアルバリエーション（プライマリー、セカンダリー、ゴースト、危険）
• サイズバリエーション（小、中、大）
• 機能バリエーション（アイコンあり、アイコンなし、アイコンのみ）

バリエーションは自由に増やせるものではなく、管理されたセットにします。サポートするセットを文書化し、実際のユースケースがない新しいバリエーションの要求は受け付けないようにします。

3. 状態

コンポーネントはどの状態に対応する必要がありますか？

• デフォルト
• ホバー（ポインターに対応している場合）
• フォーカス（常に必要です。キーボード操作には欠かせません）
• アクティブ／押下中
• 無効
• 読み込み中（該当する場合）
• エラー（入力欄、フォーム、検証に関連するコンポーネントの場合）
• 空（データを表示するコンポーネントの場合）

すべての状態に、ビジュアル面とアクセシビリティ面の両方で対応する必要があります。

4. Props／API

コンポーネントの契約を設計します。

API 設計の原則：

• 必須 props は最小限にします。 毎回本当に必要なものだけを必須にします。それ以外は、適切なデフォルト値を設定します。
• ブール値の props は要注意です。 ブール値が 3 つあると、7 通りの組み合わせが生まれます。primary={true} ghost={false} よりも、variant: "primary" | "secondary" | "ghost" のような列挙型の文字列を優先します。
• props より children を優先します。 コンテンツには children を受け付けます。slots が使えるのに、headerText や bodyText の props を作らないでください。
• 設定より合成を優先します。 12 個の props で 5 つの役割を果たすコンポーネントは、多くの場合、5 つの小さなコンポーネントに分けるべきです。
• props に型を付けます。 TypeScript、PropTypes、または JSDoc を使います。型は、古くならないドキュメントです。

5. アクセシビリティ

最初からアクセシビリティを確保して構築します。後から追加するのは5倍難しくなります。

共通：

• 汎用的な<div>より、意味を持つHTML要素（<button>、<a>、<nav>、<form>など）を使用する
• キーボードで操作できる（ボタンはTab、Shift+Tab、Enter／Spaceで操作）
• フォーカスを視認できる
• タップ対象の最小サイズは44×44ピクセル
• 意味を持つHTMLだけでは不十分な場合に限り、ARIAを使用する

コンポーネント別：

• ボタン： <button>を使用します。<div>でボタンを模倣しないでください。
• モーダル： フォーカスをモーダル内に閉じ込め、ESCキーで閉じられるようにし、閉じた後は起動元にフォーカスを戻します。role="dialog"とaria-labelledbyを設定します。
• フォーム入力： for／idまたはaria-labelledbyでラベルを関連付けます。aria-describedbyでエラーメッセージを関連付けます。エラー状態ではaria-invalidを設定します。
• 切り替え： 2状態の場合はaria-pressedを設定した<button>を、オン／オフの場合はrole="switch"を使用します。
• ツールチップとポップオーバー： フォーカス時とホバー時の両方で表示します。ESCキーで閉じられるようにします。
• 読み込み状態： aria-liveで通知し、スクリーンリーダーに状態の変化を伝えます。

6. テスト

コンポーネントの完成を宣言する前に、正しく動作することを確認します。

優先度順のテストの種類：

1. ビジュアルリグレッション。 バリエーションや状態ごとに正しくレンダリングされること。（Storybookとビジュアル差分ツール、または手動のスクリーンショット。）
2. アクセシビリティ。 axeまたは同等の自動チェックに合格すること。
3. キーボード操作。 Tab、Enter、Escape、矢印キーがすべて想定どおりに動作すること。
4. コンポーネントのロジック。 Propsが期待どおりの出力を生成すること。イベントが正しく発火すること。（ユニットテスト。）
5. 統合。 想定される親コンテキスト内でコンポーネントが動作すること。

少なくとも自動アクセシビリティテストを行っていないコンポーネントは、完成とは言えません。

---

ワークフロー

1. ユースケースを理解する。 このコンポーネントはどのようなUIのニーズに応えるものですか？どこに表示されますか？隣接するコンポーネントは何ですか？
2. 構造をスケッチする。 各パーツに名前を付けます。
3. バリエーションと状態を列挙する。 デザインシステムに合わせるか、必要であれば新たに定義します。
4. APIを設計する。 必須Props、オプションProps、子要素、イベントを決め、型を定義します。
5. 意味を持つHTMLでマークアップを作成する。 適切な要素を選びます。インタラクティブな要素に汎用的な<div>を使わないでください。
6. トークンを使ってスタイルを設定する。 色、余白、サイズをハードコードしないでください。
7. インタラクションを追加する。 フォーカス管理、キーボードハンドラー、ARIAを設定します。
8. 状態を追加する。 ホバー、フォーカス、アクティブ、無効、読み込み中、エラー。
9. テストする。 自動アクセシビリティテスト、キーボード操作、ビジュアルリグレッションを確認します。
10. ドキュメントを作成する。 使用方法、API、例、アンチパターンを記載します。

---

よくある失敗パターン

• <div onClick>で構築する。 キーボード操作のアクセシビリティ、スクリーンリーダー向けのセマンティクス、フォーカスが失われます。<button>または<a>を使用してください。
• 色やサイズをハードコードする。 トークンには存在する理由があります。ハードコードした値では、テーマ設定や一貫性の維持が困難になります。
• ブール型Propsを増やしすぎる。 <Button primary large rounded fullWidth disabled icon />。ブール値が多すぎる場合は、バリエーションを絞り、より慎重に設計する必要があります。
• フォーカス状態を忘れる。 ホバーには注意が向きますが、フォーカスは見過ごされがちです。キーボードユーザーにはボタンが見えません。
• 無効状態について考慮しない。 無効なボタンは、見た目でも明らかに無効である必要があります。さらにaria-disabledを設定し、クリックに反応しないようにします。
• ARIAを独自に作る。 ARIAのロールとプロパティには、それぞれ決められた動作があります。独自のARIAは、ARIAを使わないよりも悪影響を及ぼします。まず意味を持つHTMLを使用してください。
• 読み込み状態を通知しない。 スクリーンリーダーにはスピナーが表示されたことが伝わりません。aria-live="polite"またはrole="status"を使用してください。
• 重要な情報をツールチップだけに載せる。 ホバー時だけ表示されるコンテンツは、キーボードユーザーやタッチユーザーには見えません。重要な情報は見えるUIに配置してください。
• ドキュメントのないコンポーネント。 使い方がわからなければ、将来の自分も、チームメイトも、次のメンテナーも利用できません。

---

出力形式

コンポーネントを完全な形で納品するには、以下が含まれます。

• コンポーネントコード（適切なフレームワークを使用）
• Storybook（または同等のもの）のエントリー（すべてのバリエーションと状態を表示）
• ドキュメント：
  • 構成図または説明
  • Props/API テーブル
  • 使用例（基本、応用、エッジケース）
  • 使用する場合と代替手段を使用する場合
  • アンチパターン（避けるべきこと）
  • アクセシビリティに関する注意事項
• テスト（ビジュアルリグレッション、アクセシビリティ、ロジック）

---

参考ファイル

• references/component-spec-template.md - 作成前にコンポーネントを文書化するためのテンプレート（props、状態、アクセシビリティ、エッジケース）。
• references/component-api-patterns.md - 柔軟なコンポーネント API を設計するための一般的なパターン（複合コンポーネント、制御あり／なし、ポリモーフィックな as prop、render props、スロット）。
• references/accessibility-patterns.md - 一般的なインタラクティブコンポーネントの ARIA パターン。