1#!/usr/bin/env python3
2# -*- coding: utf-8 -*-
3"""
4Design System Generator - Aggregates search results and applies reasoning
5to generate comprehensive design system recommendations.
6 
7Usage:
8    from design_system import generate_design_system
9    result = generate_design_system("SaaS dashboard", "My Project")
10    
11    # With persistence (Master + Overrides pattern)
12    result = generate_design_system("SaaS dashboard", "My Project", persist=True)
13    result = generate_design_system("SaaS dashboard", "My Project", persist=True, page="dashboard")
14"""
15 
16import csv
17import json
18import os
19from datetime import datetime
20from pathlib import Path
21from core import search, DATA_DIR
22 
23 
24# ============ CONFIGURATION ============
25REASONING_FILE = "ui-reasoning.csv"
26 
27SEARCH_CONFIG = {
28    "product": {"max_results": 1},
29    "style": {"max_results": 3},
30    "color": {"max_results": 2},
31    "landing": {"max_results": 2},
32    "typography": {"max_results": 2}
33}
34 
35 
36# ============ DESIGN SYSTEM GENERATOR ============
37class DesignSystemGenerator:
38    """Generates design system recommendations from aggregated searches."""
39 
40    def __init__(self):
41        self.reasoning_data = self._load_reasoning()
42 
43    def _load_reasoning(self) -> list:
44        """Load reasoning rules from CSV."""
45        filepath = DATA_DIR / REASONING_FILE
46        if not filepath.exists():
47            return []
48        with open(filepath, 'r', encoding='utf-8') as f:
49            return list(csv.DictReader(f))
50 
51    def _multi_domain_search(self, query: str, style_priority: list = None) -> dict:
52        """Execute searches across multiple domains."""
53        results = {}
54        for domain, config in SEARCH_CONFIG.items():
55            if domain == "style" and style_priority:
56                # For style, also search with priority keywords
57                priority_query = " ".join(style_priority[:2]) if style_priority else query
58                combined_query = f"{query} {priority_query}"
59                results[domain] = search(combined_query, domain, config["max_results"])
60            else:
61                results[domain] = search(query, domain, config["max_results"])
62        return results
63 
64    def _find_reasoning_rule(self, category: str) -> dict:
65        """Find matching reasoning rule for a category."""
66        category_lower = category.lower()
67 
68        # Try exact match first
69        for rule in self.reasoning_data:
70            if rule.get("UI_Category", "").lower() == category_lower:
71                return rule
72 
73        # Try partial match
74        for rule in self.reasoning_data:
75            ui_cat = rule.get("UI_Category", "").lower()
76            if ui_cat in category_lower or category_lower in ui_cat:
77                return rule
78 
79        # Try keyword match
80        for rule in self.reasoning_data:
81            ui_cat = rule.get("UI_Category", "").lower()
82            keywords = ui_cat.replace("/", " ").replace("-", " ").split()
83            if any(kw in category_lower for kw in keywords):
84                return rule
85 
86        return {}
87 
88    def _apply_reasoning(self, category: str, search_results: dict) -> dict:
89        """Apply reasoning rules to search results."""
90        rule = self._find_reasoning_rule(category)
91 
92        if not rule:
93            return {
94                "pattern": "Hero + Features + CTA",
95                "style_priority": ["Minimalism", "Flat Design"],
96                "color_mood": "Professional",
97                "typography_mood": "Clean",
98                "key_effects": "Subtle hover transitions",
99                "anti_patterns": "",
100                "decision_rules": {},
101                "severity": "MEDIUM"
102            }
103 
104        # Parse decision rules JSON
105        decision_rules = {}
106        try:
107            decision_rules = json.loads(rule.get("Decision_Rules", "{}"))
108        except json.JSONDecodeError:
109            pass
110 
111        return {
112            "pattern": rule.get("Recommended_Pattern", ""),
113            "style_priority": [s.strip() for s in rule.get("Style_Priority", "").split("+")],
114            "color_mood": rule.get("Color_Mood", ""),
115            "typography_mood": rule.get("Typography_Mood", ""),
116            "key_effects": rule.get("Key_Effects", ""),
117            "anti_patterns": rule.get("Anti_Patterns", ""),
118            "decision_rules": decision_rules,
119            "severity": rule.get("Severity", "MEDIUM")
120        }
121 
122    def _select_best_match(self, results: list, priority_keywords: list) -> dict:
123        """Select best matching result based on priority keywords."""
124        if not results:
125            return {}
126 
127        if not priority_keywords:
128            return results[0]
129 
130        # First: try exact style name match
131        for priority in priority_keywords:
132            priority_lower = priority.lower().strip()
133            for result in results:
134                style_name = result.get("Style Category", "").lower()
135                if priority_lower in style_name or style_name in priority_lower:
136                    return result
137 
138        # Second: score by keyword match in all fields
139        scored = []
140        for result in results:
141            result_str = str(result).lower()
142            score = 0
143            for kw in priority_keywords:
144                kw_lower = kw.lower().strip()
145                # Higher score for style name match
146                if kw_lower in result.get("Style Category", "").lower():
147                    score += 10
148                # Lower score for keyword field match
149                elif kw_lower in result.get("Keywords", "").lower():
150                    score += 3
151                # Even lower for other field matches
152                elif kw_lower in result_str:
153                    score += 1
154            scored.append((score, result))
155 
156        scored.sort(key=lambda x: x[0], reverse=True)
157        return scored[0][1] if scored and scored[0][0] > 0 else results[0]
158 
159    def _extract_results(self, search_result: dict) -> list:
160        """Extract results list from search result dict."""
161        return search_result.get("results", [])
162 
163    def generate(self, query: str, project_name: str = None) -> dict:
164        """Generate complete design system recommendation."""
165        # Step 1: First search product to get category
166        product_result = search(query, "product", 1)
167        product_results = product_result.get("results", [])
168        category = "General"
169        if product_results:
170            category = product_results[0].get("Product Type", "General")
171 
172        # Step 2: Get reasoning rules for this category
173        reasoning = self._apply_reasoning(category, {})
174        style_priority = reasoning.get("style_priority", [])
175 
176        # Step 3: Multi-domain search with style priority hints
177        search_results = self._multi_domain_search(query, style_priority)
178        search_results["product"] = product_result  # Reuse product search
179 
180        # Step 4: Select best matches from each domain using priority
181        style_results = self._extract_results(search_results.get("style", {}))
182        color_results = self._extract_results(search_results.get("color", {}))
183        typography_results = self._extract_results(search_results.get("typography", {}))
184        landing_results = self._extract_results(search_results.get("landing", {}))
185 
186        best_style = self._select_best_match(style_results, reasoning.get("style_priority", []))
187        best_color = color_results[0] if color_results else {}
188        best_typography = typography_results[0] if typography_results else {}
189        best_landing = landing_results[0] if landing_results else {}
190 
191        # Step 5: Build final recommendation
192        # Combine effects from both reasoning and style search
193        style_effects = best_style.get("Effects & Animation", "")
194        reasoning_effects = reasoning.get("key_effects", "")
195        combined_effects = style_effects if style_effects else reasoning_effects
196 
197        return {
198            "project_name": project_name or query.upper(),
199            "category": category,
200            "pattern": {
201                "name": best_landing.get("Pattern Name", reasoning.get("pattern", "Hero + Features + CTA")),
202                "sections": best_landing.get("Section Order", "Hero > Features > CTA"),
203                "cta_placement": best_landing.get("Primary CTA Placement", "Above fold"),
204                "color_strategy": best_landing.get("Color Strategy", ""),
205                "conversion": best_landing.get("Conversion Optimization", "")
206            },
207            "style": {
208                "name": best_style.get("Style Category", "Minimalism"),
209                "type": best_style.get("Type", "General"),
210                "effects": style_effects,
211                "keywords": best_style.get("Keywords", ""),
212                "best_for": best_style.get("Best For", ""),
213                "performance": best_style.get("Performance", ""),
214                "accessibility": best_style.get("Accessibility", ""),
215                "light_mode": best_style.get("Light Mode ✓", ""),
216                "dark_mode": best_style.get("Dark Mode ✓", ""),
217            },
218            "colors": {
219                "primary": best_color.get("Primary", "#2563EB"),
220                "on_primary": best_color.get("On Primary", ""),
221                "secondary": best_color.get("Secondary", "#3B82F6"),
222                "accent": best_color.get("Accent", "#F97316"),
223                "background": best_color.get("Background", "#F8FAFC"),
224                "foreground": best_color.get("Foreground", "#1E293B"),
225                "muted": best_color.get("Muted", ""),
226                "border": best_color.get("Border", ""),
227                "destructive": best_color.get("Destructive", ""),
228                "ring": best_color.get("Ring", ""),
229                "notes": best_color.get("Notes", ""),
230                # Keep legacy keys for backward compat in MASTER.md
231                "cta": best_color.get("Accent", "#F97316"),
232                "text": best_color.get("Foreground", "#1E293B"),
233            },
234            "typography": {
235                "heading": best_typography.get("Heading Font", "Inter"),
236                "body": best_typography.get("Body Font", "Inter"),
237                "mood": best_typography.get("Mood/Style Keywords", reasoning.get("typography_mood", "")),
238                "best_for": best_typography.get("Best For", ""),
239                "google_fonts_url": best_typography.get("Google Fonts URL", ""),
240                "css_import": best_typography.get("CSS Import", "")
241            },
242            "key_effects": combined_effects,
243            "anti_patterns": reasoning.get("anti_patterns", ""),
244            "decision_rules": reasoning.get("decision_rules", {}),
245            "severity": reasoning.get("severity", "MEDIUM")
246        }
247 
248 
249# ============ OUTPUT FORMATTERS ============
250BOX_WIDTH = 90  # Wider box for more content
251 
252 
253def hex_to_ansi(hex_color: str) -> str:
254    """Convert hex color to ANSI True Color swatch (██) with fallback."""
255    if not hex_color or not hex_color.startswith('#'):
256        return ""
257    colorterm = os.environ.get('COLORTERM', '')
258    if colorterm not in ('truecolor', '24bit'):
259        return ""
260    hex_color = hex_color.lstrip('#')
261    if len(hex_color) != 6:
262        return ""
263    r, g, b = int(hex_color[0:2], 16), int(hex_color[2:4], 16), int(hex_color[4:6], 16)
264    return f"\033[38;2;{r};{g};{b}m██\033[0m "
265 
266 
267def ansi_ljust(s: str, width: int) -> str:
268    """Like str.ljust but accounts for zero-width ANSI escape sequences."""
269    import re
270    visible_len = len(re.sub(r'\033\[[0-9;]*m', '', s))
271    pad = width - visible_len
272    return s + (" " * max(0, pad))
273 
274 
275def section_header(name: str, width: int) -> str:
276    """Create a Unicode section separator: ├─── NAME ───...┤"""
277    label = f"─── {name} "
278    fill = "─" * (width - len(label) - 1)
279    return f"├{label}{fill}┤"
280 
281 
282def format_ascii_box(design_system: dict) -> str:
283    """Format design system as Unicode box with ANSI color swatches."""
284    project = design_system.get("project_name", "PROJECT")
285    pattern = design_system.get("pattern", {})
286    style = design_system.get("style", {})
287    colors = design_system.get("colors", {})
288    typography = design_system.get("typography", {})
289    effects = design_system.get("key_effects", "")
290    anti_patterns = design_system.get("anti_patterns", "")
291 
292    def wrap_text(text: str, prefix: str, width: int) -> list:
293        """Wrap long text into multiple lines."""
294        if not text:
295            return []
296        words = text.split()
297        lines = []
298        current_line = prefix
299        for word in words:
300            if len(current_line) + len(word) + 1 <= width - 2:
301                current_line += (" " if current_line != prefix else "") + word
302            else:
303                if current_line != prefix:
304                    lines.append(current_line)
305                current_line = prefix + word
306        if current_line != prefix:
307            lines.append(current_line)
308        return lines
309 
310    # Build sections from pattern
311    sections = pattern.get("sections", "").split(">")
312    sections = [s.strip() for s in sections if s.strip()]
313 
314    # Build output lines
315    lines = []
316    w = BOX_WIDTH - 1
317 
318    # Header with double-line box
319    lines.append("╔" + "═" * w + "╗")
320    lines.append(ansi_ljust(f"║  TARGET: {project} - RECOMMENDED DESIGN SYSTEM", BOX_WIDTH) + "║")
321    lines.append("╚" + "═" * w + "╝")
322    lines.append("┌" + "─" * w + "┐")
323 
324    # Pattern section
325    lines.append(section_header("PATTERN", BOX_WIDTH + 1))
326    lines.append(f"│  Name: {pattern.get('name', '')}".ljust(BOX_WIDTH) + "│")
327    if pattern.get('conversion'):
328        lines.append(f"│     Conversion: {pattern.get('conversion', '')}".ljust(BOX_WIDTH) + "│")
329    if pattern.get('cta_placement'):
330        lines.append(f"│     CTA: {pattern.get('cta_placement', '')}".ljust(BOX_WIDTH) + "│")
331    lines.append("│     Sections:".ljust(BOX_WIDTH) + "│")
332    for i, section in enumerate(sections, 1):
333        lines.append(f"│       {i}. {section}".ljust(BOX_WIDTH) + "│")
334 
335    # Style section
336    lines.append(section_header("STYLE", BOX_WIDTH + 1))
337    lines.append(f"│  Name: {style.get('name', '')}".ljust(BOX_WIDTH) + "│")
338    light = style.get("light_mode", "")
339    dark = style.get("dark_mode", "")
340    if light or dark:
341        lines.append(f"│     Mode Support: Light {light}  Dark {dark}".ljust(BOX_WIDTH) + "│")
342    if style.get("keywords"):
343        for line in wrap_text(f"Keywords: {style.get('keywords', '')}", "│     ", BOX_WIDTH):
344            lines.append(line.ljust(BOX_WIDTH) + "│")
345    if style.get("best_for"):
346        for line in wrap_text(f"Best For: {style.get('best_for', '')}", "│     ", BOX_WIDTH):
347            lines.append(line.ljust(BOX_WIDTH) + "│")
348    if style.get("performance") or style.get("accessibility"):
349        perf_a11y = f"Performance: {style.get('performance', '')} | Accessibility: {style.get('accessibility', '')}"
350        lines.append(f"│     {perf_a11y}".ljust(BOX_WIDTH) + "│")
351 
352    # Colors section (extended palette with ANSI swatches)
353    lines.append(section_header("COLORS", BOX_WIDTH + 1))
354    color_entries = [
355        ("Primary",      "primary",      "--color-primary"),
356        ("On Primary",   "on_primary",   "--color-on-primary"),
357        ("Secondary",    "secondary",    "--color-secondary"),
358        ("Accent/CTA",   "accent",       "--color-accent"),
359        ("Background",   "background",   "--color-background"),
360        ("Foreground",   "foreground",   "--color-foreground"),
361        ("Muted",        "muted",        "--color-muted"),
362        ("Border",       "border",       "--color-border"),
363        ("Destructive",  "destructive",  "--color-destructive"),
364        ("Ring",         "ring",         "--color-ring"),
365    ]
366    for label, key, css_var in color_entries:
367        hex_val = colors.get(key, "")
368        if not hex_val:
369            continue
370        swatch = hex_to_ansi(hex_val)
371        content = f"│     {swatch}{label + ':':14s} {hex_val:10s} ({css_var})"
372        lines.append(ansi_ljust(content, BOX_WIDTH) + "│")
373    if colors.get("notes"):
374        for line in wrap_text(f"Notes: {colors.get('notes', '')}", "│     ", BOX_WIDTH):
375            lines.append(line.ljust(BOX_WIDTH) + "│")
376 
377    # Typography section
378    lines.append(section_header("TYPOGRAPHY", BOX_WIDTH + 1))
379    lines.append(f"│  {typography.get('heading', '')} / {typography.get('body', '')}".ljust(BOX_WIDTH) + "│")
380    if typography.get("mood"):
381        for line in wrap_text(f"Mood: {typography.get('mood', '')}", "│     ", BOX_WIDTH):
382            lines.append(line.ljust(BOX_WIDTH) + "│")
383    if typography.get("best_for"):
384        for line in wrap_text(f"Best For: {typography.get('best_for', '')}", "│     ", BOX_WIDTH):
385            lines.append(line.ljust(BOX_WIDTH) + "│")
386    if typography.get("google_fonts_url"):
387        lines.append(f"│     Google Fonts: {typography.get('google_fonts_url', '')}".ljust(BOX_WIDTH) + "│")
388    if typography.get("css_import"):
389        lines.append(f"│     CSS Import: {typography.get('css_import', '')[:70]}...".ljust(BOX_WIDTH) + "│")
390 
391    # Key Effects section
392    if effects:
393        lines.append(section_header("KEY EFFECTS", BOX_WIDTH + 1))
394        for line in wrap_text(effects, "│     ", BOX_WIDTH):
395            lines.append(line.ljust(BOX_WIDTH) + "│")
396 
397    # Anti-patterns section
398    if anti_patterns:
399        lines.append(section_header("AVOID", BOX_WIDTH + 1))
400        for line in wrap_text(anti_patterns, "│     ", BOX_WIDTH):
401            lines.append(line.ljust(BOX_WIDTH) + "│")
402 
403    # Pre-Delivery Checklist section
404    lines.append(section_header("PRE-DELIVERY CHECKLIST", BOX_WIDTH + 1))
405    checklist_items = [
406        "[ ] No emojis as icons (use SVG: Heroicons/Lucide)",
407        "[ ] cursor-pointer on all clickable elements",
408        "[ ] Hover states with smooth transitions (150-300ms)",
409        "[ ] Light mode: text contrast 4.5:1 minimum",
410        "[ ] Focus states visible for keyboard nav",
411        "[ ] prefers-reduced-motion respected",
412        "[ ] Responsive: 375px, 768px, 1024px, 1440px"
413    ]
414    for item in checklist_items:
415        lines.append(f"│     {item}".ljust(BOX_WIDTH) + "│")
416 
417    lines.append("└" + "─" * w + "┘")
418 
419    return "\n".join(lines)
420 
421 
422def format_markdown(design_system: dict) -> str:
423    """Format design system as markdown."""
424    project = design_system.get("project_name", "PROJECT")
425    pattern = design_system.get("pattern", {})
426    style = design_system.get("style", {})
427    colors = design_system.get("colors", {})
428    typography = design_system.get("typography", {})
429    effects = design_system.get("key_effects", "")
430    anti_patterns = design_system.get("anti_patterns", "")
431 
432    lines = []
433    lines.append(f"## Design System: {project}")
434    lines.append("")
435 
436    # Pattern section
437    lines.append("### Pattern")
438    lines.append(f"- **Name:** {pattern.get('name', '')}")
439    if pattern.get('conversion'):
440        lines.append(f"- **Conversion Focus:** {pattern.get('conversion', '')}")
441    if pattern.get('cta_placement'):
442        lines.append(f"- **CTA Placement:** {pattern.get('cta_placement', '')}")
443    if pattern.get('color_strategy'):
444        lines.append(f"- **Color Strategy:** {pattern.get('color_strategy', '')}")
445    lines.append(f"- **Sections:** {pattern.get('sections', '')}")
446    lines.append("")
447 
448    # Style section
449    lines.append("### Style")
450    lines.append(f"- **Name:** {style.get('name', '')}")
451    light = style.get("light_mode", "")
452    dark = style.get("dark_mode", "")
453    if light or dark:
454        lines.append(f"- **Mode Support:** Light {light} | Dark {dark}")
455    if style.get('keywords'):
456        lines.append(f"- **Keywords:** {style.get('keywords', '')}")
457    if style.get('best_for'):
458        lines.append(f"- **Best For:** {style.get('best_for', '')}")
459    if style.get('performance') or style.get('accessibility'):
460        lines.append(f"- **Performance:** {style.get('performance', '')} | **Accessibility:** {style.get('accessibility', '')}")
461    lines.append("")
462 
463    # Colors section (extended palette)
464    lines.append("### Colors")
465    lines.append("| Role | Hex | CSS Variable |")
466    lines.append("|------|-----|--------------|")
467    md_color_entries = [
468        ("Primary",      "primary",      "--color-primary"),
469        ("On Primary",   "on_primary",   "--color-on-primary"),
470        ("Secondary",    "secondary",    "--color-secondary"),
471        ("Accent/CTA",   "accent",       "--color-accent"),
472        ("Background",   "background",   "--color-background"),
473        ("Foreground",   "foreground",   "--color-foreground"),
474        ("Muted",        "muted",        "--color-muted"),
475        ("Border",       "border",       "--color-border"),
476        ("Destructive",  "destructive",  "--color-destructive"),
477        ("Ring",         "ring",         "--color-ring"),
478    ]
479    for label, key, css_var in md_color_entries:
480        hex_val = colors.get(key, "")
481        if hex_val:
482            lines.append(f"| {label} | `{hex_val}` | `{css_var}` |")
483    if colors.get("notes"):
484        lines.append(f"\n*Notes: {colors.get('notes', '')}*")
485    lines.append("")
486 
487    # Typography section
488    lines.append("### Typography")
489    lines.append(f"- **Heading:** {typography.get('heading', '')}")
490    lines.append(f"- **Body:** {typography.get('body', '')}")
491    if typography.get("mood"):
492        lines.append(f"- **Mood:** {typography.get('mood', '')}")
493    if typography.get("best_for"):
494        lines.append(f"- **Best For:** {typography.get('best_for', '')}")
495    if typography.get("google_fonts_url"):
496        lines.append(f"- **Google Fonts:** {typography.get('google_fonts_url', '')}")
497    if typography.get("css_import"):
498        lines.append(f"- **CSS Import:**")
499        lines.append(f"```css")
500        lines.append(f"{typography.get('css_import', '')}")
501        lines.append(f"```")
502    lines.append("")
503 
504    # Key Effects section
505    if effects:
506        lines.append("### Key Effects")
507        lines.append(f"{effects}")
508        lines.append("")
509 
510    # Anti-patterns section
511    if anti_patterns:
512        lines.append("### Avoid (Anti-patterns)")
513        newline_bullet = '\n- '
514        lines.append(f"- {anti_patterns.replace(' + ', newline_bullet)}")
515        lines.append("")
516 
517    # Pre-Delivery Checklist section
518    lines.append("### Pre-Delivery Checklist")
519    lines.append("- [ ] No emojis as icons (use SVG: Heroicons/Lucide)")
520    lines.append("- [ ] cursor-pointer on all clickable elements")
521    lines.append("- [ ] Hover states with smooth transitions (150-300ms)")
522    lines.append("- [ ] Light mode: text contrast 4.5:1 minimum")
523    lines.append("- [ ] Focus states visible for keyboard nav")
524    lines.append("- [ ] prefers-reduced-motion respected")
525    lines.append("- [ ] Responsive: 375px, 768px, 1024px, 1440px")
526    lines.append("")
527 
528    return "\n".join(lines)
529 
530 
531# ============ MAIN ENTRY POINT ============
532def generate_design_system(query: str, project_name: str = None, output_format: str = "ascii", 
533                           persist: bool = False, page: str = None, output_dir: str = None) -> str:
534    """
535    Main entry point for design system generation.
536 
537    Args:
538        query: Search query (e.g., "SaaS dashboard", "e-commerce luxury")
539        project_name: Optional project name for output header
540        output_format: "ascii" (default) or "markdown"
541        persist: If True, save design system to design-system/ folder
542        page: Optional page name for page-specific override file
543        output_dir: Optional output directory (defaults to current working directory)
544 
545    Returns:
546        Formatted design system string
547    """
548    generator = DesignSystemGenerator()
549    design_system = generator.generate(query, project_name)
550    
551    # Persist to files if requested
552    if persist:
553        persist_design_system(design_system, page, output_dir, query)
554 
555    if output_format == "markdown":
556        return format_markdown(design_system)
557    return format_ascii_box(design_system)
558 
559 
560# ============ PERSISTENCE FUNCTIONS ============
561def persist_design_system(design_system: dict, page: str = None, output_dir: str = None, page_query: str = None) -> dict:
562    """
563    Persist design system to design-system/<project>/ folder using Master + Overrides pattern.
564    
565    Args:
566        design_system: The generated design system dictionary
567        page: Optional page name for page-specific override file
568        output_dir: Optional output directory (defaults to current working directory)
569        page_query: Optional query string for intelligent page override generation
570    
571    Returns:
572        dict with created file paths and status
573    """
574    base_dir = Path(output_dir) if output_dir else Path.cwd()
575    
576    # Use project name for project-specific folder
577    project_name = design_system.get("project_name", "default")
578    project_slug = project_name.lower().replace(' ', '-')
579    
580    design_system_dir = base_dir / "design-system" / project_slug
581    pages_dir = design_system_dir / "pages"
582    
583    created_files = []
584    
585    # Create directories
586    design_system_dir.mkdir(parents=True, exist_ok=True)
587    pages_dir.mkdir(parents=True, exist_ok=True)
588    
589    master_file = design_system_dir / "MASTER.md"
590    
591    # Generate and write MASTER.md
592    master_content = format_master_md(design_system)
593    with open(master_file, 'w', encoding='utf-8') as f:
594        f.write(master_content)
595    created_files.append(str(master_file))
596    
597    # If page is specified, create page override file with intelligent content
598    if page:
599        page_file = pages_dir / f"{page.lower().replace(' ', '-')}.md"
600        page_content = format_page_override_md(design_system, page, page_query)
601        with open(page_file, 'w', encoding='utf-8') as f:
602            f.write(page_content)
603        created_files.append(str(page_file))
604    
605    return {
606        "status": "success",
607        "design_system_dir": str(design_system_dir),
608        "created_files": created_files
609    }
610 
611 
612def format_master_md(design_system: dict) -> str:
613    """Format design system as MASTER.md with hierarchical override logic."""
614    project = design_system.get("project_name", "PROJECT")
615    pattern = design_system.get("pattern", {})
616    style = design_system.get("style", {})
617    colors = design_system.get("colors", {})
618    typography = design_system.get("typography", {})
619    effects = design_system.get("key_effects", "")
620    anti_patterns = design_system.get("anti_patterns", "")
621    
622    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
623    
624    lines = []
625    
626    # Logic header
627    lines.append("# Design System Master File")
628    lines.append("")
629    lines.append("> **LOGIC:** When building a specific page, first check `design-system/pages/[page-name].md`.")
630    lines.append("> If that file exists, its rules **override** this Master file.")
631    lines.append("> If not, strictly follow the rules below.")
632    lines.append("")
633    lines.append("---")
634    lines.append("")
635    lines.append(f"**Project:** {project}")
636    lines.append(f"**Generated:** {timestamp}")
637    lines.append(f"**Category:** {design_system.get('category', 'General')}")
638    lines.append("")
639    lines.append("---")
640    lines.append("")
641    
642    # Global Rules section
643    lines.append("## Global Rules")
644    lines.append("")
645    
646    # Color Palette
647    lines.append("### Color Palette")
648    lines.append("")
649    lines.append("| Role | Hex | CSS Variable |")
650    lines.append("|------|-----|--------------|")
651    master_color_entries = [
652        ("Primary",      "primary",      "--color-primary"),
653        ("On Primary",   "on_primary",   "--color-on-primary"),
654        ("Secondary",    "secondary",    "--color-secondary"),
655        ("Accent/CTA",   "accent",       "--color-accent"),
656        ("Background",   "background",   "--color-background"),
657        ("Foreground",   "foreground",   "--color-foreground"),
658        ("Muted",        "muted",        "--color-muted"),
659        ("Border",       "border",       "--color-border"),
660        ("Destructive",  "destructive",  "--color-destructive"),
661        ("Ring",         "ring",         "--color-ring"),
662    ]
663    for label, key, css_var in master_color_entries:
664        hex_val = colors.get(key, "")
665        if hex_val:
666            lines.append(f"| {label} | `{hex_val}` | `{css_var}` |")
667    lines.append("")
668    if colors.get("notes"):
669        lines.append(f"**Color Notes:** {colors.get('notes', '')}")
670        lines.append("")
671    
672    # Typography
673    lines.append("### Typography")
674    lines.append("")
675    lines.append(f"- **Heading Font:** {typography.get('heading', 'Inter')}")
676    lines.append(f"- **Body Font:** {typography.get('body', 'Inter')}")
677    if typography.get("mood"):
678        lines.append(f"- **Mood:** {typography.get('mood', '')}")
679    if typography.get("google_fonts_url"):
680        lines.append(f"- **Google Fonts:** [{typography.get('heading', '')} + {typography.get('body', '')}]({typography.get('google_fonts_url', '')})")
681    lines.append("")
682    if typography.get("css_import"):
683        lines.append("**CSS Import:**")
684        lines.append("```css")
685        lines.append(typography.get("css_import", ""))
686        lines.append("```")
687        lines.append("")
688    
689    # Spacing Variables
690    lines.append("### Spacing Variables")
691    lines.append("")
692    lines.append("| Token | Value | Usage |")
693    lines.append("|-------|-------|-------|")
694    lines.append("| `--space-xs` | `4px` / `0.25rem` | Tight gaps |")
695    lines.append("| `--space-sm` | `8px` / `0.5rem` | Icon gaps, inline spacing |")
696    lines.append("| `--space-md` | `16px` / `1rem` | Standard padding |")
697    lines.append("| `--space-lg` | `24px` / `1.5rem` | Section padding |")
698    lines.append("| `--space-xl` | `32px` / `2rem` | Large gaps |")
699    lines.append("| `--space-2xl` | `48px` / `3rem` | Section margins |")
700    lines.append("| `--space-3xl` | `64px` / `4rem` | Hero padding |")
701    lines.append("")
702    
703    # Shadow Depths
704    lines.append("### Shadow Depths")
705    lines.append("")
706    lines.append("| Level | Value | Usage |")
707    lines.append("|-------|-------|-------|")
708    lines.append("| `--shadow-sm` | `0 1px 2px rgba(0,0,0,0.05)` | Subtle lift |")
709    lines.append("| `--shadow-md` | `0 4px 6px rgba(0,0,0,0.1)` | Cards, buttons |")
710    lines.append("| `--shadow-lg` | `0 10px 15px rgba(0,0,0,0.1)` | Modals, dropdowns |")
711    lines.append("| `--shadow-xl` | `0 20px 25px rgba(0,0,0,0.15)` | Hero images, featured cards |")
712    lines.append("")
713    
714    # Component Specs section
715    lines.append("---")
716    lines.append("")
717    lines.append("## Component Specs")
718    lines.append("")
719    
720    # Buttons
721    lines.append("### Buttons")
722    lines.append("")
723    lines.append("```css")
724    lines.append("/* Primary Button */")
725    lines.append(".btn-primary {")
726    lines.append(f"  background: {colors.get('cta', '#F97316')};")
727    lines.append("  color: white;")
728    lines.append("  padding: 12px 24px;")
729    lines.append("  border-radius: 8px;")
730    lines.append("  font-weight: 600;")
731    lines.append("  transition: all 200ms ease;")
732    lines.append("  cursor: pointer;")
733    lines.append("}")
734    lines.append("")
735    lines.append(".btn-primary:hover {")
736    lines.append("  opacity: 0.9;")
737    lines.append("  transform: translateY(-1px);")
738    lines.append("}")
739    lines.append("")
740    lines.append("/* Secondary Button */")
741    lines.append(".btn-secondary {")
742    lines.append(f"  background: transparent;")
743    lines.append(f"  color: {colors.get('primary', '#2563EB')};")
744    lines.append(f"  border: 2px solid {colors.get('primary', '#2563EB')};")
745    lines.append("  padding: 12px 24px;")
746    lines.append("  border-radius: 8px;")
747    lines.append("  font-weight: 600;")
748    lines.append("  transition: all 200ms ease;")
749    lines.append("  cursor: pointer;")
750    lines.append("}")
751    lines.append("```")
752    lines.append("")
753    
754    # Cards
755    lines.append("### Cards")
756    lines.append("")
757    lines.append("```css")
758    lines.append(".card {")
759    lines.append(f"  background: {colors.get('background', '#FFFFFF')};")
760    lines.append("  border-radius: 12px;")
761    lines.append("  padding: 24px;")
762    lines.append("  box-shadow: var(--shadow-md);")
763    lines.append("  transition: all 200ms ease;")
764    lines.append("  cursor: pointer;")
765    lines.append("}")
766    lines.append("")
767    lines.append(".card:hover {")
768    lines.append("  box-shadow: var(--shadow-lg);")
769    lines.append("  transform: translateY(-2px);")
770    lines.append("}")
771    lines.append("```")
772    lines.append("")
773    
774    # Inputs
775    lines.append("### Inputs")
776    lines.append("")
777    lines.append("```css")
778    lines.append(".input {")
779    lines.append("  padding: 12px 16px;")
780    lines.append("  border: 1px solid #E2E8F0;")
781    lines.append("  border-radius: 8px;")
782    lines.append("  font-size: 16px;")
783    lines.append("  transition: border-color 200ms ease;")
784    lines.append("}")
785    lines.append("")
786    lines.append(".input:focus {")
787    lines.append(f"  border-color: {colors.get('primary', '#2563EB')};")
788    lines.append("  outline: none;")
789    lines.append(f"  box-shadow: 0 0 0 3px {colors.get('primary', '#2563EB')}20;")
790    lines.append("}")
791    lines.append("```")
792    lines.append("")
793    
794    # Modals
795    lines.append("### Modals")
796    lines.append("")
797    lines.append("```css")
798    lines.append(".modal-overlay {")
799    lines.append("  background: rgba(0, 0, 0, 0.5);")
800    lines.append("  backdrop-filter: blur(4px);")
801    lines.append("}")
802    lines.append("")
803    lines.append(".modal {")
804    lines.append("  background: white;")
805    lines.append("  border-radius: 16px;")
806    lines.append("  padding: 32px;")
807    lines.append("  box-shadow: var(--shadow-xl);")
808    lines.append("  max-width: 500px;")
809    lines.append("  width: 90%;")
810    lines.append("}")
811    lines.append("```")
812    lines.append("")
813    
814    # Style section
815    lines.append("---")
816    lines.append("")
817    lines.append("## Style Guidelines")
818    lines.append("")
819    lines.append(f"**Style:** {style.get('name', 'Minimalism')}")
820    lines.append("")
821    if style.get("keywords"):
822        lines.append(f"**Keywords:** {style.get('keywords', '')}")
823        lines.append("")
824    if style.get("best_for"):
825        lines.append(f"**Best For:** {style.get('best_for', '')}")
826        lines.append("")
827    if effects:
828        lines.append(f"**Key Effects:** {effects}")
829        lines.append("")
830    
831    # Layout Pattern
832    lines.append("### Page Pattern")
833    lines.append("")
834    lines.append(f"**Pattern Name:** {pattern.get('name', '')}")
835    lines.append("")
836    if pattern.get('conversion'):
837        lines.append(f"- **Conversion Strategy:** {pattern.get('conversion', '')}")
838    if pattern.get('cta_placement'):
839        lines.append(f"- **CTA Placement:** {pattern.get('cta_placement', '')}")
840    lines.append(f"- **Section Order:** {pattern.get('sections', '')}")
841    lines.append("")
842    
843    # Anti-Patterns section
844    lines.append("---")
845    lines.append("")
846    lines.append("## Anti-Patterns (Do NOT Use)")
847    lines.append("")
848    if anti_patterns:
849        anti_list = [a.strip() for a in anti_patterns.split("+")]
850        for anti in anti_list:
851            if anti:
852                lines.append(f"- ❌ {anti}")
853    lines.append("")
854    lines.append("### Additional Forbidden Patterns")
855    lines.append("")
856    lines.append("- ❌ **Emojis as icons** — Use SVG icons (Heroicons, Lucide, Simple Icons)")
857    lines.append("- ❌ **Missing cursor:pointer** — All clickable elements must have cursor:pointer")
858    lines.append("- ❌ **Layout-shifting hovers** — Avoid scale transforms that shift layout")
859    lines.append("- ❌ **Low contrast text** — Maintain 4.5:1 minimum contrast ratio")
860    lines.append("- ❌ **Instant state changes** — Always use transitions (150-300ms)")
861    lines.append("- ❌ **Invisible focus states** — Focus states must be visible for a11y")
862    lines.append("")
863    
864    # Pre-Delivery Checklist
865    lines.append("---")
866    lines.append("")
867    lines.append("## Pre-Delivery Checklist")
868    lines.append("")
869    lines.append("Before delivering any UI code, verify:")
870    lines.append("")
871    lines.append("- [ ] No emojis used as icons (use SVG instead)")
872    lines.append("- [ ] All icons from consistent icon set (Heroicons/Lucide)")
873    lines.append("- [ ] `cursor-pointer` on all clickable elements")
874    lines.append("- [ ] Hover states with smooth transitions (150-300ms)")
875    lines.append("- [ ] Light mode: text contrast 4.5:1 minimum")
876    lines.append("- [ ] Focus states visible for keyboard navigation")
877    lines.append("- [ ] `prefers-reduced-motion` respected")
878    lines.append("- [ ] Responsive: 375px, 768px, 1024px, 1440px")
879    lines.append("- [ ] No content hidden behind fixed navbars")
880    lines.append("- [ ] No horizontal scroll on mobile")
881    lines.append("")
882    
883    return "\n".join(lines)
884 
885 
886def format_page_override_md(design_system: dict, page_name: str, page_query: str = None) -> str:
887    """Format a page-specific override file with intelligent AI-generated content."""
888    project = design_system.get("project_name", "PROJECT")
889    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
890    page_title = page_name.replace("-", " ").replace("_", " ").title()
891    
892    # Detect page type and generate intelligent overrides
893    page_overrides = _generate_intelligent_overrides(page_name, page_query, design_system)
894    
895    lines = []
896    
897    lines.append(f"# {page_title} Page Overrides")
898    lines.append("")
899    lines.append(f"> **PROJECT:** {project}")
900    lines.append(f"> **Generated:** {timestamp}")
901    lines.append(f"> **Page Type:** {page_overrides.get('page_type', 'General')}")
902    lines.append("")
903    lines.append("> ⚠️ **IMPORTANT:** Rules in this file **override** the Master file (`design-system/MASTER.md`).")
904    lines.append("> Only deviations from the Master are documented here. For all other rules, refer to the Master.")
905    lines.append("")
906    lines.append("---")
907    lines.append("")
908    
909    # Page-specific rules with actual content
910    lines.append("## Page-Specific Rules")
911    lines.append("")
912    
913    # Layout Overrides
914    lines.append("### Layout Overrides")
915    lines.append("")
916    layout = page_overrides.get("layout", {})
917    if layout:
918        for key, value in layout.items():
919            lines.append(f"- **{key}:** {value}")
920    else:
921        lines.append("- No overrides — use Master layout")
922    lines.append("")
923    
924    # Spacing Overrides
925    lines.append("### Spacing Overrides")
926    lines.append("")
927    spacing = page_overrides.get("spacing", {})
928    if spacing:
929        for key, value in spacing.items():
930            lines.append(f"- **{key}:** {value}")
931    else:
932        lines.append("- No overrides — use Master spacing")
933    lines.append("")
934    
935    # Typography Overrides
936    lines.append("### Typography Overrides")
937    lines.append("")
938    typography = page_overrides.get("typography", {})
939    if typography:
940        for key, value in typography.items():
941            lines.append(f"- **{key}:** {value}")
942    else:
943        lines.append("- No overrides — use Master typography")
944    lines.append("")
945    
946    # Color Overrides
947    lines.append("### Color Overrides")
948    lines.append("")
949    colors = page_overrides.get("colors", {})
950    if colors:
951        for key, value in colors.items():
952            lines.append(f"- **{key}:** {value}")
953    else:
954        lines.append("- No overrides — use Master colors")
955    lines.append("")
956    
957    # Component Overrides
958    lines.append("### Component Overrides")
959    lines.append("")
960    components = page_overrides.get("components", [])
961    if components:
962        for comp in components:
963            lines.append(f"- {comp}")
964    else:
965        lines.append("- No overrides — use Master component specs")
966    lines.append("")
967    
968    # Page-Specific Components
969    lines.append("---")
970    lines.append("")
971    lines.append("## Page-Specific Components")
972    lines.append("")
973    unique_components = page_overrides.get("unique_components", [])
974    if unique_components:
975        for comp in unique_components:
976            lines.append(f"- {comp}")
977    else:
978        lines.append("- No unique components for this page")
979    lines.append("")
980    
981    # Recommendations
982    lines.append("---")
983    lines.append("")
984    lines.append("## Recommendations")
985    lines.append("")
986    recommendations = page_overrides.get("recommendations", [])
987    if recommendations:
988        for rec in recommendations:
989            lines.append(f"- {rec}")
990    lines.append("")
991    
992    return "\n".join(lines)
993 
994 
995def _generate_intelligent_overrides(page_name: str, page_query: str, design_system: dict) -> dict:
996    """
997    Generate intelligent overrides based on page type using layered search.
998    
999    Uses the existing search infrastructure to find relevant style, UX, and layout
1000    data instead of hardcoded page types.
1001    """
1002    from core import search
1003    
1004    page_lower = page_name.lower()
1005    query_lower = (page_query or "").lower()
1006    combined_context = f"{page_lower} {query_lower}"
1007    
1008    # Search across multiple domains for page-specific guidance
1009    style_search = search(combined_context, "style", max_results=1)
1010    ux_search = search(combined_context, "ux", max_results=3)
1011    landing_search = search(combined_context, "landing", max_results=1)
1012    
1013    # Extract results from search response
1014    style_results = style_search.get("results", [])
1015    ux_results = ux_search.get("results", [])
1016    landing_results = landing_search.get("results", [])
1017    
1018    # Detect page type from search results or context
1019    page_type = _detect_page_type(combined_context, style_results)
1020    
1021    # Build overrides from search results
1022    layout = {}
1023    spacing = {}
1024    typography = {}
1025    colors = {}
1026    components = []
1027    unique_components = []
1028    recommendations = []
1029    
1030    # Extract style-based overrides
1031    if style_results:
1032        style = style_results[0]
1033        style_name = style.get("Style Category", "")
1034        keywords = style.get("Keywords", "")
1035        best_for = style.get("Best For", "")
1036        effects = style.get("Effects & Animation", "")
1037        
1038        # Infer layout from style keywords
1039        if any(kw in keywords.lower() for kw in ["data", "dense", "dashboard", "grid"]):
1040            layout["Max Width"] = "1400px or full-width"
1041            layout["Grid"] = "12-column grid for data flexibility"
1042            spacing["Content Density"] = "High — optimize for information display"
1043        elif any(kw in keywords.lower() for kw in ["minimal", "simple", "clean", "single"]):
1044            layout["Max Width"] = "800px (narrow, focused)"
1045            layout["Layout"] = "Single column, centered"
1046            spacing["Content Density"] = "Low — focus on clarity"
1047        else:
1048            layout["Max Width"] = "1200px (standard)"
1049            layout["Layout"] = "Full-width sections, centered content"
1050        
1051        if effects:
1052            recommendations.append(f"Effects: {effects}")
1053    
1054    # Extract UX guidelines as recommendations
1055    for ux in ux_results:
1056        category = ux.get("Category", "")
1057        do_text = ux.get("Do", "")
1058        dont_text = ux.get("Don't", "")
1059        if do_text:
1060            recommendations.append(f"{category}: {do_text}")
1061        if dont_text:
1062            components.append(f"Avoid: {dont_text}")
1063    
1064    # Extract landing pattern info for section structure
1065    if landing_results:
1066        landing = landing_results[0]
1067        sections = landing.get("Section Order", "")
1068        cta_placement = landing.get("Primary CTA Placement", "")
1069        color_strategy = landing.get("Color Strategy", "")
1070        
1071        if sections:
1072            layout["Sections"] = sections
1073        if cta_placement:
1074            recommendations.append(f"CTA Placement: {cta_placement}")
1075        if color_strategy:
1076            colors["Strategy"] = color_strategy
1077    
1078    # Add page-type specific defaults if no search results
1079    if not layout:
1080        layout["Max Width"] = "1200px"
1081        layout["Layout"] = "Responsive grid"
1082    
1083    if not recommendations:
1084        recommendations = [
1085            "Refer to MASTER.md for all design rules",
1086            "Add specific overrides as needed for this page"
1087        ]
1088    
1089    return {
1090        "page_type": page_type,
1091        "layout": layout,
1092        "spacing": spacing,
1093        "typography": typography,
1094        "colors": colors,
1095        "components": components,
1096        "unique_components": unique_components,
1097        "recommendations": recommendations
1098    }
1099 
1100 
1101def _detect_page_type(context: str, style_results: list) -> str:
1102    """Detect page type from context and search results."""
1103    context_lower = context.lower()
1104    
1105    # Check for common page type patterns
1106    page_patterns = [
1107        (["dashboard", "admin", "analytics", "data", "metrics", "stats", "monitor", "overview"], "Dashboard / Data View"),
1108        (["checkout", "payment", "cart", "purchase", "order", "billing"], "Checkout / Payment"),
1109        (["settings", "profile", "account", "preferences", "config"], "Settings / Profile"),
1110        (["landing", "marketing", "homepage", "hero", "home", "promo"], "Landing / Marketing"),
1111        (["login", "signin", "signup", "register", "auth", "password"], "Authentication"),
1112        (["pricing", "plans", "subscription", "tiers", "packages"], "Pricing / Plans"),
1113        (["blog", "article", "post", "news", "content", "story"], "Blog / Article"),
1114        (["product", "item", "detail", "pdp", "shop", "store"], "Product Detail"),
1115        (["search", "results", "browse", "filter", "catalog", "list"], "Search Results"),
1116        (["empty", "404", "error", "not found", "zero"], "Empty State"),
1117    ]
1118    
1119    for keywords, page_type in page_patterns:
1120        if any(kw in context_lower for kw in keywords):
1121            return page_type
1122    
1123    # Fallback: try to infer from style results
1124    if style_results:
1125        style_name = style_results[0].get("Style Category", "").lower()
1126        best_for = style_results[0].get("Best For", "").lower()
1127        
1128        if "dashboard" in best_for or "data" in best_for:
1129            return "Dashboard / Data View"
1130        elif "landing" in best_for or "marketing" in best_for:
1131            return "Landing / Marketing"
1132    
1133    return "General"
1134 
1135 
1136# ============ CLI SUPPORT ============
1137if __name__ == "__main__":
1138    import argparse
1139 
1140    parser = argparse.ArgumentParser(description="Generate Design System")
1141    parser.add_argument("query", help="Search query (e.g., 'SaaS dashboard')")
1142    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name")
1143    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format")
1144 
1145    args = parser.parse_args()
1146 
1147    result = generate_design_system(args.query, args.project_name, args.format)
1148    print(result)
1149