Snapshot WIP: solver HP epic progress, BPHX/HX physics, BMAD skill refresh.

Capture uncommitted solver robustness work (regularization, domain errors, linear solver lifecycle, tube DP/MSH), web workbench updates, and synced BMAD skills across IDE agent folders before starting BPHX pressure-drop.

Co-authored-by: Cursor <cursoragent@cursor.com>

.agents/skills/ui-ux-pro-max/scripts/core.py

@@ -0,0 +1,464 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Core - BM25 search engine for UI/UX style guides
+"""
+
+import csv
+import re
+from pathlib import Path
+from math import log
+from collections import defaultdict
+
+# ============ CONFIGURATION ============
+DATA_DIR = Path(__file__).parent.parent / "data"
+MAX_RESULTS = 3
+
+CSV_CONFIG = {
+    "style": {
+        "file": "styles.csv",
+        "search_cols": ["Style Category", "Keywords", "Best For", "Type", "AI Prompt Keywords"],
+        "output_cols": ["Style Category", "Type", "Keywords", "Primary Colors", "Effects & Animation", "Best For", "Light Mode ✓", "Dark Mode ✓", "Performance", "Accessibility", "Framework Compatibility", "Complexity", "AI Prompt Keywords", "CSS/Technical Keywords", "Implementation Checklist", "Design System Variables"]
+    },
+    "color": {
+        "file": "colors.csv",
+        "search_cols": ["Product Type", "Notes"],
+        "output_cols": ["Product Type", "Primary", "On Primary", "Secondary", "On Secondary", "Accent", "On Accent", "Background", "Foreground", "Card", "Card Foreground", "Muted", "Muted Foreground", "Border", "Destructive", "On Destructive", "Ring", "Notes"]
+    },
+    "chart": {
+        "file": "charts.csv",
+        "search_cols": ["Data Type", "Keywords", "Best Chart Type", "When to Use", "When NOT to Use", "Accessibility Notes"],
+        "output_cols": ["Data Type", "Keywords", "Best Chart Type", "Secondary Options", "When to Use", "When NOT to Use", "Data Volume Threshold", "Color Guidance", "Accessibility Grade", "Accessibility Notes", "A11y Fallback", "Library Recommendation", "Interactive Level"]
+    },
+    "landing": {
+        "file": "landing.csv",
+        "search_cols": ["Pattern Name", "Keywords", "Conversion Optimization", "Section Order"],
+        "output_cols": ["Pattern Name", "Keywords", "Section Order", "Primary CTA Placement", "Color Strategy", "Conversion Optimization"]
+    },
+    "product": {
+        "file": "products.csv",
+        "search_cols": ["Product Type", "Keywords", "Primary Style Recommendation", "Key Considerations"],
+        "output_cols": ["Product Type", "Keywords", "Primary Style Recommendation", "Secondary Styles", "Landing Page Pattern", "Dashboard Style (if applicable)", "Color Palette Focus"]
+    },
+    "ux": {
+        "file": "ux-guidelines.csv",
+        "search_cols": ["Category", "Issue", "Description", "Platform"],
+        "output_cols": ["Category", "Issue", "Platform", "Description", "Do", "Don't", "Code Example Good", "Code Example Bad", "Severity"]
+    },
+    "typography": {
+        "file": "typography.csv",
+        "search_cols": ["Font Pairing Name", "Category", "Mood/Style Keywords", "Best For", "Heading Font", "Body Font"],
+        "output_cols": ["Font Pairing Name", "Category", "Heading Font", "Body Font", "Mood/Style Keywords", "Best For", "Google Fonts URL", "CSS Import", "Tailwind Config", "Notes"]
+    },
+    "icons": {
+        "file": "icons.csv",
+        "search_cols": ["Category", "Icon Name", "Keywords", "Best For"],
+        "output_cols": ["Category", "Icon Name", "Keywords", "Library", "Import Code", "Usage", "Best For", "Style"]
+    },
+    "gsap": {
+        "file": "motion.csv",
+        "search_cols": ["Category", "Intensity Tier", "Keywords", "Trigger"],
+        "output_cols": ["Category", "Intensity Tier", "Trigger", "Duration", "Easing", "GSAP Snippet", "Framework Notes", "Do", "Don't", "Performance Notes"]
+    },
+    "react": {
+        "file": "react-performance.csv",
+        "search_cols": ["Category", "Issue", "Keywords", "Description"],
+        "output_cols": ["Category", "Issue", "Platform", "Description", "Do", "Don't", "Code Example Good", "Code Example Bad", "Severity"]
+    },
+    "web": {
+        "file": "app-interface.csv",
+        "search_cols": ["Category", "Issue", "Keywords", "Description"],
+        "output_cols": ["Category", "Issue", "Platform", "Description", "Do", "Don't", "Code Example Good", "Code Example Bad", "Severity"]
+    },
+    "google-fonts": {
+        "file": "google-fonts.csv",
+        "search_cols": ["Family", "Category", "Stroke", "Classifications", "Keywords", "Subsets", "Designers"],
+        "output_cols": ["Family", "Category", "Stroke", "Classifications", "Styles", "Variable Axes", "Subsets", "Designers", "Popularity Rank", "Google Fonts URL"]
+    }
+}
+
+# Output columns whose content (code samples, checklists) must never be
+# hard-truncated for display -- truncating mid-snippet destroys the value.
+UNTRUNCATED_COLS = {
+    "Code Example Good", "Code Example Bad", "Code Good", "Code Bad",
+    "Implementation Checklist", "Design System Variables", "CSS Import",
+    "Tailwind Config", "GSAP Snippet",
+}
+
+STACK_CONFIG = {
+    "react":            {"file": "stacks/react.csv"},
+    "nextjs":           {"file": "stacks/nextjs.csv"},
+    "vue":              {"file": "stacks/vue.csv"},
+    "svelte":           {"file": "stacks/svelte.csv"},
+    "astro":            {"file": "stacks/astro.csv"},
+    "swiftui":          {"file": "stacks/swiftui.csv"},
+    "react-native":     {"file": "stacks/react-native.csv"},
+    "flutter":          {"file": "stacks/flutter.csv"},
+    "nuxtjs":           {"file": "stacks/nuxtjs.csv"},
+    "nuxt-ui":          {"file": "stacks/nuxt-ui.csv"},
+    "html-tailwind":    {"file": "stacks/html-tailwind.csv"},
+    "shadcn":           {"file": "stacks/shadcn.csv"},
+    "jetpack-compose":  {"file": "stacks/jetpack-compose.csv"},
+    "threejs":          {"file": "stacks/threejs.csv"},
+    "angular":          {"file": "stacks/angular.csv"},
+    "laravel":          {"file": "stacks/laravel.csv"},
+    "javafx":           {"file": "stacks/javafx.csv"},
+    "wpf":              {"file": "stacks/wpf.csv"},
+    "winui":            {"file": "stacks/winui.csv"},
+    "avalonia":         {"file": "stacks/avalonia.csv"},
+    "uno":              {"file": "stacks/uno.csv"},
+    "uwp":              {"file": "stacks/uwp.csv"},
+}
+
+# Common columns for all stacks
+_STACK_COLS = {
+    "search_cols": ["Category", "Guideline", "Description", "Do", "Don't"],
+    "output_cols": ["Category", "Guideline", "Description", "Do", "Don't", "Code Good", "Code Bad", "Severity", "Docs URL"]
+}
+
+AVAILABLE_STACKS = list(STACK_CONFIG.keys())
+
+
+# ============ TOKENIZATION ============
+# Common two-letter/three-letter words that add noise without adding search
+# signal. Deliberately short -- domain-relevant short tokens (ui, ux, ai,
+# css, 3d, js, os, md, gsap) must stay searchable, which is why we don't
+# filter purely by length.
+_STOPWORDS = {
+    "to", "in", "on", "at", "is", "of", "by", "or", "an", "if", "no", "so",
+    "do", "be", "we", "it", "as", "the", "and", "for", "are", "was",
+}
+
+# Query/corpus normalization so common spelling variants match each other.
+# Keep this a plain dict (stdlib only, no fuzzy-matching dependency).
+_SYNONYMS = {
+    "e-commerce": "ecommerce",
+    "dark-mode": "dark",
+    "darkmode": "dark",
+    "light-mode": "light",
+    "lightmode": "light",
+    "a11y": "accessibility",
+    "nav": "navigation",
+    "sign-up": "signup",
+    "log-in": "login",
+    "colour": "color",
+    "colours": "colors",
+    "customisation": "customization",
+    "organisation": "organization",
+    "behaviour": "behavior",
+    "ux/ui": "ux ui",
+}
+
+
+def _normalize(text):
+    """Apply synonym substitution before tokenizing."""
+    for variant, canonical in _SYNONYMS.items():
+        text = text.replace(variant, canonical)
+    return text
+
+
+# ============ BM25 IMPLEMENTATION ============
+class BM25:
+    """BM25 ranking algorithm for text search"""
+
+    def __init__(self, k1=1.5, b=0.75):
+        self.k1 = k1
+        self.b = b
+        self.corpus = []
+        self.doc_lengths = []
+        self.avgdl = 0
+        self.idf = {}
+        self.doc_freqs = defaultdict(int)
+        self.N = 0
+        self._term_freqs = []  # precomputed per-doc term frequencies
+
+    def tokenize(self, text):
+        """Lowercase, normalize synonyms, split, remove punctuation, filter stopwords"""
+        text = _normalize(str(text).lower())
+        text = re.sub(r'[^\w\s]', ' ', text)
+        return [w for w in text.split() if len(w) >= 2 and w not in _STOPWORDS]
+
+    def fit(self, documents):
+        """Build BM25 index from documents"""
+        self.corpus = [self.tokenize(doc) for doc in documents]
+        self.N = len(self.corpus)
+        if self.N == 0:
+            return
+        self.doc_lengths = [len(doc) for doc in self.corpus]
+        self.avgdl = sum(self.doc_lengths) / self.N
+
+        self._term_freqs = []
+        for doc in self.corpus:
+            tf = defaultdict(int)
+            for word in doc:
+                tf[word] += 1
+            self._term_freqs.append(tf)
+            for word in tf:
+                self.doc_freqs[word] += 1
+
+        for word, freq in self.doc_freqs.items():
+            self.idf[word] = log((self.N - freq + 0.5) / (freq + 0.5) + 1)
+
+    def score(self, query):
+        """Score all documents against query"""
+        query_tokens = self.tokenize(query)
+        scores = []
+
+        for idx in range(self.N):
+            score = 0
+            doc_len = self.doc_lengths[idx]
+            term_freqs = self._term_freqs[idx]
+
+            for token in query_tokens:
+                if token in self.idf:
+                    tf = term_freqs.get(token, 0)
+                    idf = self.idf[token]
+                    numerator = tf * (self.k1 + 1)
+                    denominator = tf + self.k1 * (1 - self.b + self.b * doc_len / self.avgdl)
+                    score += idf * numerator / denominator
+
+            scores.append((idx, score))
+
+        return sorted(scores, key=lambda x: x[1], reverse=True)
+
+    def vocabulary(self):
+        """All indexed terms, for suggestion/typo-recovery purposes."""
+        return list(self.idf.keys())
+
+
+# ============ CSV / INDEX CACHE ============
+# Data files are small and reused across multiple domain searches within a
+# single --design-system run; avoid re-reading + re-indexing the same file
+# repeatedly in one process.
+_csv_cache = {}   # filepath -> (mtime, rows)
+_bm25_cache = {}  # (filepath, tuple(search_cols)) -> (mtime, BM25 instance)
+
+
+def _load_csv(filepath):
+    """Load CSV and return list of dicts, with mtime-based caching."""
+    mtime = filepath.stat().st_mtime
+    cached = _csv_cache.get(filepath)
+    if cached and cached[0] == mtime:
+        return cached[1]
+
+    with open(filepath, 'r', encoding='utf-8') as f:
+        rows = list(csv.DictReader(f))
+
+    _csv_cache[filepath] = (mtime, rows)
+    return rows
+
+
+def _get_bm25(filepath, search_cols, data):
+    """Fitted BM25 index for this file+columns, with mtime-based caching."""
+    key = (filepath, tuple(search_cols))
+    mtime = filepath.stat().st_mtime
+    cached = _bm25_cache.get(key)
+    if cached and cached[0] == mtime:
+        return cached[1]
+
+    documents = [" ".join(str(row.get(col, "")) for col in search_cols) for row in data]
+    bm25 = BM25()
+    bm25.fit(documents)
+    _bm25_cache[key] = (mtime, bm25)
+    return bm25
+
+
+# ============ SEARCH FUNCTIONS ============
+def _search_csv(filepath, search_cols, output_cols, query, max_results):
+    """Core search function using BM25. Returns (results, bm25_or_none)."""
+    if not filepath.exists():
+        return [], None
+
+    try:
+        data = _load_csv(filepath)
+    except (csv.Error, OSError, UnicodeDecodeError) as e:
+        return [{"_error": f"Failed to read {filepath.name}: {e}"}], None
+
+    if not data:
+        return [], None
+
+    bm25 = _get_bm25(filepath, search_cols, data)
+    ranked = bm25.score(query)
+
+    results = []
+    for idx, score in ranked[:max_results]:
+        if score > 0:
+            row = data[idx]
+            results.append({col: row.get(col, "") for col in output_cols if col in row})
+
+    return results, bm25
+
+
+def _suggest_terms(bm25, query, limit=6):
+    """Nearest known vocabulary terms for a query that returned 0 hits,
+    so the caller can retry instead of silently reporting nothing."""
+    if bm25 is None:
+        return []
+    query_tokens = set(bm25.tokenize(query))
+    if not query_tokens:
+        return []
+
+    candidates = []
+    for term in bm25.vocabulary():
+        for qt in query_tokens:
+            if term.startswith(qt[:3]) or qt.startswith(term[:3]):
+                candidates.append(term)
+                break
+
+    # Stable de-dup, most frequent terms first (doc_freqs available via idf keys only,
+    # so just de-dup preserving discovery order).
+    seen = set()
+    ordered = []
+    for term in candidates:
+        if term not in seen:
+            seen.add(term)
+            ordered.append(term)
+    return ordered[:limit]
+
+
+# Load the product-domain keyword list from products.csv at import time so
+# it stays in sync with the data instead of needing manual updates to a
+# hardcoded list. Falls back to a small built-in seed if the file is
+# missing (e.g. package built without data/).
+def _load_product_keywords():
+    seed = ["saas", "ecommerce", "e-commerce", "fintech", "healthcare", "gaming",
+            "portfolio", "crypto", "dashboard", "fitness", "marketplace"]
+    filepath = DATA_DIR / CSV_CONFIG["product"]["file"]
+    if not filepath.exists():
+        return seed
+    try:
+        rows = _load_csv(filepath)
+    except (csv.Error, OSError, UnicodeDecodeError):
+        return seed
+
+    keywords = set(seed)
+    for row in rows:
+        raw = row.get("Keywords", "")
+        for kw in re.split(r"[,;]", raw):
+            kw = kw.strip().lower()
+            if kw and len(kw) >= 3:
+                keywords.add(kw)
+    return sorted(keywords, key=len, reverse=True)
+
+
+_DOMAIN_KEYWORDS = None
+
+
+def _domain_keywords():
+    global _DOMAIN_KEYWORDS
+    if _DOMAIN_KEYWORDS is not None:
+        return _DOMAIN_KEYWORDS
+
+    _DOMAIN_KEYWORDS = {
+        "color": ["color", "palette", "hex", "#", "rgb", "token", "semantic", "accent", "destructive", "muted", "foreground"],
+        "chart": ["chart", "graph", "visualization", "trend", "bar", "pie", "scatter", "heatmap", "funnel"],
+        "landing": ["landing", "page", "cta", "conversion", "hero", "testimonial", "pricing", "section"],
+        "product": _load_product_keywords(),
+        "style": ["style", "design", "ui", "minimalism", "glassmorphism", "neumorphism", "brutalism", "dark mode", "flat", "aurora", "prompt", "css", "implementation", "variable", "checklist", "tailwind"],
+        "ux": ["ux", "usability", "accessibility", "wcag", "touch", "scroll", "animation", "keyboard", "navigation", "mobile"],
+        "typography": ["font pairing", "typography pairing", "heading font", "body font"],
+        "google-fonts": ["google font", "font family", "font weight", "font style", "variable font", "noto", "font for", "find font", "font subset", "font language", "monospace font", "serif font", "sans serif font", "display font", "handwriting font", "font", "typography", "serif", "sans"],
+        "icons": ["icon", "icons", "lucide", "heroicons", "symbol", "glyph", "pictogram", "svg icon"],
+        "gsap": ["gsap", "quickto", "scrolltrigger", "stagger", "magnetic cursor", "parallax", "page transition", "scroll reveal", "scroll-triggered", "scrollytelling", "flip plugin", "splittext", "shimmer", "skeleton loader"],
+        "react": ["react", "next.js", "nextjs", "suspense", "memo", "usecallback", "useeffect", "rerender", "bundle", "waterfall", "barrel", "dynamic import", "rsc", "server component"],
+        "web": ["aria", "focus", "outline", "semantic", "virtualize", "autocomplete", "form", "input type", "preconnect"]
+    }
+    return _DOMAIN_KEYWORDS
+
+
+# Domains checked in this fixed order when scores tie, so results are
+# deterministic instead of depending on dict/hash ordering.
+_DOMAIN_TIEBREAK_ORDER = [
+    "ux", "product", "style", "color", "typography", "google-fonts",
+    "chart", "landing", "icons", "gsap", "react", "web",
+]
+
+
+def detect_domain(query, return_scores=False):
+    """Auto-detect the most relevant domain from query.
+
+    Matches are weighted by keyword length (multi-word/longer phrases are
+    more specific and score higher than short generic words). Ties are
+    broken by a fixed domain priority order, not dict/insertion order.
+    """
+    query_lower = query.lower()
+    domain_keywords = _domain_keywords()
+
+    scores = {}
+    for domain, keywords in domain_keywords.items():
+        total = 0.0
+        for kw in keywords:
+            if re.search(r'\b' + re.escape(kw) + r'\b', query_lower):
+                # weight = 1 point per word in the keyword phrase
+                total += max(1, len(kw.split()))
+        scores[domain] = total
+
+    ranked = sorted(
+        scores.items(),
+        key=lambda item: (item[1], -_DOMAIN_TIEBREAK_ORDER.index(item[0])
+                           if item[0] in _DOMAIN_TIEBREAK_ORDER else -999),
+        reverse=True,
+    )
+    best_domain, best_score = ranked[0]
+    result = best_domain if best_score > 0 else "style"
+
+    if return_scores:
+        runner_up = ranked[1][0] if len(ranked) > 1 and ranked[1][1] > 0 else None
+        return result, runner_up
+    return result
+
+
+def search(query, domain=None, max_results=MAX_RESULTS):
+    """Main search function with auto-domain detection"""
+    auto_detected = domain is None
+    runner_up = None
+    if domain is None:
+        domain, runner_up = detect_domain(query, return_scores=True)
+
+    config = CSV_CONFIG.get(domain, CSV_CONFIG["style"])
+    filepath = DATA_DIR / config["file"]
+
+    if not filepath.exists():
+        return {"error": f"File not found: {filepath}", "domain": domain}
+
+    results, bm25 = _search_csv(filepath, config["search_cols"], config["output_cols"], query, max_results)
+
+    out = {
+        "domain": domain,
+        "query": query,
+        "file": config["file"],
+        "count": len(results),
+        "results": results,
+    }
+    if auto_detected:
+        out["auto_detected"] = True
+        if runner_up:
+            out["runner_up_domain"] = runner_up
+    if not results:
+        out["suggestions"] = _suggest_terms(bm25, query)
+    return out
+
+
+def search_stack(query, stack, max_results=MAX_RESULTS):
+    """Search stack-specific guidelines"""
+    if stack not in STACK_CONFIG:
+        return {"error": f"Unknown stack: {stack}. Available: {', '.join(AVAILABLE_STACKS)}"}
+
+    filepath = DATA_DIR / STACK_CONFIG[stack]["file"]
+
+    if not filepath.exists():
+        return {"error": f"Stack file not found: {filepath}", "stack": stack}
+
+    results, bm25 = _search_csv(filepath, _STACK_COLS["search_cols"], _STACK_COLS["output_cols"], query, max_results)
+
+    out = {
+        "domain": "stack",
+        "stack": stack,
+        "query": query,
+        "file": STACK_CONFIG[stack]["file"],
+        "count": len(results),
+        "results": results,
+    }
+    if not results:
+        out["suggestions"] = _suggest_terms(bm25, query)
+    return out

.agents/skills/ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] --output-dir "<project-root>" [--page "dashboard"]
+       python search.py "<query>" --design-system --variance 8 --motion 9 --density 7
+
+Domains: style, color, chart, landing, product, ux, typography, google-fonts, icons, gsap, react, web
+Stacks: react, nextjs, vue, svelte, astro, swiftui, react-native, flutter, nuxtjs, nuxt-ui,
+        html-tailwind, shadcn, jetpack-compose, threejs, angular, laravel
+
+Design dials (1-10, only with --design-system):
+  --variance   DESIGN_VARIANCE: 1=centered/minimal, 10=bold/asymmetric
+  --motion     MOTION_INTENSITY: 1=subtle, 10=complex; attaches a GSAP snippet from motion.csv
+  --density    VISUAL_DENSITY: 1=spacious, 10=dense/dashboard; overrides the spacing scale
+
+Persistence (Master + Overrides pattern):
+  --persist      Save design system to design-system/<project-slug>/MASTER.md
+  --output-dir   Directory the design-system/ folder is created under (defaults to cwd --
+                 always pass this explicitly, pointed at the project root)
+  --page         Also create a page-specific override file in design-system/<project-slug>/pages/
+  --force        Overwrite an existing MASTER.md (without this, persistence is skipped
+                 if MASTER.md already exists, so prior design decisions aren't lost)
+"""
+
+import argparse
+import json as json_module
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, UNTRUNCATED_COLS, search, search_stack
+from design_system import generate_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+TRUNCATE_AT = 300
+
+
+def format_output(result, full=False):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append("## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append("## UI Pro Max Search Results")
+        domain_note = result['domain']
+        if result.get("auto_detected"):
+            domain_note += " (auto-detected"
+            if result.get("runner_up_domain"):
+                domain_note += f", runner-up: {result['runner_up_domain']}"
+            domain_note += ")"
+        output.append(f"**Domain:** {domain_note} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    if result['count'] == 0:
+        output.append(
+            "No matches. This is not a match with an empty value -- the query "
+            "did not hit the database. Retry with broader/different keywords "
+            "before falling back to general defaults, and say explicitly that "
+            "no database match was found if you do fall back."
+        )
+        suggestions = result.get("suggestions") or []
+        if suggestions:
+            output.append(f"**Closest known terms:** {', '.join(suggestions)}")
+        return "\n".join(output)
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if not full and key not in UNTRUNCATED_COLS and len(value_str) > TRUNCATE_AT:
+                value_str = value_str[:TRUNCATE_AT] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help=f"Stack-specific search. Available: {', '.join(AVAILABLE_STACKS)}")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    parser.add_argument("--full", action="store_true", help="Do not truncate long field values in text output")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system (ignored if --json)")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/<project-slug>/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/<project-slug>/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory -- pass this explicitly, pointed at the project root)")
+    parser.add_argument("--force", action="store_true", help="Overwrite an existing MASTER.md when persisting (default: skip if it already exists)")
+    # Design dials (1-10), only applied with --design-system
+    parser.add_argument("--variance", type=int, choices=range(1, 11), metavar="1-10", help="DESIGN_VARIANCE dial: 1=centered/minimal, 10=bold/asymmetric (only with --design-system)")
+    parser.add_argument("--motion", type=int, choices=range(1, 11), metavar="1-10", help="MOTION_INTENSITY dial: 1=subtle, 10=complex; pulls a matching GSAP snippet from motion.csv (only with --design-system)")
+    parser.add_argument("--density", type=int, choices=range(1, 11), metavar="1-10", help="VISUAL_DENSITY dial: 1=spacious, 10=dense/dashboard; overrides the spacing scale (only with --design-system)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query,
+            args.project_name,
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir,
+            variance=args.variance,
+            motion=args.motion,
+            density=args.density,
+            force=args.force,
+        )
+
+        if args.json:
+            print(json_module.dumps(
+                {"design_system": result["design_system"], "persistence": result["persistence"]},
+                indent=2, ensure_ascii=False,
+            ))
+        else:
+            print(result["text"])
+
+            if args.persist:
+                persistence = result["persistence"] or {}
+                print("\n" + "=" * 60)
+                if persistence.get("status") == "skipped_exists":
+                    print(f"⚠️  {persistence.get('message', 'MASTER.md already exists; not overwritten.')}")
+                else:
+                    ds_dir = persistence.get("design_system_dir", "design-system/<project>")
+                    print(f"✅ Design system persisted to {ds_dir}/")
+                    for f in persistence.get("created_files", []):
+                        print(f"   📄 {f}")
+                    print("")
+                    print(f"📖 Usage: When building a page, check {ds_dir}/pages/[page].md first.")
+                    print("   If it exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+                print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            print(json_module.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result, full=args.full))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            print(json_module.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result, full=args.full))

.agents/skills/ui-ux-pro-max/scripts/tests/test_core.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Stdlib-only regression tests for core.py / design_system.py (unittest, not
+pytest -- this project ships with zero external dependencies and the tests
+shouldn't add one).
+
+Run with:
+    python -m unittest discover -s scripts/tests -v
+or directly:
+    python scripts/tests/test_core.py
+"""
+
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+from core import BM25, detect_domain, search, search_stack, CSV_CONFIG, AVAILABLE_STACKS
+from design_system import generate_design_system, persist_design_system, DesignSystemGenerator
+
+
+class TestTokenizer(unittest.TestCase):
+    def test_short_domain_terms_are_kept(self):
+        bm25 = BM25()
+        tokens = bm25.tokenize("UI and UX design with 3D and AI")
+        self.assertIn("ui", tokens)
+        self.assertIn("3d", tokens)
+        self.assertIn("ai", tokens)
+
+    def test_stopwords_removed(self):
+        bm25 = BM25()
+        tokens = bm25.tokenize("this is for the team to do")
+        for stopword in ("is", "for", "the", "to", "do"):
+            self.assertNotIn(stopword, tokens)
+
+    def test_synonym_normalization(self):
+        bm25 = BM25()
+        self.assertEqual(bm25.tokenize("e-commerce store"), bm25.tokenize("ecommerce store"))
+        self.assertEqual(bm25.tokenize("dark-mode toggle"), bm25.tokenize("dark toggle"))
+
+
+class TestSearchDomains(unittest.TestCase):
+    """Known query -> expected top-domain sanity checks (not exact-row pinning,
+    since data can grow; these assert the engine still finds *something*
+    relevant for each domain's core vocabulary)."""
+
+    def test_ui_is_searchable_in_style_domain(self):
+        result = search("ui minimalism", domain="style", max_results=1)
+        self.assertGreater(result["count"], 0, "literal 'ui' token must be searchable, not filtered by tokenizer")
+
+    def test_accessibility_query_hits_ux(self):
+        result = search("accessibility contrast wcag keyboard", domain="ux", max_results=3)
+        self.assertGreater(result["count"], 0)
+
+    def test_zero_result_query_reports_suggestions_not_error(self):
+        result = search("zzqqxx totally made up gibberish", domain="ux", max_results=2)
+        self.assertEqual(result["count"], 0)
+        self.assertIn("suggestions", result)
+        self.assertNotIn("error", result)
+
+    def test_every_configured_domain_file_exists_and_is_searchable(self):
+        for domain, config in CSV_CONFIG.items():
+            with self.subTest(domain=domain):
+                result = search("design", domain=domain, max_results=1)
+                self.assertNotIn("error", result, f"domain '{domain}' failed: {result.get('error')}")
+
+    def test_every_stack_file_exists_and_is_searchable(self):
+        for stack in AVAILABLE_STACKS:
+            with self.subTest(stack=stack):
+                result = search_stack("performance", stack, max_results=1)
+                self.assertNotIn("error", result, f"stack '{stack}' failed: {result.get('error')}")
+
+
+class TestDomainDetection(unittest.TestCase):
+    def test_style_keywords_route_to_style(self):
+        self.assertEqual(detect_domain("glassmorphism dark ui"), "style")
+
+    def test_accessibility_keywords_route_to_ux(self):
+        self.assertEqual(detect_domain("accessibility contrast wcag"), "ux")
+
+    def test_ambiguous_query_returns_runner_up(self):
+        domain, runner_up = detect_domain("font pairing elegant crypto", return_scores=True)
+        self.assertIsNotNone(domain)
+        # runner_up may be None if the winning domain has no close second --
+        # this just verifies the call shape works without raising.
+
+    def test_empty_query_falls_back_to_style(self):
+        self.assertEqual(detect_domain("...!!!???"), "style")
+
+
+class TestPersistence(unittest.TestCase):
+    def test_persist_then_skip_then_force(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            result = generate_design_system("saas dashboard", "Test Project", persist=True, output_dir=tmp)
+            self.assertEqual(result["persistence"]["status"], "success")
+            master = Path(result["persistence"]["master_file"])
+            self.assertTrue(master.exists())
+            original_content = master.read_text(encoding="utf-8")
+
+            # Second persist without force must not overwrite.
+            result2 = generate_design_system("saas dashboard", "Test Project", persist=True, output_dir=tmp)
+            self.assertEqual(result2["persistence"]["status"], "skipped_exists")
+            self.assertEqual(master.read_text(encoding="utf-8"), original_content)
+
+            # With force=True it must overwrite.
+            result3 = generate_design_system("ecommerce luxury", "Test Project", persist=True, output_dir=tmp, force=True)
+            self.assertEqual(result3["persistence"]["status"], "success")
+
+    def test_persist_writes_only_under_output_dir(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            generate_design_system("saas dashboard", "Scoped Project", persist=True, output_dir=tmp)
+            expected = Path(tmp) / "design-system" / "scoped-project" / "MASTER.md"
+            self.assertTrue(expected.exists())
+
+
+class TestReasoningMatch(unittest.TestCase):
+    def test_known_category_matches_exactly(self):
+        gen = DesignSystemGenerator()
+        rule = gen._find_reasoning_rule("SaaS (General)")
+        self.assertTrue(rule, "exact-match category lookup should not fall through to fuzzy matching")
+
+    def test_unknown_category_falls_back_gracefully(self):
+        gen = DesignSystemGenerator()
+        rule = gen._find_reasoning_rule("Totally Unknown Category XYZ")
+        # Should not raise; may return {} which _apply_reasoning handles with defaults.
+        self.assertIsInstance(rule, dict)
+
+
+if __name__ == "__main__":
+    unittest.main()

.agents/skills/ui-ux-pro-max/scripts/validate_data.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Data integrity guardrail for ui-ux-pro-max. Stdlib-only, no pytest dependency,
+so it can run as a standalone pre-publish/CI check:
+
+    python validate_data.py
+
+Checks, per configured domain/stack CSV:
+  - file exists
+  - header row contains every column referenced in search_cols/output_cols
+  - no duplicate primary-key values (first column) within a file
+  - any "Decision_Rules"-style JSON column parses as JSON
+
+Exits 0 with no output on success; exits 1 and prints every problem found
+on failure (fail-fast is the wrong call here -- a data change can break
+several files at once, so we want the full list in one run).
+"""
+
+import csv
+import json
+import sys
+from pathlib import Path
+
+from core import CSV_CONFIG, STACK_CONFIG, _STACK_COLS, DATA_DIR
+
+# REASONING_FILE lives in design_system.py, not core.py -- redeclared here to
+# avoid a circular import (design_system.py imports core.py).
+REASONING_FILE = "ui-reasoning.csv"
+JSON_COLUMNS = {"Decision_Rules"}
+
+
+def _read_rows(filepath):
+    with open(filepath, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        return reader.fieldnames or [], list(reader)
+
+
+def _check_file(label, filepath, search_cols, output_cols, problems):
+    if not filepath.exists():
+        problems.append(f"[{label}] missing file: {filepath}")
+        return
+
+    try:
+        headers, rows = _read_rows(filepath)
+    except (csv.Error, UnicodeDecodeError, OSError) as e:
+        problems.append(f"[{label}] failed to parse {filepath.name}: {e}")
+        return
+
+    header_set = set(headers)
+    for col in set(search_cols) | set(output_cols):
+        if col not in header_set:
+            problems.append(f"[{label}] {filepath.name}: expected column '{col}' not found in header")
+
+    # Only check for duplicates against an actual identifier column ("No" is
+    # the sequential-index convention used across this dataset). The first
+    # CSV column is not reliably a unique key -- e.g. stack files use
+    # "Category", which legitimately repeats across many guideline rows.
+    if "No" in header_set:
+        seen = {}
+        for i, row in enumerate(rows, start=2):  # +1 header, +1 to be 1-indexed
+            key = row.get("No", "")
+            if key in seen:
+                problems.append(
+                    f"[{label}] {filepath.name}: duplicate 'No' value '{key}' on rows {seen[key]} and {i}"
+                )
+            else:
+                seen[key] = i
+    elif label.startswith("stack:"):
+        problems.append(
+            f"[{label}] {filepath.name}: missing 'No' index column present in other stack files "
+            "(schema drift -- harmless for search, but inconsistent with the rest of data/stacks/)"
+        )
+
+    for row_idx, row in enumerate(rows, start=2):
+        for col in JSON_COLUMNS:
+            if col in row and row[col]:
+                try:
+                    json.loads(row[col])
+                except json.JSONDecodeError as e:
+                    problems.append(
+                        f"[{label}] {filepath.name} row {row_idx}: column '{col}' is not valid JSON: {e}"
+                    )
+
+
+def main():
+    problems = []
+
+    for domain, config in CSV_CONFIG.items():
+        _check_file(f"domain:{domain}", DATA_DIR / config["file"],
+                    config["search_cols"], config["output_cols"], problems)
+
+    for stack, config in STACK_CONFIG.items():
+        _check_file(f"stack:{stack}", DATA_DIR / config["file"],
+                    _STACK_COLS["search_cols"], _STACK_COLS["output_cols"], problems)
+
+    reasoning_path = DATA_DIR / REASONING_FILE
+    if reasoning_path.exists():
+        _check_file("reasoning", reasoning_path, ["UI_Category"], ["UI_Category", "Decision_Rules"], problems)
+    else:
+        problems.append(f"[reasoning] missing file: {reasoning_path}")
+
+    if problems:
+        print(f"FAILED: {len(problems)} data integrity issue(s) found:\n")
+        for p in problems:
+            print(f"  - {p}")
+        sys.exit(1)
+
+    print(f"OK: validated {len(CSV_CONFIG)} domain files, {len(STACK_CONFIG)} stack files, and ui-reasoning.csv")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()