frontend-implementation

name	frontend-implementation
user-invocable	false
description	デザインツール（Figma/Pencil等）やUI要件を「壊れない・拡張しやすい」実装へ翻訳するための判断軸。px写経を避け、比率・構造・制約・状態を先に設計してからUIを組み立てる。

Frontend Implementation Skill

発火条件（適用タイミング）

• 依頼が「UI実装」「デザインから実装」「Figmaから実装」「Pencilから実装」「コンポーネント実装」「スタイル調整」「レスポンシブ対応」「既存UIの崩れ修正」なら適用する。
• 技術（React/Next/Svelte/Tailwind等）は別skillに委ねる。このSkillは「読み替え」と「実装の判断基準」に集中する。
• デザインツールの種類は問わない（Figma/Pencil/Canva/手書きスケッチ等）。

共通前提（参照）

• 実装規約・口調・TDD・Docコメント等は CLAUDE.md に従う

このSkillの基本方針（整理軸）

• 基本方針: 目的は「細部の写経」ではなく「全体の比率・整合・崩れ耐性・一貫性」。
• 翻訳: デザインツールの数値（px）は参考値。実装は スケール/比率/構造 に変換する。
• 例外管理: 固定値は例外。採用するなら「なぜ固定が必要か」を言語化する（仕様・メディア・タップ領域等）。

思想（判断ルール）

1. UIは“絵”ではなく“制約の集合”。状態（loading/error/empty/disabled）まで含めて完成。
2. “揃え”は margin の微調整で作らない。構造（flex/grid）と gap で整える。
3. 高さ固定を避け、min/max/overflow を先に検討する。
4. タイポは役割ベース。数値コピペで増殖させない。
5. 例外（長文/0件/失敗/遅延）は後付け禁止。最初から扱う。
6. デザインの意図（何を目立たせ、どう視線誘導するか）を先に言語化し、それを壊さない構造に落とす。
7. 横幅は"切り出さない"。デザインの基準ビューポート（RDDのターゲット表示環境）に対して、UIは原則「画面幅に追従」させる（SCALE/FILLの意図を優先）。
   • 左から“表示範囲だけ”を作る（画面の一部を切り出して終わる）実装は禁止。
   • full-bleed（背景が端まで伸びる）と content（本文の最大幅）を分け、背景は w-full、本文は max-width + margin-inline: auto 等で表現する。

読み替えの手順（デザインツール → 実装）

1) 数値より先に読む（抽出するもの）

• 目的（この画面でユーザーに最初に何を理解/実行させたいか）
• 視線誘導（最初に見る→次に見る→最後に見る、の順序）
• 強弱（強調の主役/準主役/脇役）
• 階層（何が親で、何がグループか）
• 伸縮意図・状態（Auto Layout / Constraints / Variants 等、ツール固有の表現を読み替える）
• 余白規則（gap/paddingの法則）
• 整列（どこが揃っているか、何を基準に揃えるか）
• 可変要素（文言長、一覧件数、画像比率、入力値）

2) 実装へ変換する（ルール）

• px → スケールへ丸める（例: 4/8/12/16/24/32/40/48）
• font-size → 役割へマッピング（見出し/本文/補足）
• marginの局所調整 → レイアウト構造へ変換（flex/grid/gap、親子の責務を整理）
• 幅/高さの固定 → 制約へ変換（min/max、折り返し、ellipsis、overflow）
• 横幅の設計 → 背景/コンテナ/コンテンツの責務へ変換（背景は画面幅、コンテンツは最大幅と余白規則で担保）

2.5) 「揃える/揃えない」を判断する（比率・視線誘導）

• 揃える（align）べきとき
  • 反復する要素（カード/リスト/フォーム）で“比較”させたい
  • 主列（本文/主要入力/主要CTA）の視線の通り道を作りたい
  • 迷いを減らすのが目的（管理画面/設定/入力が多い）
• 揃えない（break align）を許すとき
  • “主役”を意図的に浮かせたい（ヒーロー/主要CTA/重要通知）
  • 情報のグルーピングを切りたい（セクション境界を強調したい）
  • 装飾やメディアが主役で、規則より印象が優先（ただし崩れ耐性は担保）
• 揃えない場合のルール（事故防止）
  • どこか1本は“基準線”を残す（例: 見出しの左端だけは揃える）
  • ズラしは 1〜2種類に限定（ズラしパターンが増えると一貫性が死ぬ）
  • レスポンシブ時は“揃える側”へ寄せる（狭幅でズラしを減らす）

2.6) 横並びの「幅配分（重み）」を守る（均等割り事故を防ぐ）

• 幅配分は視線誘導そのもの。1列目・2列目を太く、3列目は補助…のような“重み”は意図として扱う。
• やってはいけないこと（よくある事故）
  • 横並びを雑に均等化して、脇役が主役と同じ存在感になる（例: flex: 1 を全要素に付ける）
  • 「端は揃っているけど、重要度が揃ってしまった」状態にする
• 守るべき判断
  • 「主役/準主役/脇役」の列（またはブロック）をまず決め、**比率（幅の段差）**を仕様として残す
  • “揃える”は 基準線の整列 と 幅配分 を分けて扱う（整列は揃っても、幅は揃えないことがある）
• 実装へ落とすときの指針（技術は問わない）
  • 比率で表現できるなら 比率（例: 2 : 2 : 1 / 5 : 3 : 2） を優先する
  • 可変長で崩れるなら 最小幅（min） と 折返し/詰め方 を先に決める
  • 狭幅では段組み変更（縦積み）も許容し、重要度順を維持する

flex / grid を前提にした「比率の表現」メモ（CSS概念）

• 比率（重み）は “成長” で表現する
  • flex: 各要素の「伸び方（growの重み）」で比率を表現する（均等化の罠に注意）
  • grid: 列の「比率（fr等の重み）」で比率を表現する（列の役割を仕様化しやすい）
• 比率だけだと壊れるので、必ず制約もセットで持つ
  • 最小幅（小さくなりすぎない）／最大幅（太りすぎない）／折返し（wrap/改行）／省略（ellipsis）をセットで設計する
• 比率を崩す条件を明文化する
  • 例: 狭幅では「脇役列は下に落とす」、主役→準主役→脇役の順序は維持する

典型パターン別の判断（汎用）

• (a) 一覧/カード列（比較させたい）
  • 意図: “同じ種類”を比較するので、基本は揃える（基準線・カード高さ・主情報の位置）。
  • 幅配分: 目立たせたいカード（推し/おすすめ）がある場合のみ比率を崩す（それ以外は均等寄り）。
  • 狭幅: 1列化（縦積み）しても、主情報→補助情報の順序は維持する。
• (b) フォーム行（入力の効率を上げたい）
  • 意図: 迷いを減らすため揃える（ラベル列/入力列/補助列の基準線を作る）。
  • 幅配分: 主役は入力欄、脇役は補助（例: 単位/ヒント/操作）なので、補助列は小さくして存在感を落とす（均等割りにしない）。
  • 狭幅: ラベルを上、入力を下、補助をその下に落とす（順序は維持）。
• (c) ヘッダー（検索 + ボタン + 補助）
  • 意図: 主役は検索/タイトル/主要CTAのどれか1つに寄せ、他は補助に落とす（主役を2つ作らない）。
  • 幅配分: 主役（例: 検索）を太く、補助（例: フィルタ/ヘルプ/件数）を細くして重みを表現する（均等割りにしない）。
  • 狭幅: 補助は折り返し/メニュー化/省略を許容し、主役の操作性を優先する。

3) 不明点の扱い（短問の順序）

• 入出力（表示/操作/結果）
• 状態遷移（いつloading/error/disabledになるか）
• 制約（レスポンシブ/可変長/最大行数/折返しルール）
• エッジケース（0件/長文/通信失敗/遅延/低速端末）

実装規約（壊れにくさのルール）

タイポグラフィ（比率と可読性）

• 単位は原則 rem（必要なら clamp()）。em は「親の比率で揃えたい」場面に限定して使う（乱用しない）。
• line-height は原則単位なし（例: 1.5〜1.7）。
• 本文は可読性優先（目安: max-width: 60ch）。

スペーシング（スケールと責務）

• 余白はスケールに丸める（“端数”を増やさない）。
• 子要素へmarginを散らさず、親の gap/padding を優先する。

比率（プロポーション）を守る

• “全体の見た目”は数値一致ではなく比率で担保する（列幅の比、余白の段差、タイポの段差）。
• 固定幅より「最大幅＋余白のルール」を優先する（狭幅/広幅で破綻しにくい）。
• 横並びで“目立たせない列”がある場合、均等割りで存在感を揃えない（幅配分の意図を守る）。

レイアウト（揃えを構造で作る）

• 一方向の並び: flex、二次元の配置: grid、間隔: gap を基本にする。
• position: absolute は重なり/装飾など目的があるときだけ。
• 画像は比率維持を基本にし、必要なら aspect-ratio 相当の設計を入れる。

固定値を許す条件（例外）

• アイコン/サムネ等のメディア、タップ領域、仕様で確定したヘッダー高さ等。
• 崩れ防止が目的でも、まず min/max を検討してから固定に落とす。

状態と耐性（必須）

• default/hover/active/focus/disabled/loading/error/empty を実装仕様に含める。
• 長文・0件・通信失敗・遅延を最初から扱う（後付け禁止）。

出力フォーマット（必ずこの順）

1. 目的（このUIで何を達成するか）
2. 前提（デザイン入力の種類 / 既存規約 / 制約）
3. 読み替え結果（階層/揃え/余白規則/可変要素）
4. 実装方針（レイアウト構造 / スケール / 例外条件）
5. 状態設計（default/hover/active/focus/disabled/loading/error/empty）
6. チェックリスト自己判定（OK/要対応）

チェックリスト（仕上げの品質）

• empty / loading / error がある
• disabled条件がある（連打/不正防止）
• 長文で崩れない（wrap/ellipsis/最大幅/overflow）
• キーボード操作とフォーカスがある
• 狭幅/モバイルで破綻しない
• 余白/文字/色が規約（トークン/スケール）に寄っている

よくある落とし穴

• デザインデータのpx写経で、例外状態やレスポンシブが破綻する
• marginの微調整が増殖して、保守不能になる
• “見た目の一致”を優先して、状態（loading/error/empty）が後付けになる