ui-ux-pro-max-skill/docs/code-standards.md

Code Standards & Development Guidelines

---

1. Python Code Standards (Search Engine & Design System)

1.1 General Style

Compliance: PEP 8 with pragmatism Tools: Black (code formatter), flake8 (linter), mypy (type checking) Min Python: 3.8+

1.2 File Structure

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Module docstring (purpose, usage, examples)
"""

import <stdlib>
from <stdlib> import <specific>
import <third-party>
from <third-party> import <specific>

# ============ CONFIGURATION ============
CONSTANT_NAME = value
DICT_CONFIG = {...}

# ============ CLASS DEFINITIONS ============
class ClassName:
    """Class docstring"""

    def __init__(self):
        """Initialize"""
        pass

    def method_name(self):
        """Method docstring"""
        pass

# ============ FUNCTION DEFINITIONS ============
def function_name(param1, param2):
    """Function docstring with Args, Returns, Raises"""
    pass

# ============ MAIN ENTRY ============
if __name__ == "__main__":
    main()

1.3 Naming Conventions

Type	Format	Example
Constants	UPPER_SNAKE_CASE	MAX_RESULTS = 3
Functions	snake_case	def _load_csv():
Classes	PascalCase	class BM25:
Private	_snake_case prefix	def _internal_function():
Dunder	name (avoid custom)	__init__, __str__
Variables	snake_case	query_result = []

1.4 Docstring Format

def search(query, domain=None, max_results=MAX_RESULTS):
    """
    Main search function with auto-domain detection.

    Args:
        query (str): Search query string
        domain (str, optional): Specific domain to search. If None, auto-detect.
        max_results (int): Maximum number of results (default: 3)

    Returns:
        dict: Result dictionary with keys: domain, query, file, count, results

    Raises:
        FileNotFoundError: If CSV file not found
        ValueError: If domain is invalid

    Example:
        >>> result = search("minimalism", "style", 5)
        >>> print(result['count'])  # 3
    """
    pass

1.5 Imports & Dependencies

Rule: Minimize external dependencies for portability

# Good
import csv
from pathlib import Path
from math import log

# Avoid
import numpy  # Not in stdlib, adds weight
import requests  # Use only if absolutely necessary

Organization:

1. Stdlib imports first
2. Third-party imports next (none for search engine)
3. Local imports last
4. Blank line between groups

1.6 Error Handling

# Good
try:
    result = _search_csv(filepath, columns, query, max_results)
except FileNotFoundError:
    return {"error": f"File not found: {filepath}", "domain": domain}
except Exception as e:
    logger.error(f"Unexpected error: {e}")
    raise

# Avoid
try:
    # code
except:
    pass  # Silent failures are bad

1.7 Type Hints

Required for:

• Public function signatures
• Class methods with complex logic
• Design system generator (all methods)

Format:

def _search_csv(
    filepath: Path,
    search_cols: list[str],
    output_cols: list[str],
    query: str,
    max_results: int
) -> list[dict]:
    """Search CSV and return results."""
    pass

# Return types
def get_results(self) -> dict[str, any]:
    pass

1.8 Code Comments

Good comments explain WHY, not WHAT:

# Good
# BM25 uses k1=1.5 and b=0.75 (standard tuning for document length normalization)
idf = log((self.N - freq + 0.5) / (freq + 0.5) + 1)

# Avoid
# Calculate log
idf = log((self.N - freq + 0.5) / (freq + 0.5) + 1)

# Good
# Exclude words < 3 chars to reduce noise (and, the, a, etc.)
return [w for w in text.split() if len(w) > 2]

# Avoid
# Filter words
return [w for w in text.split() if len(w) > 2]

1.9 Line Length

• Maximum: 100 characters (flexible for URLs/strings)
• Readability: Break long lines at logical operators

# Good
if (config_exists and
    permission_granted and
    not already_installed):
    proceed()

# Avoid
if config_exists and permission_granted and not already_installed and something_else: proceed()

1.10 CSV Handling

Rules:

1. Always use UTF-8 encoding
2. Handle missing fields gracefully
3. Preserve field order for consistency
4. Use DictReader/DictWriter for clarity

# Good
with open(filepath, 'r', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    data = list(reader)

# Handle missing
value = row.get('Column', 'default_value')

# Avoid
open(filepath)  # No encoding specified
row['Column']  # KeyError if missing

1.11 Windows Compatibility

# Good - UTF-8 for emoji/special chars on Windows
if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

# Good - Use pathlib for cross-platform paths
from pathlib import Path
filepath = Path(__file__).parent / "data" / "styles.csv"

# Avoid
filepath = f"{os.getcwd()}\\data\\styles.csv"  # Windows-specific

---

2. TypeScript Code Standards (CLI)

2.1 General Style

Compliance: ESLint (airbnb config) + Prettier Min TypeScript: 4.8+ Target: Node 18+

2.2 File Structure

/**
 * Module purpose and usage
 */

import type { TypeName } from './types/index';
import { functionName } from './utils/logger';

// ============ TYPES ============
interface ConfigOptions {
  platform: string;
  offline?: boolean;
}

// ============ CONSTANTS ============
const PLATFORMS = ['claude', 'cursor', 'windsurf'] as const;
const DEFAULT_TIMEOUT = 30000;

// ============ EXPORTED FUNCTIONS ============
export async function initCommand(options: ConfigOptions): Promise<void> {
  // implementation
}

// ============ PRIVATE FUNCTIONS ============
function detectPlatform(): string {
  // implementation
}

// ============ MAIN ENTRY ============
export default function main() {
  // entry point
}

2.3 Naming Conventions

Type	Format	Example
Constants	UPPER_SNAKE_CASE	const MAX_RETRIES = 3
Functions	camelCase	function detectPlatform()
Classes	PascalCase	class TemplateRenderer
Interfaces	PascalCase	interface ConfigOptions
Types	PascalCase	type Platform = 'claude' | 'cursor'
Variables	camelCase	let platformName = 'claude'
Private	leadingUnderscore	_internalFunction()
Files	kebab-case	template-renderer.ts, detect.ts

2.4 Type Definitions

Rules:

1. Always export types from types/index.ts
2. Use type for unions/aliases, interface for objects
3. Strict null checking enabled

// types/index.ts
export interface InitOptions {
  platform: 'claude' | 'cursor' | 'windsurf';
  offline?: boolean;
  outputDir?: string;
}

export type Platform = InitOptions['platform'];

// Usage
export async function init(options: InitOptions): Promise<void> {
  const platform: Platform = options.platform;
}

2.5 Async/Await

// Good
async function downloadAssets(): Promise<void> {
  try {
    const data = await fetchFromGitHub(url);
    await writeFiles(data);
  } catch (error) {
    logger.error(`Download failed: ${error.message}`);
    throw new Error('Failed to download assets');
  }
}

// Avoid
function downloadAssets() {
  return new Promise((resolve, reject) => {
    // callback hell
  });
}

2.6 Error Handling

// Good - Custom error types
class InstallerError extends Error {
  constructor(message: string, public platform?: string) {
    super(message);
    this.name = 'InstallerError';
  }
}

// Usage
try {
  await installSkill(platform);
} catch (error) {
  if (error instanceof InstallerError) {
    logger.error(`Installation failed for ${error.platform}: ${error.message}`);
  } else {
    throw error;
  }
}

2.7 Comments & Documentation

/**
 * Detects the current AI coding assistant platform.
 *
 * @returns The detected platform name, or 'unknown' if not detected
 *
 * @example
 * const platform = detectPlatform();
 * console.log(platform); // 'claude'
 */
function detectPlatform(): string {
  // implementation
}

2.8 Module Exports

// Good - Named exports for tree-shaking
export { initCommand } from './commands/init';
export { updateCommand } from './commands/update';
export type { ConfigOptions } from './types/index';

// Avoid
export default { initCommand, updateCommand };  // Default export
export * from './types';  // Wildcard exports (less clear)

---

3. CSV Data Format Standards

3.1 Structure Requirements

Rules:

1. UTF-8 encoding (no BOM)
2. Unix line endings (LF, not CRLF)
3. Comma-separated values
4. Header row with descriptive names
5. Consistent data types per column

3.2 CSV Header Naming

# Good - Clear, no special chars
Style Category,Type,Keywords,Best For,Performance,Accessibility

# Avoid
StyleCat,T,KW,BF,Perf,A11y  # Unclear abbreviations
style_category,type,keywords  # snake_case in CSV (use PascalCase)

3.3 Field Requirements

All Fields:

• Non-empty unless explicitly optional
• Properly escaped if containing quotes/commas
• Consistent data type per column

Style Category,Keywords,Best For
"Glassmorphism","glass, frosted, transparency, modern",SaaS apps
"Claymorphism","clay, soft, rounded, tactile",Educational apps

3.4 Data Consistency

Domain	Requirement	Example
Styles	Consistent capitalization	"Glassmorphism" not "glassmorphism"
Colors	Valid hex format	#E8B4B8 not E8B4B8 or #e8b4b8 (case-insensitive OK)
Products	Consistent categories	"SaaS" not "saas" or "SAAS"
URLs	Absolute, http/https	https://fonts.google.com/...
Lists	Comma-separated, consistent	"item1, item2, item3"

3.5 Search Column Selection

Rules:

1. Include searchable columns in config
2. Exclude very long text (use truncation in output)
3. Prioritize frequently-searched fields

# In core.py CSV_CONFIG
"style": {
    "file": "styles.csv",
    "search_cols": ["Style Category", "Keywords", "Best For", "Type", "AI Prompt Keywords"],
    "output_cols": ["Style Category", "Type", "Keywords", ..., "Design System Variables"]
}

3.6 Size Guidelines

File	Max Rows	Max Size	Rationale
styles.csv	100	100KB	Most important, larger acceptable
typography.csv	100	50KB	Detailed font information
products.csv	150	50KB	Comprehensive product coverage
colors.csv	150	50KB	Industry-specific palettes
Others	50	20KB	Specialized domains

---

4. Git & Version Control

4.1 Branching Strategy

Pattern: <type>/<description>

# Feature development
git checkout -b feat/add-design-system-caching
git checkout -b feat/support-droid-platform

# Bug fixes
git checkout -b fix/windows-unicode-emoji
git checkout -b fix/version-mismatch-plugin

# Documentation
git checkout -b docs/update-codebase-summary

# Refactoring
git checkout -b refactor/modularize-design-system

# Never commit directly to main

4.2 Commit Message Format

Standard: Conventional Commits

<type>(<scope>): <subject>

<body>

<footer>

Types:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• refactor: - Code restructuring
• perf: - Performance improvement
• test: - Test additions
• chore: - Build, CI, dependencies

Examples:

git commit -m "feat(design-system): add caching for repeated queries"
git commit -m "fix(cli): resolve Windows emoji encoding issue"
git commit -m "docs(readme): update installation instructions"
git commit -m "refactor(search): extract reasoning rules to separate module"

4.3 Code Review Checklist

Before pushing, verify:

• Code follows style standards (Python PEP 8, TypeScript ESLint)
• No hardcoded values or secrets
• Tests pass (if applicable)
• Linting passes
• Documentation updated
• Version numbers correct
• Commit message is descriptive
• No unnecessary files committed

4.4 Release Process

# 1. Update version numbers
# - cli/package.json
# - .claude-plugin/marketplace.json
# - .claude-plugin/plugin.json

# 2. Update CHANGELOG
# - Note what changed, list new features/fixes

# 3. Sync CLI assets
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/

# 4. Build and test
cd cli && bun run build
node dist/index.js init --ai claude --offline

# 5. Publish
npm publish

# 6. Tag release
git tag -a v2.2.3 -m "Release v2.2.3"
git push origin v2.2.3

---

5. Testing Standards

5.1 Python Tests (pytest)

Location: tests/test_*.py Target Coverage: ≥ 70%

# tests/test_core.py
import pytest
from core import BM25, search

class TestBM25:
    """Test BM25 ranking algorithm"""

    def test_tokenize_removes_short_words(self):
        bm25 = BM25()
        tokens = bm25.tokenize("the quick brown fox jumps")
        assert "the" not in tokens
        assert "quick" in tokens

    def test_search_returns_top_results(self):
        result = search("minimalism", "style", max_results=3)
        assert result['count'] <= 3
        assert 'Minimalism' in [r.get('Style Category') for r in result['results']]

@pytest.mark.skip(reason="Requires CSV files")
def test_design_system_generation():
    """Design system generation test"""
    pass

5.2 TypeScript Tests (vitest)

Location: cli/src/__tests__/test_*.ts Target Coverage: ≥ 70%

import { describe, it, expect, beforeEach } from 'vitest';
import { detectPlatform } from '../utils/detect';

describe('Platform Detection', () => {
  it('should detect Claude Code', () => {
    process.env.CLAUDE_CODE = 'true';
    const platform = detectPlatform();
    expect(platform).toBe('claude');
  });

  it('should return unknown for undetected platform', () => {
    delete process.env.CLAUDE_CODE;
    const platform = detectPlatform();
    expect(platform).toMatch(/unknown|fallback/);
  });
});

5.3 Integration Tests

# Integration test: Full design system generation
def test_design_system_beauty_spa():
    """Test design system generation for beauty spa"""
    result = generate_design_system(
        "beauty spa wellness",
        "Serenity Spa",
        format="ascii"
    )

    # Assertions
    assert "Serenity Spa" in result
    assert "STYLE:" in result
    assert "COLORS:" in result
    assert "TYPOGRAPHY:" in result
    assert "ANTI-PATTERNS:" in result

5.4 Linting & Formatting

Python:

# Install
pip install black flake8 mypy

# Format
black src/ui-ux-pro-max/scripts/

# Lint
flake8 src/ui-ux-pro-max/scripts/

# Type check
mypy src/ui-ux-pro-max/scripts/

TypeScript:

# Install
npm install --save-dev eslint prettier @typescript-eslint/parser

# Format
prettier --write cli/src/

# Lint
eslint cli/src/

# Type check
tsc --noEmit

---

6. Documentation Standards

6.1 Markdown Style

File Structure:

# Main Title (H1)

Brief intro (1-2 sentences)

## Section (H2)

Content with `code inline`

### Subsection (H3)

- Bullet point
- Another point

| Column 1 | Column 2 |
|----------|----------|
| Data | More data |

## Code Blocks

\`\`\`python
# Language-specified
def example():
    pass
\`\`\`

## Links

[Text](relative/path.md) or [Text](https://example.com)

6.2 README Requirements

• One-sentence project description
• Installation instructions (quick start)
• Basic usage examples
• Supported platforms/stacks
• Contributing guidelines
• License information
• Links to detailed docs in docs/

Max Length: 300 lines (link to docs/ for details)

6.3 Code Example Standards

All examples must:

1. Be runnable (copy-paste and work)
2. Show expected output
3. Include comments explaining WHY
4. Use realistic data

# Good example with explanation
def example_search():
    """Example: Search for minimalism style"""
    result = search("minimalism", "style", max_results=3)

    # Result contains metadata + top matches
    print(f"Domain: {result['domain']}")  # 'style'
    print(f"Found: {result['count']} results")  # 3
    print(result['results'][0]['Style Category'])  # 'Minimalism & Swiss Style'

---

7. Accessibility Standards

7.1 Design System Accessibility

All generated designs must:

1. WCAG AA compliance minimum
2. Text contrast ≥ 4.5:1 (normal text)
3. Focus states visible for keyboard nav
4. Respect prefers-reduced-motion
5. No information conveyed by color alone

7.2 UI Component Accessibility

<!-- Good -->
<button class="cta" aria-label="Subscribe to newsletter">
  Subscribe
</button>

<!-- Avoid -->
<div class="button" onclick="...">Subscribe</div>

7.3 Color Palette Guidelines

Rules:

1. Check contrast ratios (WebAIM Contrast Checker)
2. Include colorblind-safe palettes
3. Don't rely on color alone for meaning
4. Test with Lighthouse/axe DevTools

---

8. Performance Standards

8.1 Python Performance

Operation	Target	Limit
CSV load	< 50ms	100ms
BM25 index	< 100ms	200ms
Single search	< 200ms	500ms
Design system	< 2s	3s

Optimization Strategies:

• Load CSVs once, cache in memory
• Use generators for large datasets
• Profile with cProfile before optimizing

8.2 CLI Performance

Operation	Target	Limit
Platform detection	< 100ms	200ms
Template rendering	< 50ms	100ms
File generation	< 1s	2s
Full installation	< 5s	10s

---

9. Security Standards

9.1 Code Security

Rules:

1. No hardcoded API keys/secrets
2. No eval() or dynamic code execution
3. Sanitize user input (file paths, queries)
4. Validate CSV data before use

# Good
filepath = Path(__file__).parent / "data" / filename
if not filepath.is_file():
    raise ValueError(f"File not found: {filename}")

# Avoid
filepath = f"./data/{user_input}"  # Path traversal vulnerability
exec(user_query)  # Code injection

9.2 Dependency Security

# Regular audits
npm audit
pip audit

# Only add necessary dependencies
# No "just in case" packages

9.3 Data Privacy

• No telemetry without consent
• Generated design systems stay local
• No tracking of user queries

---

10. File Organization Best Practices

10.1 Project Structure Enforcement

Rule: Always edit in src/ui-ux-pro-max/, sync to CLI/skill

CORRECT:
  1. Edit src/ui-ux-pro-max/data/styles.csv
  2. Run sync: cp -r src/ui-ux-pro-max/data/* cli/assets/data/
  3. Test in CLI
  4. Commit both src/ and cli/assets/

WRONG:
  1. Edit cli/assets/data/styles.csv directly
  2. Changes lost on next sync

10.2 CSV File Organization

data/
├── styles.csv              # Must exist
├── colors.csv              # Must exist
├── typography.csv          # Must exist
├── products.csv            # Must exist
├── charts.csv              # Must exist
├── landing.csv             # Must exist
├── ui-reasoning.csv        # Must exist (v2.0+)
├── ux-guidelines.csv       # Required
├── icons.csv               # Optional
├── react-performance.csv   # Optional
├── web-interface.csv       # Optional
└── stacks/                 # 13 stack CSVs
    ├── html-tailwind.csv
    ├── react.csv
    └── ... (11 more)

---

11. Unresolved Questions

1. Test Framework: Should we use pytest + vitest, or add coverage tools like coverage.py?
2. CI/CD: Should we add GitHub Actions for linting/testing on PR?
3. Python Version: Drop support for Python 3.8 and require 3.9+ for better type hints?
4. Linting Config: Should we enforce strict mypy mode or keep pragmatic?
5. API Stability: How to version the Python API (core.py/design_system.py) for external users?