# website-evaluator

A Docker-based website audit tool. Given a URL it captures screenshots, runs
Lighthouse audits (desktop + mobile), extracts DOM metadata, and assembles a
structured Markdown report designed to be read by Claude for design critique
and improvement recommendations.

## Quick Start

```bash
# Build the image
docker build -t website-evaluator .

# Evaluate a site
mkdir -p output
docker run --rm -v "$(pwd)/output:/output" website-evaluator https://example.com

# Feed the report to Claude
# Open output/report.md and paste it into a Claude conversation with:
# "Here is a website evaluation report. Please analyse it and suggest improvements."
```

## Output

```
output/
  report.md                # Primary artifact — structured Markdown for Claude
  screenshots/
    desktop.png            # Full-page desktop (1440×900)
    mobile.png             # Full-page mobile (375×812)
  raw/
    lighthouse-desktop.json
    lighthouse-mobile.json
    dom.json
```

## What the Report Covers

- **Lighthouse scores** — Performance, Accessibility, Best Practices, SEO (desktop + mobile)
- **Core Web Vitals** — LCP, TBT, CLS, TTFB with status labels
- **Critical issues** — Pre-interpreted findings with "so what" explanations and fix guidance
- **Page structure** — Title, meta description, canonical, heading hierarchy, images, links
- **Accessibility detail** — WCAG violations grouped by impact level
- **Performance detail** — Opportunities and diagnostics with estimated savings
- **SEO detail** — Meta, robots, canonical, structured data

## Milestones

| # | Scope | Status |
|---|---|---|
| M1 | Core pipeline: screenshot + Lighthouse + DOM → report.md | ✅ Complete |
| M2 | `--analyze` flag: Claude API integration, AI recommendations | Planned |
| M3 | Comparison mode: before/after and competitor diffs | Planned |

## Scripts

| Script | Purpose |
|---|---|
| `scripts/verify-m1.sh` | Smoke test: builds image, runs against example.com, checks all outputs exist |

## Architecture

```
URL in
  └─▶ Playwright: screenshot desktop (1440px) + mobile (375px) + DOM extraction
  └─▶ Lighthouse: desktop audit
  └─▶ Lighthouse: mobile audit
  └─▶ Report assembly → /output/report.md
```

Built on `mcr.microsoft.com/playwright/node:20-noble` — Chrome is bundled, no separate install needed.