Files

Duy Nguyen 1eb0f7f3b0 docs(agent-docs): added

2026-02-08 12:46:48 +07:00

19 KiB

Raw Blame History

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):

Product search (1 result) - Identify product type
Style search (3 results) - Best matching styles
Color search (2 results) - Industry color palettes
Landing search (2 results) - Page patterns
Typography search (2 results) - Font pairings

Reasoning Application:

Find matching rule by UI_Category
Apply style priority weights
Filter anti-patterns for industry
Apply decision rules (JSON conditions)
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:

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)

{
  "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)

{
  "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

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

19 KiB Raw Blame History

Codebase Summary

1. Directory Structure

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

2.1 Core Databases (12)

2.2 Stack-Specific Databases (13)

2.3 Data Characteristics

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

3.1 search.py (115 LOC)

3.2 core.py (254 LOC)

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

4. CLI (cli/src/)

4.1 File Structure

4.2 Key Commands

4.3 Platform Support

4.4 Installation Flow

4.5 Bundled Assets

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

5.1 Base Templates

5.2 Platform Configs (15)

6. Marketplace Plugin (.claude-plugin/)

6.1 plugin.json (v2.0.1 - OUTDATED)

6.2 marketplace.json (v2.2.1)

7. File Statistics

7.1 Top 5 Largest Files

7.2 Codebase Composition

7.3 Dependencies

8. Execution Flow

8.1 User Request → Design System

8.2 CLI Installation Flow

9. Key Dependencies & Integrations

9.1 Internal Dependencies

9.2 External Dependencies

9.3 Data Integrations

10. Entry Points

11. Configuration Management

12. Known Issues & TODOs

13. Performance Characteristics

14. Unresolved Questions

19 KiB

Raw Blame History