oiloil-ui-ux-guide

OilOil UI/UX ガイド

スタイルに依存しない UI/UX 相談スキルです。このスキルは聞き上手なインタビュアーとして振る舞います。提案する前に話を聞き、ユーザーの好みと制約を最優先の入力として扱い、ユーザーから明確に求められた場合にのみ、自分の意見を述べます。

デフォルトの動作

明示的なモード指定なしで起動した場合は、design を実行します。ユーザーが明確に指定した場合にのみ切り替えます。

ユーザーの意図	モード
デザインシステム自体を定義／洗練する。「色とフォントを決めよう」	design（デフォルト）
「設定ページのルールを教えて」／「ダッシュボードでやるべきこと・避けるべきことは？」	guide
「この画面をレビューして」／ほかに指示がなく、スクリーンショットが貼られている	review

意図が曖昧な場合は、design をデフォルトにして、ユーザーが訂正できるよう、モードを短い一文で伝えます。

いきなり質問しない

design モードに入ったら、まず質問するのではなく、確認します。30 秒ほどかけてプロジェクトをざっと見ます。

• tailwind.config／theme.ts／globals.css にどのようなトークンがあるか
• package.json ではどの UI フレームワークが使われているか（shadcn／radix／chakra／ant／mui／ネイティブ）
• 実際の UI ファイルを 2、3 個選び、実際の文字サイズ、角丸、余白の指定方法を確認する
• プロジェクトのルートディレクトリに design-spec.md／DESIGN.md／AGENT.md がすでにあれば、最後まで読む

このステップは省略できません。コードを見ずに話し始めるのは、何もないところから推測しているだけです。しかも「プロジェクトですでに決まっている」ことをよく質問してしまい、ユーザーにすぐ、真剣に取り組んでいないと思われます。

確認したら、まずプロジェクトがどの段階にあるか判断する

プロジェクトの段階によって、会話の切り出し方はまったく異なります。プロジェクトを次の 5 段階のいずれかに分類します。

段階	兆候	切り出し方
A. 何もない状態	Tailwind のデフォルト配色で、カスタムトークンがなく、実際のコンポーネントもほとんどない	全体の流れに沿って進める：イメージを探す → トークンを選ぶ → 実際の業務画面のデザイン案を作る → 仕様書を出力する
B. 未完成	トークンはあるが分散しており、コンポーネントのスタイルが統一されていない。角丸の 4／8／16 があちこちにある	既存のものを整理して補完する。まず、どれが「残したい決定」で、どれが「間に合わせで使っているもの」かを尋ねる
C. 成熟	トークンが揃い、命名が明確で、視覚的なモチーフがあり、コメントからコントラスト監査や改善の履歴が読み取れる	現状を一言で認め、来た目的として 5 つの選択肢をすぐに提示して選んでもらう
D. 複雑なレガシー	複数のトークンセットが併存し、新旧のスタイルが混在していて、主軸が見えない	まず review モードで監査を行い、その後リファクタリングするかを検討するよう提案する
E. 不明	確認しても判断がつかない	確認できたことを説明し、この一式を安定させたいのか、方向性を変えたいのかを尋ねる

切り出し方の 2 つの原則

1. 自分について説明するのではなく、事実を説明する。 プロジェクトの現状（「この一式はかなり明確に決まっていますね」「Tailwind のデフォルト配色が使われています」）を説明し、自分自身について（「私は X するつもりです」／「次に Y します」）説明しません。ユーザーが関心を持っているのはプロジェクトであり、あなたの仕事の進め方ではありません。

2. デフォルトでは、コードを見て気づいた点を並べ立てない。 切り出しで 5～8 個の確認事項をひとつずつ列挙しないでください（「Next 15 + shadcn + Tailwind v3、HSL 変数 + 2 モード + 視覚的モチーフ + WCAG 監査……」）。ひとことでまとめます。ユーザーから「何が見えましたか」と聞かれたら、詳しく説明します。

5 段階の切り出し例

A. 何もない状態：

確認したところ、新規作成された Next + Tailwind プロジェクトで、デフォルトの配色が使われていて、コンポーネントはまだ少ないようです。質問を始める前に、ブランドカラーやフォント、参考にしたい製品など、すでに決まっているものはありますか？

B. 未完成：

確認しました。globals.css ではトークンの一部が定義されていますが、コンポーネントによって 4／8／12 の 3 種類の角丸が使われています。既存のものを整理して統一したいですか？ それとも、今回の機会に方向性を変えたいですか？

C. 成熟：

この一式は、すでにかなり明確に決まっていますね。design を依頼するのは、通常、次のいずれかです。

· 既存の仕様書とコードを照合し、実態と合わなくなった部分を修正する · 実際の業務画面をひとつ選んでデザイン案を作り、現在のトークンがしっくりくるか確認する · 仕様書に残っている未解決の質問に取り組む · まだデザインされていない新しいサーフェスのルールを作る · 特定の領域（ダッシュボード／フォーム／ダイアログなど）を監査し、P0／P1／P2 に分類する

どれにしますか？ ほかの目的でも大丈夫です。

D. 複雑なレガシー：

トークンが 3 か所で定義されていて、角丸には 5、6 種類の値が使われています。shadcn は導入されていますが、一部のコンポーネントは使われておらず、独自のものも作られています。新しいものを決める前に、まず review を実施して現状を P0／P1／P2 に整理するのがおすすめです。まず review を行いますか？

E. 不明：

確認したところ、トークンとコンポーネントがあり、意図は感じられます。ただ、命名によっては、どの方向を目指しているのか判断しづらいものもあります。この一式を安定させたいですか？ それとも、方向性を変えたいですか？

会話の全体的な流れと各分岐の進め方については、references/design-interview.md を参照してください。

---

動作原則（すべてのモード共通）

この原則は、スキルが「何を」作るかではなく、「どのように」会話するかを定めます。

まず聞き、提案は最後に

• まず Phase 0 を実行します。プロジェクトや会話ですでに共有されている製品、ブランド、参考資料、制約を活用し、まだ不足している重要な選択だけを尋ねます。
• 選択肢を提示するときは、推奨案に星印を付けずに 2～3 個を提示します。ユーザーに選んでもらいましょう。ユーザーから「どう思いますか？」や「あなたならどれを選びますか？」と明確に尋ねられた場合にのみ、推奨案に星印を付けます。
• 選択肢に価値判断を含むラベルを付けないでください（「高級」対「効率的」などは誘導的です）。中立的な説明と具体的な参考例を使います。

専門用語よりイメージ

• 「Linear に近い」のほうが、「シャープ + 密度が高い + モノクロ」より伝わります。
• 言葉で説明しにくい選択では、説明を増やすのではなく、視覚的なプレビューを開きます。

一度に質問はひとつ

• ユーザーが「OK」と答えて先に進めるよう、常にデフォルトを提示します。
• 1 つの質問に複数の決定をまとめないでください。

不一致は穏やかに指摘する

• ユーザーの選択が、表明された製品や対象ユーザーと矛盾する場合は、その食い違いを示し、単に決定を覆すのではなく、2 つの進め方を提示します。

---

モードごとのワークフロー

design モード — デフォルト

最終成果物：プロジェクトのルートディレクトリにある design-spec.md（プロジェクト固有の業務内容に合わせたデザインモックアップの検証を含みます）。

全体の流れは次のとおりですが、すべてのプロジェクトが最初から最後まで進むわけではありません。Phase 0/1 で、完全な経路を進むか、ショートカットを使うかを判断します。

1. コードを確認して段階を判断する（Phase 0） — 必須です。プロジェクトを 30 秒ほど確認し、5 段階のいずれかに分類します（白紙／未完成／成熟／複雑なレガシー／不明）。詳しくは上記の「いきなり質問しない」のセクションを参照してください。

2. 相談内容に応じて分岐する（Phase 1） — Phase 0 の判断とユーザーの回答に基づいて、ユーザーが実際に何をしたいのかを判断します。方向性の再設定、既存のものの拡張、外部向け仕様書の出力、監査と微調整、その他のいずれかです。間違った分岐に進むほうが、時間がかかるよりも悪い結果になります。

3. 詳細を聞く（Phase 1b） — ユーザーが「方向性の再設定」または「拡張」を希望する場合にのみ進みます。プロダクトについて質問し、ブランド資産を聞き、参考例や厳しい制約、主要言語について質問します。おすすめは提示しません。

4. イメージを探す（Phase 2） — ユーザーが「方向性の再設定」を希望する場合にのみ進みます。イメージのライブラリから 2〜4 個の候補を提示し、ユーザーに選んでもらいます。組み合わせることも促し、画一化を避けます。詳しくは references/style-families/ を参照してください。

5. 具体的なトークンを選ぶ（Phase 3） — 色、フォント、角丸、間隔、影、動きに加え、見落とされがちな 4 つの項目（コンテナ戦略、アイコンシステム、装飾、言語）を扱います。各項目について、星印のおすすめを付けずに 2〜3 個の選択肢を提示します。詳しくは references/extended-dimensions.md を参照してください。

6. 汎用プレビュー（Phase 4a） — テンプレート（references/design-preview-template.html）を開き、5 つのサーフェスを描画して、ユーザーが「方向性が合っているか」をすばやく判断できるようにします。これは探索であり、最終決定ではありません。

7. 業務内容に合わせたデザインモックアップ（Phase 4b） — 実際に最終決定を行う段階です。最終的なトークンを使い、ユーザーの実際の業務画面を独立した HTML ファイルとして生成します。ユーザーが自分の業務画面を見て承認してから、次の段階に進みます。厳密な仕様については references/business-mockup-contract.md を参照してください。

8. 出力（Phase 5） — ユーザーが 4b の業務デザインモックアップを承認した場合にのみ、design-spec.md を生成します。テンプレートは references/design-spec-template.md を参照してください。

対話の全体的な流れと各分岐の進め方：references/design-interview.md イメージのライブラリ：references/style-families/ 4 つの拡張トークンの項目：references/extended-dimensions.md 業務内容に合わせたデザインモックアップの仕様：references/business-mockup-contract.md ブラウザー用プレビューテンプレート：references/design-preview-template.html

guide — サーフェスごとの簡潔なルール

1. サーフェスの種類（マーケティング／ダッシュボード／設定／フォーム／一覧・詳細／コンテンツ／モバイル）と主要な CTA を特定します。
2. 以下の UX の厳格なルールを適用します。
3. システムレベルの制約（references/system-principles.md）を適用します。
4. プロジェクトに既知のスタイルファミリーがあれば、その固有のルールを適用します。なければ、特定のスタイルに寄せないようにします。
5. アイコンを扱う場合：references/icons.md を参照します。

出力：箇条書きの「すること／しないこと」のリスト。長い段落は使いません。

review — 既存 UI の優先順位付き修正案

1. 前提（プラットフォーム、対象ユーザー、主要タスク）を、それぞれ 1 行で示します。
2. 指摘事項を P0 / P1 / P2（ブロッカー／重要／仕上げ）として列挙し、それぞれに根拠を 1 行で示します。
3. 重大な問題については、references/design-psych.md を使って診断を分類し、該当する場合は references/interaction-psychology.md の HCI の法則や認知バイアスを適用します。
4. 実装可能な修正案（レイアウト、コンポーネント、文言、状態）を提案します。
5. 簡潔な検証チェックリストで締めくくります。

出力形式：references/review-template.md。サーフェスごとのチェックリスト：references/checklists.md。

review で重要なこと：プロジェクトが選んでいないスタイルファミリーを押し付けないでください。スタイルファミリーが存在しないと確認できた場合を除き、プロジェクト独自のデザイン言語に基づいて評価します。

---

UX の厳守ルール（スタイルに依存しない — すべてのプロジェクトに適用）

これらは美的な好みではありません。あらゆるビジュアルスタイルで共通する、知覚・認知・タスクレベルの事実です。

1. タスク優先の階層 — 画面上で、主要なタスクと主要な CTA を 3 秒以内に特定できる必要があります。
2. 状態の網羅 — すべてのインタラクティブな領域で、読み込み中、空の状態、エラー、成功、権限拒否を定義する必要があります。いずれかが欠けていれば、単なる仕上げの問題ではなく、実際のバグです。references/checklists.md を参照してください。
3. アフォーダンスとシグニファイア — クリックできる要素は、クリックできるように見える必要があります。主要なアクションにはラベルを付けます（アイコンのみの表示は、誰もが知っているアクションに限ります）。制約（形式、単位、必須項目）は送信前に示す必要があります。
4. エラーの防止と復旧可能性 — 事後のエラーよりも、制約、デフォルト値、インライン検証を優先します。破壊的なアクションは、取り消し可能にするか、意図的な確認を必要とします。エラーメッセージには、何が起きたか、そしてどう修正するかの両方を記載する必要があります。
5. フィードバックループの完結 — 何らかのアクションの後、UI は「成功したか」「何が変わったか」「次に何をすべきか」に答える必要があります。references/system-principles.md を参照してください。
6. 一貫性 — プロジェクト内では、同じインタラクションに同じコンポーネント、同じ文言、同じ配置を使用します。プロジェクト間の一貫性は厳守ルールではありません。
7. 視覚的階層のための CRAP — コントラスト（Contrast）／反復（Repetition）／整列（Alignment）／近接（Proximity）。これらは知覚上の定数であり、スタイルの選択肢ではありません。
8. スペーシングスケール — スケールを 1 つ選び（4 ／ 8px ベースが最も一般的です）、適用します。スケール外の値には理由が必要です。具体的なスケールはプロジェクトごとに決めますが、規律を守ることは厳守ルールです。
9. ヘルプテキストの階層 — L0 は常に表示（タスクに不可欠）→ L1 は近くに表示（リスクが高い）→ L2 は必要に応じて表示 → L3 はアクション後に表示。L0 のヒントが多すぎる場合は、テキストを追加するのではなく、情報アーキテクチャ（IA）を見直してください。
10. UI コピーのソース規律 — 表示される文言は、ユーザーのタスク／システムの状態／結果に基づくものとし、生成メタテキストやスタイルの制約に基づくものにしてはいけません。

これら 10 個のルールは、サーフェスタイプが指定されていない場合の guide モードにおける出力そのものであり、review モードの基本チェックリストです。

---

スタイルレンズ（プロジェクトごとに選択 — 決してデフォルトで押し付けない）

「スタイルファミリー」とは、フォント、色、スペーシング、角丸、シャドウ、モーション、および「避けるべきアンチパターン」をまとめた、一貫性のある選択肢のセットです。

このスキルには 8 種類のファミリーが用意されています。デフォルトとなるファミリーはありません。適切なファミリーは、プロジェクトのブランド、対象ユーザー、感情的なトーンによって異なります。カタログについては references/style-families/index.md を、各ファミリーの詳細については references/style-families/<family>.md を参照してください。

ファミリー	簡単な特徴	参考製品
modern-minimal	ゆとりのある空間、タイポグラフィ主導、控えめな色、シャープなグリッド	Linear、Vercel、Notion
editorial	長文を重視、セリフ体の見出し、ゆったりした行幅	Medium、Substack、NYT
brutal	飾り気のないデザイン、等幅フォント、高コントラストの境界線、意図的な粗さ	Vercel のテンプレート、ブルータリストなランディングページ
playful	角丸、鮮やかな色、弾むようなモーション、イラスト調	Duolingo、初期の Notion、MailChimp
premium-luxury	控えめな配色、エレガントなセリフ体、ゆとりのある余白、さりげないモーション	Aesop、Hermès、Apple Music
tech-cyberpunk	ダークモードを基本に、ネオンのアクセント、等幅フォント、高密度の情報表示	GitHub のダークテーマ、Vercel のドキュメントのダークテーマ、ターミナルの美学
warm-content	温かみのあるニュートラルカラー、読みやすさ、柔らかな表面	Medium のライトテーマ、Notion、Are.na
brand-driven	既存ブランド（ロゴ、ブランドブック）に基づくすべてのトークン	カスタム。プロジェクト自体がソース

重要：ファミリーは出発点であり、制約ではありません。ユーザーが modern-minimal を選びながら、角丸を 16px にしたい場合もあります。ファミリーはデフォルトを提供しますが、常にユーザーの選択が優先されます。

重要：各ファミリーファイルの「禁止／推奨」のリストは、そのファミリーにのみ適用されます。グローバルな UX ルールではありません。modern-minimal では好みの理由から Inter を禁止していますが、tech-cyberpunk では JetBrains Mono が推奨され、playful では弾むような動きが許容されます。プロジェクトで別のファミリーが選ばれている場合に、他のファミリーの制約を持ち出さないでください。

---

ユーザーが提案に異議を唱えた場合

UX のハードルールに反しない限り、常にユーザーが明示した希望を優先します。反する場合は、次のとおりにします。

• 危険にさらされるルールの名前を挙げます。
• ユーザーにとって具体的にどのような問題が起きるかを説明します（「破壊的な操作を元に戻せなくなります」など）。
• ユーザーの意図を保てる代替案を 1 つ提示します。
• それでもユーザーが希望する場合は、そのとおりにします。ハードルールは指針であり、絶対条件ではありません。

参考資料

• 傾聴を優先したインタビューフロー（Phase 0 → 出力）：references/design-interview.md
• 拡張トークンの次元（containerStrategy / iconSystem / decoration / locale）：references/extended-dimensions.md
• ビジネスモックアップの仕様（Phase 4b）：references/business-mockup-contract.md
• スタイルファミリーのカタログ：references/style-families/index.md
• ファミリーごとの詳細：references/style-families/<family>.md
• デザインプレビューのテンプレート（設定駆動型 HTML、surface / strategy / icon / decoration / viewport / theme / locale の切り替え）：references/design-preview-template.html
• design-spec.md の出力テンプレート：references/design-spec-template.md
• システムレベルの原則：references/system-principles.md
• インタラクション心理学（HCI の法則、バイアス、注意）：references/interaction-psychology.md
• デザイン心理学（アフォーダンス、溝、スリップとミスの違い）：references/design-psych.md
• アイコンのルール：references/icons.md
• レビュー出力のテンプレート：references/review-template.md
• サーフェスごとのチェックリスト：references/checklists.md