agy-superpowers 5.1.1 → 5.1.3

package/template/agent/.tests/mobile-uiux-promax/test_search.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""
+Comprehensive test suite for mobile-search.py
+Tests all 9 domains, 4 stacks, edge cases, and data integrity.
+"""
+import subprocess
+import sys
+import csv
+from pathlib import Path
+
+# Project root: 3 levels up (.agent/.tests/<skill>/test_*.py → project root)
+BASE = str(Path(__file__).resolve().parents[3])
+SCRIPT = f"{BASE}/.agent/.shared/mobile-uiux-promax/scripts/mobile-search.py"
+DATA_DIR = f"{BASE}/.agent/.shared/mobile-uiux-promax/data"
+
+passed = []
+failed = []
+
+
+def run(query, flag, target, n=3):
+    return subprocess.run(
+        ["python3", SCRIPT, query, flag, target, "-n", str(n)],
+        capture_output=True, text=True, cwd=BASE
+    )
+
+
+def check(label, output, expected_kw, returncode=0):
+    ok_code = (output.returncode == returncode)
+    all_output = output.stdout + output.stderr
+    ok_kw = expected_kw.lower() in all_output.lower() if expected_kw else True
+    ok = ok_code and ok_kw
+    if ok:
+        passed.append(label)
+        print(f"  ✅ {label}")
+    else:
+        failed.append(label)
+        reasons = []
+        if not ok_code:
+            reasons.append(f"returncode={output.returncode} (expected {returncode})")
+        if not ok_kw:
+            reasons.append(f"keyword '{expected_kw}' not found")
+        print(f"  ❌ {label}")
+        for r in reasons:
+            print(f"     → {r}")
+        print(f"     → stdout[:300]: {output.stdout[:300]!r}")
+
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 1: Navigation domain
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 1: Navigation domain")
+check("tab bar primary sections",    run("bottom tab bar primary sections", "--domain", "navigation"), "Tab Bar")
+check("hamburger discoverability",   run("hamburger hidden navigation discoverability", "--domain", "navigation"), "discoverability")
+check("thumb zone ergonomics",       run("thumb zone one handed ergonomics bottom", "--domain", "navigation"), "Thumb")
+check("drawer sidebar menu",         run("drawer sidebar menu hamburger secondary", "--domain", "navigation"), "Drawer")
+check("modal full screen overlay",   run("modal full screen immersive camera auth", "--domain", "navigation"), "Modal")
+check("bottom sheet partial",        run("bottom sheet action partial overlay", "--domain", "navigation"), "Bottom Sheet")
+check("deep link universal",         run("deep link universal link routing url", "--domain", "navigation"), "Deep Link")
+check("back navigation ios swipe",   run("back navigation ios swipe gesture return", "--domain", "navigation"), "Back")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 2: Gestures domain
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 2: Gestures domain")
+check("swipe back ios edge",         run("swipe back dismiss ios edge left", "--domain", "gestures"), "Swipe")
+check("pinch zoom two finger",       run("pinch zoom scale two finger gesture", "--domain", "gestures"), "Pinch")
+check("long press context menu",     run("long press hold context menu action", "--domain", "gestures"), "Long")
+check("pull to refresh scroll",      run("pull to refresh scroll top reload", "--domain", "gestures"), "Pull")
+check("double tap zoom toggle",      run("double tap zoom toggle like", "--domain", "gestures"), "Double")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 3: Components domain
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 3: Components domain")
+check("bottom sheet component",      run("bottom sheet modal partial screen", "--domain", "components"), "Bottom Sheet")
+check("FAB floating action button",  run("floating action button primary create", "--domain", "components"), "FAB")
+check("skeleton loading shimmer",    run("skeleton loading placeholder shimmer", "--domain", "components"), "Skeleton")
+check("snackbar toast feedback",     run("snackbar toast feedback notification", "--domain", "components"), "Snackbar")
+check("chip filter tag",             run("chip filter tag selection category", "--domain", "components"), "Chip")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 4: Layout domain
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 4: Layout domain")
+check("safe area notch inset",       run("safe area notch inset dynamic island", "--domain", "layout"), "Safe Area")
+check("touch target 44pt 48dp",     run("touch target minimum size 44pt 48dp", "--domain", "layout"), "44")
+check("thumb zone bottom reach",     run("thumb zone reachability bottom reach", "--domain", "layout"), "Thumb")
+check("keyboard avoidance input",    run("keyboard avoidance input scroll TextField", "--domain", "layout"), "Keyboard")
+check("spacing design system 8pt",  run("spacing 8pt grid system padding margin", "--domain", "layout"), "8")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 5: Platform domain
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 5: Platform domain")
+check("dark mode system appearance", run("dark mode night system appearance adaptive", "--domain", "platform"), "Dark Mode")
+check("haptic feedback vibration",   run("haptic feedback vibration taptic engine", "--domain", "platform"), "Haptic")
+check("typography font system",      run("typography font ios android system native", "--domain", "platform"), "Typography")
+check("navigation ios android diff", run("navigation back button ios android differ", "--domain", "platform"), "Navigation")
+check("status bar appearance",       run("status bar color tint appearance", "--domain", "platform"), "Status Bar")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 6: Onboarding domain
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 6: Onboarding domain")
+check("permission priming camera",   run("permission priming rationale camera notification", "--domain", "onboarding"), "Permission")
+check("paywall timing subscription", run("paywall timing subscription trial premium", "--domain", "onboarding"), "Paywall")
+check("sign in apple social",        run("sign in with apple social login auth", "--domain", "onboarding"), "Sign in with Apple")
+check("value proposition screen",    run("value proposition benefit feature showcase", "--domain", "onboarding"), "Value")
+check("progress step indicator",     run("onboarding step indicator progress multi", "--domain", "onboarding"), "Step")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 7: Animation domain
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 7: Animation domain")
+check("spring animation modal",      run("spring animation modal sheet natural", "--domain", "animation"), "Spring")
+check("skeleton shimmer loading",    run("skeleton shimmer loading placeholder animation", "--domain", "animation"), "Shimmer")
+check("reduce motion accessibility", run("reduce motion accessibility preference disable", "--domain", "animation"), "Reduce")
+check("page transition navigation",  run("page transition navigation push slide", "--domain", "animation"), "Transition")
+check("haptic sync animation",       run("haptic feedback sync animation success", "--domain", "animation"), "Haptic")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 8: Accessibility domain
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 8: Accessibility domain")
+check("touch target 44pt minimum",   run("touch target size minimum 44pt", "--domain", "accessibility"), "Touch Target")
+check("screen reader label name",    run("screen reader voiceover label accessible name", "--domain", "accessibility"), "Screen Reader")
+check("view-tap asymmetry small",    run("view tap asymmetry visible untappable small dot", "--domain", "accessibility"), "Asymmetry")
+check("color contrast ratio 4.5:1",  run("color contrast ratio 4.5 text background", "--domain", "accessibility"), "Contrast")
+check("dynamic type font scaling",   run("dynamic type font scaling text size large", "--domain", "accessibility"), "Dynamic Type")
+check("NNGroup 1cm physical touch",  run("NNGroup physical 1cm touch target research", "--domain", "accessibility"), "NNGroup")
+check("coach mark single tip",       run("coach mark single tip one at a time overlay", "--domain", "accessibility"), "Coach Mark")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 9: UX Laws domain
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 9: UX Laws domain")
+check("Fitts touch target size",     run("touch target size placement distance primary", "--domain", "ux-laws"), "Fitts")
+check("Hick choices decision time",  run("choices menu options decision time complexity", "--domain", "ux-laws"), "Hick")
+check("Jakob mental model familiar", run("mental model convention familiar platform", "--domain", "ux-laws"), "Jakob")
+check("Goal-Gradient progress bar",  run("progress steps completion motivation reward", "--domain", "ux-laws"), "Goal-Gradient")
+check("Peak-End memorable delight",  run("memorable experience delight success moment", "--domain", "ux-laws"), "Peak")
+check("Doherty 400ms threshold",     run("400ms response time loading feedback threshold", "--domain", "ux-laws"), "Doherty")
+check("Miller 7 items memory",       run("7 chunks working memory cognitive load limit", "--domain", "ux-laws"), "Miller")
+check("Zeigarnik streak incomplete", run("streak incomplete task engagement retention", "--domain", "ux-laws"), "Zeigarnik")
+check("Von Restorff standout color", run("standout highlight color accent primary call", "--domain", "ux-laws"), "Von Restorff")
+check("Serial Position first last",  run("first last item serial position memory recall", "--domain", "ux-laws"), "Serial Position")
+check("Proximity grouping related",  run("proximity grouping related elements spacing", "--domain", "ux-laws"), "Proximity")
+check("Common Region card container",run("card container region visual grouping border", "--domain", "ux-laws"), "Common Region")
+check("Paradox coach mark tutorial", run("tutorial coach mark skip learn by doing", "--domain", "ux-laws"), "Paradox")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 10: Stack — React Native
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 10: Stack — React Native")
+check("FlatList performance",        run("FlatList list performance rendering key", "--stack", "react-native"), "FlatList")
+check("Reanimated animations",       run("Reanimated animation gesture performant", "--stack", "react-native"), "Reanimated")
+check("accessibilityLabel VoiceOver",run("accessibilityLabel accessible name VoiceOver", "--stack", "react-native"), "accessibilityLabel")
+check("Metro bundler fast refresh",  run("Metro bundler fast refresh hot reload", "--stack", "react-native"), "Metro")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 11: Stack — Flutter
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 11: Stack — Flutter")
+check("GoRouter navigation",         run("GoRouter routing navigation deep link", "--stack", "flutter"), "GoRouter")
+check("ListView.builder lazy",       run("ListView builder lazy performance list", "--stack", "flutter"), "ListView")
+check("Riverpod state management",   run("Riverpod state management provider", "--stack", "flutter"), "Riverpod")
+check("MediaQuery safe area",        run("MediaQuery safe area padding inset", "--stack", "flutter"), "MediaQuery")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 12: Stack — SwiftUI
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 12: Stack — SwiftUI")
+check("NavigationStack push view",   run("NavigationStack navigation push screen iOS", "--stack", "swiftui"), "NavigationStack")
+check("@StateObject ViewModel",      run("StateObject ViewModel lifecycle init", "--stack", "swiftui"), "StateObject")
+check("reduce motion isReduceMotion",run("reduce motion isReduceMotionEnabled animation", "--stack", "swiftui"), "reduceMotion")
+check("task modifier async load",    run("task async await data loading onAppear", "--stack", "swiftui"), "task")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 13: Stack — Jetpack Compose
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 13: Stack — Jetpack Compose")
+check("LazyColumn list performance", run("LazyColumn list performance lazy scroll", "--stack", "jetpack-compose"), "LazyColumn")
+check("sealed UiState data class",   run("sealed class UiState loading error success", "--stack", "jetpack-compose"), "sealed")
+check("WindowInsets edge-to-edge",   run("WindowInsets edge to edge insets system bar", "--stack", "jetpack-compose"), "WindowInsets")
+check("remember derivedStateOf",     run("remember derivedStateOf state performance recomposition", "--stack", "jetpack-compose"), "derivedStateOf")
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 14: Edge Cases
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 14: Edge Cases")
+
+# -n flag returns correct count
+r = run("navigation tab bottom bar", "--domain", "navigation", n=5)
+count = r.stdout.count("### Result")
+ok = count == 5
+(passed if ok else failed).append("navigation: -n 5 returns 5 results")
+print(f"  {'✅' if ok else '❌'} -n 5 flag returns 5 results (got {count})")
+
+# invalid domain → non-zero exit
+r_bad = subprocess.run(["python3", SCRIPT, "test", "--domain", "foobar"],
+                       capture_output=True, text=True, cwd=BASE)
+check("invalid domain → error exit",  r_bad, None, returncode=2)
+
+# invalid stack → non-zero exit
+r_bad2 = subprocess.run(["python3", SCRIPT, "test", "--stack", "xamarin"],
+                        capture_output=True, text=True, cwd=BASE)
+check("invalid stack → error exit",   r_bad2, None, returncode=2)
+
+# no flag → non-zero exit
+r_bad3 = subprocess.run(["python3", SCRIPT, "hello"],
+                         capture_output=True, text=True, cwd=BASE)
+check("no --domain/--stack → error",  r_bad3, None, returncode=2)
+
+# zero results for nonsense query → "No results" message
+r_zero = run("xyzxyzxyz_gibberish_asdfqwer", "--domain", "navigation")
+check("gibberish query → no crash",  r_zero, "results", returncode=0)
+
+# ═══════════════════════════════════════════════════════════
+# GROUP 15: Data Integrity
+# ═══════════════════════════════════════════════════════════
+print("\n📍 GROUP 15: Data Integrity (row counts)")
+
+expected_min_rows = {
+    "navigation.csv":             20,
+    "gestures.csv":               20,
+    "components.csv":             15,
+    "layout.csv":                 15,
+    "platform.csv":               15,
+    "onboarding.csv":             12,
+    "animation.csv":              15,
+    "accessibility.csv":          20,
+    "ux-laws.csv":                12,
+    "stacks/react-native.csv":    15,
+    "stacks/flutter.csv":         15,
+    "stacks/swiftui.csv":         14,
+    "stacks/jetpack-compose.csv": 14,
+}
+
+for fname, min_rows in expected_min_rows.items():
+    fpath = Path(DATA_DIR) / fname
+    if not fpath.exists():
+        failed.append(f"file exists: {fname}")
+        print(f"  ❌ file exists: {fname} → FILE MISSING")
+        continue
+    with open(fpath, encoding="utf-8") as f:
+        rows = list(csv.reader(f))
+    data_rows = len(rows) - 1  # minus header
+    ok = data_rows >= min_rows
+    (passed if ok else failed).append(f"row count: {fname}")
+    print(f"  {'✅' if ok else '❌'} {fname}: {data_rows} rows (min {min_rows})")
+
+# ═══════════════════════════════════════════════════════════
+# FINAL REPORT
+# ═══════════════════════════════════════════════════════════
+total = len(passed) + len(failed)
+pct = int(100 * len(passed) / total) if total else 0
+print(f"\n{'═'*55}")
+print(f"  TOTAL TESTS : {total}")
+print(f"  PASSED      : {len(passed)}  ({pct}%)")
+print(f"  FAILED      : {len(failed)}")
+if failed:
+    print(f"\n  ❌ FAILED TESTS:")
+    for f in failed:
+        print(f"     - {f}")
+print(f"{'═'*55}")
+sys.exit(0 if not failed else 1)

package/template/agent/.tests/run_tests.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+.agent/.tests/run_tests.py
+Auto-discover and run all test_*.py files for a given skill.
+
+Usage:
+  python3 .agent/.tests/run_tests.py mobile-uiux-promax
+  python3 .agent/.tests/run_tests.py --all
+"""
+import sys
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent  # .agent/.tests/
+
+
+def run_suite(skill_name: str) -> tuple[int, int]:
+    """Run all test_*.py in .agent/.tests/<skill_name>/. Returns (passed_files, failed_files)."""
+    suite_dir = ROOT / skill_name
+    if not suite_dir.exists():
+        print(f"  ⚠️  No test suite found for '{skill_name}' at {suite_dir}")
+        return 0, 0
+
+    test_files = sorted(suite_dir.glob("test_*.py"))
+    if not test_files:
+        print(f"  ⚠️  No test_*.py files found in {suite_dir}")
+        return 0, 0
+
+    passed_files = 0
+    failed_files = 0
+
+    for tf in test_files:
+        print(f"   → {tf.name}")
+        result = subprocess.run(
+            ["python3", str(tf)],
+            capture_output=False,   # let output stream directly (verbose)
+            cwd=str(ROOT.parent.parent),  # project root
+        )
+        if result.returncode == 0:
+            passed_files += 1
+        else:
+            failed_files += 1
+
+    return passed_files, failed_files
+
+
+def main():
+    args = sys.argv[1:]
+
+    if not args:
+        print("Usage: python3 run_tests.py <skill-name>  OR  --all")
+        sys.exit(1)
+
+    if args[0] == "--all":
+        skills = [d.name for d in ROOT.iterdir() if d.is_dir() and not d.name.startswith(".")]
+        if not skills:
+            print("No test suites found.")
+            sys.exit(0)
+    else:
+        skills = [args[0]]
+
+    total_passed = total_failed = 0
+
+    for skill in skills:
+        print(f"\n🧪 Running tests for: {skill}")
+        p, f = run_suite(skill)
+        total_passed += p
+        total_failed += f
+
+    total = total_passed + total_failed
+    if total == 0:
+        print("\nNo test files executed.")
+        sys.exit(0)
+
+    print(f"\n{'═' * 55}")
+    if total_failed == 0:
+        print(f"  ✅ ALL SUITES PASSED ({total_passed}/{total} files)")
+    else:
+        print(f"  ❌ {total_failed} SUITE(S) FAILED ({total_passed}/{total} files passed)")
+    print(f"{'═' * 55}")
+
+    sys.exit(0 if total_failed == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()

package/template/agent/patches/skills-patches.md

@@ -72,3 +72,23 @@ inline comments). The code should work without platform-specific annotations.
 - If `auto_commit: false`: skip commit and staging entirely. Print: "Skipping commit (auto_commit: false in .agent/config.yml). Files left as modified for manual commit."
 Update any diagram labels that mention "commits" to reflect this conditionality
 (e.g. "commits (if auto_commit: true)").
+
+---
+
+## Patch: auto_commit flag — writing-plans task template
+
+**File:** `writing-plans/SKILL.md`
+**Intent:** Make the commit step in the plan task template conditional on `.agent/config.yml`:
+- Step 5 should be titled "Commit (if auto_commit enabled)" instead of just "Commit"
+- Before the `git add`/`git commit` block, add: Check `.agent/config.yml` for `auto_commit` setting
+- If `auto_commit: true` (default): run the git add + git commit as normal
+- If `auto_commit: false`: skip commit and staging. Print: "Skipping commit (auto_commit: false)."
+
+---
+
+## Patch: auto_commit flag — implementer-prompt
+
+**File:** `subagent-driven-development/implementer-prompt.md`
+**Intent:** Make the "Commit your work" step in the implementer's job list conditional:
+- Change "4. Commit your work" to "4. Commit your work (if auto_commit is enabled)"
+- Add sub-steps: read `.agent/config.yml`, if `auto_commit: true` (or not set): `git add` + `git commit`, if `auto_commit: false`: skip commit and staging entirely, print skip message.

package/template/agent/skills/brainstorming/SKILL.md

@@ -25,6 +25,7 @@ You MUST create a task for each of these items and complete them in order:
 2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
 4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+   - *UI/visual tasks only:* Before proposing, run `search.py` to gather style, typography, color, and UX data so proposals are grounded in real design patterns. See the [UI/UX Intelligence](#uiux-intelligence) section below.
 5. **Present design** — in sections scaled to their complexity, get user approval after each section
 6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
 7. **Spec review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 3 iterations, then surface to human)
@@ -86,6 +87,62 @@ digraph brainstorming {
 - Present options conversationally with your recommendation and reasoning
 - Lead with your recommended option and explain why
 
+## UI/UX Intelligence
+
+**When the task involves any visual/UI work** (landing pages, dashboards, components, screens, design systems), run the UI/UX Pro Max search tool **before** presenting the design. This grounds your proposals in a curated knowledge base rather than generic defaults.
+
+**How to trigger:**
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain>
+```
+
+**Recommended search sequence** (run in parallel where possible):
+
+| # | Domain | What to search | Example |
+|---|--------|----------------|---------|
+| 1 | `product` | Product type + industry | `"SaaS dashboard"`, `"beauty landing page"` |
+| 2 | `style` | Desired visual style | `"glassmorphism dark"`, `"minimal clean"` |
+| 3 | `typography` | Mood/personality | `"elegant modern"`, `"playful friendly"` |
+| 4 | `color` | Industry or product type | `"fintech"`, `"healthcare"`, `"beauty spa"` |
+| 5 | `landing` | Page structure type | `"hero-centric social-proof"` |
+| 6 | `ux` | `"animation"`, `"accessibility"`, `"z-index"` | Always check these three |
+| 7 | `stack` | Target framework | `--stack react-native`, `--stack flutter` |
+
+**When to use each domain:**
+- Always run `product` + `style` + `ux` as a baseline for any UI task
+- Add `typography` + `color` when presenting a full design system
+- Add `landing` only for marketing/landing pages
+- Add `chart` only for analytics dashboards
+- Use `--stack` flag to get implementation-specific patterns (e.g., `--stack react-native` for mobile)
+
+**Synthesize results before presenting design:** Do not dump raw search output to the user. Summarize what you found and explain how it informs your design choices.
+
+> **Skip this step** for purely backend, data-model, or logic-only tasks where no UI is involved.
+
+### Mobile UI/UX Intelligence (Extended Layer)
+
+**When the request is for a mobile app** — detect keywords like: `iOS`, `Android`, `React Native`, `Flutter`, `SwiftUI`, `Jetpack Compose`, `mobile`, `app screen`, `native app` — run the **mobile-uiux-promax workflow** IN ADDITION to the web tool above.
+
+Read the workflow file first: `.agent/workflows/mobile-uiux-promax.md`
+
+The mobile workflow adds 3 more steps after the web style layer:
+
+```bash
+# Step 2: Mobile behavior
+python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<nav pattern>" --domain navigation
+python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<component>" --domain components
+python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<platform topic>" --domain platform
+python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<animation>" --domain animation
+
+# Step 3: Stack guidelines (react-native / flutter / swiftui / jetpack-compose)
+python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<topic>" --stack react-native
+
+# Step 4: Synthesize style + mobile behavior + stack patterns → present design
+```
+
+Read and apply the mobile-uiux-promax skill: `.agent/skills/mobile-uiux-promax/SKILL.md`
+
 **Presenting the design:**
 
 - Once you believe you understand what you're building, present the design

package/template/agent/skills/frontend-design/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: frontend-design
+description: Use when building web components, pages, artifacts, or applications — especially when high design quality is needed. Generates creative, polished code that avoids generic AI aesthetics (purple gradients, Inter font, card-in-card layouts).
+---
+
+# Frontend Design
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+## Context Gathering Protocol
+
+Design skills produce generic output without project context. Before doing any design work, confirm:
+
+- **Target audience**: Who uses this product and in what context?
+- **Use cases**: What jobs are they trying to get done?
+- **Brand personality/tone**: How should the interface feel?
+
+**Gathering order:**
+1. **Check current instructions**: If your loaded instructions contain a Design Context section, proceed immediately.
+2. **Check `.impeccable.md`**: If it exists in the project root and has context, use it.
+3. **Ask the user**: If neither source has context, ask these 3 questions before proceeding.
+
+---
+
+## Design Direction
+
+Commit to a **BOLD** aesthetic direction before writing any code:
+
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme — brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing users remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute with precision. Bold maximalism and refined minimalism both work — the key is **intentionality**, not intensity.
+
+Implement working code that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+---
+
+## Frontend Aesthetics Guidelines
+
+### Typography
+→ *See [typography reference](reference/typography.md) for scales, pairing, and loading strategies.*
+
+Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font.
+
+**DO**: Use a modular type scale with fluid sizing (`clamp()`)
+**DO**: Vary font weights and sizes to create clear visual hierarchy
+**DON'T**: Use overused fonts — Inter, Roboto, Arial, Open Sans, system defaults
+**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes
+**DON'T**: Put large icons with rounded corners above every heading
+
+### Color & Theme
+→ *See [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.*
+
+**DO**: Use modern CSS color functions (`oklch`, `color-mix`, `light-dark()`) for perceptually uniform palettes
+**DO**: Tint your neutrals toward your brand hue
+**DON'T**: Use gray text on colored backgrounds — looks washed out; use a shade of the bg color instead
+**DON'T**: Use pure black (`#000`) or pure white (`#fff`) — always tint
+**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon on dark
+**DON'T**: Use gradient text for "impact" on metrics or headings
+**DON'T**: Default to dark mode with glowing accents without real design decisions
+
+### Layout & Space
+→ *See [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.*
+
+**DO**: Create visual rhythm through varied spacing — tight groupings, generous separations
+**DO**: Use fluid spacing with `clamp()` that breathes on larger screens
+**DO**: Use asymmetry and unexpected compositions; break the grid intentionally
+**DON'T**: Wrap everything in cards — not everything needs a container
+**DON'T**: Nest cards inside cards — visual noise
+**DON'T**: Use identical card grids (same-sized card with icon + heading + text, repeated)
+**DON'T**: Center everything — left-aligned text with asymmetric layouts feels more designed
+**DON'T**: Use the same spacing everywhere
+
+### Visual Details
+**DO**: Use intentional, purposeful decorative elements that reinforce brand
+**DON'T**: Use glassmorphism everywhere — blur/glass/glow as decoration rather than purpose
+**DON'T**: Use rounded rectangles with generic drop shadows — forgettable
+**DON'T**: Use sparklines as decoration
+**DON'T**: Use modals unless there's truly no better alternative
+
+### Motion
+→ *See [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.*
+
+**DO**: Use motion to convey state changes — entrances, exits, feedback
+**DO**: Use exponential easing (`ease-out-quart/quint/expo`) for natural deceleration
+**DO**: For height animations, use `grid-template-rows` transitions instead of animating `height`
+**DON'T**: Animate layout properties (width, height, padding, margin) — use `transform` and `opacity` only
+**DON'T**: Use bounce or elastic easing — dated and tacky
+
+### Interaction
+→ *See [interaction reference](reference/interaction-design.md) for forms, focus, loading patterns.*
+
+**DO**: Use progressive disclosure — start simple, reveal sophistication through interaction
+**DO**: Design empty states that teach the interface, not just say "nothing here"
+**DON'T**: Make every button primary — use ghost buttons, text links, secondary styles
+**DON'T**: Repeat the same information redundantly
+
+### Responsive
+→ *See [responsive reference](reference/responsive-design.md) for mobile-first, fluid design.*
+
+**DO**: Use container queries (`@container`) for component-level responsiveness
+**DO**: Adapt the interface for different contexts — don't just shrink it
+**DON'T**: Hide critical functionality on mobile
+
+### UX Writing
+→ *See [UX writing reference](reference/ux-writing.md) for labels, errors, and empty states.*
+
+**DO**: Make every word earn its place
+**DON'T**: Repeat information users can already see
+
+---
+
+## The AI Slop Test
+
+**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
+
+A distinctive interface should make someone ask "how was this made?" not "which AI made this?"
+
+Review the DON'T guidelines above — they are the fingerprints of AI-generated work from 2024-2025.
+
+---
+
+## Implementation Principles
+
+Match implementation complexity to the aesthetic vision:
+- **Maximalist designs** → elaborate code, extensive animations, rich effects
+- **Minimalist designs** → restraint, precision, careful spacing, subtle details
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. **No design should be the same.** Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations.
+
+---
+
+## Quick Reference: What to Avoid
+
+| Category | DON'T |
+|----------|-------|
+| **Fonts** | Inter, Roboto, Arial, Open Sans |
+| **Colors** | Pure black/white, purple gradients, gray on color |
+| **Layout** | Cards in cards, centered everything, identical grids |
+| **Motion** | Bounce/elastic easing, animating height/width |
+| **Visual** | Glassmorphism everywhere, gradient text, generic shadows |
+| **Writing** | "OK", "Submit", redundant copy, vague errors |