uidetox 0.1.0

Agent harness and CLI to eliminate AI slop from frontend code

UIdetox

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

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

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 -e .
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

Cursor

Copy AGENTS.md, SKILL.md, commands/, and reference/ into your project root.

Note: Cursor Agent Skills require Nightly channel. Enable in Settings → Beta, then enable Agent Skills in Settings → Rules.

Claude Code

# Project-specific
cp AGENTS.md SKILL.md your-project/
cp -r commands/ reference/ your-project/

# Or copy into .claude/skills/
mkdir -p your-project/.claude/skills/uidetox
cp SKILL.md your-project/.claude/skills/uidetox/
cp -r reference/ your-project/.claude/skills/uidetox/

Gemini CLI

cp SKILL.md your-project/
# Reference in GEMINI.md:
echo '@./SKILL.md' >> your-project/GEMINI.md

Codex CLI

mkdir -p ~/.codex/skills/uidetox
cp SKILL.md ~/.codex/skills/uidetox/
cp -r reference/ ~/.codex/skills/uidetox/
cp -r commands/ ~/.codex/prompts/

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

UIdetox combines knowledge from:

• taste-skill by @lexnlin — Design dials, creative arsenal, motion engine, output enforcement
• Uncodixfy — Anti-AI-aesthetic pattern catalog, curated color palettes
• impeccable by Paul Bakaus — Frontend design skill, 17 commands, domain references

Inspired by desloppify by Pete O'Mallet.

License

See individual source repositories for their respective licenses.