# Frontend Implementation

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

- Skill: `mae616/frontend-implementation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mae616/frontend-implementation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mae616/frontend-implementation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media, Web & Frontend
- Author: mae616 (https://skillmd.com/u/mae616)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/mae616/frontend-implementation

---


# Frontend Implementation Skill

## 発火条件（適用タイミング）
- 依頼が「UI実装」「デザインから実装」「Figmaから実装」「コンポーネント実装」「スタイル調整」「レスポンシブ対応」「既存UIの崩れ修正」なら適用する。
- 技術（React/Next/Svelte/Tailwind等）は別skillに委ねる。このSkillは「読み替え」と「実装の判断基準」に集中する。
- デザインツールの種類は問わない（Figma/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）が後付けになる