design-philosophy

VS Code のデザイン哲学

このスキルは、開発者とエージェントの両方にとって、UI について考える際の唯一の信頼できる情報源となる、VS Code の標準的なデザイン哲学です。

UI の実装にエージェントやツールがますます多く使われるようになるにつれて、ピクセルの調整は次第に自動で行われるようになり、希少な人間の役割は、その背後にあるデザイン上の判断になっていきます。

これは、シフトレフト、つまりピクセルではなくデザインの観点から UI を語り、その対話を早い段階で始めることです。何かがしっくりこないとき、「8px なので 6px にする」という修正では数字を一つ直すだけですが、「このサーフェスの角丸は誤った エレベーション階層 になっている」と表現すればルールを特定できます。そのため修正をあらゆる箇所に反映でき、コードレビューではなくモックアップやスクリーンショットで問題を発見できます。目指すのは、デザイナーとエンジニアが共有できる言葉で、UI はどうあるべきか、そしてなぜそうあるべきかについて合意することです。デザインが固まれば、実装（どのトークンをどのファイルで使うか）は自然と決まります。

---

読み方：3 つのレイヤー

どのデザイン言語でも最も難しいのは、「何だかしっくりこない」という感覚から、誰もが納得できる明確で共通の修正案にたどり着くことです。この構成では、下位のレイヤーを一つずつ説明する 3 つのステップで、その道筋を示します。

レイヤー	内容	例
価値観	人にどのように感じてほしいか、そしてそれがなぜ重要なのか	集中できる
原則	デザインを評価するためのルール。問いかけの形で表現します	「一つが先導し、残りが支える」―最初に目が向かうのはどこか？
手法	具体的な仕組み。それぞれに、どれを選ぶか、なぜ選ぶかのルールがあります	セカンダリーパネルを、凹んだ背景トークン／より控えめな文字スタイルの役割にする

仕組みを学ぶときは上から下へ、バグを修正するときは下から上へ読みます。感覚を言葉にし、そこから外れている原則を見つけ、最後にそれを取り戻す手法を選びます。

例：情報が多すぎるパネル

• **気づくこと：**パネルの情報量が多く、エディターから何度も目をそらされます。
• **感覚：**落ち着きもなく、集中もできません。
• **原則：**常に静かにに反しています（不要な塗りが常に表示されている）。また、一つが先導するにも反しています（セカンダリーの装飾要素がエディターと競合しています）。
• **手法：**パネルを凹んだ背景トークンまたは透明な背景トークンにし、境界線はホバー時だけ表示して、ラベルをより控えめな文字スタイルの役割にします。

---

価値観：デザインの目標

この 4 つの価値観は、VS Code を使う人にどのように感じてほしいかを表します。最上位のレイヤーにあたり、下位の原則と手法はすべて、最終的にはこれらの実現を目指します。これらを理解すれば、ほとんどのバグを説明できるようになります。それぞれが UI によって与えられるべき感覚であり、下記の 1 つ以上の原則によって実現されます。まず価値観に立ち返り、次に原則を確認し、最後に手法を選びます。

価値観	意味	損なわれると感じること…	原則
落ち着き	何もしていないときは静かですっきりしている。余白があり、鋭さではなく柔らかさがあり、率直で人間味がある	ごちゃごちゃしている、騒がしい、窮屈、ぎざぎざしている、分かりにくい、押しつけがましい	1、2、3
集中	明確な階層。一つが先導し、残りが支える	平坦でどれも同じに見え、目の向かう先がない	4、5
一貫性	すべてが同じ段階と階層に収まっている	ばらばら、グリッドからずれている、統一感が失われている	5、6
喜び	役割を果たす小さな瞬間。導き、確認し、方向を示す	生気がない、唐突、または奇をてらっている	7

*「背景を透明にするべき」と言う前に、「騒がしく感じる。落ち着きがない」*と言いましょう。価値観を示すことで、全員が同じ原則に目を向けられます。

なぜこの4つなのか？

こう尋ねるのはもっともです。落ち着いていて、集中でき、一貫性があり、心地よい UI を望まない人がいるでしょうか？まさにそれがポイントです。これらは他の製品に対して優位性として主張する差別化要素ではありません。むしろ、私たちのようなツールで最も脅かされている特性であり、名前を付けることで守れるのです。これらを選んだのは、VS Code が構造的に失いやすい価値だからです。

• 落ち着きは IDE で最初に損なわれます。VS Code は情報量が多く、何時間も使い続けるものです。どの機能チームにも、もう1つ操作要素を追加する正当な理由がありますが、それらが積み重なるとノイズになります。落ち着きは、私たち自身の勢いに歯止めをかける価値です。
• 集中が重要なのは、私たちの画面が奥深いからです。重みも妥当性も同じコントロールが並ぶ画面は、高機能ツールでよくある失敗の形です。集中を掲げることで、何を主役にするかを決めざるを得なくなります。
• 一貫性は、守るべき範囲が最も広い価値です。VS Code は長年にわたり多くの人の手で作られているため、自然な状態はばらつきです。一貫性は、目指すべき理想というより、維持管理の規律です。
• 心地よさは、私たちが意図的に節度をもって使う価値です。役割を果たす場合にのみ、その存在が認められます（原則7）。これを掲げるのは、さらに装飾を加えるためではなく、誠実さを保つためです。そうすることで、心地よさは飾りではなく、導き、確信を与えるものになります。

また、それぞれの価値は、得をするだけの選択ではなく、現実に存在するトレードオフを示しています。だからこそ、ありきたりな決まり文句ではなく、明示する価値のある選択なのです。

• 落ち着きは情報密度とトレードオフになります。何もしていないときに、どれだけの情報を見せるべきでしょうか？
• 集中は平等なアクセス性とトレードオフになります。1つの要素を主役にするために、何を目立たなくするのでしょうか？
• 一貫性は真に特別なケースとトレードオフになります。どんなときに、違いは単なるばらつきではなく、正当なものになるのでしょうか？
• 心地よさは節度とトレードオフになります。どんなときに、ちょっとした演出がノイズになってしまうのでしょうか？

ですから、役に立つ問いは「これらを望まないことなどあるのか？」ではなく、「この画面はどの価値を犠牲にしていて、それは意図したものか？」です。ある価値をどうしても譲らなければならない場合――たとえば、注意を引くためにあえて落ち着きを損なうべき重大な警告など――それは意図的に名付けられた例外であり、その価値を捨てる理由にはなりません。

---

原則

原則は評価の基準です。それぞれが、あらゆる画面について問いかけられる質問であり、その答えから、ピクセル値に左右されずにデザインの良し悪しを判断できます。原則は、それぞれが支える価値ごとに分類されています。

---

落ち着き

1. 何もないときは控えめに、意図した操作には応える

問い： 何も起きていないときに、目立ちすぎているものはありませんか？

操作部品は、操作するまでは目立たないようにします。必要性がないのに常に塗りつぶし、境界線、フォーカスリングが表示される画面は、必要もないのにユーザーのコンテンツと注意を奪い合います。現代的な見た目とは控えめであることです。ホバー、フォーカス、操作など、意図的な操作があったときに要素が現れ、それ以外は静かに収まっています。

これが正しくないときには、「何もしていないのにうるさい／ホバーするまで控えめにするべき」や「クリックするとフォーカスリングが表示される」といった表現になります。これは色の値ではなく、動作の説明です。

実現方法： 意図的な操作に応じて表示する動作、1本の線、テーマカラー。

2. ゆとりを持たせる

問い： 窮屈、詰まっている、あるいはぎざぎざした印象はありませんか？

落ち着いた UI は、ゆったりとして柔らかなものです。余白は無駄ではありません。視線を休ませ、線を引かずに要素をグループ化できます。角は鋭くするのではなく、丸くします。画面が窮屈だったり、ごちゃついて感じられたりするときは、コンテンツを小さくするより、通常はスペーシングの段階に沿って余裕を増やすのが解決策です。

実現方法： スペーシングの段階、エレベーションの段階（鋭角ではなく、角を丸くする）。

3. インターフェースは、わかりやすく親切に説明します

問いかけ： 推測しなくても、ひと目で理解できますか？

UIは、人が話すように読めるものにします。謎めいた記号より言葉を選び、文頭だけを大文字にし、人間味のある口調を保ちます。ラベルのないアイコンや、各単語を大文字で始めたマーケティング用の見出しは、ユーザーに余計な負担をかけます。わかりにくくせず、声を張り上げないようにします。

実現方法： 言葉と大文字・小文字の使い分け。

実例 - 枠に閉じ込められたツールバー

• 見るもの： ツールバーが塗りつぶされたバーの上にあり、各ボタンの間には区切り線があり、ボタン同士が隙間なく並んでいます。
• 感じること： 落ち着きとは言えず、窮屈で忙しない印象です。
• 原則： 静止時は静かに（塗りつぶしや区切り線は、そこにある理由がないまま常に表示される装飾です）と、呼吸できる余白（ボタンが詰め込まれています）に反しています。
• 対応： 静止時にはバーを透明に見せ、区切り線をなくし（線は一本――ここでの答えは「なし」です）、ボタンの間隔を段階的に広げます。

集中

4. ひとつを主役にし、ほかは支えます

問いかけ： 視線はどこに最初に向かいますか？ また、二次的な要素がそれと競合していませんか？

どのビューにも、明確な注目の中心、つまり視線が最初に向かうべきものを設けます。二次的な情報はその場所から外し、控えめな文字スタイル、奥まった面、小さめのアイコンなどで目立たなくして、重要なものを主役にし、それ以外は支えるようにします。すべてが同じ重みのビューは平板で、視線の行き先がありません。

実現方法： 文字スタイル、エレベーション階層、コンテキストに応じたアイコンサイズ。

5. 高さは目分量ではなく、表現で伝えます

問いかけ： この面の丸みは、その下にあるものからどれだけ浮いているかと合っていますか？

面の丸みと高さには意味があります。積み重なった面のどこに位置するかを伝えるものです。浮かぶオーバーレイは、ペイン内に平らに配置されたコントロールよりも丸みを強くします。角丸の半径は好みで決めず、階層における面の役割に応じて選びます。（これは集中と一貫性の両方に役立ちます。）

実現方法： エレベーション階層、意図したときに表示（スクロール時の影）。

実例 - 平板な設定行

• 見るもの： 設定行に、ラベル、ヘルプテキスト、「リセット」操作がすべて同じサイズと太さで表示されています。
• 感じること： 集中とは言えず、平板で、視線をどこに向ければよいかわかりません。
• 原則： ひとつを主役にするに反しています。注目の中心がありません。
• 対応： ラベルを最も目立つ文字スタイルにし、ヘルプテキストをbody2に格下げして、「リセット」は控えめな二次操作にすることで、行を上から下へ読めるようにします。

一貫性

6. 同じものは同じ見た目にします

問いかけ： 似たもの同士は同じ見た目ですか？ また、ここに違いがあるとすれば、それは意図的ですか？

同等の要素は、同等の見た目にする必要があります。同じ名前のスケールから値を選ぶためです。似たもの同士に違いがある場合、その違いには意味があるべきです。意図しないずれは避けなければなりません。だからこそ、サイズ、角丸、太さ、色はすべて、リテラル値ではなく役割を持つ名前付きトークンにします。リテラル値は、対応するトークンの仮の値としてのみ使います。

実現方法： 以下のすべての対応が、共有スケールを形作ります。特にデザイントークン、スペーシングスケール、文字スタイルのスケール、アイコンサイズ、一本の線を参照してください。

実例 - 半径が一致しない2つのダイアログ

• 見るもの： 2つのダイアログが並んで開いています。一方の角は8px、もう一方は6pxで、どちらも浮かぶオーバーレイです。
• 感じること： 一貫性がなく、UIにずれが生じているように感じます。
• 原則： 同じものは同じ見た目にする（同等の面が理由もなく異なる見た目です）と、高さは表現で伝える（オーバーレイは最外層に属します）に反しています。
• 対応： 両方を最外層の角丸トークンに合わせます。6pxは、階層の名前を使わずに誰かが入力したリテラル値でした。

楽しさ

7. 喜びには役割がある

問いかけ： これはユーザーに何をできるようにするのでしょうか？

動きや表示、仕上げの工夫を取り入れてもかまいません。ただし、どれも役割を果たす必要があります。視線を導く、操作を確認する、ユーザーの位置を把握しやすくする、あるいは画面遷移をスムーズにする、といった役割です。この問いに答えられないなら、それは装飾であり、ノイズとして受け取られます（Calmに立ち戻りましょう）。控えめで、短く、中断できるものにしてください。prefers-reduced-motionを尊重し、動かすこと自体を目的にしたアニメーションは避けてください。

喜びに関する不具合は、「このトランジションは何の役にも立っていない」（削除する）や、「この画面遷移は戸惑うので、機能的なトランジションが必要だ」（追加する）といったものです。調整するのは、時間やイージングの値ではありません。

実現するもの： 意図に応じて表示する動作。

実例 - バウンスするパネル

• 見た目： サイドパネルを切り替えるたびに、600msのバウンスを伴ってスライド表示されます。
• 印象： Delightful（ギミック）でもCalm（遅く、騒がしい）でもありません。
• 原則： 喜びには役割があるに反しています。バウンスは役割を果たしておらず、切り替え操作もすでに明確です。
• 対応： 位置を把握しやすくする必要がないなら、アニメーションを削除します。パネルの表示を本当に説明する必要があるなら、prefers-reduced-motionを尊重する、短く、控えめで、中断可能なフェードに置き換えます。

---

手段：仕組みをまとめたツールボックス

手段とは、トークン、段階、階層などの具体的な仕組みです。それだけでは、許容値を並べたリストにすぎません。それぞれを使えるものにするのは、どの値を、なぜ選ぶのかを示す判断ルールと、それが支える原則です。手段を使うときは、値そのものではなく、まずルールを示してください。

実装に触れるのは、このセクションだけです。それでも、ここでの目標は会話をデザインについてのものに保つことです。手段は、合意したデザインを一貫して構築するための共通語彙として扱い、レビューの最初に持ち出すものではありません。まず印象と原則を明確にしてから手段を使い、決してそれらの代わりにしないでください。

サイズとフォントのトークンはbaseSizes.tsにあり、全体のリファレンスはdesign-tokens.instructions.mdにあります。

トークンを正とし、ピクセル値を基準にしない

デザインシステムの間隔、角丸、文字の役割、色には、該当する名前付きトークンや段階があれば、それを使用してください。構造上の寸法には、数値を直接指定してもかまいません。

• 判断ルール： 何かがおかしく見えるときは、本来どのトークンで表現すべきかを見つけ、その値ではなく、トークンについて考えます。
• 支える原則： 同じものは同じと伝える（6）。

8pxの角丸は「8px」ではありません。誰かが数値を直接指定した外側サーフェスの角丸です。役割に名前を付ければ、修正方法も見えてきます。

エレベーションの階層 - 数値ではなく役割で丸める

角丸は、サーフェスがその下のものからどれほど浮いているかを表します。角丸のある要素は、必ず次のいずれか1つの階層に属します。

階層	半径	トークン	対象
コントロール	4px	--vscode-cornerRadius-small	ボタン、入力欄、リストの行、タブなどの操作可能な要素
内側	6px	--vscode-cornerRadius-medium	サーフェスの内側に配置される、コントロールではないコンテナー
外側	8px	--vscode-cornerRadius-large	メニュー、ホバー表示、ダイアログ、トーストなどのフローティング／オーバーレイサーフェス

ピル型（半径 ≈ 高さの半分）は「大きな半径」ではなく、完全な円形（--vscode-cornerRadius-circle）です。

• 判断ルール： 角の見た目ではなく、スタック内でのサーフェスの役割に基づいて階層を選びます。ここでの不具合は、*「このオーバーレイはコントロール階層の角丸になっている」というものであり、「border-radiusをもっと大きくする必要がある」*ではありません。
• 支える原則： エレベーションを表現する（5）、余白を確保する（2）。

スペーシングランプ - スケール内かスケール外か

パディング、マージン、ギャップはスペーシングランプ（0、2、4、6、8、10、12、16、20、24、28、32、36、40）から取得します。

• 判断ルール: 値はランプに乗るか乗らないかのどちらかです。スケール外の値（3、5、7、14、26…）はリズムを崩します。最も近いステップにスナップし、中間の場合は切り上げます。リズムのバグは*「これはスペーシングランプから外れています」として報告し、「数ピクセル追加してください」*とは言いません。
• 役立つ原則: 呼吸の余地（2）、同じであることは同じであることを示す（6）。

タイプランプ - 自由なサイズではなく、役割と2つのウェイト

テキストスタイルは任意のサイズではなく役割です: heading1–3、body1–2、label1–3。ウェイトはちょうど2つ - regular（400）とsemiBold（600）です。medium（500）は存在しません。「強」はより大きなサイズではなく、同じ役割トークンをsemiBoldで使うことです。

• 判断ルール: 役割はサイズを目分量で測るのではなく、テキストの階層内での順位で選びます。弱く見える見出しは*「タイプ役割が間違っている」または「semiBoldウェイトが欠けている」のであり、「フォントを14に上げる」*のではありません。どこかに500があればランプ外です。
• 役立つ原則: ひとつが導く（4）、同じであることは同じであることを示す（6）。

アイコンサイズ - コンテキストで選ぶ2つのサイズ

Codiconsは16px（ベース）または12px（コンパクト） - 中間はありません。14pxは常にバグです。コンパクトサイズでは、*Compactグリフ（Codicon.close → Codicon.closeCompact）にも切り替えて、アイコンが単に縮小されるだけでなく光学的に調整されるようにします。

• 判断ルール: サイズはコンテキストの密度と順位に追従します。単独または主要なアクションや快適なクリックターゲットには**ベース（16px）を使用し、密な行、インライングリフ、アイコンがテキストの横に並ぶ二次的なクロームにはコンパクト（12px）*を使用します。つまり「16か12か？」の答えは「ここでのこのアイコンの役割は何か？」であり、好みの判断ではありません。「このアイコンはコンパクトにすべきです」と言い、「少し縮めてください」*とは言いません。
• 役立つ原則: ひとつが導く（4）、同じであることは同じであることを示す（6）。

1本のストローク

標準のボーダー/セパレーターストロークは1px（--vscode-strokeThickness）です。

• 判断ルール: 通常のボーダーが存在するかどうかははい/いいえの判断です。フォーカスインジケーターなど、より太い意味的またはアクセシビリティ上のストロークは維持します。
• 役立つ原則: 静止時は静かに（1）、同じであることは同じであることを示す（6）。

色はテーマから取得する

すべての色は--vscode-*テーマトークンなので、UIはアクティブなテーマとハイコントラストモードに追従します。

• 判断ルール: ハードコードされた16進数は構造上バグです。色のバグは*「間違ったテーマトークン」（または「ライト/HCで消えるトークン」*）であり、微調整すべき16進数の値ではありません。
• 役立つ原則: 静止時は静かに（1）、同じであることは同じであることを示す（6）。

意図に応じて表示する動作

以前は恒久的な塗りつぶしを持っていたクロームは、今では静止時は透明に見え、インタラクション時にのみ表示されます。各動作は役割も果たすため、二重の役割を担います:

• commandCenter - 静止時は透明。ホバー時に背景/ボーダーを表示するので、ポインターがその上にあるものを確認します。

• statusBar - ウィンドウに対して中和され、ホバー時に背景のみが変化し、前景はそのままです。

• keyboardFocusOnly - フォーカスリングはキーボードフォーカス（:focus-visible）で表示され、マウスクリックでは表示されないので、アフォーダンスはまさに役立つときに表示されます。

• scrollShadows - コンテンツはハードな線で切られるのではなく、サーフェスの端の下でフェードするので、折り返しの先にさらにあることを感じられます。

• 役立つ原則: 静止時は静かに（1）、喜びはその価値に見合う（7）、そして（スクロールシャドウ）エレベーションはエンコードされている（5）。

単語と大文字・小文字の使い分け

アイコンよりテキストラベルを優先します。 単語は読めますが、アイコンは推測するものです。意味がほぼ普遍的な場合（閉じる、検索など）や、スペースが本当に限られている場合にだけグリフを使います。それ以外では、対象にラベルを付けるか、認識と想起の両方が必要ならアイコンとラベルを組み合わせます。単独で置かれた謎のグリフは、選び方の悪いアイコンではなくバグです。「この操作にラベルがないので、単語を付ける」と指摘しましょう。「もっと分かりやすいアイコンを探す」ではありません。

センテンスケースで記述します。 ラベル、ボタン、メニュー、メッセージでは、最初の単語と固有名詞だけを大文字にします。「新しいセッションを開始」であり、「新しいセッションを開始」のように各単語を大文字にするわけではありません。こちらのほうが落ち着いた親しみやすい印象になり、すばやく読み取れます。「これはタイトルケースなので、センテンスケースにする」と報告しましょう。これは言い換えではなく、トーンの修正です。

⚠️ 既知の競合 — 後で調整してください。 このセンテンスケースの指針は、現代的な UI に向けた意図された方向性ですが、コマンドラベル、ボタン、メニュー項目にタイトル形式の大文字表記を義務付けているリポジトリ全体のコーディングガイドラインと矛盾しています（coding-guidelines.instructions.md の「UI labels」を参照）。この2つの規則は、まだ調整されていません。調整されるまでは、リリース済みの実験的でない UI では既存のタイトルケースの規則に従い、センテンスケースは、現代的な UI の方向性を明示的に採用している画面でのみ適用してください。TODO：大文字・小文字の使い分けを統一し、採用されなかったほうのドキュメントを更新する。

• 役立つもの： インターフェースが自らを説明する（3）。

---

フレーズ集：バグを説明し、原則を示す

数値ではなく、まず役割／段階／スケールを示し、その後で原則を挙げます。そうすれば、修正がここだけでなく、あらゆる場所に適用されます。数値は症状にすぎません。

❌ こう言わない	✅ こう言う	原則
「border-radiusは8ではなく6にする」	「これは外側の段階で角を丸めた内側のサーフェスです」	5 · 階層
「このメニューの角が尖りすぎている」	「このオーバーレイは外側の半径段階にするべきです」	5 · 階層
「パディングを2px追加する」	「このコンテンツはスペーシングスケールから外れている／スケールに沿った余裕が必要です」	2 · 余裕を持たせる
「これを14pxにする」	「これは**label1／body1のタイポグラフィロール**を使うべきです」	4 · ひとつに絞る
「タイトルが細く見える」	「見出しに**semiBoldのウェイトがありません**」	4 · ひとつに絞る
「ここはfont-weight 500にする」	「500はスケールから外れています。semiBold（600）に合わせます」	6 · 統一
「このアイコンを少し小さくする」	「このアイコンにはコンパクト（12px）サイズと*Compactグリフを使うべきです」	4 · ひとつに絞る
「このアイコンは14pxです」	「codiconは16か12のみです。基本サイズかコンパクトサイズを選びます」	6 · 統一
「この通常の境界線は太すぎる」	「標準の境界線は**1ストローク（1px）**です。ここに必要かどうかを判断し、太いフォーカス／セマンティックストロークはそのままにします」	1 · 通常時は控えめに
「このグレーの16進数カラーを変える」	「これはテーマトークンが間違っています／ライトモードやHCで見えなくなります」	6 · 統一
「コマンドセンターが枠で囲まれている」	「クロームは通常時は控えめにし、ホバー時に表示するべきです」	1 · 通常時は控えめに
「クリックするとフォーカスアウトラインが表示される」	「リングはキーボードフォーカス時のみ表示します（:focus-visible）」	1 · 通常時は控えめに
「リストが下端で途切れている」	「サーフェスにスクロールシャドウのフェードがありません」	7 · 心地よさ／5 · 階層
「ペインのヘッダーに線／硬い縁がある」	「ペインのヘッダーは角丸で、区切り線のないセクションタイトルです」	1 · 通常時は控えめに

フィードバックを伝え、受け取る

ピクセルではなく、デザインについて説明しましょう。 破られているルールを伝えれば、気づいた一箇所だけでなく、同じ問題があるすべての箇所で修正できます。

何かがおかしいと感じたら、次の順番で伝えましょう。

1. 感じ方 - 4つの価値のうち、どれが欠けていますか？ Calm、Focused、Consistent、Delightful。
2. 対象箇所 - どこが、どのようにおかしいですか？ 「サイドバーペインのヘッダー」「保存ダイアログ」など。
3. 破られている原則 - その感じ方の根底にあるルールは何ですか？
4. 修正方法 - その感じ方を取り戻す仕組みは何ですか？
5. 必要であれば、最後に数値を添える - 「4pxに見えますが、6pxがよさそうです。」

例 「アクティビティバーはCalmに感じられません。何も操作していないときに主張が強すぎます。アイコンが常に塗りつぶされていて、エディターの邪魔になっています（何も操作していないときは控えめに、意図した操作には反応する）。ホバー時だけ塗りつぶしを表示できますか？ 余白も約2px狭く見えますが、根本的な問題は塗りつぶしです。」

修正方法ではなく、感じ方から始める

どのピクセルを修正するか意見が一致する前でも、感じ方を表す言葉があれば、全員が同じ原則に目を向けられます。

まずこう伝える	こちらではなく
「これはCalmに感じられません。何も操作していないときに騒がしく見えます」	「背景を透明にしてください」
「これはFocusedではありません。視線を向ける先がありません」	「タイトルを大きくしてください」
「一貫性がありません。この2つのダイアログは見た目が合っていません」	「角丸を6にしてください」
「このトランジションはDelightfulではなく、ただの飾りです」	「アニメーションを速くしてください」

フィードバックを対応しにくくするもの

間違いではありませんが、不十分です。一箇所だけを修正しても、また調和が崩れてしまいます。

• 数値だけを伝える。 「ここは6pxにしてください。」 どのトークンでしょうか？ なぜでしょうか？ 役割と修正方法を伝えれば、該当するすべての箇所で修正できます。
• ルールを伴わない好みの主張。 「この角が好きではありません。」 価値や原則に結びつけ、個人の好みではなく、共有できる基準にしましょう。
• 感じ方を伝えない修正案。 「透明にしてください。」 そうかもしれません。ただし、まず何が問題なのか（「何も操作していないときに騒がしく見える」）を伝え、今回の箇所だけでなく原因を修正しましょう。
• 複数の指摘を一度に伝える。 「このパネルは情報が多すぎるし、グリッドからずれているし、アイコンも違う」 という内容は、それぞれの価値に沿った3つの指摘に分けましょう。

実用的なヒント

• 対象箇所を示す。 スクリーンショット、または短いクリップ（動きに関する場合）にビューの名前を添えると、説明を長々と書くより効果的です。該当箇所に丸を付けましょう。
• スレッドごとに指摘は1つ。 フィードバックは、対象箇所と価値の組み合わせを1つだけにしましょう。それぞれを個別に検討し、解決できます。
• ライト、ダーク、ハイコントラスト。 あるテーマでのみ問題が発生する場合は、そのことを伝えましょう。色の選択ではなく、テーマトークンの問題である可能性が高いです。
• モーションの軽減。 アニメーションについてフィードバックする場合は、prefers-reduced-motion が有効かどうかを記載しましょう。それがなくても、トランジションが適切に機能する必要があります。