# Figma Design Basics

> Figma で UI をデザイン・修正するときの基本手順と原則。着手前の調査（既存実装の確認・既存の型のサンプリング・起こりうる状態の洗い出し）、作図中に守る原則（何を正とするかの優先順位＝DS＞プラットフォーム規範＞既存の型＞一般原則・スケールを増やさない・間隔のリズム・スケールの作り方（調和数列とフィボナッチ）・強弱はウェイトと濃さで作る・同じ役割は同じ型・アイコンの向き・カードと見出しの階層・DS に値が無いときの数値の目安・動きと遷移＝HIG/M3を土台にトークンで指定）、完了報告前の検品（スクリーンショットによる6点チェック）、意図の残し方をまとめる。Figma への書き込み（use_figma）を伴う作業に入る前に必ず読む。Design System（トークン・コンポーネントの正解）とは別レイヤーで、DS を守っていても防げない手戻りを止めるためのもの。

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

---


# figma-design-basics

Figma で UI をつくる／直すときの手順書。**`use_figma` を実行する前に読む。**

DS（プロダクトのデザインシステム）は「何を使うか」の正解を持つ。ここは「**どう進めるか**」を持つ。

---

## Phase 1: 着手前に調べる（作図を始める前）

作図に入る前に、以下を**必ず**済ませる。ここを飛ばした結果の手戻りが最も高い。

### 1-1. その機能は既に存在しないか

- **既存機能をこの画面に置くだけ**のケースがある。その場合、デザインを起こすのではなく**既存のUIを持ってくる**のが正解
- 確認手段：本人に実機（iOSシミュレータ等）のキャプチャを頼む／既存の Figma ファイルを探す／実装のコードを見る
- **実物を見ずに「たぶんこういうUI」で起こさない。** 実例＝ある指標を「レンジ1行のカード」で作ったが、実物は「概要＋カテゴリごとのレンジバー＋カテゴリ別導線」だった

### 1-2. この画面群の「型」は何か

同じセクション／同じファイル内の**完成済みフレームを1枚以上読む**。読んだうえで真似る。

見るべき型：

| 観点 | 確認すること |
|---|---|
| 見出しとカードの関係 | 見出しはカードの外か中か |
| カードの分け方 | 項目ごとに別カードか、1枚のカードに区切り線で並べるか |
| カードの見た目 | 塗り・角丸・余白・幅（左右マージン） |
| リストの行 | タイトル／サブ／右側の値／シェブロンの構成 |
| 空きの取り方 | セクション間・カード間・カード内のギャップ |

- **推測でなく実測する。** `get_metadata` や読み取り用の `use_figma` でノードの fill / cornerRadius / padding / itemSpacing を数字で取る
- 型が2つ以上見つかったら、**どちらが正かを本人に確認**してから進む（実例＝一覧系の2画面で「項目ごとに別カード」と「1枚のカードに区切り線」の2つの型が見つかり、後者が正だった）

### 1-3. その画面で起こりうる状態を洗い出す

正常系だけ作って出さない。着手前に**どの状態が起こりうるか**を列挙し、作るもの／作らないものを決める。

| 状態 | 典型 |
|---|---|
| 空 | データ0件、まだ登録していない、非公開 |
| 読み込み中 | 一覧・画像・外部データの待ち |
| エラー | 通信失敗、取得できない、権限がない |
| 非活性 | 押せるが受け付けない／条件を満たしていない |
| 上限・超過 | 件数上限、回数上限、文字数超過 |
| 部分欠落 | 一部の項目だけデータが無い（画像なし・数値なし） |

- **作らないと決めたものは付箋に書く。** 黙って落とすと「考えていない」と読まれる
- 実例＝状態フレームの一部だけ決定に追従しておらず、旧仕様のまま残っていた（5枚中1枚を取りこぼした）。**状態フレームは「全部で何枚あるか」を数えてから直す**

### 1-4. 決まっていないことを切り分ける

- 依頼の中に**確定事項と未確定事項が混ざっている**ことが多い。未確定のまま作図すると、決まった後に作り直しになる
- 未確定は作らずに止め、**付箋に「要確認」として書く**。止めた項目は完了報告にも書く
- **多義語はどの階層を指すか確認する。** 「トップ」＝トップページか画面上部か、「一覧」＝L1かL2か、「詳細」＝どの階層か。**コメント1件がどの画面についての話かを取り違えると、作ったもの全部がずれる**
- **★指示の「余り」を置く場所を自分で作らない。** 「画像3枚のうち1枚目はトップ」のように置き場所が一部しか指定されていないとき、残りの置き場所として**新しいセクションを起こすのは要件の追加**になる。まず**そのコメントがどの画面の話か**を確認し、残りは作らずに付箋へ書く（2026-08-24：別画面のコメントから新しいセクションを1つ起こしたが、要件定義書にもSlackにも根拠が無かった）

### 1-5. 外ではどう解かれているかを当てる（トレンドの肩代わり）

**本人はUIのトレンドを追っていない（本人申告）。その引き出しはこちらが持つ。** ただし目的は「流行に乗ること」ではなく、**判断が外の標準から外れていないかの確認**。

- **論点が立ったときにだけ調べる。** 汎用の「最近のイケてるアプリ探訪」はしない。案件に届かないため
- 出し方＝**2〜3例＋それぞれの解き方＋この案件に効くか効かないか**。「流行っているから」を採用理由にしない。効かないと判断した例も1つ残す
- **調べられるもの**：公開されているデザイン記事・各社のデザインシステム公開ドキュメント・App Store / Google Play のスクリーンショット・実装記事・HIG / Material の更新
- **調べられないもの**：実際の操作感、遷移のモーション、触ったときの手応え、体感速度
  - ⚠️ **「触った」と書かない。「調べた」と書く。** 出典を明記する。実機の手触りが判断を分ける論点（アニメーション、ジェスチャー、入力の追従）では、**調べただけでは足りないと明言する**
- 定例やレビューで「他社はどうなっている？」と聞かれたときに出せる形にしておく

### 1-6. 着手の封をする（2026-09-04 追加）

**Phase 1 を終えたら、`use_figma` を打つ前に進行の予測を封じる。** ここが「AI clone」の**進行**を測る唯一の発火点。作図を始めたあとに書いたものは予測ではなく結果になるので、測定にならない。

**Phase 1 の成果がそのまま封の中身になる。新しく書き起こさない：**

| Phase 1 でやったこと | 封の項目 |
|---|---|
| 1-1 その機能は既に存在しないか | **1. 最初に見るもの** |
| 1-3 起こりうる状態を洗い出す | **2. 作る範囲** |
| 1-4 決まっていないことを切り分ける | **4. 未確定として付箋に回すもの** |

これに次の3つを足して `~/.claude/board/mirror/YYYY-MM-DD-<slug>.md` に保存する（テンプレートと手順はスキル `mirror` のモード A2）：

- **3. 作らないと決めたもの**（スコープ外にした理由つき）
- **5. 誰に何を聞くか**（誰も答えを持っていないなら「聞かない」と書く）
- **6. いつ出すか** — **必ず日付で**。期日 → 逆算した中間期限 → 今日やること。入稿・印刷・レビュー待ちの後工程を織り込む

封じたら「着手の封をしました」とだけ言って作図に入る。**予測の解説をしない**（解説すると本人の進行が引きずられ、測定が汚れる）。

**封じない**：1コンポーネントの値直しなど進行の判断が発生しない作業／`~/side-projects` 配下の作業。

---

## Phase 2: 作図中に守る原則

### 2-0. 何を正とするか（優先順位）

判断が割れたときは、この順で上のものを採る。

| 順位 | 正とするもの | 守備範囲 |
|---|---|---|
| 1 | **プロダクトの DS** | トークン・コンポーネントの定義と使い方 |
| 2 | **プラットフォーム規範**（iOS=HIG / Android=Material） | DS が黙っている領域の作法 |
| 3 | **その画面群の既存の型** | レイアウトの語彙・粒度・並びの約束 |
| 4 | **一般原則**（このスキル） | 上のどれも答えを持たないとき |

- **3 は「その場の約束事」なので踏襲する。一貫性そのものが価値**（カードの分け方、見出しの置き方、リスト行の構成）
- **ただし 3 が 2 に反しているときは踏襲しない。** 誤りが伝播する。**正しい形で作り、付箋に「実装から意図的に変えた」と書いて相談に回す**
  - 実例＝既存実装が `＞ カテゴリ別` だったが、進む導線のシェブロンは HIG も Material もラベルの**後ろ**。既存の絵に引きずられて誤りを写した
- **「既存がそうなっている」は理由にならない。** それが約束事なのか誤りなのかを一度分ける
- OS で挙動が分かれる領域（戻る、シート、ハプティクス、システムフォント）は、**どちらのOSを想定した図かを付箋に書く**。DS が両OS共通の定義を持っているならDSが優先

### 2-1. スケールを増やさない

- **文字サイズ・余白・角丸・色・アイコンサイズは、その画面群で既に使われている値から選ぶ**
- 新しい値を作りたくなったら、それは「型を読めていない」兆候。既存を探し直す
- **1つのブロックの中でサイズを混ぜない。** 実例＝項目名14pt・数値16ptで揃っておらず指摘を受けた。**同じ行に並ぶ要素は同じサイズが既定**、変えるなら理由を言えること
- **強弱はサイズだけでつくらない。** ウェイト（Regular / Medium / Bold）と文字色の濃さ（本文／ミュート）で差をつけると、サイズの種類を増やさずに階層がつくれる。**1画面で使う文字サイズの種類は少ないほどよい**

### 2-1b. 迷ったときの数値の目安（DS に値があれば DS が優先）

DS やその画面群に既存値があれば**必ずそちらを使う**。無いときだけこの目安で決め、決めた根拠を付箋に書く。

| 項目 | 目安 |
|---|---|
| 余白・サイズ | 行送りは 4 の倍数／コンポーネント間は 8 × フィボナッチ（8 / 16 / 24 / 40 / 64 / 104）。詳しくは 2-1d |
| 行間 | 本文 1.5〜1.75、見出し 1.2〜1.3 |
| コントラスト比 | 本文は 4.5:1 以上（WCAG AA）。大きい文字は 3:1 以上 |
| タップ領域 | 最小 44×44pt。見た目が小さくても当たり判定で確保する |
| 色数 | ベース／メイン／アクセントの3階層に収める。アクセントは画面の1割程度 |

- 数値の検証が要るときは `/design-check`（重心・大きさ・カーニング・色・WCAG）を使う

### 2-1c. リズム（間隔の設計）

「4/8 の倍数を使う」だけでは心地よさは出ない。**効いているのは、間隔の種類を絞ることと、間隔で意味を表すこと。**

- **1画面で使う間隔の種類を3〜4に抑える**（例：4 / 8 / 16 / 24）。倍数であっても種類が増えれば散らかる
- **近接＝意味の距離を間隔で表す。** 関係が近い要素ほど狭く、切れ目ほど広く。**同じ間隔で並んでいるものは同じ階層**、という読み方を壊さない
- **階層をまたぐ間隔は内側より必ず広く。** カード内のギャップ ＜ カード間 ＜ セクション間、と単調に増やす。**逆転するとグループが読めなくなる**（要素が隣のグループに属して見える）
- **スケールは単発でなく段で作る。1つの要素だけ比率で決めても効かない**——効くのは段全体が揃っているとき（段の作り方は 2-1d）
- **黄金比（1.618）はアプリUIでは優先度が低い。** 再現性は 4/8 グリッドと既存の型の踏襲のほうが高い。効くのは**面の比率を選ぶとき**（メディアの高さ、2カラムの分割比）くらい。**決めた値の後付けの理由づけには使わない**
- 縦方向は行間も間隔のうち。**テキストブロックの行間を変えたら、その前後の余白も見直す**（行間が広いブロックの直後に狭い余白を置くと詰まって見える）

### 2-1d. スケールの作り方（DS に無いとき／スケール自体の良し悪しを見るとき）

出典＝鈴木丈「音楽、数学、タイポグラフィ」（ekrits.jp/2020/02/3309/）。**DS にスケールがあれば DS が優先**。ここを使うのは、DS が黙っている領域と、既存のスケールが妥当かを判断するとき。

**なぜ「4/8 の倍数」だけでは足りないか**

| 作り方 | 弱点 |
|---|---|
| 等差（8, 16, 24, 32, 40…） | **大きいサイズで差が感じられない**（64 と 72 は違って見えない） |
| 倍々（8, 16, 32, 64） | **差が極端**になって中間が無く、実用に耐えない |
| 等比＝モジュラースケール（16, 20, 25, 31.25…） | **本文サイズの周辺にバリエーションが無い**。実務で欲しい 14 や 15 が段に無い |

**文字サイズ＝調和数列でつくる**

基準サイズに 1/1, 1/2, 1/3, 1/4 … を掛ける（記事の例＝16px 基準・整数8を乗じる）。

| n | 計算 | 値 |
|---|---|---|
| 1 | 16 × 1/1 × 8 | 128 |
| 2 | 16 × 1/2 × 8 | 64 |
| 3 | 16 × 1/3 × 8 | 42.67 |
| 4 | 16 × 1/4 × 8 | 32 |
| 5 | 16 × 1/5 × 8 | 25.6 |
| 6 | 16 × 1/6 × 8 | 21.3 |
| 7 | 16 × 1/7 × 8 | 18.3 |
| 8 | 16 × 1/8 × 8 | 16（基準） |
| 9 | 16 × 1/9 × 8 | 14.2 |
| 10 | 16 × 1/10 × 8 | 12.8 |

- **性質＝小さいほど密、大きいほどまばら。** これが実務の需要と一致する（本文まわりは細かく選びたい／見出しは大きく跳ばしたい）。等比だとこれが逆になる
- 由来は弦の分割（1/2, 1/3, 1/4 が倍音として調和する）。**「音楽的だから正しい」ではなく、密度の分布が知覚と合うから使える**と理解しておく
- 実際には整数に丸める。**丸めた結果が既存スケールと1〜2pt違うだけなら、既存に寄せる**（スケールを増やさない原則が上位）
- 日本語では副次的な利点がある＝**本文8文字・見出し3文字・キャプション10文字が同じ幅に揃う**。全角の字幅が効くので、和文のブロックを並べるときに端が揃いやすい

**スペーシング＝3層で考える**

| 層 | 単位 | 用途 |
|---|---|---|
| L1 | **4px グリッド** | テキストの行送りの最小単位。**すべての line-height を4の倍数に**して縦のリズムを揃える |
| L2 | **8px グリッド＋スケール** | コンポーネント間の余白。**8 × フィボナッチ（1,2,3,5,8,13）＝ 8 / 16 / 24 / 40 / 64 / 104** |
| L3 | **本文の行送り単位** | 大きな要素・セクション間 |

- **8の倍数なら何でもよい、ではない。** 8 の上にスケール（どの倍数を使ってよいか）を定義するのが肝。フィボナッチにすると**差が大きすぎず小さすぎない**段になる
- L2 のスケールを決めたら、**そこに無い値（32, 48, 56 など）は使わない**。これが 2-1c の「間隔の種類を絞る」の具体形
- **既存ファイルのスペーシングを実測して、この形になっているかを見る**。なっていなければ、そのファイルの中では既存に合わせつつ、逸脱を付箋に書く

### 2-2. 同じ役割には同じ型、粒度も揃える

- 見出し／リスト／カード／テキストリンクの表現は画面群で1つに統一する
- **「どこで分けるか」の粒度も型のうち**。カードを項目ごとに割るのか、1枚にまとめて区切り線で分けるのかは、見た目より先に決まっている約束

### 2-3. 方向を持つ要素は意味のある側に置く

- 進む導線の `＞` は**ラベルの後ろ**（`カテゴリ別 ＞`）。戻るの `＜` は前
- 順序を入れ替えると意味が壊れる。**既存実装がそうなっていても、それは実装の誤りとして扱い、正しい向きで作って付箋に「実装から意図的に変えた」と書く**
- シェブロンを置かず**単に青字のテキストリンク**にする選択肢も常にある。導線が1つなら後者のほうが軽い

### 2-4. 階層は「見出しは外・中身はカード」

- セクション見出しはカードの**外**（ページ背景の上）に置く
- 中身は角丸のカードに入れる
- カードの中で更に分けるときは**区切り線**を使い、カードを分割しない

### 2-5. 強度は役割で決める

- 主動線と従属オプションは、**位置・型・ボタンの強度**で差をつける（例：主＝横スクロールのカード列、従＝単体カード＋Outlined ボタン）
- 並び順を変える指示が来たら、**主従の関係が壊れないか**を確認する。壊れるなら比較案を添えて相談する

### 2-6. Figma の実装上の落とし穴

- **`figma.createAutoLayout()` は白（#FFFFFF）の塗りが入った状態で生まれる。** 消し忘れるとページ背景の上に白い帯が敷かれ、**カードがカードとして見えなくなる**。自作したラッパーのフレームは原則 `fills = []`
- **絶対配置のテキストは `textAutoResize = 'WIDTH_AND_HEIGHT'` を先に入れてから x を計算する。** クローン元の幅が残っていると `x - width/2` が負になり左端に重なる
- 折り返しテキストは `layoutSizingHorizontal='FILL'` だけでは幅が決まらない。`FIXED` ＋ `resize()` で明示幅を与える
- `layoutSizingHorizontal='FILL'` はテキストの `textAutoResize` より強い。ラベルを内容幅にしたいなら `HUG` にする
- ノード名での一括削除は**type も絞る**（`findAll(n => n.type === 'FRAME' && n.name === ...)`）。同名のテキストを巻き込んで消した実例がある
- 既存フレームは触らず**複製で組む**。原本を変更すると、コメントやコネクタの導線が切れる
- **SECTION の子の `x`/`y` はセクション相対。ページ絶対座標ではない。** `get_metadata` が返す子の座標も相対値なので、それを絶対座標と誤読して `appendChild` 後に絶対値を入れると、中身がセクションの遥か外へ飛ぶ（レイヤーには並ぶのに**キャンバスでは空の枠に見える**）。セクション内に置くときは `子の相対座標 = 置きたい絶対座標 − セクションの x / y` で計算する。**セクションを作ったら、子を1つ入れた時点で `screenshot()` を撮って枠内にあるか見る**（2026-09-02）
- **`node.screenshot()` / `get_screenshot` を SECTION に対して使うと、bounding が y=0 起点で解釈され、上に無関係な余白が入る。** セクション全体の検品には使えるが縮尺が狂うので、**細部は個別ノードを撮って確認する**（個別ノードなら正しい寸法で返る）
- **`query()` のセレクタはノード名に空白があると効かない。** `[name=Frame 626052]` は0件になる。空白を含む名前で探すときは `findAll(n => n.name === '...')` を使う（2026-08-28 に1度、08-31 に再発）
- **付箋を既存から複製するとき、元ノードに箇条書き書式が付いていることがある。** その状態で本文に `・` を打つと記号が二重になる（`• ・…`）。**複製したら1枚スクショを撮って記号の重複を見る**
- テキスト編集の前に**そのノードの現在のフォントを読んでロードする**（`getStyledTextSegments(['fontName'])`）。日本語フレームでも英数字が別ファミリ（Roboto）のことがある

### 2-7. 動きと遷移

**前提＝DS に motion のトークンは無い**（2026-08-21 本人確認）。よって 2-0 の優先順位で **2位＝プラットフォーム規範（HIG / Material 3）を土台**にする。以下はすべて一次資料から取ったもので、**出典の無い記述は置いていない**。

**① 動きは情報の関係を表す**

- 何がどこから来てどこへ行くかで、要素どうしの関係が決まる。**元のカードから拡大して出れば「あれの中身」、下から出れば「一時的な別レイヤー」**
- **ジェスチャーと逆向きの消え方をさせない。** HIG の例＝「上から引き下ろして出したビューを、横に払って消す」とは誰も思わない（出典：HIG Motion）
- **動きを唯一の伝達手段にしない。** 重要な情報は動き以外でも伝える（出典：HIG Motion）

**② 足しすぎない（出典：HIG Motion）**

- **目的をもって動かす。動きのための動きを足さない。** 過剰・不必要な動きは注意をそらし、身体的な不快感を与えうる
- **頻繁に起きる操作には動きを足さない。** 標準部品には既にさりげない動きがある
- **短く正確に。** 短く精密なフィードバックのほうが、目立つアニメーションより情報を伝える
- **完了を待たせない・キャンセルできるように**

**③ duration / easing は M3 のトークンから選ぶ**

DS に無いため。値は Flutter SDK の M3 実装（`material/motion.dart`・M3 仕様へのリンク付き）から。

| duration | 値 |
|---|---|
| short1–4 | 50 / 100 / 150 / 200 ms |
| medium1–4 | 250 / 300 / 350 / 400 ms |
| long1–4 | 450 / 500 / 550 / 600 ms |
| extralong1–4 | 700 / 800 / 900 / 1000 ms |

| easing | cubic-bezier |
|---|---|
| standard | (0.2, 0, 0, 1) |
| standardAccelerate | (0.3, 0, 1, 1) |
| standardDecelerate | (0, 0, 0, 1) |
| emphasizedAccelerate | (0.3, 0, 0.8, 0.15) |
| emphasizedDecelerate | (0.05, 0.7, 0.1, 1) |

- ⚠️ **どのトークンをどの用途に使うかの指針は未取得**（M3「Applying easing and duration」が取得できていない）。**用途の当てはめを推測で書かない。** 必要になったらそのページを読んでから足す
- **選んだ値は必ずトークン名で書く**（「300ms」ではなく「medium2 / 300ms」）。名前で書くと、後からスケールに乗っているかを検証できる

**④ Reduce Motion に対応する（出典：HIG Accessibility / WCAG 2.3.3）**

Reduce Motion が有効なとき、自動・反復するアニメーション（ズーム、スケール、周辺の動き）を減らす。HIG が挙げる具体策：

- ばねを固くしてバウンドを減らす
- アニメーションをジェスチャーに直接追従させる
- **z軸（奥行き）の変化をアニメートしない**
- **x, y, z の遷移をフェードに置き換える**
- ぼかしの出入りをアニメートしない

WCAG 2.3.3（レベル AAA）＝「操作によって起きるアニメーションは無効にできること。ただしその機能や情報伝達に本質的な場合を除く」。実装手段は `prefers-reduced-motion`。

- **動きを設計したら、Reduce Motion 時の代替を付箋に1行書く。** 図を2枚作らなくてよいが、無いまま出さない

**⑤ エージェントが判定できないこと（明示）**

- **気持ちよさ、間、追従の質感、イージングの官能は判定できない。** 静止画しか見られないため
- 書けるのは「何がどこから来てどこへ行くか」「どのトークンか」「なぜその関係か」まで。**良し悪しの判定は本人に返す**
- ⚠️ **「この動きのほうが良い」と書かない。** 関係が正しいかどうかだけを述べる

---

## Phase 3: 完了報告の前の検品（ゲート）

**「できました」と言う前に必ず通す。**

### 3-1. スクリーンショットで見る

- `node.screenshot()` または `get_screenshot` で**実際に描画された絵を見る**
- **metadata・自分の作業ログ・「置いたつもり」を正本にしない。** 絵と食い違っていた実例が複数回ある（PRバッジを置いたつもり／いいねを置かなかったつもり）
- フレームが `clipsContent` の場合、追加した要素が切れる。**中身の bottom を測ってフレーム高さを合わせる**

### 3-2. 6点チェック

1. **背景の上でカードとして成立しているか** — 白い帯が敷かれていないか、角丸が見えているか
2. **使った文字サイズの種類を数える** — 増えていたら型から外れている疑い。同じ行・同じブロックの中で混在していないか
3. **同じ画面群の完成済みフレームと並べて差分を言葉にする** — 言葉にできない差があるなら型を外している
4. **切れ・重なり・はみ出しが無いか** — 特に横スクロールのはみ出し、絶対配置のラベル、フレーム下端
5. **状態が揃っているか** — Phase 1-3 で「作る」と決めた状態が全部あるか。同じ状態フレームが複数枚あるなら**枚数を数えて全部直したか**
6. **文字と背景のコントラスト・タップ領域** — ミュート色の文字、薄い背景の上のリンク、小さいアイコンボタンを重点的に

### 3-3. 複製したものは複製先も見る

- 1枚直して他へクローンしたときは、**クローン先でも位置とサイズが保たれているか**を確認する（絶対配置は特に崩れやすい）

---

## Phase 4: 完了報告の書き方

- **作ったもの**（node ID つき）
- **自分で判断して決めたこと**とその理由
- **確定待ちで作らなかったもの**
- **実装や既存画面から意図的に変えたところ**（相談扱いにする）
- **踏んだ不具合と直し方**（隠さない）

---

## 意図を残す（付箋の書き方）

**すべての指定に「なぜそれか」を言えること。** 言えない指定は、たいてい型を読めていない。

- 付箋には**結論だけでなく、選ばなかった案とその理由**を1行入れる。レビューで同じ論点を2回話さずに済む
- 根拠の型：視覚的な優先度／認知負荷／視線誘導／既存の型に合わせた／実装コストを増やさない
- **既存の実装や決定から意図的に変えたところは、必ず「変えた」と書く。** 黙って直すと差分がミスに見える
- **★調査の過程を付箋に書かない。** 何で確かめたか（実機キャプチャ／実装のファイル名／確認した日付）は自分の作業記録であって、読む人に渡すものではない。付箋に残すのは判断とその根拠だけ。**数値を書かないのと同じ理由**（2026-09-01：実機キャプチャで確認した内容とDSのずれを付箋に書き、本人に削除された）

## 採らない考え方

- **「要件やDSに不足があってもプロ判断で補完する」は採らない。** この環境では手戻りの最大要因（既存実装があるのに独自に起こした実例）。**補完の前に既存を調べ、未確定は止めて付箋に書く**。補完してよいのは Phase 1 で「既存が無い」と確認できてから
- **Web/コード前提の指針は当てない** — Tailwind、aria 属性、HTML タグ、Hover/Focus、ブレイクポイント。対象がアプリUI（iOS/Android）のときは存在しないか、DS 側が持っている
- **px の直指定を前提にしない** — DS のトークンがあるならトークンで指定する。数値の目安（2-1b）は DS に値が無いときだけ

## 学習ループ

デザイン面の差し戻し・指摘を受けたら、原因を1行に圧縮して追記し、「これを追記しました」と報告する。

- 汎用原則 → `~/.claude/rules/common/ui-design-principles.md`
- Figma 作業の手順・落とし穴 → このファイル
- プロダクト固有の型・トークン → 自分の DS のメモ、または案件の memory

---

## 差し戻しの実績（同種の再発を止めるための記録）

| 日付 | 指摘 | 原因の型 | 対応した節 |
|---|---|---|---|
| 2026-08-21 | ある指標の画面に既存実装があるのに独自に起こした | 着手前の調査不足 | 1-1 |
| 2026-08-21 | カードの型が他画面と違う | 型のサンプリング不足 | 1-2 |
| 2026-08-21 | カードの分け方の粒度が違う | 型のサンプリング不足 | 1-2 / 2-2 |
| 2026-08-21 | ラッパーの白塗りでカードが成立していない | Figma の落とし穴＋検品不足 | 2-6 / 3-2 |
| 2026-08-21 | `＞ カテゴリ別` の並びが逆 | **既存実装の誤りを踏襲した**（HIG/Material に反する） | 2-0 / 2-3 |
| 2026-08-21 | 項目名14pt・数値16ptで不統一 | スケールの混在 | 2-1 |
| 2026-08-21 | 写真の上の再生アイコンが灰色で読めない | コントラスト（検品6） | 3-2 |
| 2026-08-21 | コメントの「トップ」がトップページか画面上部か未確認 | 語義の確認漏れ | 1-4 |
| 2026-08-31 | `query()` が空白入りのノード名にヒットせず、削除したい要素が消えないまま進んだ | Figma API の落とし穴（既知だったのに再発） | 2-6 |
| 2026-08-24 | **別画面についてのコメントを根拠に、要件に無いセクションを新設した**（「アピール内に画像3枚」は別画面の話だった） | **コメントの対象画面を確認せず、指示の余りを置く場所を自分で作った** | 1-4 |
| 2026-09-01 | **相談されていない論点に案を2つ作った**（「あるタブが無くなると入口も消える」） | **自分が前に書いたドラフトの誤りを訂正する過程で、論点そのものを新設した**。元資料（依頼者のモック）で「別に残す」と書かれていたのは一部の機能だけで、検索の置き場はグリッドのタイルとして既に決まっていた | 1-1 / 1-4 |
| 2026-09-01 | **提案した「逃がし先」が過去に否定されていた**（長い生成文をカードから詳細画面へ移す案） | **解決策の置き場所が成立するかを、過去の決定で確認せずに出した。** 7/31 に「詳細画面には商品観点で掲載できない仕切り」と決着済みで、200文字という制約もその前提から出ていた | 1-1 / 1-4 |
| 2026-09-02 | **セクションを作ったが中身がキャンバスに見えない**（レイヤーには18個並ぶのに枠は空） | **SECTION の子の座標がセクション相対であることを知らず、ページ絶対座標を入れた。** `get_metadata` の返す子の座標を絶対値と誤読したのが発端 | 2-6 / 3-1 |

---

## ★素材の正体を確認してから使う（2026-09-10 追加）

**属性の一致（色・寸法・名前）で正体を判定しない。** 複製・引用する前に、そのノードが**何なのか**を確認する。

Figma のガイドライン系ファイルには**正例と NG 例が同じページに並んでいる**。色や寸法は同じなので、検索では区別がつかない。

```js
// 複製の前に必ず走らせる：祖先を3段たどって周辺テキストを集め、NG 文脈を検出する
const NG = /してはいけ|禁止|NG|ドロップシャドウ|色の変更|回転|重ねる|視認できない|変形|やってはい/;
const ctx = (n) => { let p = n.parent, up = 0, t = [];
  while (p && up < 3 && p.type !== 'PAGE') {
    if ('findAllWithCriteria' in p) for (const x of p.findAllWithCriteria({types:['TEXT']}).slice(0,12)) t.push(x.characters.slice(0,26));
    p = p.parent; up++; }
  return { ng: NG.test(t.join(' / ')), sample: t.join(' / ').slice(0,170) }; };
// 兄弟のテキストも見る（NG 例は「何が NG か」を隣に書いてある）
const siblings = node.parent.children.filter(c => c.type === 'TEXT').map(c => c.characters);
```

- **実例（2026-09-10）**：ブランド4色で検索して 275×54 のロゴを見つけ、テンプレートに複製した。実際は**兄弟のテキストが「ドロップシャドウをつける」**、親の説明が**「右記のようなロゴの改変は禁止されています」**＝ NG 事例ページ。**影が付いていたのは禁止例そのものだった**。同じ寸法のカラーロゴは3つあり、**3つとも NG 事例**だった
- **正しい入手先はブランドキットの正本**＝`assets/brand-kit/logo/svg/*.svg`。`figma.createNodeFromSvg()` で読み込む（効果0件・寸法が明確）
- ⚠️ **単色版はカラー版の色替えでは作れない。** mono と white は完全同形（12/12 のパスが一致）だが、**color とは形が違う**（1/12 しか一致しない）。白抜きが必要なら mono を白にする

## ★検品6点に追加（2026-09-10）

7. **複製した素材の効果（影・線・不透明度）を確認する。** スクリーンショットを撮っても、影は「そういうデザイン」に見えて気づけない。`node.findAll(n => 'effects' in n && n.effects.length)` で数える

## ★数値の出どころを持つ（2026-09-10 追加）

**汎用の運用は `rules/common/provenance.md`（常時ロード）が正本。** Figma 作業に固有の点だけここに置く。

- **派生物を測って正本を直すと判断しない。** 実例＝実物の資料（PDF）を測って「テンプレートの画像位置がずれている」と報告したが、テンプレートは正しく、ずれていたのは資料だった
- **実装の定数から規定を書かない。** 実例＝旧ツールの `PAD_L=104` から版面を書いたが、Figma の実座標は 112 だった。**ガイドが「Figma が正本」と書いている項目は、書く前に Figma の実座標を取る**
- 座標は `get_metadata` で取る。画素の実測は補助（縮小レンダリングで枠線を横罫と誤検出した実例あり＝1:1 で撮り直して確認する）