中文 English

别再让 Agent 瞎画界面：UI UX Pro Max 安装与正确使用指南

发布时间: 2026-05-22
AI Agent UI UX Pro Max Skill Codex Claude Cursor Windsurf UI设计 UX设计 前端开发

先说结论

UI UX Pro Max 不是一个“让 Agent 变会审美”的魔法提示词，而是一套可以被 Claude Code、Codex、Cursor、Windsurf、Gemini、OpenCode 等 Agent 调用的 UI/UX 设计知识库与搜索型 Skill。它把产品类型、行业、视觉风格、色彩、字体、落地页结构、图表、可访问性、前端技术栈建议等内容整理成可查询的数据和脚本，让 Agent 在动手写页面之前先生成一套设计系统，再按设计系统实现。

正确姿势不是“装完以后继续一句话让它做个好看的页面”，而是让 Agent 先调用 search.py --design-system，再补充 UX、图表、技术栈查询，最后把这些结果落到组件、布局、颜色、动效和验收清单里。这样做的价值很直接：减少 AI 紫色渐变、千篇一律 Hero、低对比度文字、移动端溢出、卡片套卡片、按钮没有 hover/focus 状态这些常见 Agent UI 问题。

本文只使用公开资料、公开仓库和干净示例目录中的验证结果。文中的命令、路径、项目名均为通用示例，不包含任何真实内网地址、账号、密钥、业务项目名或个人配置。截图来自公开参考页面和一次隔离目录中的安装/使用验证，不包含隐私信息。

UI UX Pro Max 的 GitHub 仓库首页，显示项目结构、版本信息和功能定位

图 1：UI UX Pro Max 是一个面向 AI 编码助手的设计智能 Skill，核心是让 Agent 在实现 UI 前先查询设计知识库。

1. 为什么我会建议给 Agent 装 UI UX Pro Max

很多人第一次用 Agent 做前端页面时，都会经历一个很熟悉的阶段：你说“帮我做一个 SaaS 首页”“做一个管理后台”“做一个产品定价页”，Agent 很快就能给你生成一屏东西。它甚至会写 Tailwind，知道放 Hero、Feature、Pricing、FAQ，也会给按钮加点阴影。问题是，这些页面经常看起来像同一个模板换了文案。

最常见的味道大概有这些：大面积蓝紫渐变、三四个圆形光斑、黑色背景叠半透明卡片、Hero 区巨大标题、下面一排功能卡、CTA 按钮永远是“Get Started”、移动端一看就挤、图表像装饰、可访问性几乎没考虑。你让它“高级一点”，它可能继续加阴影；你让它“更科技”，它可能继续加霓虹；你让它“更专业”，它可能只是把颜色改暗。

这不是某一个模型的问题，而是 Agent 做 UI 时缺少结构化设计依据。它知道很多网页长什么样，但不知道这个产品类型在当前场景下应该更偏“数据密度”“转化效率”“信任感”“阅读舒适度”还是“操作效率”。它能写 CSS，却不一定先问：这是什么产品？服务谁？要完成什么任务？页面是落地页、仪表盘、定价页、设置页、移动端结账页，还是一个内容型博客模板？

UI UX Pro Max 解决的正是这件事。它把 Agent 从“凭印象画页面”拉回“先查设计系统，再写界面”的流程。官方仓库把它描述为给 AI 编码助手提供跨平台 UI/UX 设计智能的 Skill，数据里包含 UI 风格、行业色板、字体组合、UX 指南、图表类型、技术栈规则等内容。换句话说，它不是代替设计师，而是给 Agent 一个更可靠的设计起点。

这类 Skill 对两种人特别有用。

第一种，是经常让 Agent 直接做产品原型、后台界面、营销页、组件库的人。你不一定要成为视觉设计师，但至少希望 Agent 不要一上来就拿通用模板糊你。

第二种，是已经有前端能力、但希望 Agent 在实现前先收敛风格的人。你可以把 UI UX Pro Max 当作“设计系统草案生成器”：先让它给出色彩、字体、布局模式、交互效果、反模式，再由你决定哪些采纳、哪些调整。

2. 它到底装了什么

从一次干净目录的 Codex 安装结果看，uipro-cli 会把 Skill 安装到目标 Agent 对应的技能目录中。以 Codex 为例，目录结构大致是：

.codex/skills/ui-ux-pro-max/SKILL.md
.codex/skills/ui-ux-pro-max/scripts/search.py
.codex/skills/ui-ux-pro-max/scripts/core.py
.codex/skills/ui-ux-pro-max/scripts/design_system.py
.codex/skills/ui-ux-pro-max/data/*.csv
.codex/skills/ui-ux-pro-max/data/stacks/*.csv

这里最关键的是三类东西。

第一类是 SKILL.md。这是 Agent 能读懂的入口说明，里面定义了什么时候该触发这个 Skill、怎样分析用户需求、怎样生成设计系统、怎样补充领域查询、怎样按技术栈查询实现建议。对 Agent 来说，这份文件相当于“工作规程”。

第二类是 scripts/search.py。这是实际查询入口。它可以做 --design-system 综合设计系统生成，也可以按 --domain 搜索 style、color、typography、landing、chart、ux、web 等领域，还可以用 --stack 查询 React、Next.js、Vue、Svelte、SwiftUI、React Native、Flutter、shadcn、HTML + Tailwind 等技术栈的实现建议。

第三类是 data/ 里的 CSV 数据。官方 README 提到它包含多种 UI 风格、行业色板、字体组合、UX 指南、图表类型、技术栈建议和推理规则。DeepWiki 页面也把它概括为一个通过可搜索数据库给 AI 编码助手提供设计智能的 Skill，并强调它会在用户请求 UI/UX 工作时引导 Agent 走系统化工作流。

这就解释了为什么它比一段提示词更稳。提示词只能说“请设计得专业一点”，而 UI UX Pro Max 可以让 Agent 查询：“这是 B2B SaaS 仪表盘，应该偏数据密集、低装饰、高可读；颜色不要只用紫色；图表需要按比较、趋势、漏斗或分布选择；可访问性至少检查对比度、键盘焦点和错误提示。”

3. 安装前准备

安装前建议先确认三件事。

第一，确认你要给哪个 Agent 安装。UI UX Pro Max 支持多种 AI coding assistant，但每个工具读取 Skill 的目录不一样。给 Codex 安装不等于 Claude Code 自动可用；给 Cursor 安装也不等于 Windsurf 自动可用。多 Agent 用户应该分别安装、分别验证。

第二，确认本机有 Node.js 和 npm。推荐方式是使用官方 CLI：

npm install -g uipro-cli
uipro init --ai codex

如果你不想全局安装，也可以直接用：

npx uipro-cli@latest init --ai codex

第三，确认有 Python。安装后的搜索脚本是 Python 入口，至少需要能运行：

python3 --version

如果你的环境不能访问 GitHub，或者在公司网络、CI、离线环境里，CLI 支持 --offline。它会使用 npm 包内置资源，不在安装后继续下载远端内容：

npx uipro-cli@latest init --ai codex --offline

我这次为了避免污染真实工作区，就是在临时目录里验证的离线安装。实际输出显示它会安装到 Codex 的 .codex/skills/ 结构下，并生成 ui-ux-pro-max/SKILL.md、scripts/、data/ 等文件。

安装指南页面提供 CLI、手动、离线等安装方式

图 2：安装方式不要只看一条命令，要根据网络环境、团队可复现性和 Agent 类型选择。

4. 推荐安装方式：先用 CLI，再按团队需要固化

如果只是个人使用，我建议从 CLI 开始。它的好处是路径和文件生成更不容易出错，还能根据 --ai 参数自动放到对应目录。

常用格式如下：

# 安装到 Claude Code
npx uipro-cli@latest init --ai claude

# 安装到 Codex
npx uipro-cli@latest init --ai codex

# 安装到 Cursor
npx uipro-cli@latest init --ai cursor

# 安装到 Windsurf
npx uipro-cli@latest init --ai windsurf

# 给多个工具统一安装
npx uipro-cli@latest init --ai all

CLI 的帮助信息显示，--ai 支持的类型包括 claude、cursor、windsurf、antigravity、copilot、roocode、kiro、codex、qoder、gemini、trae、opencode、continue、codebuddy、all。如果你不确定当前工具名称，先运行：

npx uipro-cli@latest init --help

安装时还有两个很实用的参数。

--force 用于覆盖已有文件，适合你明确要重装或修复损坏安装时使用。不要一上来就 --force，因为它可能覆盖你手工修改过的 Skill 文件。

--offline 用于跳过 GitHub 下载，使用 CLI 包内置资源。它适合网络不稳定、公司防火墙、隔离环境、CI 或你只是想稳定复现安装结果的场景。

如果是团队项目，我更建议把安装结果固定到仓库里，而不是只依赖每个人本机的全局状态。比如将 .codex/skills/ui-ux-pro-max/ 或对应 Agent 的 skill 目录纳入项目模板，再在 README 里说明：修改 UI 前必须先执行设计系统查询，并把结果保存到 design-system/MASTER.md 或项目文档中。这样团队每个人得到的是同一个设计起点，而不是每台机器一套。

5. Codex 中的安装和验证

以 Codex 为例，安装命令可以这样写：

mkdir demo-ui-project
cd demo-ui-project
npx uipro-cli@latest init --ai codex

安装完成后，确认目录：

find .codex/skills/ui-ux-pro-max -maxdepth 2 -type f | sort

你应该能看到 SKILL.md、scripts/search.py、data/*.csv 之类的文件。然后不要急着让 Agent 写页面，先手工跑一次搜索：

python3 .codex/skills/ui-ux-pro-max/scripts/search.py   "AI SaaS analytics dashboard"   --design-system   -p "DemoAgent"   -f markdown

一次真实验证里，它返回了完整设计系统，包括推荐 Pattern、Style、Colors、Typography、Key Effects、Avoid 和 Pre-Delivery Checklist。比如一个 AI SaaS analytics dashboard 的查询，会偏向数据密集仪表盘，强调 KPI 卡片、网格布局、图表缩放、行 hover、高对比度、可访问焦点和响应式检查。

再补一个 UX 查询：

python3 .codex/skills/ui-ux-pro-max/scripts/search.py   "accessibility dashboard"   --domain ux   -n 3

返回结果会提醒图片替代文本、错误消息、颜色对比度等问题。这些东西很基础，但恰恰是 Agent 做 UI 最容易漏的地方。很多 AI 页面第一眼看着花，真正用起来却没有键盘焦点、没有 aria-live、错误只靠红框、文字对比度不够。把 UX 查询放在实现前，可以减少这类低级返工。

6. 不同 Agent 里应该怎么“正确调用”

装上 Skill 只是第一步。更重要的是让 Agent 正确使用它。

很多人会这么问：

帮我做一个好看的 SaaS landing page

这个提示太弱。它没有产品类型、页面表面、风格偏好、约束、技术栈和验收标准。UI UX Pro Max 官方文档里的使用说明强调，一个更好的提示应该包含产品类型、页面/屏幕、风格提示和约束。你可以这样写：

使用 UI UX Pro Max 帮我设计并实现一个 B2B SaaS 数据分析后台首页。
产品类型：AI analytics SaaS。
页面：dashboard home。
风格：专业、克制、数据密集，不要紫色渐变和装饰性光斑。
技术栈：React + Tailwind。
约束：移动端 375px 不溢出，文字对比度至少 WCAG AA，所有可点击控件有 hover/focus 状态。
请先生成 design system，再实现页面。

这段提示的关键不是长，而是信息完整。Agent 拿到它以后，应该先抽取需求：产品类型是 B2B SaaS，页面是 dashboard，行业是 AI analytics，风格是 professional/data-dense，技术栈是 React + Tailwind。然后执行：

python3 .codex/skills/ui-ux-pro-max/scripts/search.py   "B2B SaaS AI analytics dashboard professional data dense"   --design-system   -p "Project Name"   -f markdown

接着补充：

python3 .codex/skills/ui-ux-pro-max/scripts/search.py   "dashboard accessibility loading error states"   --domain ux

python3 .codex/skills/ui-ux-pro-max/scripts/search.py   "analytics dashboard trend comparison funnel"   --domain chart

python3 .codex/skills/ui-ux-pro-max/scripts/search.py   "dashboard responsive state performance"   --stack react

最后才进入实现。这样做有一个好处：你可以要求 Agent 在动手前先把查询结果摘要贴出来，确认它的设计方向是否正确。如果方向错了，你在写代码前就能纠偏。

How to Use 页面强调好提示需要产品类型、页面、风格和约束

图 3：UI UX Pro Max 的正确使用不是一句“变好看”，而是给 Agent 足够的产品、表面、风格和约束。

7. 我推荐的 Agent 工作流

如果你想把它真正用起来，可以固定成五步。

7.1 第一步：让 Agent 复述 UI 目标

先让 Agent 不写代码，只复述：

在写代码前，请先说明你理解的产品类型、目标用户、页面类型、主要任务、技术栈和视觉约束。

这一步能防止需求错位。比如你要的是“后台仪表盘”，Agent 却按“营销落地页”去查；你要的是“给企业客户看的操作台”，它却按“年轻消费品牌”去配色。

7.2 第二步：强制生成设计系统

要求 Agent 必须先执行 --design-system，并输出：Pattern、Style、Colors、Typography、Effects、Anti-patterns、Pre-delivery checklist。不要接受“我会参考 UI UX Pro Max”这种空话。最好让它贴出真实命令和核心结果。

请先调用 UI UX Pro Max 的 search.py --design-system，输出设计系统摘要。确认后再实现。

如果你希望设计系统跨会话复用，可以加 --persist：

python3 .codex/skills/ui-ux-pro-max/scripts/search.py   "fintech billing dashboard"   --design-system   --persist   -p "Billing Console"

它会生成类似 design-system/MASTER.md 的设计源文件，以及页面级 overrides。后续做 checkout、settings、dashboard 等页面时，Agent 可以先读 Master，再读对应页面 override。

7.3 第三步：按风险补查询

设计系统是总纲，但不一定覆盖所有细节。具体做页面时，我一般会让 Agent 额外查三类。

做仪表盘，查 chart：趋势、比较、漏斗、热力、分布，分别适合什么图表。

做表单和设置页，查 ux 和 web：错误提示、键盘导航、焦点状态、aria、loading、empty state。

做 React/Next/Vue 项目，查对应 --stack：避免状态提升混乱、重复渲染、图片加载问题、客户端组件滥用等。

这一步的目标不是让 Agent 把搜索结果照搬，而是让它实现前知道哪些坑不能踩。

7.4 第四步：实现时把设计系统变成代码约束

很多 Agent 的坏习惯是：前面生成了一套设计系统，后面写代码时忘光。所以你要把设计系统变成代码约束。例如：

  1. 颜色必须来自设计系统，不允许临时发明一堆相近色。
  2. 字体层级必须和页面密度匹配，Dashboard 里不要用 Hero 级巨字。
  3. 按钮、菜单、输入框、图表 tooltip 都要有 hover/focus/loading/empty/error 状态。
  4. 移动端必须检查 375px，不能横向溢出。
  5. 不要卡片套卡片，不要只靠大圆角和阴影制造层级。
  6. 图标优先用项目已有图标库，比如 lucide，不要手写随意 SVG。
  7. 颜色对比度、文本换行和触控目标必须作为验收项。

这些约束写进提示里，比“高级”“现代”“有设计感”更有效。

7.5 第五步：交付前让 Agent 自查

交付前，不要只让它跑测试。UI 还需要视觉和交互检查。可以这样要求：

完成后请按 UI UX Pro Max 的 pre-delivery checklist 自查：
1. 375px、768px、1024px、1440px 响应式截图。
2. 文本是否溢出或遮挡。
3. 点击控件是否有 hover/focus 状态。
4. 颜色对比度是否足够。
5. loading、empty、error 状态是否存在。
6. 是否违反本次 design system 的 anti-patterns。

如果是前端应用，还应该让 Agent 打开本地页面做截图验证，而不是只看编译通过。UI 的很多问题不会在 TypeScript 或单元测试里报错。

8. 什么时候不要盲目相信它

UI UX Pro Max 很有用，但不是审美裁判，也不是产品经理。它给的是设计知识库和推荐路径，不是绝对答案。

第一，行业推荐不是品牌规范。如果你的公司已经有成熟设计系统，品牌色、字号、组件行为都应以自家规范为准。UI UX Pro Max 可以作为参考，但不能覆盖品牌系统。

第二，设计系统输出不是最终稿。它会给 Pattern、Style、Colors、Typography，但真正的页面还要结合内容密度、业务优先级、用户任务和真实数据。特别是后台、CRM、运维平台、财务系统，应该更重视扫描效率和操作确定性，而不是营销页式视觉冲击。

第三，它不能代替真实用户测试。一个页面是否好用，不只看颜色和布局，还看用户能否快速完成任务、错误能否恢复、关键路径是否顺畅、弱网和异常状态是否可理解。

第四，不要把它当素材库。它不是让你随便拼风格词的“审美抽卡机”。每次查询都应该围绕产品、页面和约束。如果你输入“cyberpunk glassmorphism luxury SaaS kids healthcare dashboard”，得到的结果再漂亮也不一定合理。

第五，注意版本差异。GitHub releases 页面显示项目版本在持续更新，而 npm 上的 CLI 版本和 Skill 内容版本不一定总是同一个数字。安装和更新前建议看一下 uipro versions，团队项目则建议锁定版本或把 Skill 文件纳入仓库。

9. 常见问题与排查

问题一：装完 Agent 没有自动使用。

先确认目录是否装对。Codex 看 .codex/skills/ 或当前版本支持的 skills 目录；Claude、Cursor、Windsurf、Gemini 等工具各有自己的插件或技能加载路径。其次重启 Agent，让它重新扫描技能。最后在提示里显式写“使用 UI UX Pro Max，先生成 design system”。

问题二：python3 找不到。

安装 Python。macOS 可以用 Homebrew，Linux 可以用系统包管理器，Windows 可以用 winget 或官方安装包。安装后重新打开终端，确认 python3 --version 可用。

问题三：npx 下载很慢或失败。

优先确认网络和 npm registry。如果环境不能访问 GitHub，可以用 --offline。如果公司网络必须走代理，请先在 shell 里配置 npm/http 代理，但不要把代理地址、Token 或公司内网信息写进项目文档。

问题四：输出很好，实现仍然丑。

这通常是 Agent 没有把设计系统落实到代码约束。要求它在实现前写出颜色 token、字体层级、组件状态、响应式断点和 anti-patterns；实现后按清单截图检查。

问题五：生成结果和项目现有设计冲突。

以项目现有设计系统为准。UI UX Pro Max 适合给新页面、新原型、新产品提供起点；在成熟产品里，它应该作为补充建议，而不是推翻原有规范。

10. 一个可直接复制的高质量提示词

下面这段可以直接给 Agent，用来替代“帮我做个好看的页面”：

请使用 UI UX Pro Max 处理这个 UI/UX 任务。

目标：为一个 B2B SaaS 产品设计并实现 dashboard 首页。
用户：企业运营人员和管理者，需要快速查看 KPI、趋势、告警和待办。
页面：应用内 dashboard，不是营销落地页。
风格：专业、克制、信息密度高、适合长期使用；避免大面积紫色渐变、装饰性光斑、卡片套卡片和无意义插画。
技术栈：React + Tailwind + lucide 图标。
约束：
- 先调用 search.py --design-system 生成设计系统，并输出摘要。
- 再查询 ux、chart 和 react stack 建议。
- 实现时颜色、字体、间距、组件状态必须服从设计系统。
- 移动端 375px 不允许横向溢出。
- 所有可点击控件需要 hover/focus 状态。
- 错误、空状态、加载状态都要有明确 UI。
- 完成后按 pre-delivery checklist 自查，并说明哪些截图或命令验证过。

这段提示词的核心是把 Agent 的动作顺序写死：先理解，后查询，再设计，再实现，最后验证。只要顺序对了，UI UX Pro Max 的价值才会出来。

11. 我对它的定位

我会把 UI UX Pro Max 放在“Agent 前端工作流的设计情报层”这个位置。它不是 Figma，不是设计师，不是组件库，也不是万能模板。它更像一个能被 Agent 调用的 UI/UX 资料库：当 Agent 准备写页面时，先从这里查产品类型、行业风格、配色、字体、图表和 UX 清单，再把结果翻译成代码。

如果你本来就有成熟设计团队，它可以减少 Agent 输出和设计系统之间的偏差。如果你没有设计团队，它至少能帮你避开最典型的 AI 页面味道。如果你正在做原型，它能让第一版更接近“可讨论的产品稿”，而不是“看起来像 AI 生成的网页”。

最重要的是，它让 Agent 的 UI 工作从一句模糊审美要求变成一条可检查流程。对现在的 AI coding 来说，这比“再高级一点”“再现代一点”有效得多。

12. 参考资料

  1. UI UX Pro Max GitHub 仓库：https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
  2. UI UX Pro Max 官方/多语言文档安装页：https://ui-ux-pro-max-skill.com/en/docs/cli-reference/
  3. UI UX Pro Max 使用说明页：https://ui-ux-pro-max-skill.com/en/docs/examples/
  4. DeepWiki 项目结构说明：https://deepwiki.com/nextlevelbuilder/ui-ux-pro-max-skill/3-uiux-pro-max-skill
  5. npm 包 uipro-cli：https://www.npmjs.com/package/uipro-cli