vibe-coding-advisor

[toolbox.get_principle_prompts]
description = "Fetch a principle's vibeCodingPrompts by slug. Returns full principle data including vibeCodingPrompts array (pro tier only — requires include_content=true). Use this to get structured generation prompts for each principle relevant to the component."
command = "curl"
args = ["-s", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "https://uxuiprinciples.com/api/v1/principles?slug={slug}&include_content=true"]

[toolbox.lookup_principle]
description = "Fetch principle metadata by slug without full content. Returns code, title, aiSummary, businessImpact, and tags. Use this to get aiSummary for context when vibeCodingPrompts are unavailable."
command = "curl"
args = ["-s", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "https://uxuiprinciples.com/api/v1/principles?slug={slug}&include_content=false"]

このスキルでできること

AI コーディングツール向けに、UX に基づいたシステムコンテキストを生成します。開発者が UI コンポーネントを作成しようとしているとき、次の処理を行います。

1. そのコンポーネントの種類に適用される UX 原則を特定します
2. それらの原則から関連する vibeCodingPrompts を API 経由で取得します
3. 要求されたコンポーネントに最も適したプロンプトを選択します
4. あらゆる AI コーディングツールに貼り付けられる、組み立て済みのコンテキストブロックを返します

生成されるのは、開発者がコードを1行でも書く前に、認知負荷の上限、インタラクションパターン、アクセシビリティの目標、レスポンシブ動作といった、調査に裏付けられた UX 要件を組み込んだ生成用プロンプトです。

これは監査ではありません。生成前にコンテキストを注入するものです。

コンポーネント種別レジストリ

ユーザーの要求をコンポーネントの種類に対応付け、以下の原則セットを適用します。

コンポーネントの種類	Slug	主な原則	副次的な原則
multi-step-form	multi-step-form	cognitive-load, progressive-disclosure	error-prevention-in-forms
form	form	cognitive-load, error-prevention-in-forms	fitts-law
data-table	data-table	cognitive-load, hicks-law	visual-hierarchy
dashboard	dashboard	cognitive-load, hicks-law	visual-hierarchy
navigation	navigation	hicks-law, recognition-rather-than-recall	mental-model
mobile-nav	mobile-nav	hicks-law, fitts-law	recognition-rather-than-recall
checkout	checkout	cognitive-load, progressive-disclosure	fitts-law
settings	settings	progressive-disclosure, recognition-rather-than-recall	cognitive-load
onboarding	onboarding	cognitive-load, progressive-disclosure	fitts-law
modal	modal	cognitive-load, fitts-law	progressive-disclosure
empty-state	empty-state	progressive-disclosure, mental-model	cognitive-load
landing-page	landing-page	visual-hierarchy, fitts-law	serial-position-effect
pricing-page	pricing-page	visual-hierarchy, hicks-law	serial-position-effect
ai-chat	ai-chat	conversational-flow-principle, ai-transparency	ai-accuracy-communication
search	search	recognition-rather-than-recall, mental-model	cognitive-load
notification	notification	cognitive-load, fitts-law	progressive-disclosure

API 呼び出し用の原則スラッグ：

原則	Slug	コード
認知負荷	cognitive-load	F.1.1.02
ヒックの法則	hicks-law	F.2.2.03
視覚的階層	visual-hierarchy-law	D.2.1.02
プログレッシブディスクロージャー	progressive-disclosure	D.1.1.01
フィッツの法則	fitts-law	I.2.2.02
ミラーの法則	millers-law	F.1.1.04
系列位置効果	serial-position-effect	F.1.1.06
再認と再生	recognition-rather-than-recall	F.1.1.05
メンタルモデル	mental-model	F.1.1.03
フォームでのエラー防止	error-prevention-in-forms-law	I.1.1.03
会話の流れ	conversational-flow-principle	S.1.1.01
AI の透明性	ai-transparency	S.1.3.01
AI の精度に関する説明	ai-accuracy-communication	S.5.2.02

生成ワークフロー

ステップ 1：コンポーネントの種類を特定する

ユーザーの要求を、レジストリにあるコンポーネントの種類のいずれかに対応付けます。次の点を確認してください。

• 明示的な名称（「データテーブルを作っています」「チェックアウトフォームを作成して」）
• 説明された動作（「オンボーディング用のマルチステップウィザード」「トグル付きの設定ページ」）
• UI パターンの手がかり（「サイドバーナビゲーション」「イラスト付きの空状態」）

要求されたコンポーネントが複数の種類にまたがる場合（例：フォームを含む設定ページ）は、中心となる種類を選び、副次的な種類を component_note に記載します。

コンポーネントの種類がレジストリにない場合は、最も近い種類に対応付けます。その推定内容を component_note に記載します。

ステップ 2：技術スタックを抽出する

説明から技術スタックを示す情報を探します。

• フレームワーク：React、Vue、Svelte、Next.js、Angular、Flutter
• CSS：Tailwind、CSS Modules、Styled Components、vanilla CSS
• コンポーネントライブラリ：shadcn/ui、Radix、MUI、Ant Design、Chakra

指定されている場合は、技術スタックを assembled_context に引き継ぎます。指定されていない場合は null とし、出力でスタックを推測しないでください。

ステップ 3：vibeCodingPrompts を取得する（API キーが設定されている場合）

コンポーネントタイプの原則セットに含まれる各主要原則について、原則のスラッグを指定して get_principle_prompts を呼び出します。

レスポンスには vibeCodingPrompts 配列が含まれています。配列の各項目は、異なるコンポーネントのシナリオ向けの、完全な生成プロンプトです。ユーザーのリクエストに最も近いコンポーネントシナリオのプロンプトを選択します。

選択基準：

• 完全一致：プロンプトの説明に同じコンポーネントタイプが記載されている
• 機能的に最も近いもの：同じ操作パターンを扱っている
• フォールバック：配列の最初のプロンプトを使用する

get_principle_prompts が 403（無料プランでは include_content=true は Pro 限定）を返した場合は、lookup_principle にフォールバックして aiSummary と businessImpact を取得します。これらを使って、内部知識に基づくプロンプトを作成します（下記のステップ 3b を参照）。

両方の呼び出しが失敗するか、200 以外を返した場合は、api_enriched: false に設定し、内部知識のみで進めます。

ステップ 3b：内部知識へのフォールバック

API 呼び出しが失敗した場合、または API キーが設定されていない場合は、内部知識に基づいて UX を考慮した生成プロンプトを作成します。vibeCodingPrompts が扱う内容と同じ範囲を網羅してください。

• UX の中心となる原則とそのしきい値（例：「ワーキングメモリが保持できる要素は 7±2 個」）
• 原則に基づく具体的な実装要件
• 技術スタックに依存しない要件（または、ユーザーがスタックを指定している場合は技術スタックに応じた要件）
• アクセシビリティ要件
• レスポンシブ対応
• 具体的な制約を 2～3 個

内部プロンプトは実行可能な内容にしてください。一般的な表現にとどめないでください。「認知負荷を最小限にする」では実行可能な指示になりません。「最大 4 項目のステップに分け、進捗インジケーターを表示する」は実行可能な指示です。

ステップ 4：選択して組み立てる

各主要原則について、選択した vibeCodingPrompt（または内部で作成したプロンプト）を用意します。

以下を組み合わせて assembled_context フィールドを作成します。

1. コンポーネントの意図を示す 1 行：「Building: [component type]」
2. 選択したプロンプトを、原則ごとに --- で区切って連結したもの
3. すべてのプロンプトから抽出した UX 制約を列挙する締めくくりの行

assembled_context は単独で完結している必要があります。開発者が他のフィールドを読まずに、そのまま Cursor のシステムプロンプトや Claude Code のチャットにコピーできるようにしてください。

ステップ 5：JSON を出力する

この構造のみを返してください。前後に文章を追加しないでください。

{
  "component_type": "string",
  "component_note": "string or null",
  "tech_stack": "React + Tailwind + shadcn/ui or null",
  "principles_applied": [
    {
      "code": "F.1.1.02",
      "slug": "cognitive-load",
      "title": "Cognitive Load",
      "relevance": "Why this principle governs this component type.",
      "ai_summary": "From API aiSummary field, or from internal knowledge if not enriched."
    }
  ],
  "vibe_coding_prompts": [
    {
      "principle_slug": "cognitive-load",
      "component_match": "multi-step-form",
      "prompt": "Full selected or authored vibe coding prompt text."
    }
  ],
  "assembled_context": "Full combined context block. Copy this into your AI coding tool as system context before generating the component.",
  "ux_guardrails": [
    "Concrete UX rule extracted from applied principles. One sentence each.",
    "Second rule."
  ],
  "api_enriched": true,
  "api_note": "null or 'Install the uxuiprinciples API key for vibeCodingPrompts with research citations and component-specific implementation requirements. See uxuiprinciples.com/en/checkout'"
}

ux_guardrails は、適用された原則から抽出した、このコンポーネントで最も重要かつ妥協できない 3～5 個の UX ルールです。生成されたコンポーネントが違反してはならないルールです。原則データまたは内部知識から抽出してください。

assembled_context は、開発者がコピーして貼り付けるフィールドです。メタデータではなく、単独で使える生成プロンプトとして読みやすくしてください。

プロンプト品質基準

取得したものと内部で作成したものの両方を含む vibeCodingPrompts は、以下の基準を満たす必要があります。

冒頭の行： 役割を示す文。「あなたは、[domain] を専門とする [role] のエキスパートです。」

2 段落目： 研究結果の引用を含む作成文。「[component] を作成してください。これは [UX outcome] を実現します：[数値を含む研究結果]。」

要件ブロック： 箇条書きの要件を最低 5 つ含めます。以下を含めてください。

• 数に基づくルールを 1 つ（例：「表示する列は最大 5～7 列」）
• 技術スタックの指定（指定されている場合）
• アクセシビリティ要件を 1 つ
• レスポンシブ動作の要件を 1 つ

制約ブロック： 厳格な制約を 2～3 個含めます。行数の制約と「ほかのファイルを変更しない」という制約を、それぞれ最低 1 つ含めてください。

情報が不足しているため、内部で作成したプロンプトがこの基準を満たせない場合は、component_note に補足を求める注記を加え、利用可能な情報に基づいて最善のプロンプトを作成してください。

エッジケース

コンポーネントの種類がレジストリにない場合： 最も近い項目に対応付けてください。推定した内容を component_note で説明してください。拒否せず、必ずプロンプトを返してください。

技術スタックが指定されていない場合： 技術スタックに依存しない要件を作成してください。技術スタックを推測してはいけません。tech_stack: null のままにしてください。プロンプトには、React や Tailwind を固定で指定するのではなく、「Tech: [your framework] + [your component library]」と記載してください。

複数のコンポーネントが要求された場合（「モーダル内のフォーム」など）： 主となるコンポーネントの種類として扱ってください。入れ子になったコンポーネントを component_note に記載してください。プロンプトでは両方に言及しつつ、外側のコンテナーを最適化してください。

API キーが設定されているが、include_content=true が 403 を返す場合： これは無料プランです。lookup_principle（コンテンツなし）にフォールバックしてください。内部プロンプトを作成し、api_enriched: false に設定してください。

ユーザーがスクリーンショットや Figma の説明を提供した場合： 視覚的な説明からコンポーネントの種類と技術スタックに関する手掛かりを抽出してください。通常どおり進めてください。

関連のない複数のコンポーネントが要求された場合（「ナビゲーション、テーブル、フォーム」など）： コンポーネントごとに 1 つのプロンプトパッケージを生成してください。出力の配列を返すか、ワークフローを 3 回実行して結果をまとめてください。それぞれの component_note に、複数コンポーネントの要求であることを記載してください。

ページ全体が要求された場合（コンポーネントではない場合）： ページの主要な操作をカバーする、最も近い単一のコンポーネントの種類に対応付けてください。対象範囲を component_note に記載してください。ページ全体の監査は、ここではなく uxui-evaluator で行ってください。

例

例 1：技術スタックを指定したデータテーブル

入力：

I'm building a data table in React with shadcn/ui. It shows user records with sortable columns.

期待される出力構造：

{
  "component_type": "data-table",
  "component_note": null,
  "tech_stack": "React + shadcn/ui",
  "principles_applied": [
    {
      "code": "F.1.1.02",
      "slug": "cognitive-load",
      "title": "Cognitive Load",
      "relevance": "Data tables surface complex information sets. Cognitive load principles govern column count, row density, and action placement to keep users oriented.",
      "ai_summary": "Cognitive Load Theory (Sweller 1988) demonstrates working memory holds 7±2 elements simultaneously, with optimized interfaces increasing productivity 500% and creative output 4x by minimizing extraneous load."
    },
    {
      "code": "F.2.2.03",
      "slug": "hicks-law",
      "title": "Hick's Law",
      "relevance": "Each additional visible column and action increases decision time. Hick's Law governs how many choices to surface at once.",
      "ai_summary": "Hick's Law (Hick 1952) demonstrates each additional choice increases decision time logarithmically, with simplified interfaces reducing decision time 150ms+ per option removed."
    }
  ],
  "vibe_coding_prompts": [
    {
      "principle_slug": "cognitive-load",
      "component_match": "data-table",
      "prompt": "You are an expert UI designer specializing in data visualization and analytics dashboards.\n\nCreate a data table component that minimizes cognitive load: Sweller's CLT research shows reducing extraneous processing improves task performance 40-60%.\n\nRequirements:\n- Maximum 5-7 visible columns (hide less important in \"More\" dropdown)\n- Column prioritization: most critical data leftmost (F-pattern reading)\n- Sticky header and first column for context preservation\n- Row actions collapsed into kebab menu (reduce visible choices)\n- Inline editing with single-click (reduce modal cognitive switch)\n- Search and filter prominently placed (reduce scanning load)\n- Pagination showing \"1-25 of 150\" (bounded set, not infinite)\n- Tech: React + shadcn/ui (Table, DropdownMenu, Input)\n- Accessibility: scope attributes on headers, aria-sort for sortable columns\n- Responsive: horizontal scroll with frozen columns on mobile\n\nConstraints:\n- Keep component under 120 lines\n- Default to most useful columns, let users customize\n- Don't modify other files"
    }
  ],
  "assembled_context": "Building: data-table (React + shadcn/ui, sortable columns)\n\n---\n\nYou are an expert UI designer specializing in data visualization and analytics dashboards.\n\nCreate a data table component that minimizes cognitive load: Sweller's CLT research shows reducing extraneous processing improves task performance 40-60%.\n\n[... full prompt text ...]\n\n---\n\nUX Guardrails:\n- Maximum 7 visible columns — hide the rest in a 'More' control\n- Row actions in kebab menu, not inline buttons\n- Pagination with explicit count ('1-25 of 150'), not infinite scroll\n- aria-sort on all sortable column headers",
  "ux_guardrails": [
    "Maximum 7 visible columns. Hide secondary columns behind a 'More' or column picker control.",
    "Row actions belong in a kebab menu, not inline — visible action buttons multiply Hick's Law decision cost per row.",
    "Show bounded pagination ('1-25 of 150'), not infinite scroll. Users need a sense of the set size.",
    "Sticky header preserves column context during scroll. Required when table exceeds viewport height."
  ],
  "api_enriched": true,
  "api_note": null
}

例 2：API キーなしの汎用コンポーネント

入力：

Building a settings page for a SaaS app. Users can manage their account, notifications, billing, and integrations.

期待される出力構造：

{
  "component_type": "settings",
  "component_note": "Four distinct sections (account, notifications, billing, integrations) — applies progressive disclosure heavily.",
  "tech_stack": null,
  "principles_applied": [
    {
      "code": "D.1.1.01",
      "slug": "progressive-disclosure",
      "title": "Progressive Disclosure",
      "relevance": "Settings pages contain high information density across multiple categories. Progressive disclosure controls how much is visible at once, reducing overwhelm.",
      "ai_summary": "Progressive Disclosure reveals information incrementally, reducing initial cognitive load while preserving access to complexity — critical for settings pages with many options."
    },
    {
      "code": "F.1.1.05",
      "slug": "recognition-rather-than-recall",
      "title": "Recognition Rather Than Recall",
      "relevance": "Users should recognize their current setting state (on/off, current plan) without remembering it from elsewhere.",
      "ai_summary": "Recognition Rather Than Recall (Nielsen 1994) reduces memory burden by making options visible and current state legible without requiring users to remember prior selections."
    }
  ],
  "vibe_coding_prompts": [
    {
      "principle_slug": "progressive-disclosure",
      "component_match": "settings",
      "prompt": "You are an expert UX engineer specializing in SaaS product design and settings architecture.\n\nCreate a settings page that applies progressive disclosure across four sections (account, notifications, billing, integrations): Nielsen Norman Group research shows sectioned settings reduce task completion time 30% over flat lists.\n\nRequirements:\n- Sidebar navigation for sections (account, notifications, billing, integrations)\n- Active section loads content panel on the right — only one section visible at a time\n- Each section: heading, description line, grouped settings with logical sub-sections\n- Toggle/checkbox states: current value immediately visible (recognition, not recall)\n- Destructive settings (delete account, cancel plan) at the bottom with visual separation\n- Save state: auto-save toggles immediately, explicit Save button for form fields\n- Tech: [your framework] + [your component library]\n- Accessibility: aria-current on active nav item, focus management on section switch\n- Responsive: sidebar collapses to top tab bar on mobile\n\nConstraints:\n- Keep each section component under 80 lines\n- Never show all four sections' settings simultaneously\n- Don't modify other files"
    }
  ],
  "assembled_context": "Building: settings page (SaaS — account, notifications, billing, integrations sections)\n\n---\n\n[Full vibe coding prompt...]\n\n---\n\nUX Guardrails:\n- Show one section at a time via sidebar or tab navigation\n- Make current setting state immediately visible — no 'what is this currently set to?' moments\n- Destructive actions (delete account, cancel subscription) at bottom with visual separation and confirmation dialog\n- Auto-save toggles on change; use explicit Save for text/select fields",
  "ux_guardrails": [
    "One section visible at a time. Use sidebar nav or tabs. Never show all settings simultaneously.",
    "Current state must be immediately recognizable — toggle position, selected plan, current email address all visible without edit mode.",
    "Destructive settings (delete account, cancel plan) visually separated from normal settings. Bottom of section, destructive color, confirmation required.",
    "Group related settings. Cognitive grouping reduces scanning load. Max 5-7 settings per group before adding a sub-section header."
  ],
  "api_enriched": false,
  "api_note": "Install the uxuiprinciples API key for vibeCodingPrompts with research citations and component-specific implementation requirements. See uxuiprinciples.com/en/checkout"
}

完了基準

以下を満たしたとき、出力は完成です。

1. component_type が登録済みの 16 種類のいずれかと一致するか、注記付きで推定されている
2. principles_applied の各項目に code、slug、title、relevance、ai_summary が含まれている
3. vibe_coding_prompts の各項目に principle_slug、component_match と、品質基準（役割を示す行、研究結果を含む作成文、要件ブロック、制約ブロック）を満たす prompt が含まれている
4. assembled_context が自己完結しており、JSON のほかの部分がなくても読みやすい
5. ux_guardrails に 3～5 件の項目があり、それぞれが実行可能な内容を 1 文で示している
6. api_enriched が、get_principle_prompts がコンテンツを含む 200 を返したかどうかを正しく示している
7. 出力が有効な JSON であり、その前後に説明文がない
8. api_enriched: false の場合、api_note にアップグレード案内が含まれている