design-auditor · diff
v2.1.0 to v2.2.0
32 added, 194 removed. Audit A to A.
---
name: design-auditor
description: >
Audit UI/UX designs for quality, AI-generated slop, and accessibility. Use when reviewing
designs, detecting slop patterns, validating WCAG compliance, checking design-token
adherence, or reviewing responsive design across breakpoints.
license: MIT + Commons Clause
metadata:
- version: 2.1.0
+ version: 2.2.0
author: borghei
category: engineering
domain: design-engineering
- updated: 2026-04-02
+ updated: 2026-06-17
tags: [design-audit, ai-slop, color-contrast, accessibility]
python-tools: design_scorer.py, ai_slop_detector.py, color_contrast_checker.py, design_system_validator.py
tech-stack: python, css, accessibility, wcag, design-systems
---
# Design Auditor
- The agent performs systematic 12-category UI/UX audits, detects AI-generated slop patterns, validates WCAG color contrast, and checks design system token compliance. Produces three independent grades: Design (A-F), AI Slop (A-F), and Accessibility (A-F).
-
- ---
-
- ## Quick Start
+ Performs systematic 12-category UI/UX audits, detects AI-generated slop patterns, validates WCAG color contrast, and checks design system token compliance. Produces three independent grades: Design (A-F), AI Slop (A-F), and Accessibility (A-F).
- ```bash
- # Score a full design audit (12 categories -> 3 grades)
- python scripts/design_scorer.py --input findings.json --output report.json --verbose
+ ## Core Capabilities
- # Detect AI-generated slop in HTML/CSS
- python scripts/ai_slop_detector.py --input page.html --css styles.css --threshold 0.6
+ - **Full design audit** — score 12 weighted categories in five passes into a Design grade with prioritized recommendations and baseline comparison.
+ - **AI slop detection** — flag visual, copy, and structural slop in HTML/CSS with confidence scores and per-finding remediation.
+ - **Accessibility audit** — WCAG color-contrast checking (AA/AAA) with closest-compliant-color suggestions.
+ - **Design-system compliance** — detect hardcoded colors, spacing, fonts, radii, shadows, z-indices, and transitions that deviate from tokens; report compliance percentage.
+ - **Three independent grades** — Design (weighted aggregate), AI Slop (inverted), Accessibility (WCAG), each A–F.
+ - **Operating system** — 10 design principles, fix-session rules with a risk accumulator, and CI/CD gating.
- # Check color contrast (single pair or batch)
- python scripts/color_contrast_checker.py --fg "#333" --bg "#fff" --level AA
- python scripts/color_contrast_checker.py --input color-pairs.json --level AAA --suggest-fixes
+ ## When to Use
- # Validate design system token compliance
- python scripts/design_system_validator.py --tokens tokens.json --input src/styles/
- ```
+ - Reviewing a UI/UX design for quality, originality, and accessibility.
+ - Detecting AI-generated slop patterns in HTML/CSS.
+ - Validating WCAG color contrast or design-token adherence.
+ - Gating deployments or PRs on minimum compliance scores.
- ## Tools Overview
+ ## Tools
- | Tool | Input | Output |
- |------|-------|--------|
- | `design_scorer.py` | 12-category audit findings JSON | Three grades, category breakdown, prioritized recommendations |
- | `ai_slop_detector.py` | HTML + optional CSS file | Findings with confidence scores (0.0-1.0), slop grade |
- | `color_contrast_checker.py` | Color pairs (hex/rgb/hsl/named) | WCAG pass/fail, ratios, compliant color suggestions |
- | `design_system_validator.py` | Design tokens JSON + CSS files | Compliance percentage, violations with token suggestions |
+ | Tool | Purpose | Command |
+ |------|---------|---------|
+ | `design_scorer.py` | Score 12-category audit findings into three grades | `python scripts/design_scorer.py --input findings.json --output report.json --verbose` |
+ | `ai_slop_detector.py` | Detect AI-generated slop in HTML/CSS | `python scripts/ai_slop_detector.py --input page.html --css styles.css --threshold 0.6` |
+ | `color_contrast_checker.py` | Check WCAG color contrast (single/batch) | `python scripts/color_contrast_checker.py --input color-pairs.json --level AA --suggest-fixes` |
+ | `design_system_validator.py` | Validate CSS against design tokens | `python scripts/design_system_validator.py --tokens tokens.json --input src/styles/` |
All tools support `--format json|text` and `--output` for file writing.
- ---
-
- ## Workflow 1: Full Design Audit
-
- The agent evaluates 12 weighted categories in five passes:
-
- 1. **Visual Pass** -- Visual Hierarchy (10%), Typography (8%), Color & Contrast (8%), Spacing & Layout (8%)
- 2. **Interaction Pass** -- Interaction States (10%), Navigation & IA (8%)
- 3. **Platform Pass** -- Responsive Design (8%), Accessibility/WCAG (12%)
- 4. **Polish Pass** -- Motion & Animation (5%), Content & Microcopy (5%)
- 5. **Integrity Pass** -- AI Slop Indicators (8%), Performance as Design (5%), Coherence Bonus (5%)
-
- ```bash
- python scripts/design_scorer.py --input audit_findings.json --baseline last_sprint.json --format text --verbose
- ```
-
- **Three independent grades:**
-
- | Grade | Design (weighted aggregate) | AI Slop (inverted) | Accessibility (WCAG) |
- |-------|----|----|----|
- | A+ | 95-100 | Highly original | AAA compliant |
- | A | 90-94 | No detectable patterns | Full AA compliant |
- | B | 80-89 | 1-2 minor patterns | Mostly AA, 1-3 minor violations |
- | C | 70-79 | Several AI patterns | Partial AA |
- | D | 60-69 | Heavily templated | Significant gaps |
- | F | 0-59 | Pure AI-generated slop | Fundamental failures |
-
- **Validation checkpoint:** Release gate requires minimum B Design grade and A Accessibility grade.
-
- ---
-
- ## Workflow 2: AI Slop Detection
-
- ```bash
- python scripts/ai_slop_detector.py --input index.html --css styles.css --threshold 0.6 --format json
- ```
-
- The agent detects patterns across three categories:
-
- **Visual slop** (confidence 0.4-0.9):
- - Generic hero section (full-width, centered text, gradient)
- - Stock gradients (trending purple-blue, pink-orange)
- - 3-column feature grid (icon + heading + paragraph x3)
- - Shadow/blur overuse on >60% of containers
-
- **Copy slop** (confidence 0.5-1.0):
- - Vague CTAs: "Get Started", "Learn More" without context
- - Buzzword clustering: "Seamless", "Powerful", "Revolutionary"
- - Lorem ipsum residue or uniform paragraph lengths
-
- **Structural slop** (confidence 0.4-0.8):
- - Template ordering: Hero > Features > Social Proof > Pricing > CTA > Footer
- - Cookie-cutter pricing (3 tiers, middle highlighted)
-
- Each finding includes a remediation suggestion for making the element more intentional.
-
- ---
-
- ## Workflow 3: Accessibility & Design System Compliance
-
- **Color contrast audit:**
-
- ```bash
- python scripts/color_contrast_checker.py --input brand-colors.json --level AA --suggest-fixes --format text
- ```
-
- Input format:
- ```json
- [
- {"foreground": "#666666", "background": "#ffffff", "label": "body text"},
- {"foreground": "#999999", "background": "#f5f5f5", "label": "muted text"}
- ]
- ```
-
- The agent checks against WCAG thresholds (4.5:1 normal text, 3:1 large text) and suggests the closest compliant alternative for failing pairs.
-
- **Design system validation:**
-
- ```bash
- python scripts/design_system_validator.py --tokens design-tokens.json --input src/styles/ --glob "*.scss"
- ```
-
- Token file format:
- ```json
- {
- "colors": {"primary": "#1a73e8", "secondary": "#5f6368", "error": "#d93025"},
- "spacing": [0, 4, 8, 12, 16, 24, 32, 48, 64],
- "typography": {"body": "16px", "h1": "32px", "h2": "24px"},
- "radii": [0, 4, 8, 16, 9999]
- }
- ```
-
- Detects hardcoded colors, spacing, fonts, radii, shadows, z-indices, and transitions that deviate from tokens. Reports compliance percentage and suggests nearest token for each violation.
-
- **Validation checkpoint:** Token compliance >= 90%. Zero off-system colors in production CSS.
-
- ---
-
- ## Design Principles (Audit Operating System)
-
- These 10 principles drive every finding evaluation:
-
- 1. **Specificity over vibes** -- "Clean UI" is banned. Name the font, spacing scale, color system.
- 2. **Empty states are features** -- "No items found" is a bug. Guide users to first action.
- 3. **Subtraction default** -- every element must earn its place. When in doubt, remove it.
- 4. **Edge cases are user experiences** -- 47-character names, zero results, slow networks, stale state.
- 5. **Four shadow paths** -- happy path, nil input, empty input, error upstream. Blank screen = Critical.
- 6. **Loading states earn trust** -- skeleton screens > spinners > blank pages.
- 7. **Consistency compounds** -- one off-system color erodes the entire design language. Tokens are contracts.
- 8. **Motion has meaning** -- decorative animation without purpose is noise.
- 9. **Accessibility is baseline** -- WCAG AA is the floor. Accessibility findings are never "Low" priority.
- 10. **Performance is perceived design** -- 3-second load feels broken regardless of visual quality.
-
- ---
-
- ## Fix Session Rules
-
- - **One issue = one question** -- never batch multiple findings.
- - **AUTO-FIX**: Cosmetic -- spacing token mismatches, off-system colors to nearest token.
- - **ASK**: Structural -- layout changes, component swaps, navigation restructuring.
- - **Max 30 fixes per session.** Hard stop, then generate report.
- - **Risk accumulator**: component (+5), global style (+8), layout (+10), revert (+15). Stop at 20% of budget.
- - **Revert on regression** -- if fix breaks visual tests or introduces Critical finding, `git revert` immediately.
-
- ---
-
- ## CI/CD Integration
-
- ```yaml
- jobs:
- design-checks:
- steps:
- - run: python scripts/color_contrast_checker.py --input color-pairs.json --level AA
- - run: |
- python scripts/design_system_validator.py --tokens tokens.json --input src/styles/ --format json > compliance.json
- python -c "import json; exit(0 if json.load(open('compliance.json')).get('compliance_percentage',0)>=90 else 1)"
- - run: python scripts/ai_slop_detector.py --input dist/index.html --threshold 0.7 --format json
- ```
-
- ---
-
- ## Anti-Patterns
-
- 1. **Scoring categories too high relative to findings** -- if there are 4 accessibility findings, the score should not be 8/10.
- 2. **Ignoring interaction states** -- every interactive element needs: default, hover, focus, active, disabled, loading, error, empty, success.
- 3. **Color as sole information carrier** -- information must not be conveyed by color alone.
- 4. **Skipping edge cases** -- test with long names, empty data, error states, not just the happy path.
-
- ---
-
- ## Troubleshooting
-
- | Problem | Cause | Solution |
- |---------|-------|----------|
- | `design_scorer.py` exits "Missing category" | Input JSON missing required keys | Ensure all 12 keys present under `categories` |
- | Color checker rejects value | Unsupported format | Use hex, `rgb()`, `hsl()`, or named colors |
- | AI slop detector finds zero on templated page | Threshold too high | Lower `--threshold` to 0.3 |
- | Validator reports "No CSS files found" | SCSS not matched | Pass `--glob "*.scss"` |
- | Scores seem inflated | Author-provided scores too generous | Re-evaluate each 0-10 score against finding count and severity |
+ ## References
- ---
+ Load the reference that matches the task — keep this file lean and pull detail on demand:
- ## References
+ - **[references/audit-workflows-and-operations.md](references/audit-workflows-and-operations.md)** — quick-start commands, tools-overview table, the three workflows (full audit, slop detection, accessibility/token compliance), grade tables, the 10 design principles, fix-session rules, CI/CD integration, anti-patterns, and troubleshooting. Read when running an audit end to end.
+ - **[references/design_audit_methodology.md](references/design_audit_methodology.md)** — systematic audit approach, heuristic evaluation, Gestalt principles, critique frameworks, and anti-patterns. Read when designing the evaluation pass.
+ - **[references/ai_slop_patterns.md](references/ai_slop_patterns.md)** — comprehensive catalog of AI-generated UI patterns and remediation guidance. Read when judging originality.
+ - **[references/accessibility_checklist.md](references/accessibility_checklist.md)** — full WCAG 2.1 Level A/AA/AAA checklist organized by POUR with testing methodology and fixes. Read when auditing accessibility.
- | Guide | Path |
- |-------|------|
- | Audit Methodology | `references/design_audit_methodology.md` |
- | AI Slop Patterns Catalog | `references/ai_slop_patterns.md` |
- | WCAG 2.1 Checklist | `references/accessibility_checklist.md` |
+ ## Scope & Limitations
- ---
+ Covers static design quality, AI-slop, WCAG contrast, and design-token compliance auditing for web UI (HTML/CSS). Does not run live browsers, render-test layouts, or replace manual usability research. Accessibility findings are never "Low" priority; WCAG AA is the floor.
## Integration Points
| Skill | Integration |
|-------|-------------|
| `senior-frontend` | Design audit on component library after build |
| `senior-qa` | Accessibility and design regression in QA pipelines |
| `code-reviewer` | Attach audit findings to frontend PR reviews |
| `senior-devops` | Gate deployments on minimum compliance scores |
| `product-team/ux-researcher` | Feed findings into usability research prioritization |
---
- **Last Updated:** April 2026
- **Version:** 2.1.0
+ **Last Updated:** June 2026
+ **Version:** 2.2.0