UI/UX Prompt Optimizer

Compliance Mandate

You are a constrained design executor once tokens are frozen.

• Style/Font/Color decisions not in Token Scaffold: FORBIDDEN after Phase 2.
• Missing required token category: warn and ask user — do NOT infer.
• Before Phase 2: full creative freedom. After Phase 2 freeze: zero discretion.
• FREEZE ENFORCEMENT: scripts/validate-tokens.cjs enforces the freeze programmatically.

Swarm-powered skill for generating implementation-ready UI/UX prompts. Uses 7 specialized agents, an autoresearch loop (try → score → keep/revert → repeat), and backpressure quality gates.

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 or variant generation for a design system

Supported: web apps, mobile apps, dashboards, admin tools, e-commerce, SaaS, games, kiosk/touch UIs, 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

Anti-AI-Slop Guide

Systematic antidote for generic AI patterns in UI, UX, and copy. Modes: (1) Audit existing UI, (2) Creation (read rules first), (3) Spot-fix one element. Always name the sin before fixing. Full pattern tables → references/anti-slop-guide.md and references/anti-slop-rules.md. Doctrine: specificity over universality; constraints create identity; undo over confirm.

Swarm Architecture

7 specialized agents. Full details → references/swarm-coordination.md

Autoresearch Loop

Try → measure → keep/revert → repeat. Full details → references/swarm-coordination.md

1. Run full swarm pipeline
2. Quality Auditor scores (MAD-based): Game 0–66, Non-game 0–57. Use effective percentage (score/max_applicable).
3. Effective ≥ 91% AND confidence ≥ 2.0× → KEEP
4. Effective < 91% OR confidence < 1.0× → REVISE
5. Score regresses → REVERT
6. Max 5 iterations per session

Session Files

• ui-ux-session.md — living document: objective, wins, dead ends
• ui-ux-session.jsonl — append-only log: one JSON line per iteration

Compare against evals/golden-tokens.json if it exists. Revise if output deviates.

Gotchas

• AI Slop gravity: Agents default to Inter, purple gradients, three-column grids. Override with opinionated font choices.
• Mobile horizontal overflow: Nav/lists break on <768px. Enforce overflow-x-auto on horizontal nav, overflow-x-hidden on root.
• Z-Index wars: Use Flexbox/Grid for layout; absolute only for HUDs/overlays.
• Flickering transitions: Use AnimatePresence with mode="wait" and initial={false}.
• Scrollbar jitter / Nested scroll: Use overflow-x-hidden on root, min-h-full for sub-components.

Token Scaffold (Phase 2, Frozen for All Subsequent Phases)

Define and commit all categories to docs/design/design-tokens.json (W3C Design Tokens format). FROZEN once written.

FREEZE RULE: No token value may change without explicit user instruction. All phases read from this file.

CREATIVE FREEDOM: Values up to model's judgment based on Research Scout findings, Anti-Slop Sentinel translation, and platform guidelines.

Required Workflow

Run every step. Swarm coordinates handoffs.

Phase 1: Research & Translate

Step 0 — Research Scout: Auto-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. Handoff → antislopwarnings. See → references/anti-slop-rules.md

Phase 2: Token & Structure

Step 2 — Token Architect: Build & Freeze Tokens. If docs/design/design-tokens.json exists, READ only. Otherwise populate categories from researchcontext and antislopwarnings. DIFF check against frozen tokens. Handoff → designtokens. See → references/design-tokens.md

Step 3 — Layout Engineer. Nav model, screen map, responsive spec. See → references/navigation-clarity.md, references/layout-composition.md. 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. Copy frozen Token Scaffold keys as comment header into every generated file. Reference only token keys — never raw values. Include responsive styles for all four breakpoints.

Step 4a — Sync Code. Run node .agents/skills/ui-ux-optimize/scripts/sync-tokens.cjs to generate src/lib/design-system.tsx. Never edit the .tsx file directly.

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.

Step 6a — Token Validation. Run node .agents/skills/ui-ux-optimize/scripts/validate-tokens.cjs to fast-fail if tokens or design system are misaligned.

Step 6b — Browser Verifier (when HTML available). Playwright at 375/768/1024/1440px. If no HTML, SKIP. 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 — Record Lessons. Append to session files. See → references/self-learning-loop.md

Quality Bar

• Navigation defined before aesthetics, no vague adjectives, semantic token 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

References

Scripts

See Also

• css-render-performance — CSS render performance optimization

Rationalizations

Red Flags

• Token scaffold modified after Phase 2 freeze
• Anti-slop audit skipped to save time
• Variants generated without shared token foundation