mcpField
U
uxui-evaluator

uxui-evaluator

github.com/uxuiprinciples设计与 UI27187 次安装8 周前更新
代码仓库

关于 uxui-evaluator

依据包含 6 个部分的 UX/UI 原则框架评估界面描述，并以 JSON 返回问题、严重程度和修复建议。提供 API 密钥时可调用 uxuiprinciples API，否则依据内部知识评估。

主要功能

  1. 01识别界面类型
  2. 02选择相关框架部分
  3. 03发现并评估 UX/UI 问题
  4. 04以 JSON 返回问题与修复建议
  5. 05在可用时调用 API 补充信息

适用场景

  1. 01审查仪表盘或表单描述
  2. 02评估 AI 聊天界面
  3. 03确定界面改进的优先顺序

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/uxuiprinciples/agent-skills --skill uxui-evaluator

安装后在 Claude Code 中输入/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 框架评估界面描述：该框架包含 195 条有研究支持的 UX/UI 原则，分为 6 个部分。你返回结构化的 JSON 结论，而不是散文式描述。每条结论都会指明具体原则、分配严重程度、说明违反了哪些内容及原因，并给出具体的修复建议。

当设置了 UXUI_API_KEY 时，首先调用 audit。它会直接返回来自 API 的完整结构化结果。使用 lookup_principle 和 list_principles_by_part 可进一步丰富单条结论，或在 audit 不可用时使用它们。

当未设置 UXUI_API_KEY 时，使用内部知识应用该框架，并在输出中说明这一限制。

框架结构

6 个部分的分类法涵盖：

部分领域关键原则
第 1 部分基础认知负荷（F.1.1.02）、米勒定律（F.1.1.04）、分块、希克定律（F.2.2.03）、心智模型（F.1.1.03）、系列位置效应（F.1.1.06）法则
第 2 部分核心原则错误预防（C.1.4.01）、一致性与标准（C.1.1.01）、反馈循环、用户控制、帮助与文档
第 3 部分设计系统渐进式披露（D.1.1.01）、视觉层级（D.2.1.02）、排版、色彩、内容层级、留白
第 4 部分界面模式菲茨定律（I.2.2.02）、表单中的错误预防（I.1.1.03）、触摸目标、移动端导航、响应式设计
第 5 部分AI 原生与专用对话流（S.1.1.01）、AI 透明度（S.1.3.01）、认知负荷校准（F.1.3.01）、自动化偏见预防
第 6 部分以人为本的设计无障碍、包容性设计、信任信号、情感化设计、合乎伦理的模式

原则代码遵循 F.[部分].[章节].[序号] 格式。例如：F.1.1.02 是第 1 部分、第 1 章、第 02 条原则（认知负荷）。

评估工作流

按顺序执行以下步骤。不要跳过步骤。

第 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 key）

首选路径： 调用 audit，传入 {"description": "<interface description>"}。响应是完整的结构化审计结果——直接将其用作你的输出。如果 audit 返回 200，跳过第 5 步和第 6 步。

回退路径： 如果 audit 不可用或返回错误，针对第 3 步中发现的每项违规调用 lookup_principle。使用返回的 aiSummary 和 businessImpact 字段填充 message 和 business_impact。

如果所有工具调用都失败或返回非 200，则不进行增强继续执行。设置 api_enriched: false。

常见原则的 slug：

  • 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 个词）： 在继续之前先提出一个澄清问题。"用户在此屏幕上应完成的主要操作是什么？"然后基于你已有的信息进行评估，并在 interface_type_note 中注明信息缺口。

未发现违规： 至少返回 2 项优点。设置 findings: []。分数 100，分级 excellent。这是有效输出。

一个描述中包含多种界面类型（例如仪表盘 + 设置侧边栏）： 确定主导界面类型。在 interface_type_note 中添加说明。评估主导类型。

AI 界面但无 AI 相关信号： 跳过第 5 部分的评估。不要编造与 AI 相关的发现。

模糊文案如"用户可以看到自己的数据"： 不要臆造具体内容。基于你能从描述中观察到的信息进行评估。如果适用，在识别 vs 回忆下将模糊性标记为 suggestion。

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. 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 准确反映 toolbox 调用是否成功
  9. 输出为有效 JSON，前后无任何说明文字

评论

支持 Markdown