Metadata-Version: 2.4
Name: uidetox
Version: 1.4.2
Summary: Agent harness and CLI to eliminate AI slop from frontend code
Author: artmanuky
License: MIT
Project-URL: Homepage, https://github.com/OJamals/UIdetox
Project-URL: Repository, https://github.com/OJamals/UIdetox
Project-URL: Issues, https://github.com/OJamals/UIdetox/issues
Keywords: code-quality,frontend,design,ai-slop,agent,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: tree-sitter>=0.21.0
Requires-Dist: tree-sitter-javascript>=0.21.0
Requires-Dist: tree-sitter-typescript>=0.21.0
Requires-Dist: tree-sitter-css>=0.21.0
Requires-Dist: chromadb>=0.4.24
Requires-Dist: playwright>=1.42.0
Dynamic: license-file

![UIdetox Banner](https://raw.githubusercontent.com/OJamals/UIdetox/master/assets/banner.png)

**The anti-slop harness for AI-generated frontends.**

[UIdetox](https://github.com/OJamals/UIdetox) helps your coding agent turn generic, LLM-style UI output into production-quality interface work through a repeatable **scan → fix → verify** loop.

It combines:
- deterministic anti-pattern detection,
- opinionated design guidance,
- mechanical tooling checks,
- and autonomous issue batching with memory-aware continuation.

[Quick Start](#quick-start) • [Autonomous Loop](#the-autonomous-loop) • [Commands](#commands)

---

### The AI Slop Problem

![Slop vs Crafted](https://raw.githubusercontent.com/OJamals/UIdetox/master/assets/slop-vs-crafted.png)

AI tools can produce UI quickly, but often converge on the same visual clichés: default font stacks, purple-blue gradients, glass cards, repetitive metric blocks, and shallow interaction states.

UIdetox gives your agent a target and a process:
- detect what looks autogenerated,
- prioritize the highest-impact fixes,
- enforce consistent design rules,
- and iterate until the **Design Score** reaches release quality.

This is not just linting. It is a structured quality system for frontend output.

---

## Quick Start

```bash
pip install uidetox

# Install agent-specific skill assets
uidetox update-skill [agent]    # supports: claude, cursor, gemini, windsurf, codex, copilot

# Initialize project dials + optional auto-commit flow
uidetox setup --auto-commit

# Start autonomous protocol
uidetox loop
```

---

## Agent Bootstrap Prompt

Paste this into your coding agent to kick off a full detox pass:

```text
Eliminate AI slop from this codebase. Make the frontend feel hand-crafted. Target: Design Score 95+.

BOOTSTRAP:
  pip install uidetox
  uidetox update-skill <your_agent>   # claude | cursor | gemini | codex | windsurf | copilot
  uidetox setup --auto-commit
  uidetox loop                        # prints the full protocol — follow it

THE LOOP (repeat until score ≥ 95 and queue is empty):
  1. uidetox next                     # get highest-priority batch + SKILL.md context
  2. Fix every issue properly          # full rewrites, not snippets — read files first
  3. uidetox batch-resolve IDs --note "..." && uidetox check --fix && uidetox status

RULES:
  - Don't be lazy. Rewrite entire files if needed. No TODOs, no "I'll handle this later."
  - The tool's rules override your instincts. Trust the analyzer and SKILL.md over your biases.
  - Don't stop after one fix. Don't ask permission. Don't summarize between iterations.
  - When score ≥ 95 and queue is empty: uidetox finish
```
---

## The Autonomous Protocol

`uidetox loop` drives a fully autonomous **scan → fix → verify** cycle. The loop continues until the Design Score meets the target (default 95) and the issue queue is empty.

### The Intelligence Layer
UIdetox uses a multi-modal approach to detect slop and plan remediation. It combines static AST analysis with persistent semantic memory to ensure fixes are both correct and consistent with the project's identity.

![The Intelligence Layer](https://raw.githubusercontent.com/OJamals/UIdetox/master/assets/intelligence.png)

### The Remediation Flow
Each iteration follows a strict quality gate. Issues are batched by component, skill rules are injected, and fixes are verified against the project's build system before being committed.

![UIdetox Flow](https://raw.githubusercontent.com/OJamals/UIdetox/master/assets/explained.png)

> [!TIP]
> **Self-Healing Mechanics**: If a fix breaks the build (TSC or Lint errors), UIdetox captures the compiler output, injects it back into the agent's context, and requires a fix before the issue can be resolved.

> [!TIP]
> **Visual Regression Workflow**: Use `uidetox capture --stage before` and `uidetox capture --stage after` (optionally with `--responsive`) to generate screenshot diffs that are surfaced inside `uidetox review`.


**Design Score** = Objective × 0.6 + Subjective × 0.4 — the agent keeps looping until this hits the target.

---

## Commands

| Command | Purpose |
| :--- | :--- |
| `uidetox loop` | Start the autonomous workflow (scan → fix → verify cycle). |
| `uidetox scan` | Run 60+ rule static analysis + dynamic WCAG theme audit + subjective rubric injection. |
| `uidetox next` | Get the highest-priority issue batch with SKILL.md context. |
| `uidetox batch-resolve` | Resolve issues atomically with verification + auto-commit. |
| `uidetox status` | Show blended Design Score, velocity, and queue health. |
| `uidetox review` | Subjective quality scoring across 4 design dimensions. |
| `uidetox capture` | Capture before/after screenshots and visual diffs (`--stage before/after`, `--responsive`). |
| `uidetox rescan` | Fresh re-analysis with dedup and auto-escalation. |
| `uidetox check --fix` | Mechanical gate: tsc → lint → format. |
| `uidetox plan` | Attack plan grouped by component with effort estimates. |
| `uidetox autofix` | T1-first quick-win guidance across 12 categories. |
| `uidetox finish` | Squash-merge session branch into main. |

### Design skill commands

Targeted refinement — use when a component needs deeper attention:

`uidetox polish` · `animate` · `colorize` · `harden` · `normalize` · `bolder` · `distill` · `audit` · `critique`

---

## Design Dials

Set during `uidetox setup` and used throughout scan/fix prompts:

- **DESIGN_VARIANCE (1–10)**
  - 1–3: clean, centered, conventional
  - 4–7: varied composition, controlled asymmetry
  - 8–10: aggressive asymmetry, whitespace contrast, high visual character

- **MOTION_INTENSITY (1–10)**
  - 1–3: minimal transitions
  - 4–7: meaningful motion and staged reveal
  - 8–10: advanced spring/scroll-driven interactions

- **VISUAL_DENSITY (1–10)**
  - 1–3: spacious editorial feel
  - 4–7: balanced application density
  - 8–10: compact cockpit-like information layout

Default baseline: **(8, 6, 4)**.

---

## Anti-Pattern Coverage

The analyzer includes **60+ deterministic rules** organized across these categories:

| Category | Examples |
| :--- | :--- |
| **Typography** | Generic font stacks, hardcoded px fonts, tight line-height, weak weight spectrum |
| **Color** | Purple-blue gradients, pure black, raw hex literals, duplicate color values, gradient text |
| **Layout** | Center bias, flex-math, card nesting, overpadding, viewport height, lazy flex-center |
| **Materiality** | Glassmorphism abuse, generic shadows, neon glow, opacity stacking, gradient text |
| **Motion** | Bounce animation clichés, missing transitions on interactive elements |
| **States** | Missing hover/focus/dark-mode, disabled without cursor change |
| **Content** | Generic copy, AI cliché phrases, lorem ipsum, placeholder names, emoji overuse |
| **Code Quality** | Div soup, z-index stacking, inline styles, nested ternaries, `any` type, ts-ignore |
| **Duplication** | Duplicate Tailwind blocks, copy-paste components, repeated handlers/media queries |
| **Dead Code** | Commented-out code, unused imports/state, unreachable code, empty handlers, dead CSS |

Each rule is classified into **tiers** with estimated effort:

| Tier | Effort | Impact | Examples |
| :--- | :--- | :--- | :--- |
| **T1** | ~2 min | 1 pt | Font swap, color fix, remove unused import |
| **T2** | ~8 min | 3 pts | Add hover states, fix layout pattern, extract duplicate |
| **T3** | ~20 min | 5 pts | Redesign component layout, implement dark mode |
| **T4** | ~45 min | 10 pts | Major component restructure, full accessibility pass |

---

## Credits & License

Inspired by and built on ideas from:
- [desloppify](https://github.com/peteromallet/desloppify)
- [impeccable](https://github.com/pbakaus/impeccable)

MIT © [OJamals](https://github.com/OJamals)
