uxui-evaluator

[toolbox.lookup_principle]
description = "Fetch principle metadata by slug from the uxuiprinciples API. Returns code, title, aiSummary, businessImpact, tags, and difficulty. Pro tier returns all 195 principles; free tier returns 12."
command = "curl"
args = ["-s", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "https://uxuiprinciples.com/api/v1/principles?slug={slug}&include_content=false"]

[toolbox.list_principles_by_part]
description = "List all principles for a framework part. Parts: part-1 through part-6."
command = "curl"
args = ["-s", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "https://uxuiprinciples.com/api/v1/principles?part={part}"]

[toolbox.audit]
description = "Run a full structured audit of an interface description against 195 UX principles. Returns findings, severity, remediation, smells detected, strengths, and an overall score. Requires API key (pro tier)."
command = "curl"
args = ["-s", "-X", "POST", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "-H", "Content-Type: application/json", "-d", "{\"description\": \"{input}\"}", "https://uxuiprinciples.com/api/v1/audit"]

このスキルの機能

uxuiprinciples フレームワークに照らして、インターフェースの説明を評価します。このフレームワークは、6 つのパートに分類された、調査に裏付けられた 195 の UX/UI 原則で構成されています。文章ではなく、構造化された JSON 形式の調査結果を返します。各調査結果には、具体的な原則、深刻度、何が、なぜ違反されているのか、そして具体的な改善策を記載します。

UXUI_API_KEY が設定されている場合は、最初に audit を呼び出します。API から、完全に構造化された結果が直接返されます。個々の調査結果をさらに詳しくする場合や、audit を利用できない場合は、lookup_principle と list_principles_by_part を使用します。

UXUI_API_KEY が設定されていない場合は、内部知識を使ってフレームワークを適用し、出力にその制約を明記します。

フレームワークの構造

6 つのパートからなる分類体系は、以下を網羅しています。

Part	分野	主な原則
Part 1	基礎	認知負荷（F.1.1.02）、ミラーの法則（F.1.1.04）、チャンク化、ヒックの法則（F.2.2.03）、メンタルモデル（F.1.1.03）、系列位置（F.1.1.06）効果
Part 2	基本原則	エラーの防止（C.1.4.01）、一貫性と標準（C.1.1.01）、フィードバックループ、ユーザー制御、ヘルプとドキュメント
Part 3	デザインシステム	プログレッシブディスクロージャー（D.1.1.01）、視覚的階層（D.2.1.02）、タイポグラフィ、色、コンテンツ階層、余白
Part 4	インターフェースパターン	フィッツの法則（I.2.2.02）、フォームにおけるエラーの防止（I.1.1.03）、タッチターゲット、モバイルナビゲーション、レスポンシブデザイン
Part 5	AI ネイティブおよび特化型	会話の流れ（S.1.1.01）、AI の透明性（S.1.3.01）、認知負荷の調整（F.1.3.01）、自動化バイアスの防止
Part 6	人間中心設計	アクセシビリティ、インクルーシブデザイン、信頼性を示す要素、感情に訴えるデザイン、倫理的なパターン

原則コードは F.[part].[chapter].[sequence] の形式です。例：F.1.1.02 は、パート 1、第 1 章、原則 02（認知負荷）を表します。

評価のワークフロー

以下の手順を順番どおりに実行してください。手順を省略しないでください。

ステップ 1：インターフェースを分類する

説明からインターフェースの種類を特定します。以下から 1 つ選びます：dashboard、form、onboarding、modal、navigation、settings、landing-page、checkout、empty-state、data-table、ai-chat、mobile-app、email、documentation。

種類が曖昧な場合は、最も近いものを選び、interface_type_note に記載します。

ステップ 2：関連するパートを選択する

インターフェースの種類に応じて、評価するフレームワークのパートに優先順位を付けます。

• dashboard：パート 1、2、4
• form / checkout：パート 1、3、4
• onboarding：パート 1、3、4、6
• navigation：パート 1、2、4
• ai-chat：パート 1、5、6
• modal：パート 1、3
• landing-page：パート 2、3、4、6

インターフェースの種類にかかわらず、必ずパート 1（基礎）を評価します。

ステップ 3：違反を特定する

選択した各パートについて、原則が違反されている、リスクにさらされている、または適切に適用されている兆候がないか、説明を確認します。以下を探します。

• 情報密度の兆候（要素、選択肢、手順の数）
• 視覚的な構成の兆候（階層、グループ化、余白）
• インタラクションの兆候（CTA、アフォーダンス、フィードバック）
• 信頼性と明確さの兆候（文言、エラーメッセージ、空の状態）
• AI 固有の兆候（信頼度の表示、人による上書きが可能な箇所）

ステップ 4：Toolbox で補完する（API キーが設定されている場合）

推奨パス： {"description": "<interface description>"} を指定して audit を呼び出します。レスポンスは完全に構造化された監査結果です。そのまま出力として使用してください。audit が 200 を返した場合は、ステップ 5 と 6 をスキップします。

フォールバックパス： audit が利用できない場合、またはエラーを返した場合は、ステップ 3 で見つかった違反ごとに lookup_principle を呼び出します。返された aiSummary と businessImpact のフィールドを使用して、message と business_impact を設定します。

すべてのツール呼び出しが失敗するか、200 以外を返した場合は、補完せずに続行します。api_enriched: false を設定します。

一般的な原則のスラッグ：

• cognitive-load、hicks-law、millers-law、chunking、working-memory
• progressive-disclosure、fitts-law、serial-position-effect
• visual-hierarchy、law-of-proximity、figure-ground
• recognition-rather-than-recall、mental-model
• cognitive-load-calibration-ai、automation-bias-prevention

ステップ 5：スコアと評価ランク

0 から 100 のスコアを付けます。100 から開始し、以下の点数を差し引きます。

• critical の指摘：-15 点
• warning の指摘：-7 点
• suggestion の指摘：-3 点

評価ランクのしきい値：

• 85-100：excellent
• 65-84：good
• 40-64：fair
• 0-39：poor

減点は 0 を上限とします（スコアは 0 未満になりません）。

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

以下の構造をそのまま返します。JSON ブロックの前後に文章を追加しないでください。

{
  "interface_type": "string",
  "interface_type_note": "string or null",
  "overall_score": 0,
  "band": "poor|fair|good|excellent",
  "findings": [
    {
      "id": "finding-1",
      "principle": {
        "code": "F.1.1.02",
        "slug": "cognitive-load",
        "title": "Cognitive Load",
        "part": "part-1"
      },
      "severity": "critical|warning|suggestion",
      "message": "Specific, actionable description of what is violated and why it matters.",
      "remediation": "Concrete fix with measurable outcome.",
      "business_impact": "String from principle data, or null if not enriched."
    }
  ],
  "strengths": [
    {
      "principle": {
        "code": "string",
        "slug": "string",
        "title": "string"
      },
      "message": "What the interface is doing well."
    }
  ],
  "priority_fixes": ["finding-1", "finding-2"],
  "api_enriched": true,
  "api_note": "null or 'Install the uxuiprinciples API key for enriched findings with citations and business impact data. See uxuiprinciples.com/en/checkout'"
}

priority_fixes には、推奨する修正順に指摘 ID を列挙します。まず critical を挙げ、次に主要なユーザー操作に最も影響する warning を挙げます。

重大度のガイドライン

重大度	使用する状況
critical	違反によってタスクの完了が直接妨げられる、またはユーザーが離脱する場合。7 項目を超える認知過負荷、エラーフィードバックがない、主要な CTA がない、コントラストにアクセシビリティ上の問題がある場合などです。
warning	違反によってユーザー体験が低下し、コンバージョンや満足度が測定可能なほど下がる場合。選択肢の数が最適でない、階層が不明確、アフォーダンスが不足している場合などです。
suggestion	改善の機会がある場合。インターフェースは機能しますが、修正すれば指標の向上が見込める形で原則に違反している場合です。マイクロコピー、間隔、段階的開示の機会などです。

エッジケース

最小限の説明（30 語未満）： 作業を進める前に、確認の質問を 1 つ尋ねます。「この画面でユーザーが完了すべき主な操作は何ですか？」その後、入手できた情報に基づいて評価し、不足情報を interface_type_note に記載します。

違反が見つからない場合： 強みを少なくとも 2 つ返します。findings: [] を設定します。スコアは 100、評価ランクは excellent です。これは有効な出力です。

1 つの説明に複数のインターフェースタイプが含まれる場合（例：ダッシュボード＋設定サイドバー）： 主なインターフェースタイプを特定します。interface_type_note に注記を追加します。主なタイプを評価します。

AI 固有のシグナルがない AI インターフェース： パート 5 の評価をスキップします。AI 関連の指摘を捏造しないでください。

「ユーザーは自分のデータを確認できます」のような曖昧なコピー： 具体的な内容を推測で補わないでください。説明から観察できる範囲を評価します。該当する場合は、曖昧さを「認識と想起」の原則に関する提案として指摘します。

API が 403 を返す場合（無料プランでは原則に Pro が必要）： その原則について内部知識を用いてフォールバックします。api_enriched: false に注記します。

例

例 1：過負荷の問題があるダッシュボード

入力：

Admin dashboard with 15 KPI cards, 4 filter dropdowns, a data table showing 50 rows, 3 chart widgets, and a sidebar navigation with 12 items.

期待される出力構造：

{
  "interface_type": "dashboard",
  "interface_type_note": null,
  "overall_score": 43,
  "band": "fair",
  "findings": [
    {
      "id": "finding-1",
      "principle": {
        "code": "F.1.1.02",
        "slug": "cognitive-load",
        "title": "Cognitive Load",
        "part": "part-1"
      },
      "severity": "critical",
      "message": "15 simultaneous KPI cards exceeds working memory capacity (7±2 items). Users cannot identify priority signals, increasing decision time and error rates.",
      "remediation": "Group KPIs into 3-5 thematic sections. Surface the 5 most critical metrics above the fold. Move secondary metrics to an expandable section or secondary view.",
      "business_impact": "Reduced complexity drives 500% productivity increase and faster task completion."
    },
    {
      "id": "finding-2",
      "principle": {
        "code": "F.2.2.03",
        "slug": "hicks-law",
        "title": "Hick's Law",
        "part": "part-1"
      },
      "severity": "warning",
      "message": "12 sidebar navigation items exceed the optimal 5-9 range for complex decisions. Each extra item adds ~150ms decision time per visit.",
      "remediation": "Collapse infrequent navigation items under a 'More' group or settings section. Keep primary navigation to 5-7 items.",
      "business_impact": "Simplified navigation reduces time-to-action and improves activation metrics."
    }
  ],
  "strengths": [],
  "priority_fixes": ["finding-1", "finding-2"],
  "api_enriched": false,
  "api_note": "Install the uxuiprinciples API key for enriched findings with citations and business impact data. See uxuiprinciples.com/en/checkout"
}

例 2：最小限の入力

入力：

Login page.

期待される動作： 確認の質問を 1 つ尋ねます。「ログインページにはどのような要素がありますか？たとえば、メールアドレス／パスワード欄、ソーシャルログインボタン、「パスワードをお忘れですか？」リンク、エラー状態などです。」

完了条件

スキルの出力は、次の条件を満たすと完了です。

1. interface_type が許可された値のいずれかに設定されている
2. すべての指摘に、F.X.X.XX 形式の principle.code がある
3. すべての指摘に、空でない message と remediation がある
4. severity が critical、warning、suggestion のいずれかである
5. overall_score が 0 から 100 の範囲内である
6. band がスコアのしきい値と一致している
7. priority_fixes に、findings に存在する ID のみが記載されている
8. api_enriched が、ツールボックスの呼び出しが成功したかどうかを正確に示している
9. 出力が、前後に説明文のない有効な JSON である