72 lines
2.3 KiB
Markdown
72 lines
2.3 KiB
Markdown
# 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.
|