mae616 Frontend Implementation Skill
発火条件（適用タイミング）
- 依頼が「UI実装」「デザインから実装」「Figmaから実装」「コンポーネント実装」「スタイル調整」「レスポンシブ対応」「既存UIの崩れ修正」なら適用する。
- 技術（React/Next/Svelte/Tailwind等）は別skillに委ねる。このSkillは「読み替え」と「実装の判断基準」に集中する。
- デザインツールの種類は問わない（Figma/Canva/手書きスケッチ等）。
共通前提（参照）
- 実装規約・口調・TDD・Docコメント等は
CLAUDE.mdに従う
このSkillの基本方針（整理軸）
- 基本方針: 目的は「細部の写経」ではなく「全体の比率・整合・崩れ耐性・一貫性」。
- 翻訳: デザインツールの数値（px）は参考値。実装は スケール/比率/構造 に変換する。
- 例外管理: 固定値は例外。採用するなら「なぜ固定が必要か」を言語化する（仕様・メディア・タップ領域等）。
思想（判断ルール）
- UIは“絵”ではなく“制約の集合”。状態（loading/error/empty/disabled）まで含めて完成。
- “揃え”は margin の微調整で作らない。構造（flex/grid）と
gapで整える。 - 高さ固定を避け、
min/max/overflowを先に検討する。 - タイポは役割ベース。数値コピペで増殖させない。
- 例外（長文/0件/失敗/遅延）は後付け禁止。最初から扱う。
- デザインの意図（何を目立たせ、どう視線誘導するか）を先に言語化し、それを壊さない構造に落とす。
- 横幅は"切り出さない"。デザインの基準ビューポート（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件・通信失敗・遅延を最初から扱う（後付け禁止）。
出力フォーマット（必ずこの順）
- 目的（このUIで何を達成するか）
- 前提（デザイン入力の種類 / 既存規約 / 制約）
- 読み替え結果（階層/揃え/余白規則/可変要素）
- 実装方針（レイアウト構造 / スケール / 例外条件）
- 状態設計（default/hover/active/focus/disabled/loading/error/empty）
- チェックリスト自己判定（OK/要対応）
チェックリスト（仕上げの品質）
- empty / loading / error がある
- disabled条件がある（連打/不正防止）
- 長文で崩れない（wrap/ellipsis/最大幅/overflow）
- キーボード操作とフォーカスがある
- 狭幅/モバイルで破綻しない
- 余白/文字/色が規約（トークン/スケール）に寄っている
よくある落とし穴
- デザインデータのpx写経で、例外状態やレスポンシブが破綻する
- marginの微調整が増殖して、保守不能になる
- “見た目の一致”を優先して、状態（loading/error/empty）が後付けになる