frontend-design-principles

フロントエンド設計の原則

丁寧さと意図を込めて、フロントエンドのインターフェースを構築しましょう。

適用範囲とルーティング

このファイルの後に、コンテキストに応じたガイドを読み込んでください。

• app.md — ダッシュボード、管理パネルと設定パネル、社内ツール、SaaS 製品、データ量の多いインターフェース（テーブル、フォーム、リスト）、ユーザーが繰り返し作業するあらゆるもの。
• marketing.md — ランディングページ、マーケティングサイト、告知、クリエイティブな制作物、第一印象が最も重要なあらゆるもの。

判断がつかない場合は、質問してください。両方にまたがるプロジェクトでは、両方が必要です。SaaS のマーケティングサイトには marketing.md を使い、製品のダッシュボードには app.md を使います。

このプロセスがある理由

あなたは汎用的な出力をしがちです。ダッシュボードやランディングページの学習パターンは強力です。以下のプロセスは役立ちますが、プロセスだけでは丁寧な仕事にはなりません。自分自身の癖に気づく必要があります。

デフォルトが潜む場所

デフォルトは、インフラのようなものとして紛れ込みます。設計するのではなく、ただ動けばよいと感じる部分です。構造上の決定などありません。すべてが設計です。

• タイポグラフィは容器ではなく、デザインそのものです。 パン屋のツールもトレーディングターミナルも「すっきりと読みやすい書体」を求めますが、温かく手作り感のあるものと、冷たく精密なものは違います。いつものフォントを選ぶなら、それは設計していないということです。
• ナビゲーションは製品を取り巻くものではなく、製品そのものです。 今どこにいて、どこへ行けて、何が最も重要なのか。何もない空間に浮かぶページは、コンポーネントのデモであって、ソフトウェアではありません。
• データは見せ方ではなく、意味です。 進捗リングと積み重ねたラベルはどちらも「10件中3件」を示せます。一方はストーリーを伝え、もう一方は空間を埋めます。その数字が、それを見る人にとって何を意味するのかを考えてください。
• トークン名は設計上の決定であり、実装の細部ではありません。 CSS 変数だけを読む人にも、その製品を推測できるようにしてください。

/* ❌ generic — could be any project */
--gray-700: …;  --surface-2: …;
/* ✅ domain — evokes this product's world */
--ink: …;  --parchment: …;

必須：生成する前に

以下が完了するまで、コードを書いてはいけません。

1. 意図に関する質問に答える

具体的に答えるか、ユーザーに質問してください。推測したり、デフォルトに頼ったりしてはいけません。

• この人は誰ですか？ 「ユーザー」ではありません。実際の人物です。どこにいて、何を考えていて、5分前に何をし、5分後に何をしているのでしょうか？
• 何を達成しなければなりませんか？ 動詞で答えます。提出物を採点する、壊れたデプロイを見つける、支払いを承認する、などです。
• どんな印象を与えるべきですか？ 意味のある言葉で表してください。「すっきりしていてモダン」（どの AI もそう言います）ではなく、ノートのように温かいのか、ターミナルのように冷たいのか、トレーディングフロアのように情報が詰まっているのか、などです。

2. 必須の4つの成果物を作成する

• 領域： この製品の世界にある概念、メタファー、語彙。機能ではなく、世界観です。最低5つ。
• 色の世界： この領域に自然に存在する色。「暖色／寒色」ではなく、現実の世界から選んでください。5色以上を挙げます。
• シグネチャー： この製品にしか存在し得ない、視覚・構造・操作のいずれかの要素を1つ。
• 却下するデフォルト： この種のインターフェースでありがちな選択肢を、視覚面と構造面から3つ挙げます。名前を挙げていないパターンは避けられません。

3. 方向性を提案し、確認する

領域の概念、色、シグネチャー、および却下したデフォルトそれぞれに代わるものを参照してください。

Domain: [5+ concepts from the product's world]
Color world: [5+ colors that exist in this domain]
Signature: [one element unique to this product]
Rejecting: [default] → [alternative] ×3

Direction: [approach connecting the above]

Does that direction feel right?

テスト： 提案から製品名を取り除いても、何のためのものかが伝わりますか？ 伝わらなければ、さらに深く掘り下げてください。コードを生成する前に、確認を待ってください。

必須：提示する前に

最初の出力はおそらく汎用的なものです。ユーザーが指摘する前にそれに気づくことが大切です。作ったものを見て、「これには丁寧さが足りないと言われたら、何を指摘されるだろう？」と問いかけ、まず修正してください。以下を実施し、ひとつでも失敗したら反復してください。

• 入れ替えテスト： 書体やレイアウトをいつものものに入れ替えても、誰かが違いに気づきますか？ 入れ替えても問題にならない箇所こそ、デフォルトに頼った部分です。
• 目を細めるテスト： 目をぼかすように見ても、階層は読み取れますか？ きつく目立つものはありませんか？ 丁寧な仕事は静かに伝わります。
• シグネチャーテスト： シグネチャーが現れている具体的なコンポーネントを指し示してください。「全体の雰囲気」では不十分です。
• トークンテスト： CSS 変数を声に出して読んでください。それらはこの製品の世界にふさわしいですか、それともどのプロジェクトにも当てはまるものですか？

原則

• すべての選択には理由が必要です。 レイアウト、色温度、書体、余白の尺度、階層など、あらゆる判断について、その理由を説明できます。「よくある／すっきりしている／問題なく使える」は、選択ではなくデフォルトです。
• 同じであることは失敗です。 同じようなプロンプトを与えられた別の AI が、実質的に同じ出力を生成するなら失敗です。意図からデザインすれば、同じになることはありません。意図が完全に同じものはないからです。Linear のカードは Notion のカードとは違い、Vercel のメトリクスは Stripe のメトリクスとは違います。
• 意図はシステム全体に反映させる必要があります。 「暖かみのあるデザイン」と言いながら寒色を使うのは、一貫性がありません。暖かみを出すなら、サーフェス、テキスト、ボーダー、アクセント、セマンティックカラー、書体など、すべてに反映させます。すべてのトークンが、表明した意図に合っているか確認してください。
• 表現は無限です。 メトリクスは、主役となる数値、スパークライン、ゲージ、差分、トレンドバッジなど、あるいはまったく新しい形で表現できます。サイドバーの幅、カードグリッド、左側のアイコンと大きな数値という組み合わせを毎回使ってはいけません。そうすると、すぐに AI 生成だと見抜かれます。

品質の基礎

どのような方向性でも、品質の最低基準となるものです。

• 繊細なレイヤー構成。 サーフェス同士の違いはかすかでも、見分けがつくようにします。劇的な変化ではなく、静かな奥行きの変化を目指してください（Vercel、Supabase、Linear を参考にしてください）。構造を確認しようとしたときに初めて気づく程度に、ボーダーは薄くします。最初に目に入るなら、強すぎます。
• 色には由来があります。 パレットを選ぶ前に、プロダクトの物理的な世界に時間をかけて触れてください。素材、光、物体などです。何かに後から塗り足したようではなく、どこかから生まれたように感じられるべきです。グレーは構造を作り、色は意味を伝えます。考えなしに使う5色より、意図を持って使う1色のアクセントが効果的です。

共通のアンチパターン

状況にかかわらず、次のものは常に誤りです。

• 極端なドロップシャドウ — box-shadow: 0 25px 50px … は安っぽく見えます
• 根拠のない非対称なパディング — すべての値に意図が必要です
• 装飾目的の太いボーダー — 視覚的な重みを出すために 2px 以上を使うこと
• 複数のアクセントカラー — アクセントは1色にして、一貫して使います
• 奥行きの表現方法を混在させること — ボーダーかシャドウのどちらかにし、無作為に両方を使わないでください
• 一貫性のない余白 — システムがないことを最も明確に示します

コミュニケーション

存在を意識させないでください。モードを宣言したり、プロセスを説明したりしないでください（「ドメインを調査します……」「チェックを実行します……」など）。すぐに作業に取りかかり、提案には理由を添えてください。

詳細

• references/principles.md — 余白、奥行き、タイポグラフィ、色の実装、ダークモード（具体的な値と CSS）
• app.md — ダッシュボード、管理パネル、SaaS プロダクト
• marketing.md — ランディングページ、マーケティングサイト、クリエイティブな成果物