Figma Design Basics

figma-design-basics

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

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

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

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

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

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

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

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

見るべき型：

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

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

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

• 作らないと決めたものは付箋に書く。 黙って落とすと「考えていない」と読まれる
• 実例＝状態フレームの一部だけ決定に追従しておらず、旧仕様のまま残っていた（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 の成果がそのまま封の中身になる。新しく書き起こさない：

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

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

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

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

Phase 2: 作図中に守る原則

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

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

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

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

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

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

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

• 数値の検証が要るときは /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 の倍数」だけでは足りないか

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

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

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

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

• 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 仕様へのリンク付き）から。

• ⚠️ どのトークンをどの用途に使うかの指針は未取得（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-09-10 追加）

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

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

// 複製の前に必ず走らせる：祖先を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 で撮り直して確認する）