Merge pull request #83 from nextlevelbuilder/feat/v2.0.0-design-system

feat: v2.0.0 - Design System Generator with 100 reasoning rules

Author: viettranx

.agent/workflows/ui-ux-pro-max.md

@@ -3,9 +3,9 @@ description: Plan and implement UI
 auto_execution_mode: 3
 ---
 
-# UI/UX Pro Max - Design Intelligence
+# ui-ux-pro-max
 
-Searchable database of UI styles, color palettes, font pairings, chart types, product recommendations, UX guidelines, and stack-specific best practices.
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 9 technology stacks. Searchable database with priority-based recommendations.
 
 ## Prerequisites
 
@@ -46,28 +46,46 @@ Extract key information from user request:
 - **Industry**: healthcare, fintech, gaming, education, etc.
 - **Stack**: React, Vue, Next.js, or default to `html-tailwind`
 
-### Step 2: Search Relevant Domains
+### Step 2: Generate Design System (REQUIRED)
 
-Use `search.py` multiple times to gather comprehensive information. Search until you have enough context.
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 .shared/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches 5 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 .shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
 
 ```bash
 python3 .shared/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
 ```
 
-**Recommended search order:**
+**When to use detailed searches:**
 
-1. **Product** - Get style recommendations for product type
-2. **Style** - Get detailed style guide (colors, effects, frameworks)
-3. **Typography** - Get font pairings with Google Fonts imports
-4. **Color** - Get color palette (Primary, Secondary, CTA, Background, Text, Border)
-5. **Landing** - Get page structure (if landing page)
-6. **Chart** - Get chart recommendations (if dashboard/analytics)
-7. **UX** - Get best practices and anti-patterns
-8. **Stack** - Get stack-specific guidelines (default: html-tailwind)
+| Need | Domain | Example |
+|------|--------|---------|
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
 
-### Step 3: Stack Guidelines (Default: html-tailwind)
+### Step 4: Stack Guidelines (Default: html-tailwind)
 
-If user doesn't specify a stack, **default to `html-tailwind`**.
+Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**.
 
 ```bash
 python3 .shared/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
@@ -90,6 +108,8 @@ Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`
 | `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` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize |
 | `prompt` | AI prompts, CSS keywords | (style name) |
 
 ### Available Stacks
@@ -112,33 +132,51 @@ Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`
 
 **User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp"
 
-**AI should:**
+### Step 1: Analyze Requirements
+- Product type: Beauty/Spa service
+- Style keywords: elegant, professional, soft
+- Industry: Beauty/Wellness
+- Stack: html-tailwind (default)
+
+### Step 2: Generate Design System (REQUIRED)
 
 ```bash
-# 1. Search product type
-python3 .shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --domain product
+python3 .shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service elegant" --design-system -p "Serenity Spa"
+```
 
-# 2. Search style (based on industry: beauty, elegant)
-python3 .shared/ui-ux-pro-max/scripts/search.py "elegant minimal soft" --domain style
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
 
-# 3. Search typography
-python3 .shared/ui-ux-pro-max/scripts/search.py "elegant luxury" --domain typography
+### Step 3: Supplement with Detailed Searches (as needed)
 
-# 4. Search color palette
-python3 .shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness" --domain color
+```bash
+# Get UX guidelines for animation and accessibility
+python3 .shared/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux
 
-# 5. Search landing page structure
-python3 .shared/ui-ux-pro-max/scripts/search.py "hero-centric social-proof" --domain landing
+# Get alternative typography options if needed
+python3 .shared/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography
+```
 
-# 6. Search UX guidelines
-python3 .shared/ui-ux-pro-max/scripts/search.py "animation" --domain ux
-python3 .shared/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux
+### Step 4: Stack Guidelines
 
-# 7. Search stack guidelines (default: html-tailwind)
-python3 .shared/ui-ux-pro-max/scripts/search.py "layout responsive" --stack html-tailwind
+```bash
+python3 .shared/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind
 ```
 
-**Then:** Synthesize all search results and implement the design.
+**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 .shared/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 .shared/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
 
 ---
 
@@ -150,10 +188,6 @@ python3 .shared/ui-ux-pro-max/scripts/search.py "layout responsive" --stack html
 4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues
 5. **Use stack flag** - Get implementation-specific best practices
 6. **Iterate** - If first search doesn't match, try different keywords
-7. **Split Into Multiple Files** - For better maintainability:
-   - Separate components into individual files (e.g., `Header.tsx`, `Footer.tsx`)
-   - Extract reusable styles into dedicated files
-   - Keep each file focused and under 200-300 lines
 
 ---
 
@@ -206,6 +240,7 @@ Before delivering UI code, verify these items:
 - [ ] All icons from consistent icon set (Heroicons/Lucide)
 - [ ] Brand logos are correct (verified from Simple Icons)
 - [ ] Hover states don't cause layout shift
+- [ ] Use theme colors directly (bg-primary) not var() wrapper
 
 ### Interaction
 - [ ] All clickable elements have `cursor-pointer`
@@ -222,7 +257,7 @@ Before delivering UI code, verify these items:
 ### Layout
 - [ ] Floating elements have proper spacing from edges
 - [ ] No content hidden behind fixed navbars
-- [ ] Responsive at 320px, 768px, 1024px, 1440px
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
 - [ ] No horizontal scroll on mobile
 
 ### Accessibility

.claude/skills/ui-ux-pro-max/SKILL.md

@@ -130,28 +130,46 @@ Extract key information from user request:
 - **Industry**: healthcare, fintech, gaming, education, etc.
 - **Stack**: React, Vue, Next.js, or default to `html-tailwind`
 
-### Step 2: Search Relevant Domains
+### Step 2: Generate Design System (REQUIRED)
 
-Use `search.py` multiple times to gather comprehensive information. Search until you have enough context.
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 .claude/skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches 5 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 .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
 
 ```bash
 python3 .claude/skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
 ```
 
-**Recommended search order:**
+**When to use detailed searches:**
 
-1. **Product** - Get style recommendations for product type
-2. **Style** - Get detailed style guide (colors, effects, frameworks)
-3. **Typography** - Get font pairings with Google Fonts imports
-4. **Color** - Get color palette (Primary, Secondary, CTA, Background, Text, Border)
-5. **Landing** - Get page structure (if landing page)
-6. **Chart** - Get chart recommendations (if dashboard/analytics)
-7. **UX** - Get best practices and anti-patterns
-8. **Stack** - Get stack-specific guidelines (default: html-tailwind)
+| Need | Domain | Example |
+|------|--------|---------|
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
 
-### Step 3: Stack Guidelines (Default: html-tailwind)
+### Step 4: Stack Guidelines (Default: html-tailwind)
 
-If user doesn't specify a stack, **default to `html-tailwind`**.
+Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**.
 
 ```bash
 python3 .claude/skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
@@ -198,33 +216,51 @@ Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`
 
 **User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp"
 
-**AI should:**
+### Step 1: Analyze Requirements
+- Product type: Beauty/Spa service
+- Style keywords: elegant, professional, soft
+- Industry: Beauty/Wellness
+- Stack: html-tailwind (default)
+
+### Step 2: Generate Design System (REQUIRED)
 
 ```bash
-# 1. Search product type
-python3 .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --domain product
+python3 .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service elegant" --design-system -p "Serenity Spa"
+```
 
-# 2. Search style (based on industry: beauty, elegant)
-python3 .claude/skills/ui-ux-pro-max/scripts/search.py "elegant minimal soft" --domain style
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
 
-# 3. Search typography
-python3 .claude/skills/ui-ux-pro-max/scripts/search.py "elegant luxury" --domain typography
+### Step 3: Supplement with Detailed Searches (as needed)
 
-# 4. Search color palette
-python3 .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness" --domain color
+```bash
+# Get UX guidelines for animation and accessibility
+python3 .claude/skills/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux
 
-# 5. Search landing page structure
-python3 .claude/skills/ui-ux-pro-max/scripts/search.py "hero-centric social-proof" --domain landing
+# Get alternative typography options if needed
+python3 .claude/skills/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography
+```
 
-# 6. Search UX guidelines
-python3 .claude/skills/ui-ux-pro-max/scripts/search.py "animation" --domain ux
-python3 .claude/skills/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux
+### Step 4: Stack Guidelines
 
-# 7. Search stack guidelines (default: html-tailwind)
-python3 .claude/skills/ui-ux-pro-max/scripts/search.py "layout responsive" --stack html-tailwind
+```bash
+python3 .claude/skills/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind
 ```
 
-**Then:** Synthesize all search results and implement the design.
+**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 .claude/skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 .claude/skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
 
 ---
 
@@ -305,7 +341,7 @@ Before delivering UI code, verify these items:
 ### Layout
 - [ ] Floating elements have proper spacing from edges
 - [ ] No content hidden behind fixed navbars
-- [ ] Responsive at 320px, 768px, 1024px, 1440px
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
 - [ ] No horizontal scroll on mobile
 
 ### Accessibility