frontend-design

フロントエンドデザイン

ありきたりなテンプレートではなく、明確な個性を持つ、記憶に残る実用的なインターフェースを作ります。デザインの方向性をひとつに定め、トークンを定義し、アクセシブルでレスポンシブな UI を実装し、変更範囲を絞ります。

推奨する対象（最適なものを選択）

1. Next.js（TypeScript）：本番アプリのルートやマーケティング用ルート、デザインシステムの作業に適しています。
2. React（TypeScript）：Next.js 以外の SPA やコンポーネントライブラリに適しています。
3. Vanilla HTML/CSS/JS：静的なデモ、プロトタイプ、単独で埋め込むコンテンツに最適です。

クイックスタート（最初に行うこと）

1. 最大 4 つの質問をします。
   • 誰が何をするためのものですか（変更後、何が「簡単」だと感じられるべきですか）？
   • どこに配置しますか（コンポーネント／ルート）？使用する技術スタックは何ですか？Next.js／React を推奨しますが、単独のページやプロトタイプには Vanilla も適しています。
   • Next.js の場合：App Router（app/）を前提とします。サーバー／クライアントに関する制約はありますか？
   • 絶対に守るべき制約はありますか（ブランドトークン、ライト／ダーク、モーションの制限、維持必須の UI 要素、パフォーマンス予算など）？
2. デザインの方向性とひとつのシグネチャー要素を選びます。指示が曖昧な場合は、references/aesthetic-playbook.md から 2～3 個の選択肢を提案します。
3. トークンを定義します（タイポグラフィ、カラーパレット、スペーシング、角丸、シャドウ、モーション）。アクセントは 1～2 色に抑えます。
4. まず構造（セマンティックなマークアップとレイアウト）を作り、次にモーションを加え、最後に仕上げと QA を行います。

ガードレール（よくある落とし穴を避ける）

• 対象範囲を絞り、ユーザーが依頼したものだけを再設計します。
• 既存のリポジトリで作業する場合は、既存のトークンやコンポーネントを再利用します。依頼がない限り、新しいグローバルスタイリングシステムは導入しません。
• ビジョンに合わせて複雑さを調整します。洗練されたミニマリズムには抑制が必要です。マキシマリズムには、無作為な装飾ではなく、意図的な構造が必要です。
• すべてのアニメーションで prefers-reduced-motion を尊重します。
• 「AI スロップ」のような既定のデザインは避けます。リポジトリですでに汎用フォントが使われている場合、ユーザーが新しいタイポグラフィを明示的に希望しない限り、そのフォントを維持します。
• トークンの意味を守ります。エラー／成功／警告の色は装飾ではなく意味を伝えるために使い、ライト／ダークの両方でアクセシブルなコントラストを維持します。
• 保守しやすいコードを基本とします。小さなコンポーネント、明確な階層、最小限の依存関係を心がけます。
• ユーザーが明示的に希望した場合、またはリポジトリですでに使われている場合を除き、新しいパッケージ（アニメーションライブラリ、UI キット、アイコンセットなど）は追加しません。
• 1 つのビューにつき、主な CTA は 1 つを基本とします。アクションが競合しないよう、ほかのアクションはセカンダリ／ターシャリに格下げします。

ワークフロー

1) 方向性をひとつに定める

• デザインの方向性、パレットの雰囲気、フォントの組み合わせ、シグネチャー要素を明示します。
• 階層と雰囲気を説明する、1～2 文のデザイン方針を書きます。
• 予測可能なレイアウトや使い古されたカラーパレットを避けるため、references/anti-patterns.md を参照します。

1b) デザインシステムのルール（厳守／柔軟）

• 厳守：セマンティックカラーの意味、読みやすい文字サイズの段階、モーションの軽減、視認できるフォーカス、AI アクションにおける「人が制御できること」（取り消し／適用／確認）。
• 柔軟：ブランドアクセントの色相、ダークモードにおけるサーフェスの「温度感」、密度プリセット（コンパクト／ゆったり）。
• 詳しく調べるタイミング：トークンの定義時には references/tokens-and-semantics.md を、AI 関連の UI の追加時には references/ai-native-ui-patterns.md を読み込みます。

1a) React／Next.js のコーディング指針（実装時に読む）

• React の基本：コンポーネントは純粋に保ち、ユーザー操作に起因する処理では Effect よりイベントハンドラーを優先し、Rules of Hooks に従います。
• Next.js App Router：Client Component は小さく保ち、デフォルトでは Server Component を使います。状態、エフェクト、ブラウザー API が必要な箇所に限り、"use client" を指定します。
• データ取得：サーバー側の fetch と明示的なキャッシュ／再検証の制御を優先し、データ取得のために不要なクライアント側エフェクトを避けます。
• 詳しく調べるタイミング：複雑な React ロジックを書く前、または新しいデータ取得パターンを導入する前に、references/react-next-best-practices.md を読み込みます。

2) トークンとレイアウトを計画する（詳細に入る前に）

• 以下を定義します。CSS 変数（またはテーマオブジェクト）を使用します。
  • 色：背景／サーフェス／文字色／控えめな色／アクセント（＋任意で第2アクセント）
  • 文字：ディスプレイ／本文／等幅、サイズスケール、行の高さ
  • 形状：角丸スケールと境界線のルール
  • 奥行き：影とアウトラインのルール
  • モーション：再生時間＋イージング＋表示時の段階的な遅延
• ページ／コンポーネントの骨組みとコンテンツ階層を設計します。
• パターンと QA については、references/implementation-patterns.md を参照してください。

3) 実装する（ムードボードではなく、コードを仕上げる）

• セマンティックな構造と、アクセシブルなインタラクション（キーボード操作＋フォーカス状態）から始めます。
• 大きなレイアウトには Grid、細かなレイアウトには Flexbox を使います。
• Next.js／React では、コンポーネントを小さく組み合わせ可能に保ちます。CSS Modules またはリポジトリですでに採用されているスタイル方式を優先します。
• セマンティクスとキーボード操作を適切に保つため、「ナビゲーションにはリンク、アクションにはボタン」を使います。
• 特徴的な演出は、控えめながら効果的に適用します（印象に残るものを1つ、10個ではなく）。
• モーションは、ランダムな装飾ではなく、演出として追加します（強いページ読み込みアニメーションを1つと、いくつかのマイクロインタラクション）。

3a) Next.js の実装メモ（該当する場合）

• App Router のみ：pages/ ではなく app/ ルーティングを前提にします。
• サーバーとクライアント：デフォルトでは Server Components を使用し、インタラクティブな領域にのみ "use client" を追加します。
• データと状態：可能な限りサーバー側でデータを取得し、クライアントの状態はローカルかつ目的を持ったものに保ちます。
• パフォーマンス：レイアウトシフトを避けます（高さを安定させ、予測可能なグリッドを使います）。モバイルでは、ぼかしや影が描画に与える負荷を抑えます。
• プラットフォームのプリミティブ：利用可能な場合は、ナビゲーションには next/link、実画像には next/image を優先します。
• フォント：Next.js でタイポグラフィを変更する場合は、FOIT／FOUT を避けるため next/font を優先します。
• スタイル：一貫性を保ちます。CSS Modules、Tailwind、または既存のシステムを使用し、確認せずに新しい方式を導入しないでください。

3b) コンテンツと状態（中身のない枠だけを出荷しない）

• データ駆動型 UI には、読み込み中、空、エラーの各状態を定義します。
• 文章は簡潔で目的に沿ったものにし、依頼がない限りプレースホルダーの Lorem Ipsum は避けます。
• ユーザーから文言の変更を依頼されない限り、既存の製品用語を維持します。

4) 仕上げと QA

• レスポンシブ対応を確認します。グリッドを折りたたみ、パディングを維持し、モバイルでも CTA の目立ちやすさを保ちます。
• アクセシビリティを確認します。ランドマーク、h1 を1つにすること、ラベル、コントラスト、フォーカス順、必要に応じたスキップリンクを確認します。
• パフォーマンスを確認します。モバイルで負荷の大きい影を避け、アニメーションの描画負荷を抑え、大きな画像を避けます。

完了の定義

• モバイルとデスクトップのブレークポイントで、意図的なレイアウトに見えること（文字が窮屈でなく、CTA が孤立していないこと）。
• フォーカス状態が視認でき、タブ順序が論理的で、モーションが prefers-reduced-motion に従うこと。
• トークンが一元管理され（CSS 変数／テーマ）、特徴的な演出が含まれつつも、過剰に使われていないこと。

成果物（結果の提示方法）

• 変更したファイルと、それぞれの役割を列挙します。
• 美的な方向性と特徴的な演出を1～2文で説明します。
• 検証用のコマンドを提示します（リポジトリの慣例に従い、一般的なものには npm run dev、npm run lint、npm test などがあります）。

同梱リソース

• references/aesthetic-playbook.md：方向性、タイポグラフィと色のヒント、特徴的な演出。
• references/implementation-patterns.md：vanilla + React 向けのレイアウト／モーション／アクセシビリティのパターン。
• references/anti-patterns.md：ありきたりな出力を避けるための「やってはいけないこと」チェックリスト。
• references/react-next-best-practices.md：React + Next.js のコーディングガイドライン（フック、エフェクト、サーバー／クライアント、データ取得）。
• references/tokens-and-semantics.md：トークンのセマンティクス、文字サイズの段階、ダークモード、密度のルール（厳密／柔軟）。
• references/ai-native-ui-patterns.md：コパイロットパネル、引用、開示、人間が関与する UI パターン。
• assets/vanilla-starter/：CSS 変数でテーマを変更してコピーできる、実行可能な vanilla スターター。
• assets/react-component-starter/：テーマを変更できる、小規模な React コンポーネント＋CSS モジュールの骨組み。
• assets/nextjs-app-router-starter/：コピーしてテーマを変更できる、最小限の Next.js App Router ページ＋トークン。