Marcos Paulo
aae4d42229
Adds the agent-facing workspace and a 20-task plan for migrating the site to Astro. Nothing here implements the refactor; these are briefs, rules and templates that the task agents read. - .agents/ holds context, rules, checklists, skills, specialist agents, component/page/config templates and gate scripts. It is vendor-neutral so MiniMax, Gemini and Codex can all read it; CLAUDE.md just points at AGENTS.md. - .husky/ plus .lintstagedrc.json wire the three gate tiers. gate.sh locks on the shared git-common-dir so parallel worktrees serialise, and guards the assertion count in scripts/verify.mjs against a coverage drop. - plans/astro-refactor/ carries the phase graph, per-task briefs and the model-routing recommendation. These files must be tracked before fanning out: a worktree only checks out tracked files, so an untracked plan is invisible to every agent working in one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
72 lines
2.4 KiB
Markdown
72 lines
2.4 KiB
Markdown
---
|
|
name: visual-regression
|
|
description: Prove a refactor did not change how the site looks. Use before and after any page migration, token consolidation, or breakpoint change on ai-for-dummies.
|
|
---
|
|
|
|
# Visual regression
|
|
|
|
"Maintain the same styles" is a testable claim. Test it.
|
|
|
|
## Capture
|
|
|
|
The repo already has a Playwright pattern (`scripts/inspect.py`). Extend it
|
|
rather than inventing one.
|
|
|
|
```python
|
|
from playwright.sync_api import sync_playwright
|
|
ROUTES = ['/', '/full-guide/', '/summary/', '/models/', '/agents/',
|
|
'/skills/', '/rules/', '/skills-review/',
|
|
'/hands-on/starter/', '/hands-on/rules/']
|
|
WIDTHS = [560, 800, 1100, 1600]
|
|
|
|
with sync_playwright() as p:
|
|
browser = p.chromium.launch(headless=True)
|
|
for route in ROUTES:
|
|
for w in WIDTHS:
|
|
page = browser.new_page(viewport={'width': w, 'height': 900})
|
|
page.goto(f'{BASE}{route}', wait_until='networkidle')
|
|
page.screenshot(path=f'{OUT}/{route.strip("/").replace("/","_") or "index"}-{w}.png',
|
|
full_page=True)
|
|
page.close()
|
|
browser.close()
|
|
```
|
|
|
|
Run once against the vanilla site (`npm run serve`), once against
|
|
`npm run preview`. Keep both sets.
|
|
|
|
## Compare
|
|
|
|
```bash
|
|
for f in before/*.png; do
|
|
compare -metric AE "$f" "after/$(basename $f)" null: 2>&1 # ImageMagick
|
|
echo " <- $(basename $f)"
|
|
done
|
|
```
|
|
|
|
Pixel-exact is not the bar — antialiasing differs. Judge by eye where the
|
|
metric is non-trivial, and attach the pair to the task report.
|
|
|
|
## The three widths that catch the most
|
|
|
|
- **560px** — where the 16 ad-hoc breakpoints collapse to `--bp-sm`. Highest
|
|
risk in the whole migration.
|
|
- **800px** — the most common existing breakpoint; layout flips here.
|
|
- **1600px** — `min-width` rules that only fire on large screens are the ones
|
|
nobody notices are broken.
|
|
|
|
Also screenshot at the **old** breakpoint values you removed (520, 530, 600,
|
|
620, 720, 850, 880, 900), not just the new ones. Regressions hide exactly there.
|
|
|
|
## What a real difference looks like
|
|
|
|
Expect and accept: sub-pixel text shifts, antialiasing.
|
|
|
|
Investigate: anything that moves by more than ~2px, any colour change (that is
|
|
a token bug), any element that appears or disappears (that is content loss —
|
|
stop and check the snapshot diff).
|
|
|
|
## Reduced motion
|
|
|
|
Capture one pass with `prefers_reduced_motion='reduce'`. Animations must land in
|
|
their correct end state, not vanish.
|