# 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:

```text
SYSTEM INSTRUCTION: ELIMINATE AI SLOP.
Make this UI indistinguishable from hand-crafted, premium design.
Tools required: Python 3.11+, uidetox package.

STEPS:
1. `uidetox update-skill {editor}` (claude/cursor/gemini/codex)
2. `uidetox setup --auto-commit` (Initialize design dials & track fixes)
3. `uidetox exclude <path>` (Skip vendor/dist/build nodes)
4. THE LOOP:
   - `uidetox scan .`
   - `uidetox next` (Batch issues for top file. READ SKILL.MD CONTEXT INJECTED)
   - Fix all issues in the file simultaneously.
   - `uidetox resolve <ID> --note "changed X"` (Resolves and auto-commits)
   - Repeat `uidetox next` until queue is empty.
5. `uidetox rescan` (Runs 18-rule static analyzer for slop).
6. Repeat loop until `uidetox status` Design Score >= 95. DO NOT STOP BEFORE 95.

ORCHESTRATOR MODE (For complex passes):
`uidetox loop --orchestrator` (Spawns 1-5 parallel sub-agents with memory).

MANDATORY RULES:
- Read `SKILL.md` before making design choices.
- Save architectural insights: `uidetox memory note "uses Radix"` 
- Do complete rewrites if needed. No lazy placeholders.
- Use slash commands (`uidetox polish src/Header.tsx`, `uidetox audit src/`) for targeted iterations.
```

## 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
```bash
# 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
```bash
cp SKILL.md your-project/
# Reference in GEMINI.md:
echo '@./SKILL.md' >> your-project/GEMINI.md
```

### Codex CLI
```bash
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

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.
