uidetox 0.2.2

Agent harness and CLI to eliminate AI slop from frontend code

UIdetox

An agent harness that eliminates "AI slop" from frontend code.

UIdetox is an amalgamation of pioneering UI engineering works—specifically drawing from desloppify, impeccable, taste-skill, and uncodixfy. It was created as an effective, dedicated agent harness for UI and frontend quality enforcement.

It gives your AI coding agent the instructions to identify, understand, and systematically fix generic AI-generated UI through a repeatable scan→fix loop combining design taste enforcement and anti-pattern detection.

The goal: frontend code that makes someone ask "how was this made?" — not "which AI made this?"

For your agent's consideration...

Paste this prompt into your agent:

I want you to eliminate AI slop from this codebase and make the UI indistinguishable from
hand-crafted design. To do this, install and run UIdetox.
Run ALL of the following (requires Python 3.11+):

pip install uidetox
uidetox update-skill claude    # installs the full design skill — pick yours: claude, cursor, gemini, codex, windsurf, copilot
uidetox setup                  # initialize design dials (DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY)

Before scanning, exclude directories that should be skipped (vendor, build output, generated
code, node_modules, dist) with `uidetox exclude <path>`. Check `uidetox zone show` to verify
file classifications. Share anything questionable with me before excluding.

uidetox scan --path .
uidetox next

--path is the directory to scan (use "." for the whole project, or "src/" etc).

Your goal is to get the Design Score as high as possible. The scoring is weighted across
typography, color, layout, motion, states, accessibility, and full-stack integration — the
only way to improve it is to actually make the interface better.

THE LOOP: run `next`. It batches all pending issues for the highest-priority file so you fix
files holistically, not one issue at a time. Each batch includes relevant SKILL.md design
rules injected automatically — follow them, don't substitute your own analysis. Fix all
issues in the batch, resolve each with:
  uidetox resolve <ID> --note "what you changed"
The --note is mandatory — you must explain what you did. Then run `next` again. Over and over.
When the queue empties, run `uidetox rescan` to re-audit with fresh eyes. `rescan` runs an
18-rule static slop analyzer automatically, catching glassmorphism, purple-blue gradients,
bounce animations, oversized shadows, missing dark mode, generic copy, and more. Keep looping
until `uidetox status` shows Score >= 95 and zero pending issues. Do NOT stop before that.

For safety during autonomous loops, enable auto-commit:
  uidetox setup --auto-commit
This makes every `uidetox resolve` atomically commit the fixed file to git, creating a clean
patch history you can review or rollback. Highly recommended for orchestrator mode.

Don't be lazy. Large redesigns and small detail fixes — do both with equal energy. No task
is too big or too small. Replace entire components if they reek of AI slop. Rewrite files
from scratch if the structure is unsalvageable. Fix things properly, not minimally.

Use `plan` to reorder priorities or cluster related issues. Use `uidetox tree` to see where
issues concentrate. Use `uidetox viz` to generate a visual heatmap. Rescan periodically.

For targeted design work, use the slash commands directly from the CLI:
  uidetox polish src/Header.tsx     # final quality pass
  uidetox audit src/components/     # technical a11y/perf/theming checks
  uidetox critique src/pages/       # UX design review
  uidetox harden src/forms/         # error handling, i18n, edge cases
  uidetox animate src/hero/         # add purposeful motion
All 16 design skills (audit, critique, normalize, polish, distill, harden, animate, colorize,
bolder, quieter, delight, extract, adapt, onboard, clarify, optimize) are available as native
CLI commands. Each loads its full design ruleset and targets the file or directory you specify.

For complex passes, use orchestrator mode: `uidetox loop --orchestrator`. This breaks work
into five sub-agent stages (observe → diagnose → prioritize → fix → verify), each with an
isolated prompt generated by `uidetox subagent --stage-prompt <stage>`. The orchestrator
automatically calculates optimal parallelism (1-5 agents) based on queue spread and injects
all saved memory context into the bootstrap. Launch sub-agents concurrently. Record
completions with `uidetox subagent --record`.

The agent memory persists across sessions. Save architectural decisions you discover:
  uidetox memory pattern "This project uses Radix UI, not shadcn"
  uidetox memory note "Custom SVG icon set in src/icons/, don't use lucide"
View memory with `uidetox memory show`. Clear with `uidetox memory clear`. What you learn
about this codebase stays in `.uidetox/memory.json` and is automatically injected into every
`uidetox loop` invocation so you never repeat mistakes or revert prior decisions.
History of every scan lives in `.uidetox/history/`.

If you have access to MCP servers, filesystem tools, or browser automation — use them.
Read files directly. Run terminal commands. Open the app in a browser and verify visually.
You are not a chatbot suggesting changes. You are an operator grinding through a queue until
this codebase is unrecognizable from its AI-generated origin.

From Vibe Coding to Vibe Design

Vibe coding gets things built fast. But the interfaces it produces have a smell — Inter font, purple-blue gradients, glassmorphism cards, bounce animations, hero metric dashboards. These patterns emerge because LLMs follow the path of least resistance through their training data. The result is an interface that works, but screams "AI made this" to anyone who's seen enough of them.

The core bet here is that an LLM with the right constraints can hold a frontend to a standard that used to require a senior designer paying close attention. Not by generating more of the same, but by knowing what not to do — and having a systematic loop to enforce it.

UIdetox defines what "designed" looks like as a Design Score worth optimizing. Not a lint score you game by suppressing warnings. Something where improving the number means the interface genuinely got better — better typography, better color, better states, better motion. The anti-slop rules are the difference between a useful signal and a vanity metric.

The hope is that anyone can use AI to build something a seasoned designer would look at and respect. That's the bar.

Installation

pip install uidetox

Then install the skill for your agent — this copies all design rules, reference files, and slash commands to the correct location automatically:

uidetox update-skill claude     # → .claude/skills/uidetox/
uidetox update-skill cursor     # → project root + .cursor/rules/uidetox.mdc
uidetox update-skill gemini     # → project root + GEMINI.md reference
uidetox update-skill codex      # → ~/.codex/skills/uidetox/
uidetox update-skill windsurf   # → project root + .windsurfrules
uidetox update-skill copilot    # → project root (SKILL.md + AGENTS.md)

Initialize and start scanning:

uidetox setup --auto-commit
uidetox scan .

Commands

CLI Commands (the loop engine)

Command	Purpose
uidetox scan	Full audit: auto-detect tooling → static analyzer → design review
uidetox check	Run tsc → lint → format in sequence, queue errors as T1 (--fix to auto-solve)
uidetox next	Batch issues for the top-priority file with SKILL.md context injection
uidetox resolve <id> --note "..."	Mark an issue as fixed (note is mandatory)
uidetox loop	Enter autonomous fix loop until target score is reached
uidetox loop --orchestrator	Sub-agent mode with auto-parallel (1-5 agents) and memory injection
uidetox status	Health dashboard with Design Score (--json for automation payload)
uidetox plan	Reorder the issue queue by priority
uidetox autofix	Batch-apply all safe T1 quick fixes (--dry-run to preview only)
uidetox memory	Read/write persistent agent memory (patterns, notes)
uidetox tree	Terminal tree of issue density
uidetox viz	HTML heatmap of the codebase
uidetox history	Score progression across runs (--full for details)
uidetox zone	Show/set/clear file zone classifications
uidetox suppress	Permanently silence false positive patterns
uidetox subagent	Manage sub-agent sessions and prompts
uidetox detect	Auto-discover linters, formatters, backends, databases, APIs
uidetox rescan	Clear queue, run 18-rule static analyzer, re-audit from scratch

Slash Commands (design skills)

All slash commands are now natively executable from the CLI — no need to read .md files manually:

Command	Purpose
uidetox audit [target]	Technical quality checks (a11y, perf, theming, responsive)
uidetox critique [target]	UX design review (hierarchy, emotion, composition)
uidetox normalize [target]	Align with design system standards
uidetox polish [target]	Final pre-ship quality pass
uidetox distill [target]	Strip to essence, remove complexity
uidetox clarify [target]	Improve unclear UX copy
uidetox optimize [target]	Performance improvements
uidetox harden [target]	Error handling, i18n, edge cases
uidetox animate [target]	Add purposeful motion
uidetox colorize [target]	Introduce strategic color
uidetox bolder [target]	Amplify boring designs
uidetox quieter [target]	Tone down overly bold designs
uidetox delight [target]	Add moments of joy
uidetox extract [target]	Pull into reusable components
uidetox adapt [target]	Adapt for different devices
uidetox onboard [target]	Design onboarding flows

Target can be a file, directory, or component name:

uidetox audit src/components/
uidetox polish src/Header.tsx
uidetox animate src/hero/

Configuration

Three design dials control output aesthetic (default: 8, 6, 4):

Dial	Low (1-3)	Mid (4-7)	High (8-10)
DESIGN_VARIANCE	Clean, centered, standard grids	Overlapping, varied sizes	Asymmetric, masonry, massive whitespace
MOTION_INTENSITY	CSS hover/active only	Fade-ins, smooth transitions	Scroll reveals, spring physics, magnetic effects
VISUAL_DENSITY	Art gallery, spacious	Standard web app	Cockpit mode, dense data

Override by editing SKILL.md or telling your agent directly: "Set DESIGN_VARIANCE to 3."

The AI Slop Test

If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.

UIdetox trains your agent to avoid the telltale patterns:

• Inter font everywhere
• Purple-blue gradients
• Card grids with identical layouts
• Glassmorphism panels
• Hero metric dashboards
• Bounce animations
• Gray text on colored backgrounds
• Generic startup copy

Credits

This project was created as an effective agent harness for UI/frontend work, serving as an amalgamation of the following pioneering projects:

• desloppify by Pete O'Mallet — The original inspiration for systematic slop removal.
• impeccable by Paul Bakaus — Frontend design skill, 17 robust commands, and deep domain references.
• taste-skill by @lexnlin — Core generative design rules, creative arsenal, motion engine, and output enforcement.
• Uncodixfy — Comprehensive anti-AI-aesthetic pattern catalog and curated color palettes.

License

See individual source repositories for their respective licenses.