# {{TITLE}}

{{DESCRIPTION}}
{{QUICK_REFERENCE}}

# Prerequisites

Check if Python is installed:

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

If Python is not installed, install it based on user's OS:

**macOS:**

```bash
brew install python3
```

**Ubuntu/Debian:**

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

**Windows:**

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

---

## How to Use This Skill

Use this skill when the user requests any of the following:

| Scenario                        | Trigger Examples                                  | Start From                         |
| ------------------------------- | ------------------------------------------------- | ---------------------------------- |
| **New project / page**          | "做一个 landing page"、"Build a dashboard"        | Step 1 → Step 2 (design system)    |
| **New component**               | "Create a pricing card"、"Add a modal"            | Step 3 (domain search: style, ux)  |
| **Choose style / color / font** | "What style fits a fintech app?"、"推荐配色"      | Step 2 (design system)             |
| **Review existing UI**          | "Review this page for UX issues"、"检查无障碍"    | Quick Reference checklist above    |
| **Fix a UI bug**                | "Button hover is broken"、"Layout shifts on load" | Quick Reference → relevant section |
| **Improve / optimize**          | "Make this faster"、"Improve mobile experience"   | Step 3 (domain search: ux, react)  |
| **Implement dark mode**         | "Add dark mode support"                           | Step 3 (domain: style "dark mode") |
| **Add charts / data viz**       | "Add an analytics dashboard chart"                | Step 3 (domain: chart)             |
| **Stack best practices**        | "React performance tips"、"SwiftUI navigation"    | Step 4 (stack search)              |

Follow this workflow:

### Step 1: Analyze User Requirements

Extract key information from user request:

- **Product type**: Entertainment (social, video, music, gaming), Tool (scanner, editor, converter), Productivity (task manager, notes, calendar), or hybrid
- **Target audience**: C-end consumer users; consider age group, usage context (commute, leisure, work)
- **Style keywords**: playful, vibrant, minimal, dark mode, content-first, immersive, etc.
- **Stack**: React Native (this project's only tech stack)

### Step 2: Generate Design System (REQUIRED)

**Always start with `--design-system`** to get comprehensive recommendations with reasoning:

```bash
python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
```

This command:

1. Searches domains in parallel (product, style, color, landing, typography)
2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
3. Returns complete design system: pattern, style, colors, typography, effects
4. Includes anti-patterns to avoid

**Example:**

```bash
python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
```

### Step 2b: Persist Design System (Master + Overrides Pattern)

To save the design system for **hierarchical retrieval across sessions**, add `--persist`:

```bash
python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
```

This creates:

- `design-system/MASTER.md` — Global Source of Truth with all design rules
- `design-system/pages/` — Folder for page-specific overrides

**With page-specific override:**

```bash
python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
```

This also creates:

- `design-system/pages/dashboard.md` — Page-specific deviations from Master

**How hierarchical retrieval works:**

1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
2. If the page file exists, its rules **override** the Master file
3. If not, use `design-system/MASTER.md` exclusively

**Context-aware retrieval prompt:**

```
I am building the [Page Name] page. Please read design-system/MASTER.md.
Also check if design-system/pages/[page-name].md exists.
If the page file exists, prioritize its rules.
If not, use the Master rules exclusively.
Now, generate the code...
```

### Step 3: Supplement with Detailed Searches (as needed)

After getting the design system, use domain searches to get additional details:

```bash
python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
```

**When to use detailed searches:**

| Need                     | Domain       | Example                                              |
| ------------------------ | ------------ | ---------------------------------------------------- |
| Product type patterns    | `product`    | `--domain product "entertainment social"`            |
| More style options       | `style`      | `--domain style "glassmorphism dark"`                |
| Color palettes           | `color`      | `--domain color "entertainment vibrant"`             |
| Font pairings            | `typography` | `--domain typography "playful modern"`               |
| Chart recommendations    | `chart`      | `--domain chart "real-time dashboard"`               |
| UX best practices        | `ux`         | `--domain ux "animation accessibility"`              |
| Landing structure        | `landing`    | `--domain landing "hero social-proof"`               |
| React Native perf        | `react`      | `--domain react "rerender memo list"`                |
| App interface a11y       | `web`        | `--domain web "accessibilityLabel touch safe-areas"` |
| AI prompt / CSS keywords | `prompt`     | `--domain prompt "minimalism"`                       |

### Step 4: Stack Guidelines (React Native)

Get React Native implementation-specific best practices:

```bash
python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack react-native
```

---

## Search Reference

### Available Domains

| Domain       | Use For                                             | Example Keywords                                            |
| ------------ | --------------------------------------------------- | ----------------------------------------------------------- |
| `product`    | Product type recommendations                        | SaaS, e-commerce, portfolio, healthcare, beauty, service    |
| `style`      | UI styles, colors, effects                          | glassmorphism, minimalism, dark mode, brutalism             |
| `typography` | Font pairings, Google Fonts                         | elegant, playful, professional, modern                      |
| `color`      | Color palettes by product type                      | saas, ecommerce, healthcare, beauty, fintech, service       |
| `landing`    | Page structure, CTA strategies                      | hero, hero-centric, testimonial, pricing, social-proof      |
| `chart`      | Chart types, library recommendations                | trend, comparison, timeline, funnel, pie                    |
| `ux`         | Best practices, anti-patterns                       | animation, accessibility, z-index, loading                  |
| `react`      | React/Next.js performance                           | waterfall, bundle, suspense, memo, rerender, cache          |
| `web`        | App interface guidelines (iOS/Android/React Native) | accessibilityLabel, touch targets, safe areas, Dynamic Type |
| `prompt`     | AI prompts, CSS keywords                            | (style name)                                                |

### Available Stacks

| Stack          | Focus                         |
| -------------- | ----------------------------- |
| `react-native` | Components, Navigation, Lists |

---

## Example Workflow

**User request:** "Make an AI search homepage。"

### Step 1: Analyze Requirements

- Product type: Tool (AI search engine)
- Target audience: C-end users looking for fast, intelligent search
- Style keywords: modern, minimal, content-first, dark mode
- Stack: React Native

### Step 2: Generate Design System (REQUIRED)

```bash
python3 skills/ui-ux-pro-max/scripts/search.py "AI search tool modern minimal" --design-system -p "AI Search"
```

**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.

### Step 3: Supplement with Detailed Searches (as needed)

```bash
# Get style options for a modern tool product
python3 skills/ui-ux-pro-max/scripts/search.py "minimalism dark mode" --domain style

# Get UX best practices for search interaction and loading
python3 skills/ui-ux-pro-max/scripts/search.py "search loading animation" --domain ux
```

### Step 4: Stack Guidelines

```bash
python3 skills/ui-ux-pro-max/scripts/search.py "list performance navigation" --stack react-native
```

**Then:** Synthesize design system + detailed searches and implement the design.

---

## Output Formats

The `--design-system` flag supports two output formats:

```bash
# ASCII box (default) - best for terminal display
python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system

# Markdown - best for documentation
python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
```

---

## Tips for Better Results

### Query Strategy

- Use **multi-dimensional keywords** — combine product + industry + tone + density: `"entertainment social vibrant content-dense"` not just `"app"`
- Try different keywords for the same need: `"playful neon"` → `"vibrant dark"` → `"content-first minimal"`
- Use `--design-system` first for full recommendations, then `--domain` to deep-dive any dimension you're unsure about
- Always add `--stack react-native` for implementation-specific guidance

### Common Sticking Points

| Problem                        | What to Do                                                                          |
| ------------------------------ | ----------------------------------------------------------------------------------- |
| Can't decide on style/color    | Re-run `--design-system` with different keywords                                    |
| Dark mode contrast issues      | Quick Reference §6: `color-dark-mode` + `color-accessible-pairs`                    |
| Animations feel unnatural      | Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter`          |
| Form UX is poor                | Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management`      |
| Navigation feels confusing     | Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior`          |
| Layout breaks on small screens | Quick Reference §5: `mobile-first` + `breakpoint-consistency`                       |
| Performance / jank             | Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle` |

### Pre-Delivery Checklist

- Run `--domain ux "animation accessibility z-index loading"` as a UX validation pass before implementation
- Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review
- Test on 375px (small phone) and landscape orientation
- Verify behavior with **reduced-motion** enabled and **Dynamic Type** at largest size
- Check dark mode contrast independently (don't assume light mode values work)
- Confirm all touch targets ≥44pt and no content hidden behind safe areas

---

## Common Rules for Professional UI

These are frequently overlooked issues that make UI look unprofessional:
Scope notice: The rules below are for App UI (iOS/Android/React Native/Flutter), not desktop-web interaction patterns.

### Icons & Visual Elements

- 默认图标库使用 **Phosphor (`@phosphor-icons/react`)**。`src/ui-ux-pro-max/data/icons.csv` 中列出的只是常用推荐图标，不是完整集合。
- 当推荐表中找不到合适的图标时：
  - **优先继续从 Phosphor 的完整图标集中选择任何语义更贴切的图标**；
  - 如果 Phosphor 也没有理想选项，可以使用 **Heroicons (`@heroicons/react`)** 作为备选，注意保持风格一致（线性/填充、笔画粗细、圆角风格）。

| Rule                             | Standard                                                                                                                                      | Avoid                                                                              | Why It Matters                                                                                        |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **No Emoji as Structural Icons** | Use vector-based icons (e.g., Phosphor `@phosphor-icons/react`, Heroicons `@heroicons/react`, react-native-vector-icons, @expo/vector-icons). | Using emojis (🎨 🚀 ⚙️) for navigation, settings, or system controls.              | Emojis are font-dependent, inconsistent across platforms, and cannot be controlled via design tokens. |
| **Vector-Only Assets**           | Use SVG or platform vector icons that scale cleanly and support theming.                                                                      | Raster PNG icons that blur or pixelate.                                            | Ensures scalability, crisp rendering, and dark/light mode adaptability.                               |
| **Stable Interaction States**    | Use color, opacity, or elevation transitions for press states without changing layout bounds.                                                 | Layout-shifting transforms that move surrounding content or trigger visual jitter. | Prevents unstable interactions and preserves smooth motion/perceived quality on mobile.               |
| **Correct Brand Logos**          | Use official brand assets and follow their usage guidelines (spacing, color, clear space).                                                    | Guessing logo paths, recoloring unofficially, or modifying proportions.            | Prevents brand misuse and ensures legal/platform compliance.                                          |
| **Consistent Icon Sizing**       | Define icon sizes as design tokens (e.g., icon-sm, icon-md = 24pt, icon-lg).                                                                  | Mixing arbitrary values like 20pt / 24pt / 28pt randomly.                          | Maintains rhythm and visual hierarchy across the interface.                                           |
| **Stroke Consistency**           | Use a consistent stroke width within the same visual layer (e.g., 1.5px or 2px).                                                              | Mixing thick and thin stroke styles arbitrarily.                                   | Inconsistent strokes reduce perceived polish and cohesion.                                            |
| **Filled vs Outline Discipline** | Use one icon style per hierarchy level.                                                                                                       | Mixing filled and outline icons at the same hierarchy level.                       | Maintains semantic clarity and stylistic coherence.                                                   |
| **Touch Target Minimum**         | Minimum 44×44pt interactive area (use hitSlop if icon is smaller).                                                                            | Small icons without expanded tap area.                                             | Meets accessibility and platform usability standards.                                                 |
| **Icon Alignment**               | Align icons to text baseline and maintain consistent padding.                                                                                 | Misaligned icons or inconsistent spacing around them.                              | Prevents subtle visual imbalance that reduces perceived quality.                                      |
| **Icon Contrast**                | Follow WCAG contrast standards: 4.5:1 for small elements, 3:1 minimum for larger UI glyphs.                                                   | Low-contrast icons that blend into the background.                                 | Ensures accessibility in both light and dark modes.                                                   |

### Interaction (App)

| Rule                            | Do                                                                                                                 | Don't                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| **Tap feedback**                | Provide clear pressed feedback (ripple/opacity/elevation) within 80-150ms                                          | No visual response on tap                                     |
| **Animation timing**            | Keep micro-interactions around 150-300ms with platform-native easing                                               | Instant transitions or slow animations (>500ms)               |
| **Accessibility focus**         | Ensure screen reader focus order matches visual order and labels are descriptive                                   | Unlabeled controls or confusing focus traversal               |
| **Disabled state clarity**      | Use disabled semantics (`disabled`/native disabled props), reduced emphasis, and no tap action                     | Controls that look tappable but do nothing                    |
| **Touch target minimum**        | Keep tap areas >=44x44pt (iOS) or >=48x48dp (Android), expand hit area when icon is smaller                        | Tiny tap targets or icon-only hit areas without padding       |
| **Gesture conflict prevention** | Keep one primary gesture per region and avoid nested tap/drag conflicts                                            | Overlapping gestures causing accidental actions               |
| **Semantic native controls**    | Prefer native interactive primitives (`Button`, `Pressable`, platform equivalents) with proper accessibility roles | Generic containers used as primary controls without semantics |

### Light/Dark Mode Contrast

| Rule                              | Do                                                                                      | Don't                                                |
| --------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Surface readability (light)**   | Keep cards/surfaces clearly separated from background with sufficient opacity/elevation | Overly transparent surfaces that blur hierarchy      |
| **Text contrast (light)**         | Maintain body text contrast >=4.5:1 against light surfaces                              | Low-contrast gray body text                          |
| **Text contrast (dark)**          | Maintain primary text contrast >=4.5:1 and secondary text >=3:1 on dark surfaces        | Dark mode text that blends into background           |
| **Border and divider visibility** | Ensure separators are visible in both themes (not just light mode)                      | Theme-specific borders disappearing in one mode      |
| **State contrast parity**         | Keep pressed/focused/disabled states equally distinguishable in light and dark themes   | Defining interaction states for one theme only       |
| **Token-driven theming**          | Use semantic color tokens mapped per theme across app surfaces/text/icons               | Hardcoded per-screen hex values                      |
| **Scrim and modal legibility**    | Use a modal scrim strong enough to isolate foreground content (typically 40-60% black)  | Weak scrim that leaves background visually competing |

### Layout & Spacing

| Rule                                     | Do                                                                                       | Don't                                                     |
| ---------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **Safe-area compliance**                 | Respect top/bottom safe areas for all fixed headers, tab bars, and CTA bars              | Placing fixed UI under notch, status bar, or gesture area |
| **System bar clearance**                 | Add spacing for status/navigation bars and gesture home indicator                        | Let tappable content collide with OS chrome               |
| **Consistent content width**             | Keep predictable content width per device class (phone/tablet)                           | Mixing arbitrary widths between screens                   |
| **8dp spacing rhythm**                   | Use a consistent 4/8dp spacing system for padding/gaps/section spacing                   | Random spacing increments with no rhythm                  |
| **Readable text measure**                | Keep long-form text readable on large devices (avoid edge-to-edge paragraphs on tablets) | Full-width long text that hurts readability               |
| **Section spacing hierarchy**            | Define clear vertical rhythm tiers (e.g., 16/24/32/48) by hierarchy                      | Similar UI levels with inconsistent spacing               |
| **Adaptive gutters by breakpoint**       | Increase horizontal insets on larger widths and in landscape                             | Same narrow gutter on all device sizes/orientations       |
| **Scroll and fixed element coexistence** | Add bottom/top content insets so lists are not hidden behind fixed bars                  | Scroll content obscured by sticky headers/footers         |

---

## Pre-Delivery Checklist

Before delivering UI code, verify these items:
Scope notice: This checklist is for App UI (iOS/Android/React Native/Flutter).

### Visual Quality

- [ ] No emojis used as icons (use SVG instead)
- [ ] All icons come from a consistent icon family and style
- [ ] Official brand assets are used with correct proportions and clear space
- [ ] Pressed-state visuals do not shift layout bounds or cause jitter
- [ ] Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors)

### Interaction

- [ ] All tappable elements provide clear pressed feedback (ripple/opacity/elevation)
- [ ] Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android)
- [ ] Micro-interaction timing stays in the 150-300ms range with native-feeling easing
- [ ] Disabled states are visually clear and non-interactive
- [ ] Screen reader focus order matches visual order, and interactive labels are descriptive
- [ ] Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts)

### Light/Dark Mode

- [ ] Primary text contrast >=4.5:1 in both light and dark mode
- [ ] Secondary text contrast >=3:1 in both light and dark mode
- [ ] Dividers/borders and interaction states are distinguishable in both modes
- [ ] Modal/drawer scrim opacity is strong enough to preserve foreground legibility (typically 40-60% black)
- [ ] Both themes are tested before delivery (not inferred from a single theme)

### Layout

- [ ] Safe areas are respected for headers, tab bars, and bottom CTA bars
- [ ] Scroll content is not hidden behind fixed/sticky bars
- [ ] Verified on small phone, large phone, and tablet (portrait + landscape)
- [ ] Horizontal insets/gutters adapt correctly by device size and orientation
- [ ] 4/8dp spacing rhythm is maintained across component, section, and page levels
- [ ] Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs)

### Accessibility

- [ ] All meaningful images/icons have accessibility labels
- [ ] Form fields have labels, hints, and clear error messages
- [ ] Color is not the only indicator
- [ ] Reduced motion and dynamic text size are supported without layout breakage
- [ ] Accessibility traits/roles/states (selected, disabled, expanded) are announced correctly