# Codebase Summary

**Generated:** 2026-02-07
**Repository:** https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
**Total Files:** 111
**Total Tokens:** 279,500
**Size:** ~1.1MB

---

## 1. Directory Structure

```
ui-ux-pro-max-skill/
├── src/ui-ux-pro-max/                 # Source of Truth
│   ├── data/                          # Canonical CSV databases
│   │   ├── *.csv                      # 12 core domain databases
│   │   └── stacks/                    # 13 stack-specific guidelines
│   ├── scripts/                       # Python search engine
│   │   ├── search.py                  # CLI entry point (115 LOC)
│   │   ├── core.py                    # BM25 search engine (254 LOC)
│   │   └── design_system.py           # Design system generator (1,068 LOC)
│   └── templates/                     # Platform configs & templates
│       ├── base/                      # Shared templates
│       └── platforms/                 # 15 platform-specific configs
│
├── cli/                               # TypeScript CLI installer
│   ├── src/                           # TypeScript source
│   │   ├── index.ts                   # CLI entry point
│   │   ├── commands/                  # Command handlers (init, update, versions)
│   │   ├── types/                     # TypeScript type definitions
│   │   └── utils/                     # Helper utilities
│   ├── assets/                        # Bundled data (synced from src/)
│   │   ├── data/                      # CSV copy
│   │   ├── scripts/                   # Python script copy
│   │   └── templates/                 # Template copy
│   ├── package.json                   # npm metadata (v2.2.3)
│   └── tsconfig.json                  # TypeScript configuration
│
├── .claude-plugin/                    # Claude Marketplace plugin
│   ├── plugin.json                    # Plugin metadata (v2.0.1 - OUTDATED)
│   └── marketplace.json               # Marketplace publishing (v2.2.1)
│
├── .claude/skills/                    # Claude Code skill (symlink)
│   └── ui-ux-pro-max/                 # → ../src/ui-ux-pro-max/
│
├── .shared/                           # Shared reference (symlink)
│   └── ui-ux-pro-max/                 # → ../src/ui-ux-pro-max/
│
├── screenshots/                       # Marketing screenshots
├── README.md                          # Main documentation (496 lines)
├── LICENSE                            # MIT License
└── CLAUDE.md                          # Development guidelines
```

---

## 2. Data Layer (src/ui-ux-pro-max/data/)

### 2.1 Core Databases (12)

| Database | File | Records | Key Columns | Purpose |
|----------|------|---------|------------|---------|
| **Styles** | styles.csv | 67 | Style Category, Keywords, Best For, CSS Keywords | UI style definitions |
| **Colors** | colors.csv | 96 | Product Type, Primary/Secondary/CTA/BG/Text (Hex) | Color palettes by industry |
| **Typography** | typography.csv | 57 | Font Pairing Name, Category, Heading/Body Font | Font pairings + Google Fonts |
| **Products** | products.csv | 100+ | Product Type, Keywords, Primary/Secondary Styles | Product → style mapping |
| **Charts** | charts.csv | 25 | Data Type, Best Chart Type, Library, Color Guidance | Data visualization recommendations |
| **Landing** | landing.csv | 24 | Pattern Name, Keywords, Conversion Strategy, Sections | Landing page patterns |
| **UI Reasoning** | ui-reasoning.csv | 100 | UI_Category, Recommended Pattern, Style Priority, Rules | Industry-specific reasoning rules |
| **UX Guidelines** | ux-guidelines.csv | 99 | Category, Issue, Description, Do/Don't, Code Examples | UX best practices |
| **Web Interface** | web-interface.csv | - | Category, Issue, Description, Platform | Web-specific guidelines |
| **React Performance** | react-performance.csv | - | Category, Issue, Keywords, Performance Concern | React optimization patterns |
| **Icons** | icons.csv | - | Category, Icon Name, Library, Best For | Icon library recommendations |
| **Form Patterns** | (embedded in stack CSVs) | - | Category, Guideline, Code Samples | Form validation & handling |

### 2.2 Stack-Specific Databases (13)

**Web Stacks:**
- `html-tailwind.csv` - HTML + Tailwind CSS (default)
- `react.csv` - React-specific patterns
- `nextjs.csv` - Next.js framework guidelines
- `astro.csv` - Astro framework patterns
- `vue.csv` - Vue 3 guidelines
- `nuxtjs.csv` - Nuxt.js patterns
- `nuxt-ui.csv` - Nuxt UI component library
- `svelte.csv` - Svelte framework

**Mobile Stacks:**
- `swiftui.csv` - iOS SwiftUI patterns
- `react-native.csv` - React Native guidelines
- `flutter.csv` - Flutter framework
- `jetpack-compose.csv` - Android Jetpack Compose

**Component Libraries:**
- `shadcn.csv` - shadcn/ui component patterns

**Common Stack Columns:**
- Category, Guideline, Description, Do, Don't, Code Good, Code Bad, Severity, Docs URL

### 2.3 Data Characteristics

- **Format:** CSV (UTF-8 encoding)
- **Size:** Largest file = styles.csv (24,653 tokens, 94KB)
- **No dependencies:** Plain text, no external data fetches
- **Versioning:** Embedded in each record via timestamp/version fields
- **Search columns:** Subset of all columns for BM25 optimization
- **Output columns:** Custom per-domain for user-facing results

---

## 3. Search Engine (src/ui-ux-pro-max/scripts/)

### 3.1 search.py (115 LOC)

**Purpose:** CLI entry point & argument parser

**Key Functions:**
- `format_output(result)` - Format results for Claude consumption (token-optimized)
- Argument parsing for 8 command modes:
  - Domain search (default)
  - Stack search (`--stack`)
  - Design system generation (`--design-system`)
  - Persistence (`--persist`)
  - Format selection (`-f ascii|markdown`)

**Windows Fix:** UTF-8 encoding override for emoji output (cp1252 → UTF-8)

**Exit Points:**
- JSON output (`--json`)
- ASCII design system
- Markdown design system
- Persistence confirmation

### 3.2 core.py (254 LOC)

**Purpose:** BM25 search implementation & CSV loading

**Key Classes:**
- `BM25` - Ranking algorithm (k1=1.5, b=0.75)
  - `tokenize()` - Lowercase, punctuation removal, >2 char words
  - `fit()` - Build index from documents
  - `score()` - Calculate BM25 scores for all docs

**Key Functions:**
- `_load_csv()` - Load CSV with DictReader
- `_search_csv()` - Core search using BM25
- `detect_domain()` - Auto-detect search domain from query (10 domain keywords)
- `search()` - Main search function with auto-detection
- `search_stack()` - Stack-specific search

**Configuration:**
- `CSV_CONFIG` - 9 domains (style, color, chart, landing, product, ux, typography, icons, react, web)
- `STACK_CONFIG` - 13 stacks
- `DATA_DIR` - Points to `../data/` from script location
- `MAX_RESULTS` - Default 3 results

**Algorithm:**
```
1. Load CSV & extract search columns
2. Tokenize each row into documents
3. Build BM25 index (IDF calculation)
4. Score query against all documents
5. Return top K results with output columns
```

### 3.3 design_system.py (1,068 LOC) - MODULARIZATION NEEDED

**Purpose:** Design system generation & reasoning

**Key Classes:**
- `DesignSystemGenerator` - Main generator class
  - `_load_reasoning()` - Load ui-reasoning.csv
  - `_multi_domain_search()` - Execute 5 parallel searches
  - `_find_reasoning_rule()` - Match category to reasoning rule
  - `_apply_reasoning()` - Apply rules to search results
  - `_format_output_ascii()` - Generate ASCII design system
  - `_format_output_markdown()` - Generate Markdown design system
  - `_generate_pre_delivery_checklist()` - Quality checklist

**Key Functions:**
- `generate_design_system()` - Main entry point
- `persist_design_system()` - Save to disk (Master + Overrides pattern)

**Multi-Domain Search (parallel):**
1. Product search (1 result) - Identify product type
2. Style search (3 results) - Best matching styles
3. Color search (2 results) - Industry color palettes
4. Landing search (2 results) - Page patterns
5. Typography search (2 results) - Font pairings

**Reasoning Application:**
1. Find matching rule by UI_Category
2. Apply style priority weights
3. Filter anti-patterns for industry
4. Apply decision rules (JSON conditions)
5. Generate output with sections

**Output Sections:**
- Target & recommended system
- Pattern (structure)
- Style (keywords, best for, effects)
- Colors (hex palette with mood notes)
- Typography (fonts, mood, Google Fonts URL)
- Key effects (animations, transitions)
- Anti-patterns (what to avoid)
- Pre-delivery checklist (14 items)

**Persistence Pattern:**
```
design-system/
├── {project-slug}/
│   ├── MASTER.md              # Global source of truth
│   └── pages/
│       └── {page-name}.md     # Page-specific overrides
```

**Issues:**
- Exceeds 200-line modularization guideline (1,068 LOC)
- Reasoning rules parsed but not fully applied
- Output formatting logic mixed with generation logic
- No caching for repeated queries

---

## 4. CLI (cli/src/)

### 4.1 File Structure

```
cli/src/
├── index.ts                    # Entry point (command dispatcher)
├── commands/
│   ├── init.ts                 # uipro init --ai <platform>
│   ├── update.ts               # uipro update
│   └── versions.ts             # uipro versions
├── types/
│   └── index.ts                # TypeScript interfaces
└── utils/
    ├── detect.ts               # Detect OS & AI assistant
    ├── extract.ts              # Extract ZIP from GitHub
    ├── github.ts               # GitHub API calls
    ├── logger.ts               # Logging utilities
    └── template.ts             # Template rendering
```

### 4.2 Key Commands

| Command | Purpose | Key Functions |
|---------|---------|---------------|
| **init** | Install skill for AI assistant | Platform detection, template rendering, file generation |
| **update** | Check & update to latest version | npm registry query, version comparison |
| **versions** | List available versions | GitHub releases API query |

### 4.3 Platform Support

**Skill Mode (Auto-activate):**
- Claude Code, Cursor, Windsurf, Antigravity, Codex CLI, Continue, Gemini CLI, OpenCode, CodeBuddy

**Workflow Mode (Slash command):**
- Kiro, GitHub Copilot, Roo Code

**Factory Mode (New):**
- Droid (v2.2.3)

**Legacy Mode:**
- Trae (SOLO mode first)

### 4.4 Installation Flow

```
1. uipro init --ai claude
2. Detect platform/OS
3. Download/extract assets
4. Render templates (base + platform-specific)
5. Generate SKILL.md/.claude/skills/ files
6. Provide activation instructions
7. Verify installation
```

### 4.5 Bundled Assets

Location: `cli/assets/`

**Contents:**
- Data: 25 CSV files (copied from src/ui-ux-pro-max/data/)
- Scripts: 3 Python files (copied from src/ui-ux-pro-max/scripts/)
- Templates: 2 base + 15 platform configs (copied from src/ui-ux-pro-max/templates/)

**Size:** 564KB (includes all 25 CSVs + 3 Python scripts + 17 templates)

**Sync Required:** Before `npm publish`, manually run:
```bash
cp -r src/ui-ux-pro-max/data/* cli/assets/data/
cp -r src/ui-ux-pro-max/scripts/* cli/assets/scripts/
cp -r src/ui-ux-pro-max/templates/* cli/assets/templates/
```

---

## 5. Templates (src/ui-ux-pro-max/templates/)

### 5.1 Base Templates

| Template | Purpose | Size |
|----------|---------|------|
| **skill-content.md** | Common SKILL.md for all platforms | ~5KB |
| **quick-reference.md** | Quick reference (Claude only) | ~2KB |

### 5.2 Platform Configs (15)

Each platform has a `.json` template with:
- Platform name
- File paths (where to create .claude/, .cursor/, etc.)
- Environment variables
- Activation instructions
- Specific commands

**Platforms:**
claude, cursor, windsurf, copilot, copilot-vscode, kiro, trae, roocode, codex, qoder, gemini, continue, opencode, codebuddy, droid, agent

---

## 6. Marketplace Plugin (.claude-plugin/)

### 6.1 plugin.json (v2.0.1 - OUTDATED)

```json
{
  "name": "ui-ux-pro-max",
  "version": "2.0.1",
  "description": "50 styles, 21 palettes, 50 font pairings...",
  "skills": ["./.claude/skills/ui-ux-pro-max"]
}
```

**Issues:**
- Version number outdated (should be 2.2.3)
- Feature counts outdated (50 styles → 67 styles, etc.)

### 6.2 marketplace.json (v2.2.1)

```json
{
  "name": "ui-ux-pro-max-skill",
  "version": "2.2.1",
  "metadata": {
    "description": "67 styles, 96 palettes, 57 font pairings, 25 charts, 13 stacks",
    "version": "2.2.1"
  },
  "plugins": [
    {
      "name": "ui-ux-pro-max",
      "version": "2.2.1",
      "description": "Professional UI/UX design intelligence..."
    }
  ]
}
```

**Status:** Current but should be aligned with CLI (v2.2.3)

---

## 7. File Statistics

### 7.1 Top 5 Largest Files

| File | Type | Size | Tokens |
|------|------|------|--------|
| styles.csv | CSV | 94.9KB | 24,653 |
| typography.csv | CSV | 31.9KB | 9,114 |
| ui-reasoning.csv | CSV | ~20KB | ~5,000 |
| products.csv | CSV | ~15KB | ~4,000 |
| design_system.py | Python | 43.6KB | 10,158 |

### 7.2 Codebase Composition

| Language | Files | LOC | Purpose |
|----------|-------|-----|---------|
| **Python** | 3 | 1,437 | Search engine, design system |
| **TypeScript** | 8 | ~1,200 | CLI installer |
| **CSV** | 25 | ~500K | Design databases |
| **Markdown** | 3 | 500+ | Documentation |
| **JSON** | 18 | ~300 | Configs, package info |
| **Shell/Other** | 48 | - | Binary files, configs |

### 7.3 Dependencies

**Python:** None (pure Python 3.x)
**Node/TypeScript:**
- commander (CLI framework)
- chalk (colored output)
- ora (spinners)
- prompts (interactive prompts)

**Build Tools:**
- Bun (build, package manager)
- TypeScript (compilation)

---

## 8. Execution Flow

### 8.1 User Request → Design System

```
User: "Build a landing page for my beauty spa"
  ↓
Claude Code (skill auto-activates)
  ↓
Query → search.py --design-system "beauty spa"
  ↓
Python core.py:
  • Auto-detect domain (product)
  • Perform multi-domain search
  ↓
design_system.py:
  • Find UI_Category match (Wellness/Beauty)
  • Apply reasoning rules
  • Select pattern, style, colors, typography
  • Generate anti-patterns
  • Create pre-delivery checklist
  ↓
Output (ASCII or Markdown):
  TARGET: Beauty Spa
  PATTERN: Hero-Centric + Social Proof
  STYLE: Soft UI Evolution
  COLORS: Soft Pink, Sage Green, Gold
  TYPOGRAPHY: Cormorant Garamond / Montserrat
  KEY EFFECTS: Soft shadows, smooth transitions
  ANTI-PATTERNS: Bright neon colors, harsh animations
  CHECKLIST: [...14 items...]
  ↓
Claude generates HTML/React/etc. with design system applied
```

### 8.2 CLI Installation Flow

```
User: npm install -g uipro-cli && uipro init --ai claude
  ↓
CLI index.ts (command dispatcher)
  ↓
init command:
  • Detect OS (Windows/Mac/Linux)
  • Detect project structure
  • Prompt for AI assistant
  ↓
template.ts (template rendering):
  • Load skill-content.md (base template)
  • Load claude.json (platform config)
  • Substitute variables (${AI_NAME}, ${SKILL_PATH}, etc.)
  ↓
File generation:
  • Create .claude/skills/ui-ux-pro-max/ directory
  • Copy SKILL.md with rendered template
  • Copy assets (data, scripts, templates)
  ↓
Output:
  ✓ Installed UI/UX Pro Max for Claude Code
  📖 Usage: Request UI/UX work naturally in chat
  🔧 Advanced: python .claude/skills/ui-ux-pro-max/scripts/search.py "query"
```

---

## 9. Key Dependencies & Integrations

### 9.1 Internal Dependencies

- **search.py** → imports core.py, design_system.py
- **design_system.py** → imports core.py (search function)
- **core.py** → standalone (no local imports)
- **CLI** → reads bundled assets (data/, scripts/, templates/)

### 9.2 External Dependencies

- **Python Search:** csv, pathlib, math, re (all stdlib)
- **CLI:** commander, chalk, ora, prompts (npm)
- **Marketplace:** GitHub integration (releases, publishing)

### 9.3 Data Integrations

- **Product-to-Style Mapping:** products.csv → ui-reasoning.csv
- **Style-to-Colors:** styles.csv + colors.csv (joined in generation)
- **Typography-to-Fonts:** typography.csv + Google Fonts API

---

## 10. Entry Points

| Entry Point | Type | Location | Command |
|------------|------|----------|---------|
| **Design System Query** | Python | `scripts/search.py` | `python search.py "query" --design-system` |
| **Domain Search** | Python | `scripts/search.py` | `python search.py "query" --domain style` |
| **Stack Search** | Python | `scripts/search.py` | `python search.py "query" --stack react` |
| **CLI Installation** | Node | `cli/src/index.ts` | `uipro init --ai claude` |
| **Skill Activation** | Markdown | `SKILL.md` | Auto-activates in Claude Code |

---

## 11. Configuration Management

| Config File | Purpose | Scope |
|-------------|---------|-------|
| **core.py lines 13-92** | CSV_CONFIG, STACK_CONFIG | Search domains & stacks |
| **design_system.py lines 25-33** | SEARCH_CONFIG | Multi-domain result counts |
| **cli/package.json** | npm metadata, version | CLI distribution |
| **marketplace.json** | Plugin metadata | Claude Marketplace |
| **plugin.json** | Plugin definition | Local skill reference |
| **src/ui-ux-pro-max/templates/platforms/*.json** | Platform templates | Installation files |

---

## 12. Known Issues & TODOs

| Issue | Severity | File | Fix |
|-------|----------|------|-----|
| Version mismatch (v2.0.1 vs v2.2.1 vs v2.2.3) | High | plugin.json, marketplace.json | Update to 2.2.3 |
| design_system.py exceeds 200 LOC | Medium | design_system.py (1,068) | Modularize into 3-4 modules |
| CLI assets sync required before publish | Medium | cli/assets/ | Automate pre-publish sync |
| No error handling for CSV parse errors | Low | core.py | Add try-catch for DictReader |
| Decision rules parsed but not applied | Medium | design_system.py | Complete rule application logic |
| No test coverage | High | All | Add unit tests (target 70%+) |
| README exceeds 300 lines | Low | README.md (496) | Split into docs/ with links |

---

## 13. Performance Characteristics

| Operation | Time | Bottleneck |
|-----------|------|-----------|
| CSV loading | ~50ms | File I/O (all 25 CSVs) |
| BM25 indexing | ~100ms | Tokenization + IDF calculation |
| Single search | ~200ms | Document scoring |
| Multi-domain search | ~1s | 5 parallel searches |
| Design system generation | ~2s | Reasoning rule lookup + output formatting |
| CLI installation | ~3-5s | File copying + template rendering |

---

## 14. Unresolved Questions

1. **Version Sync:** Should we maintain separate versions for CLI, Marketplace, and Plugin?
2. **Design System Modularization:** How to split design_system.py without breaking reasoning logic?
3. **Caching:** Should search results be cached for identical queries?
4. **Testing:** What framework to use for Python (pytest) and TypeScript (vitest)?
5. **Data Freshness:** How often should design trend data be updated?
6. **Analytics:** Track which design systems users generate?