| name | ui-ux-optimize |
| description | Swarm-powered UI/UX prompt optimizer with auto-research agents, handoff coordination, confidence-scored autoresearch loops, and backpressure quality gates. Use for web apps, mobile apps, games, dashboards, SaaS, e-commerce, kiosks, and any screen-based product.
|
UI/UX Prompt Optimizer
Swarm-powered skill for generating implementation-ready UI/UX prompts. Uses a swarm of 7 specialized agents with handoff coordination, an autoresearch loop (try → score → keep/revert → repeat), and backpressure quality gates to converge on high-quality output.
When to Use
- UI/UX design help, redesign, or critique for any digital product
- Prompt optimization for a design or coding agent
- A structured design brief from a vague idea
- A design audit of an existing interface
- Variant generation for a design system or component
Supported: web apps, mobile apps, dashboards, admin tools, e-commerce, SaaS, web/mobile games, kiosk/touch UIs, internal tools, prototypes.
When NOT to Use
- Pure branding (logos, print, identity only)
- Motion graphics or video production
- Backend architecture with no UI component
- Marketing copy without interface context
- Already implementation-ready requests
Swarm Architecture
7 specialized agents with handoff coordination. Full details → references/swarm-coordination.md
RESEARCH SCOUT → TOKEN ARCHITECT → LAYOUT ENGINEER → VARIANT GENERATOR → BROWSER VERIFIER → QUALITY AUDITOR
└── ANTI-SLOP SENTINEL (cross-cutting) ──┘
| Agent | Domain |
|---|
| Research Scout | Domain trends, platform guidelines, competitor analysis |
| Token Architect | Semantic design tokens, typography, color, spacing |
| Layout Engineer | Navigation, screen hierarchy, responsive composition |
| Variant Generator | 3 design variants with shared tokens + override diffs |
| Browser Verifier | Playwright screenshots, overlap detection, tap targets |
| Quality Auditor | Review checklist scoring, confidence, lessons |
| Anti-Slop Sentinel | Cross-cutting: translates vague language, detects AI patterns |
Autoresearch Loop
Inspired by pi-autoresearch: try → measure → keep/revert → repeat until score stabilizes.
- Run full swarm pipeline
- Quality Auditor scores with confidence (MAD-based)
- Game products: 0–66 (all 10 sections), threshold 60
- Non-game products: 0–57 (9 sections, game-specific N/A), threshold 52
- Use effective percentage (score/max_applicable) for keep decision
- Effective ≥ 91% AND confidence ≥ 2.0× → KEEP
- Effective < 91% OR confidence < 1.0× → REVISE (re-run weak agent downstream)
- Score regresses → REVERT (discard, try different approach)
- Max 5 iterations per session
Full details → references/swarm-coordination.md
Session Files
Two files persist across runs (matching pi-autoresearch pattern):
ui-ux-session.md — living document: objective, what's been tried, key wins, dead endsui-ux-session.jsonl — append-only log: one JSON line per iteration
Gotchas
These failure modes recur across sessions. Keep as quick-reference.
- AI Slop gravity: Agents default to Inter, purple gradients, three-column feature grids. Override explicitly with opinionated font choices and precedent products.
- Mobile horizontal overflow: Horizontal nav/lists break on mobile <768px. Always enforce
overflow-x-auto for horizontal navigation, overflow-x-hidden on root container.
- Z-Index wars: Absolute positioning for core layout causes overlapping elements. Enforce flow-based layouts (Flexbox/Grid). Absolute only for HUDs/overlays with defined safe zones.
- Flickering transitions: State transitions without presence guards flicker. Use
AnimatePresence with mode="wait" and initial={false}. High-motion elements need will-change-transform transform-gpu backface-visibility-hidden.
- Scrollbar jitter: Unstable scrollbars cause layout shifts between viewports. Enforce
overflow-x-hidden on root, overflow-y-auto for content containers.
- Nested scroll contexts:
min-h-screen in sub-components inside scrollable parents creates double scrollbars. Use min-h-full for sub-components.
Required Workflow
Run every step. Swarm coordinates handoffs.
Phase 1: Research & Translate
Step 0 — Research Scout: Auto-Research. Research domain trends, platform guidelines, competitor patterns via websearch. Handoff → research_context. See → references/auto-research.md
Step 1 — Anti-Slop Sentinel: Translate. Convert vague words to measurable constraints. Cross-ref anti-ai-slop skill. Handoff → anti_slop_warnings. See → references/anti-slop-rules.md
Phase 2: Token & Structure
Step 2 — Token Architect: Build Tokens. Semantic token system from research + translated language. Handoff → design_tokens. See → references/design-tokens.md
Step 3 — Layout Engineer: Navigation & Composition. Nav model, screen map, responsive spec. See → references/navigation-clarity.md, references/layout-composition.md
Step 3a — Game Layer (skip if not game). HUD, menus, safe zones. See → references/game-ui-rules.md
Phase 3: Generate & Verify
Step 4 — Coordinator: Assemble Prompt. See → templates/optimize-prompt-template.md
Step 5 — Variant Generator: 3 Variants. Default: editorial/product/expressive. Game: immersive/competitive/minimal-hud. See → references/variant-worktree-flow.md
Step 6 — Layout Engineer: Safety Audit. Overlap, wrapping, truncation at all breakpoints. Fill templates/design-audit-template.md.
Step 6a — Token Validation (pre-check). Run node .agents/skills/ui-ux-optimize/scripts/validate-tokens.cjs to fast-fail if design docs or TOKENS export are missing. Fix before browser verification.
Step 6b — Browser Verifier: Screenshots (when HTML available). Playwright at 375/768/1024/1440px. If no HTML prototype exists, SKIP with a browser_verification.status: "SKIPPED" note describing what would be verified. See → references/browser-verification.md
Phase 4: Audit & Learn
Step 7 — Anti-Slop Sentinel: Final Audit. No banned words remain.
Step 8 — Quality Auditor: Score & Gate. Score against checklist (0–66). See → references/review-checklist.md
Step 9 — Quality Auditor: Record Lessons. Append to session files. See → references/self-learning-loop.md
Required Outputs
| Field | Content |
|---|
research_context | Domain trends, platform guidelines, competitor patterns |
optimized_prompt | Full implementation-ready prompt |
design_tokens_summary | Token architecture with semantic roles |
product_ui_mode | Classified interface model |
navigation_model | Navigation type and screen hierarchy |
screen_or_state_map | All key screens or states |
responsive_behavior_summary | Per-breakpoint layout behavior |
anti_slop_warnings | What was removed or translated |
layout_risk_flags | Overlap, wrapping, or truncation risks |
variant_plan | Variant names, rationale, diff summaries |
implementation_notes | Agent-ready constraints |
lessons_learned | What improved, confused, or harmed this run |
improvement_rules | Reusable rules derived from lessons |
browser_verification | Screenshots + overlap/nav-wrap/tap-target results |
quality_score | Score out of 66, confidence multiplier |
Quality Bar
- Navigation defined before aesthetics
- No vague adjectives in optimized prompt
- All token roles have semantic names
- Layouts pass overlap check at all breakpoints
- Anti-slop audit passed
- Confidence ≥ 2.0× (or marginal flag)
- Lessons recorded in session files
Cross-Skill Integration
| Skill | Integration |
|---|
web-search-researcher | Research Scout — deep research |
anti-ai-slop | Anti-Slop Sentinel — pattern detection |
agent-coordination | Swarm orchestration |
iterative-refinement | Autoresearch loop |
parallel-execution | Parallel variant generation |
Reference Files Index
| File | Purpose |
|---|
references/swarm-coordination.md | Swarm architecture, handoff protocol, agent contracts |
references/auto-research.md | Auto-research workflow, search strategies |
references/design-tokens.md | Token categories, naming, semantic structure |
references/typography.md | Role-based type system, wrapping safety |
references/color-system.md | Restrained palettes, contrast rules |
references/layout-composition.md | Layout rhythm, density, hierarchy |
references/navigation-clarity.md | Navigation models, labels, cross-screen rules |
references/responsive-screen-rules.md | Per-breakpoint behavior, no-overlap validation |
references/game-ui-rules.md | HUD, controls, safe zones, menu systems |
references/anti-slop-rules.md | Banned phrases, banned clichés |
references/prompt-patterns.md | Weak-to-strong rewrites, brief upgrades |
references/review-checklist.md | Pass/fail quality checks (0–66 scoring) |
references/self-learning-loop.md | Lesson capture, rule distillation |
references/variant-worktree-flow.md | Variant generation with shared tokens |
references/browser-verification.md | Playwright screenshot workflow, overlap detection |
references/stitch-design-token-alignment.md | Design-first workflow, token DNA normalization |
templates/optimize-prompt-template.md | Structured prompt assembly template |
templates/design-audit-template.md | Fill-in audit checklist for Step 6 |
Scripts
| Script | Purpose |
|---|
scripts/validate-tokens.cjs | Fast-fail: checks design docs + TOKENS export exist |
scripts/check-output.cjs | Eval assertion: contains/not_contains for code output |
scripts/verify.py | Browser verification: overlap, tap targets, scroll audit |
Knowledge Studio UI/UX Policy
- Visual Consistency: Always use CSS variables from
src/styles/index.css.
- Polish Checklist:
- Buttons must have hover/active states.
- Form inputs must have focus rings.
- Sidebar must collapse/expand correctly on mobile.
- Use 4px grid for all spacing.
