@ranimontagna/agent-toolkit 0.3.5 → 0.3.7

package/skills/frontend/design/ui-ux-pro-max/scripts/reasoning_contract.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Closed, non-executable grammar for design-system decision rules."""
+
+import json
+import re
+
+CONDITION_SIGNALS = {
+    "if_booking": ("booking", "appointment", "calendar"),
+    "if_boutique": ("boutique",),
+    "if_casual": ("casual", "playful"),
+    "if_checkout": ("checkout", "payment", "purchase"),
+    "if_children": ("child", "children", "kids"),
+    "if_collaboration": ("collaboration", "multiplayer", "co-edit"),
+    "if_competitive": ("competitive", "leaderboard"),
+    "if_content_focused": ("content", "article", "reading", "documentation"),
+    "if_conversion_focused": ("conversion", "sales", "signup", "purchase"),
+    "if_creative_field": ("creative", "artist", "portfolio"),
+    "if_crop_focused": ("crop", "farm", "agriculture"),
+    "if_dashboard": ("dashboard", "operations", "monitoring"),
+    "if_data_heavy": ("data heavy", "data-heavy", "analytics", "large dataset"),
+    "if_delivery": ("delivery", "courier", "shipping"),
+    "if_discovery_focused": ("discover", "discovery", "browse", "directory"),
+    "if_engagement_metric": ("engagement", "retention", "contribution"),
+    "if_experience_focused": ("experience", "immersive", "journey"),
+    "if_gamification": ("gamification", "badges", "streak"),
+    "if_health": ("health", "medical", "patient"),
+    "if_hero_needed": ("hero", "showcase", "launch"),
+    "if_large_dataset": ("large dataset", "thousands", "millions"),
+    "if_light_mode_needed": ("light mode", "light theme"),
+    "if_low_performance": ("low performance", "low-end", "slow device"),
+    "if_luxury": ("luxury", "premium", "high-end"),
+    "if_medication": ("medication", "medicine", "prescription"),
+    "if_meditation": ("meditation", "breathing", "mindfulness"),
+    "if_minimal_portfolio": ("minimal portfolio", "simple portfolio"),
+    "if_mobile": ("mobile", "phone", "tablet", "ios", "android"),
+    "if_personalized": ("personalized", "personalised", "recommendation"),
+    "if_pre_launch": ("pre-launch", "prelaunch", "coming soon", "waitlist"),
+    "if_salary_focused": ("salary", "compensation", "pay range"),
+    "if_team_collaboration": ("team collaboration", "team workspace"),
+    "if_trust_needed": ("trust", "secure", "verified", "authority"),
+    "if_ux_focused": ("ux", "usability", "accessibility", "accessible"),
+    "if_video_ready": ("video ready", "product video", "demo video"),
+}
+
+ALLOWED_CONDITIONS = {"must_have", *CONDITION_SIGNALS}
+ACTION_PREFIXES = {"constraint", "style", "pattern", "mode"}
+TOKEN_ACTION_PREFIXES = {"constraint", "style"}
+TOKEN_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+CONDITION_PATTERNS = {
+    condition: tuple(
+        re.compile(r"(?<!\w)" + re.escape(signal) + r"(?!\w)")
+        for signal in signals
+    )
+    for condition, signals in CONDITION_SIGNALS.items()
+}
+
+
+def _object_without_duplicates(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate decision-rule key: {}".format(key))
+        result[key] = value
+    return result
+
+
+def parse_decision_rules(raw):
+    """Parse the canonical condition -> action-array representation."""
+    try:
+        rules = json.loads(raw or "{}", object_pairs_hook=_object_without_duplicates)
+    except json.JSONDecodeError as error:
+        raise ValueError("invalid decision-rule JSON: {}".format(error)) from error
+    if not isinstance(rules, dict):
+        raise ValueError("decision rules must be a JSON object")
+    for condition, actions in rules.items():
+        if condition not in ALLOWED_CONDITIONS:
+            raise ValueError("unknown decision-rule condition: {}".format(condition))
+        if not isinstance(actions, list) or not actions:
+            raise ValueError("{} must map to a non-empty action array".format(condition))
+        for action in actions:
+            _validate_action(action)
+        if len(actions) != len(set(actions)):
+            raise ValueError("{} contains duplicate actions".format(condition))
+    return rules
+
+
+def _validate_action(action):
+    if not isinstance(action, str) or ":" not in action:
+        raise ValueError("action must use a known prefix: {}".format(action))
+    prefix, value = action.split(":", 1)
+    if prefix not in ACTION_PREFIXES:
+        raise ValueError("unknown decision-rule action: {}".format(action))
+    if prefix in TOKEN_ACTION_PREFIXES and not TOKEN_RE.fullmatch(value):
+        raise ValueError("invalid {} action value: {}".format(prefix, value))
+    if prefix == "pattern" and not value.strip():
+        raise ValueError("pattern action must name a pattern")
+    if prefix == "mode" and value not in {"dark", "light"}:
+        raise ValueError("mode action must be dark or light")
+
+
+def apply_decision_rules(rules, query):
+    """Return deterministic mutations and an audit trail; never execute data."""
+    normalized = str(query or "").casefold()
+    result = {"activated": [], "style_ids": [], "constraints": [],
+              "pattern": None, "mode": None}
+    for condition, actions in rules.items():
+        active = condition == "must_have" or any(
+            pattern.search(normalized)
+            for pattern in CONDITION_PATTERNS.get(condition, ()))
+        if not active:
+            continue
+        result["activated"].append({"condition": condition, "actions": list(actions)})
+        for action in actions:
+            prefix, value = action.split(":", 1)
+            if prefix == "style" and value not in result["style_ids"]:
+                result["style_ids"].append(value)
+            elif prefix == "constraint" and value not in result["constraints"]:
+                result["constraints"].append(value)
+            elif prefix == "pattern":
+                result["pattern"] = value
+            elif prefix == "mode":
+                result["mode"] = value
+    return result

package/skills/frontend/design/ui-ux-pro-max/scripts/search.py

@@ -4,21 +4,33 @@
 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"] [--page "dashboard"]
+       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, prompt, color, chart, landing, product, ux, typography, google-fonts
-Stacks: react, nextjs, vue, svelte, astro, swiftui, react-native, flutter, nuxtjs, nuxt-ui, html-tailwind, shadcn, jetpack-compose, threejs
+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/MASTER.md
-  --page       Also create a page-specific override file in design-system/pages/
+  --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, search, search_stack
-from design_system import generate_design_system, persist_design_system
+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':
@@ -26,27 +38,55 @@ if sys.stdout.encoding and sys.stdout.encoding.lower() != '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):
+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(f"## UI Pro Max Stack Guidelines")
+        output.append("## UI Pro Max Stack Guidelines")
         output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
     else:
-        output.append(f"## UI Pro Max Search Results")
-        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+        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:
+        redirect = result.get("redirect")
+        if redirect:
+            output.append(
+                "This legacy style label is now modeled in the "
+                f"`{redirect['domain']}` domain as `{redirect['id']}`. "
+                "Search that domain instead of treating a page composition as a visual style."
+            )
+            return "\n".join(output)
+        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 len(value_str) > 300:
-                value_str = value_str[:300] + "..."
+            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("")
 
@@ -58,57 +98,80 @@ if __name__ == "__main__":
     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("--max-results", "-n", type=int, choices=range(1, 21), default=MAX_RESULTS,
+                        metavar="1-20", 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")
+    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/MASTER.md (creates hierarchical structure)")
-    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
-    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+    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:
+        if args.stack:
+            print(
+                f"note: --stack {args.stack} is ignored in --design-system mode; "
+                "run a separate --stack query for stack-specific guidelines",
+                file=sys.stderr,
+            )
         result = generate_design_system(
-            args.query, 
-            args.project_name, 
+            args.query,
+            args.project_name,
             args.format,
             persist=args.persist,
             page=args.page,
-            output_dir=args.output_dir
+            output_dir=args.output_dir,
+            variance=args.variance,
+            motion=args.motion,
+            density=args.density,
+            force=args.force,
         )
-        print(result)
-        
-        # Print persistence confirmation
-        if args.persist:
-            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
-            print("\n" + "=" * 60)
-            print(f"✅ Design system persisted to design-system/{project_slug}/")
-            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
-            if args.page:
-                page_filename = args.page.lower().replace(' ', '-')
-                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
-            print("")
-            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
-            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
-            print("=" * 60)
+
+        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:
-            import json
-            print(json.dumps(result, indent=2, ensure_ascii=False))
+            print(json_module.dumps(result, indent=2, ensure_ascii=False))
         else:
-            print(format_output(result))
+            print(format_output(result, full=args.full))
     # Domain search
     else:
         result = search(args.query, args.domain, args.max_results)
         if args.json:
-            import json
-            print(json.dumps(result, indent=2, ensure_ascii=False))
+            print(json_module.dumps(result, indent=2, ensure_ascii=False))
         else:
-            print(format_output(result))
+            print(format_output(result, full=args.full))