Compliance Mandate
You are operating as a constrained design executor, not a free creative agent, once tokens are frozen.
- Style decisions not listed in the project Token Scaffold: FORBIDDEN after Phase 2.
- Font substitution mid-session: FORBIDDEN.
- Color variation ("similar to...", "a shade of..."): FORBIDDEN after freeze.
- Inventing new token names not in the scaffold: FORBIDDEN.
- When a required token category is missing: output a warning and ask the user — do NOT infer a value.
- Before Phase 2: full creative freedom to research and propose. After Phase 2 freeze: zero discretion.
- FREEZE ENFORCEMENT:
scripts/validate-tokens.cjsprogrammatically enforces the freeze. Any attempt to modify a locked token after its initial commit will cause a validation failure.
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
Anti-AI-Slop Guide
AI tools flooded the design and copy space. The result: a recognizable monoculture. This section is a systematic antidote for detecting and avoiding generic AI patterns in UI, UX, and copy.
Audit Modes
- Audit mode — User shares existing UI/copy/UX flow. Run through diagnostic checklists. Call out every pattern by name. Suggest replacements.
- Creation mode — User wants new UI/copy/flow. Read the "What to do instead" sections first, then produce work that avoids all listed patterns.
- Spot-fix mode — User points to one specific element. Diagnose it, explain why it's sloppy, rewrite/redesign it.
Always name the sin before fixing it. Specificity builds trust.
UI Slop Patterns (Visual Design)
| Pattern | What it looks like | Why it's slop |
|---|---|---|
| Purple gradient hero | #7c3aed → #2563eb on white bg |
Default Tailwind AI app palette |
| Glassmorphism cards | Frosted glass, backdrop-blur, bg-white/10 |
Overused since iOS 15 |
| Rounded everything | border-radius: 24px+ on every element |
Removes personality |
| Inter / DM Sans / Space Grotesk | Default "modern" sans | Signal "AI-generated UI" |
| Emojis as icons in headers | ✨ Supercharge your workflow 🚀 | Startup theater |
| Hero headline formula | [Verb] your [noun] with [product] |
Indistinguishable from 10,000 others |
| Three-column feature grid | Icon + bold label + 1 sentence | Every SaaS landing page since 2019 |
| CTA: "Get started for free" | Large button, primary color | Meaningless |
What to do instead: Typography first (research type history), commit to one extreme (brutally minimal OR maximally dense), use real color theory, let content shape the layout, reference actual design movements (Swiss grid, Bauhaus, Brutalist web).
UX Slop Patterns (Interaction & Flow)
| Pattern | Why it's slop |
|---|---|
| Onboarding modal | Interrupts before context |
| 5-step wizard | Treats users as suspects |
| Tooltip tours | Teaches wrong interface instead of fixing it |
| "Are you sure?" | Trust issues. Use undo instead |
| Toast notifications | Noise. Users ignore them in 2 sessions |
| Hamburger menu | Discovery failure |
What to do instead: Undo over confirm, empty states with one specific next action, progressive disclosure, optimistic UI, contextual notifications (inline, not toast).
Copy Slop Patterns
| Slop Type | Examples | Fix |
|---|---|---|
| Hollow Affirmations | Absolutely!, Certainly!, Of course! | Delete them. Start with content. |
| AI Superlatives | Powerful, seamless, intuitive, robust | Use specific claims and data. |
| Listicle Reflex | Bullet points for everything | Write prose. Use lists only for genuine enumerable sets. |
| Transition Theater | "In conclusion...", "To summarize..." | Just say the thing. |
| Emoji Inflation | 🚀 💡 ✨ ⚡ 🔥 as substitutes for meaning | Use zero emojis unless genuinely casual/social. |
| Feature Announcement Formula | "We're excited to announce..." | What does it do, concretely? |
Audit Workflow
- Scan for patterns — Check all three canons (UI, UX, Copy). List every match by name.
- Score severity — 🔴 Structural (redesign), 🟡 Surface (easy fix), 🟢 Cosmetic (polish).
- Prioritize — Fix structural first.
- Rewrite/redesign — Provide specific replacements, not generic advice.
- Explain the why — Name the design principle behind each fix.
Positive Design Doctrine
- Specificity > universality. Design for this user, this task, this moment.
- Tension is interest. Contrast, asymmetry, and friction are memorable.
- Constraints create identity. Impose a real restriction and design within it.
- Respect the user's time. Every click, form field, and modal is a tax.
- Be opinionated. Show users the best path.
- Specific > general. "Saves 3 hours per week" > "Saves time"
- Write for one person. Not "users". The specific human who will read this sentence.
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
These files are for developer-led regression testing:
evals/golden-tokens.json— Reference token snapshot: the canonical correct tokens for regression testing.evals/eval-prompt.md— The exact prompt that produced the golden output.
Before submitting output, compare against
evals/golden-tokens.jsonif it exists. If your output deviates in color, font, spacing, or radius from the frozen tokens, revise before responding.
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-autofor horizontal navigation,overflow-x-hiddenon 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
AnimatePresencewithmode="wait"andinitial={false}. High-motion elements needwill-change-transform transform-gpu backface-visibility-hidden. - Scrollbar jitter: Unstable scrollbars cause layout shifts between viewports. Enforce
overflow-x-hiddenon root,overflow-y-autofor content containers. - Nested scroll contexts:
min-h-screenin sub-components inside scrollable parents creates double scrollbars. Usemin-h-fullfor sub-components.
Token Scaffold (Populated in Phase 2, Frozen for All Subsequent Phases)
Before any code or prompt is generated, the Token Architect MUST define and commit all of the following categories to docs/design/design-tokens.json (W3C Design Tokens format). Values are chosen by the model based on project context and research — but once written, they are FROZEN for the session.
Required categories:
| Category | Required keys |
|---|---|
colors |
primary, background, surface, text_primary, text_muted, accent, error, success |
typography |
font_family, scale_px[], weight{}, line_height{} |
spacing |
unit (must be 4 or 8), gutter |
radius |
sm, md, lg, pill |
shadow |
single string value |
breakpoints |
[mobile, tablet, desktop, wide] as px values |
effects |
antiFlicker string |
FREEZE RULE: Once written to docs/design/design-tokens.json, no token value may change without an explicit user instruction in the chat. All phases read from this file — never re-invent.
CREATIVE FREEDOM: The actual values are fully up to the model's judgment based on:
- Research Scout findings (domain trends, competitor patterns)
- Anti-Slop Sentinel translation (what "premium" or "minimal" actually means for this product)
- Platform guidelines (iOS HIG, Material 3, game genre conventions, etc.)
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. Use the Anti-AI-Slop Guide above for pattern detection. Handoff → anti_slop_warnings. See → references/anti-slop-rules.md
Phase 2: Token & Structure
Step 2 — Token Architect: Build & Freeze Tokens.
- If
docs/design/design-tokens.jsonexists: READ it — do NOT modify unless the user explicitly instructs an override. - If it does not exist: Populate all Token Scaffold categories creatively based on
research_contextandanti_slop_warnings. Write todocs/design/design-tokens.json. - DIFF check: For any proposed style value, compare against the local
docs/design/design-tokens.json. Reject divergence — output a warning listing the conflicting value and revert to the frozen token. - NEVER generate new token category names outside the scaffold.
- 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
- Copy the frozen Token Scaffold keys as a comment header into every generated file.
- Reference only token keys — never raw values — in component code.
- Output must include responsive styles for all four breakpoints defined in
breakpointstoken.
Step 4a — Sync Code. Run node .agents/skills/ui-ux-optimize/scripts/sync-tokens.cjs to generate src/lib/design-system.tsx from your JSON tokens. 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. 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 docs/design/design-tokens.json or src/lib/design-system.tsx are missing or misaligned. 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
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 |
agent-coordination |
Swarm orchestration, parallel variant generation |
iterative-refinement |
Autoresearch loop |
References
| 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, text-wrap and tabular numbers |
references/animations.md |
Interruptible animations, enter/exit transitions |
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 |
See Also
css-render-performance— CSS render performance optimization
Rationalizations
| Rationalization | Reality |
|---|---|
| "I can skip the token freeze and just eyeball it" | Without frozen tokens, visual drift accumulates silently across components and sessions. |
| "Research Scout is optional for a simple UI" | Even simple UIs benefit from domain context; skipping research leads to generic slop. |
| "The autoresearch loop takes too long, ship the first draft" | First drafts rarely converge on quality; the loop exists to catch regressions before users do. |
Red Flags
- Token scaffold modified after Phase 2 freeze
- Anti-slop audit skipped to save time
- Variants generated without shared token foundation