CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7UI UX Pro Max is an AI-powered design intelligence toolkit providing searchable databases of UI styles, color palettes, font pairings, chart types, and UX guidelines. It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
8 
9## Search Command
10 
11```bash
12python3 src/ui-ux-pro-max/scripts/search.py "<query>" --domain <domain> [-n <max_results>]
13```
14 
15**Domain search:**
16- `product` - Product type recommendations (SaaS, e-commerce, portfolio)
17- `style` - UI styles (glassmorphism, minimalism, brutalism) + AI prompts and CSS keywords
18- `typography` - Font pairings with Google Fonts imports
19- `color` - Color palettes by product type
20- `landing` - Page structure and CTA strategies
21- `chart` - Chart types and library recommendations
22- `ux` - Best practices and anti-patterns
23- `icons` - Icon recommendations with import code (Phosphor, Heroicons, Lucide)
24- `react` - React/Next.js performance patterns
25- `web` - App interface guidelines (iOS/Android/React Native)
26- `google-fonts` - Individual Google Fonts lookup
27- `gsap` - GSAP animation skeletons by intensity tier (hover, scroll reveal, stagger, page transition, parallax, loading)
28 
29**Design dials (optional, only with `--design-system`):**
30```bash
31python3 src/ui-ux-pro-max/scripts/search.py "<query>" --design-system --variance <1-10> --motion <1-10> --density <1-10>
32```
33`--variance` biases style selection (centered/minimal → bold/asymmetric), `--motion` attaches a matching GSAP snippet from `motion.csv`, `--density` overrides the spacing-scale tokens (spacious → dense/dashboard). Any dial left unset behaves exactly as before.
34 
35**Stack search:**
36```bash
37python3 src/ui-ux-pro-max/scripts/search.py "<query>" --stack <stack>
38```
39Available stacks: `html-tailwind` (default), `react`, `nextjs`, `astro`, `vue`, `nuxtjs`, `nuxt-ui`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`, `threejs`, `angular`, `laravel`, `javafx`, `wpf`, `winui`, `avalonia`, `uno`, `uwp`
40 
41## Architecture
42 
43```
44src/ui-ux-pro-max/                # Source of Truth
45├── data/                         # Canonical CSV databases
46│   ├── products.csv, styles.csv, colors.csv, typography.csv, ...
47│   └── stacks/                   # Stack-specific guidelines
48├── scripts/
49│   ├── search.py                 # CLI entry point
50│   ├── core.py                   # BM25 + regex hybrid search engine
51│   └── design_system.py          # Design system generation
52└── templates/
53    ├── base/                     # Base templates (skill-content.md, quick-reference.md)
54    └── platforms/                # Platform configs (claude.json, cursor.json, ...)
55 
56cli/                              # CLI installer (ui-ux-pro-max-cli on npm)
57├── src/
58│   ├── commands/init.ts          # Install command with template generation
59│   └── utils/template.ts         # Template rendering engine
60├── scripts/sync-assets.mjs       # Mirrors src/ -> cli/assets/ AND src/ -> .claude/skills/ui-ux-pro-max/
61└── assets/                       # Bundled assets (~564KB)
62    ├── data/                     # Copy of src/ui-ux-pro-max/data/
63    ├── scripts/                  # Copy of src/ui-ux-pro-max/scripts/
64    └── templates/                # Copy of src/ui-ux-pro-max/templates/
65 
66.claude/skills/ui-ux-pro-max/     # Claude Code skill: hand-authored SKILL.md +
67                                   # data/, scripts/ mirrored from src/ (see Sync Rules)
68.claude-plugin/                   # Claude Marketplace publishing
69```
70 
71The search engine uses BM25 ranking combined with regex matching. Domain auto-detection is available when `--domain` is omitted.
72 
73## Sync Rules
74 
75**Source of Truth:** `src/ui-ux-pro-max/`
76 
77There are no symlinks in this repo (git-on-Windows checks them out as plain
78text files pointing at a path, which silently breaks the skill) -- every
79mirrored copy below is a real, independently-committed file kept in sync by
80`cli/scripts/sync-assets.mjs`, enforced by the "Check asset sync" CI workflow.
81 
82When modifying files:
83 
841. **Data & Scripts** - Edit in `src/ui-ux-pro-max/`:
85   - `data/*.csv` and `data/stacks/*.csv`
86   - `scripts/*.py`
87   - Then run the sync below -- changes are NOT automatically reflected anywhere else.
88 
892. **Templates** - Edit in `src/ui-ux-pro-max/templates/`:
90   - `base/skill-content.md` - Common SKILL.md content
91   - `base/quick-reference.md` - Quick reference section (Claude only)
92   - `platforms/*.json` - Platform-specific configs
93 
943. **Sync before publishing / committing data or script changes:**
95```bash
96   cd cli
97   npm run sync:assets   # mirrors src/ -> cli/assets/ AND src/ -> .claude/skills/ui-ux-pro-max/{data,scripts}
98   npm run check:assets  # verify, no npm install required
99```
100   `.claude/skills/ui-ux-pro-max/SKILL.md` itself is hand-authored, not
101   mirrored or template-generated -- edit it directly.
102 
1034. **Reference Folders** - No manual sync needed. The CLI generates these from templates during `uipro init`.
104 
105## Prerequisites
106 
107Python 3.x (no external dependencies required)
108 
109**Note:** On Windows, use `python` instead of `python3` to run the scripts.
110 
111## Git Workflow
112 
113Never push directly to `main`. Always:
114 
1151. Create a new branch: `git checkout -b feat/...` or `fix/...`
1162. Commit changes
1173. Push branch: `git push -u origin <branch>`
1184. Create PR: `gh pr create`
119