frontend-patterns

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

フロントエンド開発全般に適用できるベストプラクティスです。以下のパターンをすべて読んでください。これから実装する内容に当てはまるものがあれば、適用してください。 ここにルールとして明記されていることについて、許可を求めないでください。ルールに従い、その旨を1行で伝えてください。

このスキルを参照するタイミング

次のいずれかを行うときはいつでも参照してください。

• TSX/JSX を記述または編集するとき
• 保存／作成／送信を行うボタンを追加するとき
• フォームを追加するとき
• ダイアログ、モーダル、ポップオーバー、またはシートを追加するとき
• キーボードショートカットを設定するとき
• UI の変更をレビューするとき

以下のパターンのどれにも当てはまらない場合は、何も言わずに元のタスクに戻ってください。

パターン

• デスクトップでは、Cmd+Enter は保存、作成、送信、確定、その他の主要なアクションのいずれの場合も、常に「送信」として機能するようにします。Cmd+Enter は、主要ボタンを手動でクリックした場合とまったく同じ動作にしてください（無効化／読み込み中／バリデーションの動作や、副作用も同じです）。Windows/Linux では Ctrl+Enter を使用します（e.metaKey || e.ctrlKey）。
• ダイアログが必要な場合は、代わりに ResponsiveDialog を使用します。デスクトップではダイアログ、モバイルではドロワーが表示されます。モバイルでダイアログを使うのはあまり使い勝手がよくないため、こちらのほうがモバイルの UX に適しています。このコンポーネントが存在しない場合は、shadcn の Dialog と Drawer コンポーネントを使用して作成します（shadcn の Dialog API を踏襲し、そのまま置き換えて使えるようにします — Content、Header、Title、Description、Footer、Trigger、Close）。
• ダイアログ／モーダル／ドロワー／シートを閉じるときに、未保存の編集内容が失われないようにします。 編集可能なフィールドを含むダイアログ（または同様に閉じられるコンテナ）に未保存の変更がある状態でユーザーが閉じようとした場合、自動保存がない、保存／送信ボタンがクリックされていない、または変更がまだ保存されていない場合は、閉じる操作を中断して、先に確認を求めます（例：「未保存の変更があります。このまま閉じますか？作業内容は失われます。」）。ユーザーが確認した場合にのみ閉じます。これは、すべての閉じる操作に適用します。X／閉じるボタン、背景／オーバーレイのクリック、Escape キー、モバイルドロワーのスワイプによる終了が対象です。フォームが変更されているかどうかを追跡し（現在の値と初期値を比較するか、フォームライブラリの変更フラグを使います）、変更がない場合は確認を省略して、一般的なケースで手間がかからないようにします。
• Markdown コンテンツ（チャットメッセージ、LLM の出力、コメント、メモなど、Markdown を含む可能性があるユーザー／AI 作成のテキスト）をレンダリングするときは、文字列を {text} や whitespace-pre-wrap を使って単に <div> や <p> に出力しないでください。 本格的な Markdown レンダラーを使用します。デフォルトでは remark-gfm（表、取り消し線、タスクリスト、自動リンク対応）と remark-breaks（単一の \n を <br> に変換します。これがないと単一の改行が折りたたまれ、出力が読みづらい長文の塊になります。これはエージェントが繰り返し実装してしまう問題です）を組み合わせた react-markdown を使用します。コードブロックには rehype-highlight または react-syntax-highlighter を追加します。インストール方法：npm i react-markdown remark-gfm remark-breaks。最小限の使用例：

  import ReactMarkdown from 'react-markdown';
  import remarkGfm from 'remark-gfm';
  import remarkBreaks from 'remark-breaks';
  
  <ReactMarkdown remarkPlugins={[remarkGfm, remarkBreaks]}>{text}</ReactMarkdown>
  

  独自の正規表現による置換（.replace(/\n/g, '<br>') など）とともに dangerouslySetInnerHTML を使用しないでください。XSS の脆弱性につながり、他の Markdown 構文も正しく処理できません。プロジェクトで別のレンダラー（marked、markdown-it、MDX）がすでに標準化されている場合はそれを使用してかまいませんが、単一の改行を <br> に変換する動作が有効であることを確認してください（marked／markdown-it では breaks: true）。
• サーバーコンポーネントを優先します。 コンポーネントでブラウザーが本当に必要な場合に限り 'use client' を追加します。対象は、インタラクティブな状態／エフェクト（useState、useEffect、ref）、イベントハンドラー、ブラウザー専用 API です。クライアント境界は、できるだけツリーの下層に配置します。ページ／ルート全体を 'use client' にするのではなく、小さな末端コンポーネントにインタラクティブな処理を移します。
• Tailwind のユーティリティとプロジェクト既存のデザイントークンでスタイルを設定し、カスタム CSS は避けます。 ハードコードした値ではなく、設定済みのトークン／テーマ（色、間隔、角丸、タイポグラフィ）を使用します。また、Tailwind では本当に表現できない場合を除き、単発の CSS ファイルやインライン style={{…}} は避けます。使用する場合は、その理由を 1 行で記載します。
• 再利用可能なデザインシステムのプリミティブは components/ui/* に配置します。 汎用的でアプリ全体から使われる基本コンポーネント（ボタン、入力欄、ダイアログなど）はここに配置します。機能固有のコンポーネントはここには配置しません（機能の近くにまとめます — codebase-conventions スキルを参照）。
• コンテンツがコンテナからはみ出すことがあってはなりません。テキストや要素が枠を越えてはみ出したり、外側に広がったり、レイアウトを枠幅より広げたりしてはいけません。 これは任意の見た目の調整ではありません。はみ出しはすべて修正すべきバグであり、報告するだけでは不十分です。よくある原因は、固定／flex／grid コンテナ内にある、長くて改行されない文字列（URL、ファイルパス、トークン、メールアドレス、ハッシュ値、word-after-word-after-word など）です。以下を適用します。
  • 折り返し可能なテキスト（段落、説明、ラベル、リンクテキスト、ユーザー／AI が指定した文字列や URL を含むもの）：長い文字列がはみ出さずに折り返されるよう、break-words（overflow-wrap: anywhere）を追加します。通常の word-break では URL やパスを任意の位置で折り返せません。break-words／anywhere を使用してください。href のテキストに生の URL を使うアンカーでは、表示テキストを折り返します。例：<a className="break-words">。
  • 折り返しが望ましくない単一行のフィールド（テーブルセル、リスト行、ピル、パンくずリスト）：truncate（overflow-hidden text-ellipsis whitespace-nowrap）を使用し、値全体を title／ツールチップに設定します。
  • テキストを含む flex／grid の子要素： flex／grid の項目に min-w-0 を追加します。追加しない場合、項目の最小幅はコンテンツのサイズになります。そのため、truncate／break-words を指定しても効かず、行が横にはみ出します。これは「まだはみ出す」問題の最も一般的な原因です。
  • 本当に幅が広いコンテンツ（コードブロック、テーブル、pre）：コンテナに overflow-x-auto を設定し、ページを引き伸ばすのではなく、スクロールできるようにします。
  • 新しい UI が完成と判断する前に、極端に長く改行されない文字列（200 文字の URL など）で必ず動作を確認します。UI を作成または編集した後は、はみ出しがないか確認し、依頼される前に積極的に修正します。

このスキルが適用される場合の動作

1. 作業に一致するパターンを特定します。
2. そのパターンを適用します。パターンが適合しない具体的な理由がない限り、代替案を提案しないでください。
3. 適用したパターンを短い一文でユーザーに伝え、必要に応じて変更できるようにします。
4. ResponsiveDialog が存在せず、作成する必要があった場合は、そのことも伝えます。

今後のパターン

このスキルは今後拡張されます。エージェントが機械的に適用できるルールとして、新しいパターンを上記の Patterns セクションに箇条書きで追加してください。