# UIdetox

An agent harness that eliminates "AI slop" from frontend code and enforces quality across frontend, backend, and database layers. It combines design taste enforcement, anti-pattern detection, mechanical linting, and structured remediation into a repeatable scan→fix loop.

UIdetox is created as an effective agent harness for UI/frontend work by serving as an amalgamation of four pioneering projects:
- **desloppify** — The original inspiration for systematic AI-slop removal and workflow automation
- **taste-skill** — Generative design rules, creative arsenal, and motion engine
- **Uncodixfy** — Comprehensive anti-AI-aesthetic pattern catalog
- **impeccable** — Frontend design commands, references, and quality guidelines

## 1. Philosophy

AI-generated UI has a recognizable aesthetic: Inter font, purple-blue gradients, glassmorphism cards, hero metric dashboards, bounce animations, gray text on colored backgrounds. These patterns emerge because LLMs follow the path of least resistance through their training data.

UIdetox fights that bias. Its instructions teach the agent what NOT to do (anti-patterns), what TO do instead (design engineering), and HOW to apply fixes systematically (the loop).

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

## 2. The Loop

`uidetox scan .` auto-detects tooling and runs 4 steps:
1. **Mechanical Checks:** `uidetox check` (tsc → lint → format). Errors = T1.
2. **Static Slop Analysis:** 18-rule deterministic scan for AI anti-patterns (glassmorphism, purple gradients, etc).
3. **Design Audit:** Agent evaluates frontend files via `SKILL.md` rules.
4. **Integration Audit:** Checks DTOs, schemas, and API state gaps.

Issues are tiered T1 (quick fix) to T4 (major redesign).

### Execution Phase
1. `uidetox plan` (Orders fixes: fonts > colors > states > layout > refinement)
2. `uidetox next` (Batches pending issues for highest-priority file. Context injects `SKILL.md`)
3. `uidetox resolve <ID> --note "..."`
4. Repeat `uidetox next` until queue is empty.
5. `uidetox rescan` (Fresh audit) -> `uidetox status` (Score 1-100). Target: >95.

## 3. Skills

The combined SKILL.md contains the full design knowledge base. It is structured as:

| Section | Source | Purpose |
|---------|--------|---------|
| Design Direction | impeccable | Bold aesthetic commitment |
| Design Engineering | taste-skill | Bias-correcting rules (typography, color, layout, materiality, states) |
| Anti-Pattern Catalog | Uncodixfy + impeccable + taste-skill | Comprehensive list of banned AI UI patterns |
| Creative Arsenal | taste-skill | Advanced design concepts for premium output |
| Motion Engine | taste-skill | Perpetual micro-interaction framework |
| Output Enforcement | taste-skill | Anti-laziness rules for complete code generation |
| Redesign Protocol | taste-skill | Audit-first upgrade workflow |
| Color Palettes | Uncodixfy | Curated dark/light color schemes |

Reference files in `reference/` provide deep-dive guidance for each design domain.

## 4. Commands

Command list removed to save agent tokens. Run `uidetox --help` for full CLI commands, or reference `README.md`.
Use slash commands (`uidetox polish src/Header.tsx`, `uidetox audit src/`) for targeted iterations.

## 5. Configuration

The harness supports three design dials that control output aesthetic:

**DESIGN_VARIANCE** (1-10) — How experimental the layout is.
- 1-3: Clean, centered, standard grids
- 4-7: Overlapping elements, varied sizes, offset margins
- 8-10: Asymmetric, masonry, massive whitespace zones

**MOTION_INTENSITY** (1-10) — How much animation.
- 1-3: CSS hover/active states only
- 4-7: Fade-ins, smooth transitions, staggered entry
- 8-10: Scroll-triggered reveals, spring physics, magnetic effects

**VISUAL_DENSITY** (1-10) — How much content per screen.
- 1-3: Art gallery mode, spacious, luxury feel
- 4-7: Standard web app spacing
- 8-10: Cockpit mode, dense data, monospace numbers

Default baseline: `(8, 6, 4)`. Override via `/setup` or direct instruction.

## 6. Provider Installation

UIdetox supports tailored integration with all major AI coding platforms.

Run `uidetox update-skill <agent>` (choices: `claude`, `cursor`, `gemini`, `codex`, `windsurf`, `copilot`) to receive exact configuration instructions and setup commands.

UIdetox reads from its `docs/` catalog to output platform-specific workflows, covering native rules (like `.cursor/rules/`), system memory integrations, and specific prompt structures.

## 7. Repository Structure

```
UIdetox/
├── pyproject.toml                # Python packaging
├── AGENTS.md                     # This file — master agent entry point
├── SKILL.md                      # Combined design skill (all three repos)
├── README.md                     # User documentation + quick-start prompt
├── uidetox/                      # Python CLI package
│   ├── cli.py                    # Argparse router (30+ commands, dynamic slash-command loading)
│   ├── state.py                  # Issue queue + config in .uidetox/
│   ├── tooling.py                # Auto-detection (tsc, biome, eslint, NestJS, etc.)
│   ├── analyzer.py               # 18-rule static slop detector (deterministic anti-pattern scan)
│   ├── history.py                # Run snapshot storage and progression tracking
│   ├── memory.py                 # Persistent agent memory (reviewed files, patterns, notes)
│   ├── subagent.py               # Sub-agent session infrastructure (5-stage pipeline)
│   └── commands/                 # Command implementations
│       ├── scan.py, next.py, resolve.py, plan.py
│       ├── setup.py, review.py, update_skill.py
│       ├── status.py, show.py, autofix.py, loop.py
│       ├── exclude.py, rescan.py, add_issue.py
│       ├── detect.py, check.py, tsc.py, lint.py, format_cmd.py
│       ├── subagent_cmd.py, history_cmd.py
│       ├── memory_cmd.py, skill_cmd.py
│       ├── viz.py, zone.py, suppress.py
├── commands/                     # Slash commands (19 total, dynamically loaded by CLI)
│   ├── scan.md, fix.md, setup.md
│   ├── audit.md, critique.md, normalize.md, ...
├── reference/                    # Deep-dive design references
│   ├── anti-patterns.md, color-palettes.md, creative-arsenal.md
│   ├── typography.md, color-and-contrast.md, ...
├── .agents/workflows/
│   └── detox.md                  # Guided workflow
```
