# 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

```bash
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:

```bash
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:
```bash
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](https://github.com/peteromallet/desloppify)** by Pete O'Mallet — The original inspiration for systematic slop removal.
- **[impeccable](https://github.com/pbakaus/impeccable)** by [Paul Bakaus](https://www.paulbakaus.com) — Frontend design skill, 17 robust commands, and deep domain references.
- **[taste-skill](https://github.com/Leonxlnx/taste-skill)** by [@lexnlin](https://x.com/lexnlin) — Core generative design rules, creative arsenal, motion engine, and output enforcement.
- **[Uncodixfy](https://github.com/cyxzdev/Uncodixfy)** — Comprehensive anti-AI-aesthetic pattern catalog and curated color palettes.

## License

See individual source repositories for their respective licenses.
