ui-ux-pro-max-skill/.codebuddy/commands/ui-ux-pro-max.md

# ui-ux-pro-max

可搜索的数据库，包含 UI 风格、配色方案、字体配对、图表类型、产品推荐、UX 指南和特定技术栈的最佳实践。

## 前置要求

检查是否已安装 Python：

```bash
python3 --version || python --version
```

如果未安装 Python，根据用户的操作系统安装：

**macOS:**

```bash
brew install python3
```

**Ubuntu/Debian:**

```bash
sudo apt update && sudo apt install python3
```

**Windows:**

```powershell
winget install Python.Python.3.12
```

---

## 如何使用此工作流

当用户请求 UI/UX 工作（设计、构建、创建、实现、审查、修复、改进）时，遵循此工作流：

### 步骤 1：分析用户需求

从用户请求中提取关键信息：

-   **产品类型**：SaaS、电商、作品集、仪表板、落地页等
-   **风格关键词**：极简、活泼、专业、优雅、深色模式等
-   **行业**：医疗、金融科技、游戏、教育等
-   **技术栈**：React、Vue、Next.js，或默认为 `html-tailwind`

### 步骤 2：搜索相关领域

多次使用 `search.py` 收集全面信息。搜索直到获得足够的上下文。

```bash
python3 .shared/ui-ux-pro-max/scripts/search.py "<关键词>" --domain <领域> [-n <最大结果数>]
```

**推荐搜索顺序：**

1. **Product（产品）** - 获取产品类型的风格推荐
2. **Style（风格）** - 获取详细风格指南（颜色、效果、框架）
3. **Typography（排版）** - 获取字体配对及 Google Fonts 导入
4. **Color（颜色）** - 获取配色方案（主色、辅助色、CTA、背景、文本、边框）
5. **Landing（落地页）** - 获取页面结构（如果是落地页）
6. **Chart（图表）** - 获取图表推荐（如果是仪表板/分析）
7. **UX** - 获取最佳实践和反模式
8. **Stack（技术栈）** - 获取特定技术栈指南（默认：html-tailwind）

### 步骤 3：技术栈指南（默认：html-tailwind）

如果用户未指定技术栈，**默认使用 `html-tailwind`**。

```bash
python3 .shared/ui-ux-pro-max/scripts/search.py "<关键词>" --stack html-tailwind
```

可用技术栈：`html-tailwind`、`react`、`nextjs`、`vue`、`svelte`、`swiftui`、`react-native`、`flutter`、`shadcn`

---

## 搜索参考

### 可用领域

| 领域 | 用途 | 示例关键词 |
| ------------ | ------------------------------------ | -------------------------------------------------------- |
| `product`    | 产品类型推荐         | SaaS、电商、作品集、医疗、美妆、服务 |
| `style`      | UI 风格、颜色、效果           | 玻璃态、极简主义、深色模式、野兽派          |
| `typography` | 字体配对、Google Fonts          | 优雅、活泼、专业、现代                   |
| `color`      | 按产品类型的配色方案       | saas、电商、医疗、美妆、金融科技、服务    |
| `landing`    | 页面结构、CTA 策略       | 英雄区、英雄中心、推荐、定价、社会证明   |
| `chart`      | 图表类型、库推荐 | 趋势、对比、时间线、漏斗、饼图                 |
| `ux`         | 最佳实践、反模式        | 动画、无障碍、z-index、加载               |
| `prompt`     | AI 提示、CSS 关键词             | （风格名称）                                             |

### 可用技术栈

| 技术栈           | 重点                                          |
| --------------- | ---------------------------------------------- |
| `html-tailwind` | Tailwind 工具类、响应式、无障碍（默认） |
| `react`         | 状态、钩子、性能、模式            |
| `nextjs`        | SSR、路由、图片、API 路由               |
| `vue`           | Composition API、Pinia、Vue Router             |
| `svelte`        | Runes、stores、SvelteKit                       |
| `swiftui`       | 视图、状态、导航、动画            |
| `react-native`  | 组件、导航、列表                  |
| `flutter`       | 小部件、状态、布局、主题                |
| `shadcn`        | shadcn/ui 组件、主题、表单、模式 |

---

## 示例工作流

**用户请求：** "为专业护肤服务制作落地页"

**AI 应该：**

```bash
# 1. 搜索产品类型
python3 .shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --domain product

# 2. 搜索风格（基于行业：美妆、优雅）
python3 .shared/ui-ux-pro-max/scripts/search.py "elegant minimal soft" --domain style

# 3. 搜索排版
python3 .shared/ui-ux-pro-max/scripts/search.py "elegant luxury" --domain typography

# 4. 搜索配色方案
python3 .shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness" --domain color

# 5. 搜索落地页结构
python3 .shared/ui-ux-pro-max/scripts/search.py "hero-centric social-proof" --domain landing

# 6. 搜索 UX 指南
python3 .shared/ui-ux-pro-max/scripts/search.py "animation" --domain ux
python3 .shared/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux

# 7. 搜索技术栈指南（默认：html-tailwind）
python3 .shared/ui-ux-pro-max/scripts/search.py "layout responsive" --stack html-tailwind
```

**然后：** 综合所有搜索结果并实现设计。

---

## 获得更好结果的技巧

1. **关键词要具体** - "医疗 SaaS 仪表板" > "应用"
2. **多次搜索** - 不同关键词揭示不同见解
3. **组合领域** - 风格 + 排版 + 颜色 = 完整设计系统
4. **始终检查 UX** - 搜索"动画"、"z-index"、"无障碍"以发现常见问题
5. **使用技术栈标志** - 获取特定实现的最佳实践
6. **迭代** - 如果首次搜索不匹配，尝试不同关键词
7. **拆分为多个文件** - 为了更好的可维护性：
    - 将组件分离到单独文件（例如 `Header.tsx`、`Footer.tsx`）
    - 将可重用样式提取到专用文件
    - 保持每个文件专注且少于 200-300 行

---

## 专业 UI 的通用规则

这些是经常被忽视的问题，会让 UI 看起来不专业：

### Icons & Visual Elements

| Rule                       | Do                                              | Don't                                  |
| -------------------------- | ----------------------------------------------- | -------------------------------------- |
| **No emoji icons**         | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons   |
| **Stable hover states**    | Use color/opacity transitions on hover          | Use scale transforms that shift layout |
| **Correct brand logos**    | Research official SVG from Simple Icons         | Guess or use incorrect logo paths      |
| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6          | Mix different icon sizes randomly      |

### Interaction & Cursor

| Rule                   | Do                                                    | Don't                                        |
| ---------------------- | ----------------------------------------------------- | -------------------------------------------- |
| **Cursor pointer**     | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements |
| **Hover feedback**     | Provide visual feedback (color, shadow, border)       | No indication element is interactive         |
| **Smooth transitions** | Use `transition-colors duration-200`                  | Instant state changes or too slow (>500ms)   |

### Light/Dark Mode Contrast

| Rule                      | Do                                  | Don't                                   |
| ------------------------- | ----------------------------------- | --------------------------------------- |
| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent)     |
| **Text contrast light**   | Use `#0F172A` (slate-900) for text  | Use `#94A3B8` (slate-400) for body text |
| **Muted text light**      | Use `#475569` (slate-600) minimum   | Use gray-400 or lighter                 |
| **Border visibility**     | Use `border-gray-200` in light mode | Use `border-white/10` (invisible)       |

### Layout & Spacing

| Rule                     | Do                                  | Don't                                  |
| ------------------------ | ----------------------------------- | -------------------------------------- |
| **Floating navbar**      | Add `top-4 left-4 right-4` spacing  | Stick navbar to `top-0 left-0 right-0` |
| **Content padding**      | Account for fixed navbar height     | Let content hide behind fixed elements |
| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths         |

---

## Pre-Delivery Checklist

Before delivering UI code, verify these items:

### Visual Quality

-   [ ] No emojis used as icons (use SVG instead)
-   [ ] All icons from consistent icon set (Heroicons/Lucide)
-   [ ] Brand logos are correct (verified from Simple Icons)
-   [ ] Hover states don't cause layout shift

### Interaction

-   [ ] All clickable elements have `cursor-pointer`
-   [ ] Hover states provide clear visual feedback
-   [ ] Transitions are smooth (150-300ms)
-   [ ] Focus states visible for keyboard navigation

### Light/Dark Mode

-   [ ] Light mode text has sufficient contrast (4.5:1 minimum)
-   [ ] Glass/transparent elements visible in light mode
-   [ ] Borders visible in both modes
-   [ ] Test both modes before delivery

### Layout

-   [ ] Floating elements have proper spacing from edges
-   [ ] No content hidden behind fixed navbars
-   [ ] Responsive at 320px, 768px, 1024px, 1440px
-   [ ] No horizontal scroll on mobile

### Accessibility

-   [ ] All images have alt text
-   [ ] Form inputs have labels
-   [ ] Color is not the only indicator
-   [ ] `prefers-reduced-motion` respected