655 lines
33 KiB
Markdown
655 lines
33 KiB
Markdown
# [UI UX Pro Max](https://uupm.cc)
|
||
|
||
<p align="center">
|
||
<a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/README.zh.md">🇨🇳 简体中文</a> |
|
||
<a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/README.md">🇺🇸 English</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/releases"><img src="https://img.shields.io/github/v/release/nextlevelbuilder/ui-ux-pro-max-skill?style=for-the-badge&color=blue" alt="GitHub Release"></a>
|
||
<img src="https://img.shields.io/badge/reasoning_rules-192-green?style=for-the-badge" alt="192 条推理规则">
|
||
<img src="https://img.shields.io/badge/UI_styles-79_searchable-purple?style=for-the-badge" alt="79 种可搜索 UI 风格">
|
||
<img src="https://img.shields.io/badge/python-3.x-yellow?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.x">
|
||
<a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/LICENSE"><img src="https://img.shields.io/github/license/nextlevelbuilder/ui-ux-pro-max-skill?style=for-the-badge&color=green" alt="License"></a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="https://www.npmjs.com/package/ui-ux-pro-max-cli"><img src="https://img.shields.io/npm/v/ui-ux-pro-max-cli?style=flat-square&logo=npm&label=CLI" alt="npm"></a>
|
||
<a href="https://www.npmjs.com/package/ui-ux-pro-max-cli"><img src="https://img.shields.io/npm/dm/ui-ux-pro-max-cli?style=flat-square&label=downloads" alt="npm downloads"></a>
|
||
<a href="https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/stargazers"><img src="https://img.shields.io/github/stars/nextlevelbuilder/ui-ux-pro-max-skill?style=flat-square&logo=github" alt="GitHub stars"></a>
|
||
<a href="https://paypal.me/uiuxpromax"><img src="https://img.shields.io/badge/PayPal-支持开发-00457C?style=flat-square&logo=paypal&logoColor=white" alt="PayPal"></a>
|
||
</p>
|
||
|
||
一个为跨多平台和框架构建专业 UI/UX 提供设计智能的 AI 技能。
|
||
|
||
<p align="center">
|
||
<a href="https://uupm.cc">
|
||
<img src="screenshots/website.png" alt="UI UX Pro Max" width="800">
|
||
</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<b>如果这个项目对你有帮助，请考虑支持：</b><br><br>
|
||
<a href="https://paypal.me/uiuxpromax"><img src="https://img.shields.io/badge/PayPal-捐赠-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="PayPal 捐赠"></a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<i>其他项目</i><br>
|
||
<a href="https://nextlevelbuilder.io">NextLevelBuilder.io</a> | <a href="https://goclaw.sh">GoClaw.sh</a> | <a href="https://claudekit.cc">ClaudeKit.cc</a> | <a href="https://tose.sh">TOSE.sh</a>
|
||
</p>
|
||
|
||
## v2.0 新特性
|
||
|
||
### 智能设计系统生成
|
||
|
||
v2.0 的旗舰特性是**设计系统生成器**——一个 AI 驱动的推理引擎，可在数秒内分析你的项目需求并生成完整、定制化的设计系统。
|
||
|
||
```
|
||
+----------------------------------------------------------------------------------------+
|
||
| 目标：Serenity Spa - 推荐设计系统 |
|
||
+----------------------------------------------------------------------------------------+
|
||
| |
|
||
| 模式：以 Hero 为中心 + 社交证明 |
|
||
| 转化：情感驱动，带信任元素 |
|
||
| CTA：首屏展示，客户评价后重复 |
|
||
| 版块： |
|
||
| 1. 主视觉区 (Hero) |
|
||
| 2. 服务 |
|
||
| 3. 客户评价 |
|
||
| 4. 预约 |
|
||
| 5. 联系我们 |
|
||
| |
|
||
| 风格：柔和 UI 进化版 (Soft UI Evolution) |
|
||
| 关键词：柔和阴影、微妙深度、 calming、高级质感、有机形状 |
|
||
| 适用：健康、美容、生活方式品牌、高端服务 |
|
||
| 性能：cost:low | 无障碍：risk:conditional；需验证具体要求 |
|
||
| |
|
||
| 配色： |
|
||
| 主色： #E8B4B8 (柔和粉) |
|
||
| 辅色： #A8D5BA (鼠尾草绿) |
|
||
| CTA： #D4AF37 (金色) |
|
||
| 背景： #FFF5F5 (暖白) |
|
||
| 文字： #2D3436 (炭灰) |
|
||
| 备注： calming 配色，金色点缀增添奢华感 |
|
||
| |
|
||
| 字体：Cormorant Garamond / Montserrat |
|
||
| 调性：优雅、 calming、精致 |
|
||
| 适用：奢侈品牌、健康、美容、编辑类 |
|
||
| Google Fonts: https://fonts.google.com/share?selection.family=... |
|
||
| |
|
||
| 关键效果： |
|
||
| 柔和阴影 + 符合平台与组件语境的过渡 + 细腻悬停状态 |
|
||
| |
|
||
| 避免 (反模式)： |
|
||
| 亮霓虹色 + 生硬动画 + 深色模式 + AI 紫/粉渐变 (银行业) |
|
||
| |
|
||
| 交付前检查清单： |
|
||
| [ ] 不使用表情符号作为图标 (使用 SVG: Heroicons/Lucide) |
|
||
| [ ] 所有可点击元素有 cursor-pointer |
|
||
| [ ] 交互时长符合平台、组件和用户偏好 |
|
||
| [ ] 浅色模式：文字对比度至少 4.5:1 |
|
||
| [ ] Focus 状态对键盘导航可见 |
|
||
| [ ] 尊重 prefers-reduced-motion 偏好 |
|
||
| [ ] 文字、chip 与 badge 能重排，不裁切或破坏标签 |
|
||
| [ ] 响应式：375px、768px、1024px、1440px |
|
||
| |
|
||
+----------------------------------------------------------------------------------------+
|
||
```
|
||
|
||
### 设计系统生成的工作原理
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 1. 用户请求 │
|
||
│ "为我的美容院搭建落地页" │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 2. 多域搜索 (5 个并行搜索) │
|
||
│ • 产品类型匹配 (192 个分类) │
|
||
│ • 风格推荐 (79 种可搜索；50 种 active) │
|
||
│ • 配色方案选择 (192 套配色) │
|
||
│ • 落地页模式 (34 种模式) │
|
||
│ • 字体配对 (74 种组合) │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 3. 推理引擎 │
|
||
│ • 匹配产品 → UI 分类规则 │
|
||
│ • 应用风格优先级 (BM25 排序) │
|
||
│ • 过滤行业反模式 │
|
||
│ • 处理决策规则 (JSON 条件) │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 4. 完整设计系统输出 │
|
||
│ 模式 + 风格 + 配色 + 字体 + 效果 │
|
||
│ + 避免的反模式 + 交付前检查清单 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 192 条行业特定推理规则
|
||
|
||
推理引擎包含针对以下领域的专门规则：
|
||
|
||
| 分类 | 示例 |
|
||
|------|------|
|
||
| **科技与 SaaS** | SaaS、微 SaaS、B2B 服务、开发者工具 / IDE、AI/聊天机器人平台、网络安全平台 |
|
||
| **金融** | 金融科技/加密货币、银行、保险、个人财务追踪、发票与账单工具 |
|
||
| **医疗健康** | 医疗诊所、药房、牙科、兽医、心理健康、用药提醒 |
|
||
| **电子商务** | 综合电商、奢侈品、二手交易平台 (P2P)、订阅盒、外卖配送 |
|
||
| **服务** | 美容/水疗、餐饮、酒店、法律、家政服务、预约与预订 |
|
||
| **创意** | 作品集、代理公司、摄影、游戏、音乐流媒体、照片/视频编辑器 |
|
||
| **生活方式** | 习惯追踪、食谱与烹饪、冥想、天气、日记、情绪追踪 |
|
||
| **新兴技术** | Web3/NFT、空间计算、量子计算、自动驾驶无人机编队 |
|
||
|
||
每条规则包括：
|
||
- **推荐模式** - 落地页结构
|
||
- **风格优先级** - 最匹配的 UI 风格
|
||
- **配色氛围** - 适合行业的调色板
|
||
- **字体氛围** - 匹配品牌个性的字体
|
||
- **关键效果** - 动画与交互
|
||
- **反模式** - 不要做哪些（例如银行业的"AI 紫/粉渐变"）
|
||
|
||
## 功能特性
|
||
|
||
- **79 种可搜索 UI 风格（50 种 active）** - 玻璃拟态、粘土拟态、极简主义、粗野主义、新拟态、便当盒网格、深色模式、AI 原生 UI 等
|
||
- **192 套配色方案** - 与 192 种产品类型 1:1 对齐的行业专属调色板
|
||
- **74 种字体配对** - 精选字体组合，含 Google Fonts 导入
|
||
- **25 种图表类型** - 适用于仪表板和分析场景的推荐
|
||
- **22 种技术栈** - React、Next.js、Astro、Vue、Nuxt.js、Nuxt UI、Svelte、SwiftUI、React Native、Flutter、HTML+Tailwind、shadcn/ui、Jetpack Compose、Angular、Laravel、Three.js、JavaFX、WPF、WinUI 3、UWP、Avalonia、Uno Platform
|
||
- **119 条 UX 指南** - 最佳实践、反模式、无障碍规则、弹性文字布局、紧凑标签与可取消交互
|
||
- **192 条推理规则** - 行业特定的设计系统生成（v2.0 新增）
|
||
|
||
### 弹性文字与紧凑型 UI
|
||
|
||
指南现在覆盖标题、长 token、chip、badge 以及微交互被中断时常见的生产问题：
|
||
|
||
- 标题平衡换行属于 progressive enhancement，不能保证某个单词一定留在最后一行。
|
||
设计仍须在不同宽度、字体和 locale 下支持自然换行。
|
||
- 关键文字在窄屏、浏览器缩放、文字缩放和用户文字间距覆盖下必须完整 reflow，
|
||
不得裁切；长 URL 和 identifier 应能安全换行。
|
||
- Chip 与 tag 集合应换行，或提供可操作的 `+n` 展开入口。紧凑标签应尽量保持
|
||
单行；不可避免的截断必须让键盘、pointer 和 touch 用户都能查看完整值。
|
||
- Badge 的含义不能只依赖颜色。交互式 chip 需要原生 semantics、可见 Focus 和
|
||
programmatic state；动态计数需要有意义的上下文。
|
||
- 快速交互可以取消 animation，但最终 semantic state、Focus 与内容必须正确。
|
||
Timing 应按平台和组件选择，并尊重 reduced-motion 偏好。
|
||
|
||
### 风格分类
|
||
|
||
数据库包含 **79 种可搜索风格**，并使用稳定 ID 和别名关联：
|
||
|
||
| 状态 | 数量 | 搜索行为 |
|
||
|------|-----:|----------|
|
||
| Active | 50 | 参与常规推荐，并默认显示在 Gallery 中 |
|
||
| Supplemental | 29 | 仅在精确名称或明确的变体/设计系统意图下返回；可通过 Gallery 状态筛选查看 |
|
||
| Deprecated | 9 | 不参与常规排序；旧名称会重定向到规范风格或落地页模式 |
|
||
|
||
Active 集合包括 43 个通用视觉家族、2 个移动端专用风格、3 个官方平台/设计系统、1 个平台材质，以及 1 个核心分析风格。当前官方系统包括 Fluent 2、Shopify Polaris 和 Adobe Spectrum；Liquid Glass 被限定为 Apple 平台材质，Material 3 Expressive 保留为 Material 移动端变体，Spectrum 2 为 Supplemental。落地页结构位于独立的 34 条模式数据集中，不再与视觉风格竞争 BM25 排名。
|
||
|
||
完整分类及 provenance 元数据见 [`styles.csv`](src/ui-ux-pro-max/data/styles.csv)。
|
||
|
||
## 💎 基础版与高级版对比
|
||
|
||
许多用户询问开源版与高级版之间的差异。以下是详细的对比，帮助你选择适合自己工作流的版本。
|
||
|
||
### 🟢 基础版（本仓库）
|
||
* **完全开源：** 适合个人开发者、爱好者及标准项目。
|
||
* **核心 UI/UX 智能：** 完整支持 79 种可搜索 UI 风格（50 种 active）、192 种产品类型、配色方案和精选字体配对。
|
||
* **智能推荐：** 内置 BM25 搜索引擎，提供高精度的设计匹配。
|
||
* **跨平台支持：** 提供针对 22 个主流技术栈（React、Vue、Tailwind、iOS、Android 等）的专属指南。
|
||
* **设计系统生成：** 通过 CLI 即时生成定制化的 UI 规则、模式与逻辑。
|
||
|
||
### 🟡 高级版
|
||
* **扩展的品牌设计能力：** 超越 UI/UX 范畴，涵盖品牌标识生成、Logo 设计、企业识别系统 (CIP)、横幅、演示文稿幻灯片及自定义图标设计。
|
||
* **高级资产生成：** 深度集成 AI 图像生成能力，创建真实视觉素材而非占位符。
|
||
* **企业级架构：** 更全面、可扩展的设计令牌 (Design Token) 架构，面向大规模团队部署。
|
||
* **优先支持：** 为需要不间断完整设计工作流的团队和专业人士提供专属技术支持。
|
||
|
||
👉 *如需了解升级到高级版的更多详情，请访问 [uupm.cc](https://uupm.cc)。*
|
||
|
||
## 安装
|
||
|
||
### 使用 Claude Marketplace (Claude Code)
|
||
|
||
通过两条命令直接在 Claude Code 中安装：
|
||
|
||
```
|
||
/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill
|
||
/plugin install ui-ux-pro-max@ui-ux-pro-max-skill
|
||
```
|
||
|
||
### 使用 CLI (推荐)
|
||
|
||
```bash
|
||
# 全局安装 CLI
|
||
npm install -g ui-ux-pro-max-cli
|
||
|
||
# 进入你的项目
|
||
cd /path/to/your/project
|
||
|
||
# 为你的 AI 助手安装
|
||
uipro init --ai claude # Claude Code
|
||
uipro init --ai cursor # Cursor
|
||
uipro init --ai windsurf # Windsurf
|
||
uipro init --ai antigravity # Antigravity
|
||
uipro init --ai copilot # GitHub Copilot
|
||
uipro init --ai kiro # Kiro
|
||
uipro init --ai codex # Codex CLI
|
||
uipro init --ai qoder # Qoder
|
||
uipro init --ai roocode # Roo Code
|
||
uipro init --ai gemini # Gemini CLI
|
||
uipro init --ai trae # Trae
|
||
uipro init --ai opencode # OpenCode
|
||
uipro init --ai continue # Continue
|
||
uipro init --ai codebuddy # CodeBuddy
|
||
uipro init --ai droid # Droid (Factory)
|
||
uipro init --ai kilocode # KiloCode
|
||
uipro init --ai warp # Warp
|
||
uipro init --ai augment # Augment
|
||
uipro init --ai codewhale # CodeWhale
|
||
uipro init --ai universal # Universal / Agent Standard (.agents/skills/)
|
||
uipro init --ai all # 所有助手
|
||
```
|
||
|
||
npm 包名为 `ui-ux-pro-max-cli`；它仍然安装 `uipro` 命令。旧版 `uipro-cli` 已过时，不应用于当前资源。
|
||
|
||
### 全局安装（适用于所有项目）
|
||
|
||
```bash
|
||
uipro init --ai claude --global # 安装到 ~/.claude/skills/
|
||
uipro init --ai cursor --global # 安装到 ~/.cursor/skills/
|
||
uipro init --ai universal --global # 安装到 ~/.agents/skills/
|
||
```
|
||
|
||
### 其他 CLI 命令
|
||
|
||
```bash
|
||
uipro versions # 列出可用版本
|
||
uipro update # 从已安装的 CLI 包刷新技能文件
|
||
uipro update --global # 从已安装的 CLI 包刷新全局技能文件
|
||
uipro init --offline # 兼容性标志；安装捆绑模板
|
||
uipro uninstall # 移除技能（自动检测平台）
|
||
uipro uninstall --ai claude # 移除特定平台
|
||
uipro uninstall --global # 移除全局安装
|
||
```
|
||
|
||
## 前置要求
|
||
|
||
搜索脚本需要 Python 3.x（仅使用标准库 — 脚本不安装任何东西，也不进行网络请求）。
|
||
|
||
```bash
|
||
# 检查是否已安装 Python
|
||
python3 --version
|
||
```
|
||
|
||
如果未安装，请**你自己**从 [python.org](https://www.python.org/downloads/) 或通过系统包管理器（Homebrew、apt、winget）安装。这些安装步骤面向人类用户 — 使用此技能的 AI 代理不应在你的机器上安装软件，而应请你自行安装。
|
||
|
||
## 使用方式
|
||
|
||
### 技能模式 (自动激活)
|
||
|
||
**支持：** Claude Code、Cursor、Windsurf、Antigravity、Codex CLI、Continue、Gemini CLI、OpenCode、Qoder、CodeBuddy、Droid (Factory)、KiloCode、Warp、Augment、CodeWhale
|
||
|
||
当你请求 UI/UX 工作时，技能会自动激活。只需自然地聊天：
|
||
|
||
```
|
||
为我的 SaaS 产品搭建一个落地页
|
||
```
|
||
|
||
> **Trae**：先切换到 **SOLO** 模式。技能会在 UI/UX 请求时激活。
|
||
|
||
### 工作流模式 (斜杠命令)
|
||
|
||
**支持：** Kiro、GitHub Copilot、Roo Code、KiloCode
|
||
|
||
使用斜杠命令调用技能：
|
||
|
||
```
|
||
/ui-ux-pro-max 为我的 SaaS 产品搭建一个落地页
|
||
```
|
||
|
||
### 示例提示词
|
||
|
||
```
|
||
为我的 SaaS 产品搭建一个落地页
|
||
|
||
创建一个医疗健康分析仪表板
|
||
|
||
设计一个带深色模式的作品集网站
|
||
|
||
为电商制作一个移动应用 UI
|
||
|
||
搭建一个带深色主题的金融科技银行应用
|
||
```
|
||
|
||
### 工作原理
|
||
|
||
1. **你提出请求** - 请求任何 UI/UX 任务（构建、设计、创建、实现、审查、修复、改进）
|
||
2. **生成设计系统** - AI 使用推理引擎自动生成完整的设计系统
|
||
3. **智能推荐** - 根据你的产品类型和需求，找到最佳匹配的风格、配色和字体
|
||
4. **代码生成** - 使用正确的颜色、字体、间距和最佳实践实现 UI
|
||
5. **交付前检查** - 针对常见 UI/UX 反模式进行验证
|
||
|
||
### 支持的技术栈
|
||
|
||
该技能为以下技术栈提供特定指南：
|
||
|
||
| 分类 | 技术栈 |
|
||
|------|--------|
|
||
| **Web (HTML)** | HTML + Tailwind (默认) |
|
||
| **React 生态** | React、Next.js、shadcn/ui |
|
||
| **Vue 生态** | Vue、Nuxt.js、Nuxt UI |
|
||
| **Angular** | Angular |
|
||
| **PHP** | Laravel (Blade、Livewire、Inertia.js) |
|
||
| **其他 Web** | Svelte、Astro、Three.js |
|
||
| **桌面端** | JavaFX、WPF、WinUI 3、Avalonia、Uno Platform、UWP |
|
||
| **iOS** | SwiftUI |
|
||
| **Android** | Jetpack Compose |
|
||
| **跨平台** | React Native、Flutter |
|
||
|
||
只需在提示词中提到你偏好的技术栈，或让它默认使用 HTML + Tailwind。
|
||
|
||
## 设计系统命令 (高级)
|
||
|
||
如需直接访问设计系统生成器：
|
||
|
||
> 注意：如果你通过 Continue 安装，将下面命令中的 `.claude/skills/` 替换为 `.continue/skills/`。对于 Droid (Factory)，使用 `.factory/skills/`。
|
||
|
||
```bash
|
||
# 生成带 ASCII 输出的设计系统
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness" --design-system -p "Serenity Spa"
|
||
|
||
# 生成带 Markdown 输出
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "fintech banking" --design-system -f markdown
|
||
|
||
# 特定领域搜索
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "glassmorphism" --domain style
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "elegant serif" --domain typography
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "dashboard" --domain chart
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "error summary validation" --domain ux
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "decorative icon aria hidden" --domain icons
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "icon button accessible label" --domain icons
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "orphan heading line balance" --domain ux
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "badge chip label wraps to second line" --domain ux
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "rapid chip animation interrupted" --domain ux
|
||
|
||
# 特定技术栈指南
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "form validation" --stack react
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "responsive layout" --stack html-tailwind
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "chip badge overflow nowrap" --stack html-tailwind
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "tableview binding" --stack javafx
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "atlantafx primer enterprise theme" --stack javafx
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "enterprise tableview density permission" --stack javafx
|
||
```
|
||
|
||
Web 技术栈搜索支持版本感知。未指定旧主版本时，只返回当前 active 指南；明确使用
|
||
legacy 关键词或旧主版本（例如 `Svelte 4`、`Next.js 15`）时，只返回经过整理的
|
||
legacy 条目，并通过 `Status` 和 `Applies To` 标识。若没有对应的 legacy 指南，
|
||
搜索会返回空结果，不会混合不同框架世代的内容。
|
||
|
||
### 持久化设计系统 (主配置 + 覆盖模式)
|
||
|
||
将设计系统保存到文件，实现**跨会话的层级检索**：
|
||
|
||
```bash
|
||
# 生成并持久化到 design-system/MASTER.md
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "SaaS dashboard" --design-system --persist -p "MyApp"
|
||
|
||
# 同时创建页面特定的覆盖文件
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "SaaS dashboard" --design-system --persist -p "MyApp" --page "dashboard"
|
||
```
|
||
|
||
这会创建 `design-system/` 文件夹结构：
|
||
|
||
```
|
||
design-system/
|
||
├── MASTER.md # 全局唯一真相源 (颜色、字体、间距、组件)
|
||
└── pages/
|
||
└── dashboard.md # 页面特定覆盖 (仅与主配置的偏差)
|
||
```
|
||
|
||
**层级检索工作原理：**
|
||
1. 构建特定页面 (如"结账页") 时，先检查 `design-system/pages/checkout.md`
|
||
2. 如果页面文件存在，其规则**覆盖**主配置文件
|
||
3. 如果不存在，仅使用 `design-system/MASTER.md`
|
||
|
||
**上下文感知检索提示词：**
|
||
```
|
||
我正在构建 [页面名称] 页面。请阅读 design-system/MASTER.md。
|
||
同时检查 design-system/pages/[page-name].md 是否存在。
|
||
如果页面文件存在，优先使用其规则。
|
||
如果不存在，仅使用主配置规则。
|
||
现在，生成代码...
|
||
```
|
||
|
||
## 架构与贡献
|
||
|
||
### 对于用户
|
||
|
||
代码库已重构为使用**基于模板的生成系统**。所有平台特定文件 (`.cursor/`、`.windsurf/`、`.kiro/`、`.factory/` 等) 现在由 CLI 动态生成。
|
||
|
||
**始终使用 CLI 安装：**
|
||
|
||
```bash
|
||
npm install -g ui-ux-pro-max-cli
|
||
uipro init --ai <platform>
|
||
```
|
||
|
||
这确保你获得随已安装 CLI 包捆绑的最新模板，以及适用于 AI 助手的正确文件结构。发布新版本时请先更新 npm 包。
|
||
|
||
### 对于贡献者
|
||
|
||
如果你想为这个项目做贡献：
|
||
|
||
```bash
|
||
# 1. 克隆仓库
|
||
git clone https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git
|
||
cd ui-ux-pro-max-skill
|
||
|
||
# 2. 理解结构
|
||
src/ui-ux-pro-max/ # 唯一真相源 (数据、脚本、模板)
|
||
cli/ # CLI 安装器 (从模板生成文件)
|
||
.claude/ # Claude Code 技能的本地开发/测试
|
||
.factory/ # Droid (Factory) 技能的本地开发/测试
|
||
|
||
# 3. 在 src/ui-ux-pro-max/ 中修改
|
||
# - data/*.csv → 数据库文件
|
||
# - scripts/*.py → 搜索引擎与设计系统
|
||
# - templates/ → 平台特定模板
|
||
|
||
# 4. 同步到 CLI 并本地测试
|
||
cd cli
|
||
npm run sync:assets
|
||
npm run check:assets
|
||
npm run verify:data
|
||
npm run typecheck
|
||
|
||
# 5. 构建并测试 CLI
|
||
bun run build
|
||
node dist/index.js init --ai claude --offline # 在临时文件夹中测试
|
||
|
||
# 6. 创建 PR (永远不要直接推送到 main)
|
||
git checkout -b feat/your-feature
|
||
git commit -m "feat: description"
|
||
git push -u origin feat/your-feature
|
||
gh pr create
|
||
```
|
||
|
||
详细的开发指南请参见 [CLAUDE.md](CLAUDE.md)。
|
||
|
||
### Catalog provenance 与刷新流程
|
||
|
||
当前提交的 catalog summary 记录了 **1,934 个已批准的 Google Fonts**，
|
||
以及 **8 个待审核的排除项**；在缺少匹配的官方 license 元数据时，这些排除项
|
||
不会被提升。图标指导仍有 **105 条精选记录**（其中 100 条是直接的
|
||
Phosphor web imports，其余为 React Native/fallback 指导）；独立的
|
||
**1,512-icon Phosphor upstream manifest** 用于验证名称、weights 以及
|
||
React/SSR imports，而不会把整个 upstream package 塞进搜索结果。
|
||
|
||
日常开发和 pull-request CI 完全离线，不依赖网络。可用以下命令运行完整
|
||
offline gate，其中包含 snapshot hash 和生成计数校验：
|
||
|
||
```bash
|
||
npm --prefix cli run verify:data
|
||
# 或仅检查生成的 catalog summary：
|
||
npm --prefix cli run validate:catalog-summary
|
||
```
|
||
|
||
也可以使用已提交的 fixtures 完全离线执行 refresh normalization。输出只写入
|
||
临时 candidate 目录，绝不会替换 canonical data：
|
||
|
||
```bash
|
||
candidate_dir="$(mktemp -d)"
|
||
python3 scripts/refresh-google-fonts.py \
|
||
--api-input src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-api.json \
|
||
--metadata-input src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-metadata.json \
|
||
--existing-csv src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-existing.csv \
|
||
--overrides src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-overrides.json \
|
||
--output-csv "$candidate_dir/google-fonts.csv" \
|
||
--license-output "$candidate_dir/google-font-licenses.json" \
|
||
--metadata-revision fixture-catalogs-v1 \
|
||
--verified-at 2026-08-13 --expected-count 2 --approve-changes
|
||
python3 scripts/refresh-icon-catalog.py \
|
||
--input src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-core.json \
|
||
--package-json src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-package.json \
|
||
--react-package-json src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-react-package.json \
|
||
--react-exports-input src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-react-exports.json \
|
||
--curated-csv src/ui-ux-pro-max/scripts/tests/fixtures/catalogs/icons-curated.csv \
|
||
--output "$candidate_dir/phosphor-icons-upstream.json" \
|
||
--verified-at 2026-08-13 --expected-count 2
|
||
```
|
||
|
||
Live upstream refresh 被有意隔离在 `refresh-catalogs.yml` workflow 中；它会在
|
||
每周一 03:17 UTC 定时运行，也可以手动触发。将 `GOOGLE_FONTS_API_KEY` 配置为
|
||
GitHub Actions secret，然后运行并下载审核 artifact：
|
||
|
||
```bash
|
||
gh workflow run refresh-catalogs.yml
|
||
run_id="$(gh run list --workflow refresh-catalogs.yml --limit 1 --json databaseId --jq '.[0].databaseId')"
|
||
gh run watch "$run_id"
|
||
gh run download "$run_id" --name "catalog-refresh-review-$run_id"
|
||
```
|
||
|
||
该 workflow 读取 Google Fonts Developer API 和固定版本的官方 Phosphor
|
||
packages，只把 candidates 与 unified diffs 写入 artifact，并且仅有只读仓库权限。
|
||
它不会 commit、push、创建 PR 或 merge。必须先审核 change reports、排除项、
|
||
licenses、relevance metrics 和 offline gate，之后才能手动把 candidate files
|
||
提升到 `src/ui-ux-pro-max/data/`。
|
||
|
||
## 自动化发布
|
||
|
||
本仓库使用 semantic-release 配合约定式提交 (Conventional Commits) 自动创建 GitHub 发布：
|
||
|
||
- `dev` 分支创建 beta GitHub 预发布，如 `2.6.0-beta.1`。
|
||
- `main` 分支创建官方稳定版 GitHub 发布，如 `2.6.0`。
|
||
|
||
发布说明和 `CHANGELOG.md` 根据约定式提交信息生成。在发布准备期间，版本号会在 `skill.json`、`.claude-plugin/plugin.json`、`.claude-plugin/marketplace.json`、`cli/package.json` 和 `cli/package-lock.json` 之间同步。
|
||
|
||
使用以下提交类型以获得正确的版本号升级：
|
||
|
||
- `fix:` -> 补丁版本发布
|
||
- `feat:` -> 次版本发布
|
||
- `feat!:` 或 `BREAKING CHANGE:` -> 主版本发布
|
||
|
||
发布工作流使用默认的 `GITHUB_TOKEN` 创建 GitHub 发布，并使用仓库的 `NPM_TOKEN` 密钥将 `ui-ux-pro-max-cli` 发布到 npm。
|
||
|
||
## 故障排查
|
||
|
||
### `uipro: unknown command 'uninstall'` 或 `unknown command 'update'`
|
||
|
||
你安装的 `ui-ux-pro-max-cli` 版本已过时。请更新后重试：
|
||
|
||
```bash
|
||
npm install -g ui-ux-pro-max-cli@latest
|
||
uipro uninstall
|
||
```
|
||
|
||
### `uipro uninstall` 提示 "No installed AI skill directories detected"
|
||
|
||
技能安装在与运行命令不同的目录中。可以：
|
||
|
||
```bash
|
||
# 方案 A — 切换到最初安装它的项目根目录
|
||
cd /path/to/your/project
|
||
uipro uninstall
|
||
|
||
# 方案 B — 移除全局安装
|
||
uipro uninstall --global
|
||
|
||
# 方案 C — 手动移除
|
||
rm -rf .claude/skills/ui-ux-pro-max # Claude Code
|
||
rm -rf .cursor/skills/ui-ux-pro-max # Cursor
|
||
rm -rf .windsurf/skills/ui-ux-pro-max # Windsurf
|
||
rm -rf .agents/skills/ui-ux-pro-max # Antigravity / Codex
|
||
```
|
||
|
||
### Claude.ai 的“上传技能”对话框提示 "Zip contains too many files (maximum 200)"
|
||
|
||
请勿上传完整的 GitHub 仓库 ZIP。该 ZIP 是开发用的代码仓库，包含源代码、CLI 资源、文档、预览以及多个打包的技能，因此会超出 Claude 的 200 个文件上传限制。它不是用于上传到 Claude 的技能安装包，并且本项目目前不提供用于手动上传到 Claude.ai 的单独 ZIP。
|
||
|
||
对于 Claude Code，请通过 Marketplace 安装：
|
||
|
||
```bash
|
||
/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill
|
||
/plugin install ui-ux-pro-max@ui-ux-pro-max-skill
|
||
```
|
||
|
||
也可以使用 CLI 安装器：
|
||
|
||
```bash
|
||
npx ui-ux-pro-max-cli init --ai claude
|
||
```
|
||
|
||
### Claude Marketplace 安装失败，提示 "Zip file contains a symbolic link"
|
||
|
||
这是 v2.5.1 之前版本的已知问题。仓库内部使用了符号链接，某些安装工具无法处理。**解决办法：** 改用 CLI 安装器：
|
||
|
||
```bash
|
||
npm install -g ui-ux-pro-max-cli
|
||
uipro init --ai claude
|
||
```
|
||
|
||
或等待下一个已修复此问题的版本发布。
|
||
|
||
### `npm install -g ui-ux-pro-max-cli` 失败，提示权限错误
|
||
|
||
使用 Node 版本管理器（推荐），或直接跳过全局安装：
|
||
|
||
```bash
|
||
# 使用 npx 而不全局安装
|
||
npx ui-ux-pro-max-cli init --ai claude
|
||
```
|
||
|
||
### 运行设计系统命令时找不到 Python
|
||
|
||
搜索脚本需要 Python 3.x。请从 [python.org](https://www.python.org/downloads/) 或通过系统包管理器（Homebrew、apt、winget）自行安装。AI 代理不应替你安装 — 它们被要求先征求你的意见。
|
||
|
||
### 设计系统输出被截断 / 字段不完整
|
||
|
||
人类可读输出会将超过 300 字符的长字段截断。使用 `--json` 获取完整、未截断的数据：
|
||
|
||
```bash
|
||
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "SaaS" --domain style --json
|
||
```
|
||
|
||
---
|
||
|
||
## Star 历史
|
||
|
||
[](https://star-history.com/#nextlevelbuilder/ui-ux-pro-max-skill&Date)
|
||
|
||
## 许可证
|
||
|
||
本项目采用 [MIT 许可证](LICENSE) 授权。
|
||
|
||
## 兼容的智能体
|
||
|
||
本技能可与以下工具配合使用：
|
||
- [Claude Code](https://claude.com/product/claude-code)
|
||
- [AdaL](https://sylph.ai/) - 自进化的 AI 编码智能体（[文档](https://docs.sylph.ai/) | [GitHub](https://github.com/SylphAI-Inc/adal-cli)）
|