frontend-patterns

フロントエンドのパターン

概要

ユーザーインターフェースは、ユーザーがタスクを達成できるよう支援するために存在します。UI に関するあらゆる判断は、ユーザーのタスクを簡単にするか、インターフェースをより利用しやすくするものであるべきです。

基本原則： 美的な好みではなく、ユーザーの成功を基準に設計します。

このスキルは助言を目的としています。明示的なユーザー指示、CLAUDE.md、リポジトリの標準、承認済みの計画は、ここに記載されたすべての提案より優先されます。

参照ファイル

現在の UI タスクに必要な参照ファイルだけを読んでください。

• references/ui-state-and-feedback.md：読み込み／エラー／空／成功状態の順序、スケルトンとスピナーの使い分け、ミューテーションのフィードバック
• references/accessibility-and-forms.md：WCAG を考慮した確認事項、キーボード／フォーカス、ラベル、フォームのパターン、モバイルでの使いやすさ
• references/performance-and-layout.md：レスポンシブの確認、モーション、オーバーフロー、URL の状態、パフォーマンスのガードレール、ライト／ダークモードの確認
• references/design-md-authoring.md：スクリーンショット、既存の UI、ユーザーの好み、選択したインスピレーションスタイルを基に、仕様に準拠したプロジェクトローカルの DESIGN.md を作成または更新する場合
• references/design-md-inspiration-index.md：ユーザーがスタイルの参考例、ブランド風の方向性、ムードボード、または DESIGN.md 形式の例を求めている場合に限り参照

注力分野（参考パターン）

• React コンポーネントのアーキテクチャ（フック、コンテキスト、パフォーマンス）
• Tailwind／CSS-in-JS による レスポンシブ CSS
• 状態管理（Redux、Zustand、Context API）
• フロントエンドのパフォーマンス（遅延読み込み、コード分割、メモ化）
• アクセシビリティ（WCAG への準拠、ARIA ラベル、キーボード操作）

アプローチ（参考パターン）

1. コンポーネントを中心に考える - 再利用可能で、組み合わせ可能な UI 部品
2. モバイルファーストのレスポンシブデザイン - 小さな画面から始め、段階的に拡張する
3. パフォーマンス予算 - 読み込み時間を 3 秒未満にすることを目指す
4. セマンティック HTML と適切な ARIA 属性
5. 該当する場合は TypeScript による 型安全性

助言としてのガードレール

このスキルを使って、次の項目を追加してください。

• アクセシビリティの確認
• レスポンシブ／レイアウトの検証
• パフォーマンスと読み込み状態の確認
• ユーザーが明示的に希望した場合の任意のスタイル案

明示されたビジュアルの方向性、コンポーネントの契約、承認済みのワークフローを覆すために、このスキルを使わないでください。

コンポーネントの成果物チェックリスト

フロントエンドの成果物には、すべて次の項目を含めてください。

• props インターフェースを備えた完全な React コンポーネント
• スタイリング方法（Tailwind クラスまたは styled-components）
• 必要に応じた状態管理の実装
• 基本的なユニットテストの構成
• コンポーネントのアクセシビリティチェックリスト
• パフォーマンスに関する考慮事項と最適化

説明よりも動作するコードを優先してください。コメントに使用例を含めてください。

鉄則

NO UI DESIGN BEFORE USER FLOW IS UNDERSTOOD

ユーザーが達成しようとしていることを把握していなければ、UI は設計できません。

デザイン思考（コーディング前）

UI コードを書く前に、次の問いへの答えを決めてください。

1. 目的：このインターフェースは、どのような具体的な問題を解決しますか？
2. トーン：美的な方向性を選び、方針を固めてください。
   • 徹底的にミニマル、マキシマリスト、レトロフューチャー、オーガニック／ナチュラル
   • 高級感／洗練、遊び心／おもちゃのような雰囲気、エディトリアル／雑誌風、ブルータリスト／無骨
   • アールデコ／幾何学的、ソフト／パステル、インダストリアル／実用本位
3. 制約：フレームワークの要件、パフォーマンス予算、アクセシビリティのレベル
4. 差別化：この UI について、誰かが覚えていることになる要素は何ですか？

重要な洞察： 大胆なマキシマリズムも、洗練されたミニマリズムも、どちらも有効です。問題なのは、決めきれないこととありきたりな初期設定です。

DESIGN.md の作成

仕様に準拠したプロジェクトローカルの DESIGN.md を作成または更新する前に、references/design-md-authoring.md を読んでください。特に、ユーザーがスクリーンショットや既存の UI、ビジュアルの好みを提示した場合や、エージェントにデザインの方向性を維持するよう求めた場合は、必ず参照してください。

インスピレーションが必要な場合は、references/design-md-inspiration-index.md を読んでスタイルの系統を選んでください。インスピレーションはプロジェクト独自のデザイン契約を作るための入力として扱い、他社の UI を模倣する指示として扱わないでください。

モックの再現度に関する棚卸し（見落としによる欠落を防ぐ）

すべてのテストに合格していても、ヒーロー、特徴的なモチーフ、またはデザインで指定されたセクション全体が、ひっそりと省かれていることがあります。UI にも VBC のアンチスタブ原則「見落としによる欠落を防ぐ」を適用しましょう。テストスイートが成功しても、デザインが実装された証明にはなりません。

デザイン／モックの承認後、コーディングを始める前に、目に見える主要な要素を棚卸しし、それぞれの実装方針を決めてください。

要素	例	実装方針
ヒーロー／注目ポイント	見出し＋主要な CTA、特徴的なビジュアル	今すぐ実装／フェーズ 2（明示）／削除（承認済み）
特徴的なモチーフ	粒子感、グラデーション、カスタムカーソル、イラストのスタイル	今すぐ実装／近似表現／削除（承認済み）
セクション	モック内の各独立した帯／領域	今すぐ実装／フェーズ 2（明示）／削除（承認済み）
インタラクション	ホバー、スクロール、モーション、トランジション	今すぐ実装／静的な代替表現／削除（承認済み）
状態	モックに示された空／読み込み中／エラーの各状態	今すぐ実装（状態は省略不可）

すべての要素に、実装方針を必ず 1 つだけ割り当ててください。「削除」と「フェーズ 2」は適切な選択肢ですが、明示的に記載されている場合に限ります。省略によって決定してはなりません。

検証 — VBC のゴールから逆算する視点と組み合わせてください。 ゴールは承認済みデザインであり、差分ではありません。棚卸しした各要素から逆算し、それが実装に含まれている（または明示的に延期／削除されている）ことを確認してください。承認済みモックには存在するのに、実装にはなく、明示的に延期もされていない主要要素の見落としによる欠落は、タスクフローの破損と同等の深刻度を持つP0 の再現度不具合として扱ってください。報告し、テストスイートの合格で覆い隠さないでください。

UI 状態の参照資料

読み込み中、エラー、空、成功、または変更後の状態を確定する前に、references/ui-state-and-feedback.md を読んでください。状態の順序を明示し、場当たり的に UI の状態を作らないでください。

モーションとアニメーション

ルール	実施すること	避けること
モーションの軽減	prefers-reduced-motion に従う	ユーザー設定を無視する
プロパティ	transform／opacity のみをアニメーションする	width／height／top／left をアニメーションする
トランジション	プロパティを明示的に列挙する	transition: all を使う
時間	マイクロインタラクションは 150～300ms	速すぎる（<100ms）、または遅すぎる（>500ms）
中断可能性	アニメーションをキャンセルできるようにする	アニメーション中に UI をロックする

/* CORRECT: Compositor-friendly, respects preferences */
@media (prefers-reduced-motion: no-preference) {
  .card { transition: transform 200ms ease-out, opacity 200ms ease-out; }
  .card:hover { transform: translateY(-2px); opacity: 0.95; }
}

アクセシビリティとフォーム

タスクがキーボードナビゲーション、フォーム、ラベル、フォーカス、コントラスト、またはタッチ操作の使いやすさに関係する場合は、references/accessibility-and-forms.md を読んでください。

成功基準のフレームワーク

すべての UI に明示的な成功基準を設けてください。

1. タスクの完了：ユーザーは目的を達成できますか？
2. エラーからの回復：ユーザーはミスから回復できますか？
3. アクセシビリティ：すべてのユーザーが利用できますか？
4. パフォーマンス：応答性がよく感じられますか？

レイアウトとパフォーマンスの参照資料

レスポンシブの確認、モーションのルール、オーバーフロー処理、URL の状態、タッチ／モバイル、カラーモードの検証については、references/performance-and-layout.md を読んでください。

共通の質問（最初に回答する）

設計／レビューの前に、必ず回答してください。

1. ユーザーは何を達成しようとしていますか？ — 機能ではなく、具体的なタスク
2. 手順は何ですか？ — クリックごとに
3. 何が問題になる可能性がありますか？ — 考えられるすべてのエラー状態
4. どのようなユーザーが困る可能性がありますか？ — アクセシビリティのニーズ
5. 既存のパターンは何ですか？ — プロジェクトの規約

まずユーザーフローを確認する

UI に関する作業を始める前に、フローを整理してください。

User Flow: Create Account
1. User lands on signup page
2. User enters email
3. User enters password
4. User confirms password
5. System validates inputs (inline)
6. User clicks submit
7. System processes (loading state)
8. Success: User sees confirmation + redirect
9. Error: User sees error + can retry

各手順について、次の点を確認してください。

• ユーザーに何が表示されるか
• ユーザーが何をするか
• どのようなフィードバックが得られるか
• 何が問題になる可能性があるか

UX レビューチェックリスト

チェック項目	基準	問題の例
タスクの完了	ユーザーは目的を達成できますか？	ボタンが機能しない
見つけやすさ	ユーザーは必要なものを見つけられますか？	ナビゲーションが隠れている
フィードバック	ユーザーは何が起きているか把握できますか？	読み込み状態が表示されない
エラー処理	ユーザーはエラーから復旧できますか？	エラーメッセージが表示されない
効率性	ユーザーはタスクをすばやく完了できますか？	手順が多すぎる

重大度レベル：

• BLOCKS：ユーザーがタスクを完了できません
• IMPAIRS：ユーザーはタスクを完了できますが、困難を伴います
• MINOR：小さな不便はありますが、タスクを妨げるものではありません

ビジュアルデザインチェックリスト

チェック項目	良い例	悪い例
階層	視覚的な優先順位が明確	すべてが同じ大きさ
余白	一貫したリズム	余白が不規則
整列	要素がグリッドに沿って整列	要素がずれている
インタラクティブ状態	ホバー／アクティブ／フォーカス状態が明確	状態が変化しない
フィードバック	操作への反応が明確	操作しても反応がない

ビジュアルの創造性（AI っぽい凡庸なデザインを避ける）

フロントエンドを作成するときは、ありきたりな AI 風の見た目を避けてください。

• フォント：デフォルトではなく、個性のあるタイポグラフィを選びます（Inter、Roboto、Arial、システムフォントは避けてください）
• 色：一貫性のある配色を選びます。無難なグラデーションより、支配的な色と鮮やかなアクセントを使います
• 避けるもの：白地に紫のグラデーション、予測しやすいレイアウト、型どおりの Bootstrap／Tailwind のデフォルト
• アイコン：SVG アイコン（Heroicons、Lucide、Simple Icons）を使います。UI アイコンとして絵文字を使わないでください
• カーソル：クリック可能な要素すべてに cursor-pointer を追加します
• ホバー：色や不透明度のトランジションを使います。レイアウトをずらす scale 変換は避けます
• 背景：単色ではなく、控えめなテクスチャ、グラデーション、粒子感で奥行きを加えます

その場に合わせてデザインされたと感じられる、創造的な選択をしてください。どのデザインも同じ見た目にならないようにしてください。

二段階の反射チェック

ありきたりなのは、明白なデフォルトだけではありません。デフォルトから予測可能な形で距離を取ることも、ありきたりです。ビジュアルの方向性を決定する前に、両方のテストを実施してください。

• 第一段階のテスト： カテゴリだけからテーマや配色を予測できますか？（「フィンテック → 青＋サンセリフ体」「AI ツール → 紫のグラデーション＋ダークモード」）予測できるなら、ありきたりです。却下してください。
• 第二段階のテスト： カテゴリと避けるべき例から予測できますか？ 誰もが「紫のグラデーションを避ける」ようになると、避けること自体が反射的な選択になります。青を避けるフィンテックは同じオフブラック＋ライムに落ち着き、紫を避ける AI ツールはどれも同じ温かみのあるベージュ＋セリフ体に落ち着きます。人々が今避けようとしているものを前提に選択を予測できるなら、それもありきたりです。却下してください。

第二のテストでは、回避の反射 #1 から、反射 #2 へまっすぐ向かうことを見抜けます。どちらにも有効な解決策は同じです。カテゴリや、そのカテゴリが現在避けているものではなく、個別の製品、対象ユーザー、コンテンツに基づいて方向性を導き出してください。

反射的に却下するリスト（傾向が飽和するたびに見直し・整理）：

反射的に却下するフォント	反射的に却下するデザイン傾向
Inter、Roboto、Arial、system-ui のデフォルト	白地に紫／バイオレットのグラデーション（AI ツールの反射 #1）
Geist／Geist Mono（今では過剰に飽和）	オフブラック＋酸性ライムの「反企業的」デザイン（反射 #2）
「モダン」な選択肢としての Space Grotesk	温かみのあるベージュ＋セリフ体の「反 AI」編集デザイン（反射 #2）
毎月のように登場する Google Fonts のありきたりな組み合わせ	グラデーションメッシュ上のグラスモーフィズムカード

あるデザイン傾向が本当に反射的な選択ではなくなったら、このリストから削除し、飽和してきた新しい傾向を追加してください。このリストは意図的に変化し続けるものです。古くなったブロックリストは、それ自体が反射的な選択になります。

空間構成（グリッドを崩す）

無難な中央揃えのレイアウトから脱却します。

テクニック	効果	使用する場面
非対称	動的な緊張感、視覚的な関心	ヒーローセクション、機能の強調
重なり	奥行き、要素間のつながり	カード、画像、推薦文
斜めの流れ	活気、動き	ランディングページ、マーケティング
グリッドを崩す	強調、驚き	主要な CTA、注目ポイント
ゆとりのあるネガティブスペース	高級感、ゆとり	プレミアム製品、エディトリアル
密度の調整	情報量の多さ、生産性	ダッシュボード、データ量の多い UI

ルール： 空間構成は、デザイン思考で選んだ美的方向性に合わせます。ミニマリストならネガティブスペース、マキシマリストなら密度を調整します。

デザインシステムの逸脱分類

機能がデザインシステムから逸脱しているとき、「少し違和感がある」だけでは対応可能な指摘になりません。それぞれの逸脱について、根本原因を分類してください。その分類によって修正方法が決まります。

根本原因	意味	修正方法
トークンの不足	システムにそのニーズに合う値（色合い、余白の段階、角丸）がありません	値を補います。システムにトークンを追加してから使用します
独自実装	トークンやコンポーネントは存在するのに、この機能でローカルに再実装しています	共通コンポーネント／トークンに置き換え、独自実装を削除します
概念上の不整合	機能のインタラクションモデルがシステムと相反しています	フローを見直します。ピクセル単位の修正では解決しません

フロー形状の一致。 トークンだけでなく、機能のフロー形状も隣接する機能と一致している必要があります。すべてのピクセルがシステムに沿っていても、フロー形状に一貫性がないと不具合のように見えます。

• モーダルか全ページか — 同種のエディターがモーダルで開くなら、全ページのルートを追加しないでください（逆の場合も同様です）。
• フォーカス喪失時に保存するか、明示的に送信するか — 隣接するフォームが自動保存するなら、送信ボタンだけのフォームはスタイル上の小さな問題ではなく、概念上の不整合です。

機能のフロー形状を隣接する機能と一致させるか、異なる形状にする明確な理由について承認を得てください。説明のないフロー形状の不一致は、軽微な問題ではなく概念上の不整合による逸脱として扱います。

コンポーネントのパターン

ボタン

// Primary action button with all states
<button
  type="button"
  onClick={handleAction}
  disabled={isLoading || isDisabled}
  aria-busy={isLoading}
  aria-disabled={isDisabled}
  className={cn(
    'btn-primary',
    isLoading && 'btn-loading'
  )}
>
  {isLoading ? (
    <>
      <Spinner aria-hidden />
      <span>Processing...</span>
    </>
  ) : (
    'Submit'
  )}
</button>

バリデーション付きフォーム

<form onSubmit={handleSubmit} noValidate>
  <div className="form-field">
    <label htmlFor="email">
      Email <span aria-hidden>*</span>
      <span className="sr-only">(required)</span>
    </label>
    <input
      id="email"
      type="email"
      value={email}
      onChange={handleChange}
      aria-invalid={errors.email ? 'true' : undefined}
      aria-describedby={errors.email ? 'email-error' : 'email-hint'}
      required
    />
    <span id="email-hint" className="hint">
      We'll never share your email
    </span>
    {errors.email && (
      <span id="email-error" role="alert" className="error">
        {errors.email}
      </span>
    )}
  </div>
</form>

読み込み状態

function DataList({ isLoading, data, error }) {
  if (isLoading) {
    return (
      <div aria-live="polite" aria-busy="true">
        <Spinner />
        <span>Loading items...</span>
      </div>
    );
  }

  if (error) {
    return (
      <div role="alert" className="error-state">
        <p>Failed to load items: {error.message}</p>
        <button onClick={retry}>Try again</button>
      </div>
    );
  }

  if (!data?.length) {
    return (
      <div className="empty-state">
        <p>No items found</p>
        <button onClick={createNew}>Create your first item</button>
      </div>
    );
  }

  return <ul>{data.map(item => <Item key={item.id} {...item} />)}</ul>;
}

エラーメッセージ

// Inline error with recovery action
<div role="alert" className="error-banner">
  <Icon name="error" aria-hidden />
  <div>
    <p className="error-title">Upload failed</p>
    <p className="error-detail">File too large. Maximum size is 10MB.</p>
  </div>
  <button onClick={selectFile}>Choose different file</button>
</div>

注意すべき兆候 — 作業を止めて再検討してください

次のような状況に気づいたら：

• ユーザーフローを整理する前に UI を設計している
• 機能性より先に見た目を重視している
• アクセシビリティを無視している（「後で対応する」）
• エラー状態に対処していない
• 読み込み中のフィードバックを提供していない
• 情報を伝えるために色だけを使っている
• 「見た目がよい」という理由で判断している

作業を止めて、ユーザーフローに立ち返ってください。

自己正当化の防止

言い訳	実際のところ
「キーボードを使うユーザーはほとんどいない」	キーボードだけを使うユーザーもいます。
「アクセシビリティは後で追加します」	後から対応するのは 10 倍難しくなります。
「エラー状態は例外的な状況です」	エラーは起こります。対処してください。
「読み込みが速いから、状態表示は不要です」	ネットワークの速度は変わります。状態を表示してください。
「ラベルがないほうが見た目がよいです」	ラベルのない入力欄はアクセシビリティに配慮されていません。
「ユーザーが自分で理解できます」	分かりにくいなら、改善してください。

アンチパターンのブロックリスト（要注意）

アンチパターン	問題点	修正方法
user-scalable=no	アクセシビリティのためのズームを妨げます	削除します
maximum-scale=1	アクセシビリティのためのズームを妨げます	削除します
transition: all	パフォーマンスの低下や予期しない影響を招きます	プロパティを明示的に列挙します
置き換えを行わない outline-none	フォーカスインジケーターが表示されなくなります	focus-visible:ring-* を追加します
<div onClick>	キーボードで操作できません	<button> または <a> を使用します
width／height のない画像	レイアウトシフト（CLS）の原因になります	寸法を明示的に指定します
ラベルのないフォーム入力	アクセシビリティに対応できません	<label> または aria-label を追加します
aria-label のないアイコンボタン	スクリーンリーダーで名前が読み上げられません	aria-label を追加します
絵文字アイコン（🚀 ✨ 💫）	プロフェッショナルさに欠け、一貫性がありません	SVG アイコンを使用します
ハードコードされた日付／数値形式	国際化に対応できません	Intl.DateTimeFormat を使用します
あらゆる場所での autoFocus	混乱を招き、モバイルで問題が発生します	デスクトップでのみ、控えめに使用します

出力形式

## Frontend Review: [Component/Feature]

### User Flow
[Step-by-step what user is trying to do]

### Success Criteria
- [ ] User can complete [task]
- [ ] User can recover from errors
- [ ] All users can access (keyboard, screen reader)
- [ ] Interface feels responsive

### UX Issues
| Severity | Issue | Location | Impact | Fix |
|----------|-------|----------|--------|-----|
| BLOCKS | [Issue] | `file:line` | [Impact] | [Fix] |

### Accessibility Issues
| WCAG | Issue | Location | Fix |
|------|-------|----------|-----|
| 1.4.3 | [Issue] | `file:line` | [Fix] |

### Visual Issues
| Issue | Location | Fix |
|-------|----------|-----|
| [Issue] | `file:line` | [Fix] |

### Recommendations
1. [Most critical fix]
2. [Second fix]

UI 状態チェックリスト（重要）

UI コンポーネントを完成させる前に、必ず確認してください。

状態

• エラー状態を処理し、ユーザーに表示する
• データが存在しない場合にのみ、読み込み状態を表示する
• すべてのコレクション／リストに空の状態を用意する
• 適切なフィードバックを伴う成功状態を用意する
• 複雑な状態の順序やスケルトン／スピナーの選択は、references/ui-state-and-feedback.md に照らして確認する

ボタンとミューテーション

• 非同期処理中はボタンを無効にする
• ボタンに読み込みインジケーターを表示する
• ミューテーションに、ユーザーへのフィードバックを伴う onError ハンドラーを設定する
• 送信ボタンをダブルクリックできないようにする

データ処理

• 状態の順序：エラー → 読み込み（データなし） → 空 → 成功
• すべてのユーザー操作にフィードバック（トースト／視覚的表示）を用意する

最終チェック

フロントエンド作業を完了する前に、次の項目を確認してください。

• ユーザーフローを整理し、理解している
• すべての状態（読み込み、エラー、空、成功）を処理している
• キーボード操作が機能する
• スクリーンリーダーでテストしている
• 色のコントラストを確認している（最小 4.5:1）
• モバイルでタッチターゲットが十分な大きさになっている（44px 以上）
• エラーメッセージが明確で、対処方法がわかる
• 成功条件を満たしている
• 絵文字アイコンを使用していない（SVG のみ）
• prefers-reduced-motion に対応している
• ライトモード／ダークモードのコントラストを確認している
• クリック可能なすべての要素に cursor-pointer を設定している
• コードベースに transition: all がない