Marcos Paulo
580293867d
Deletes the pre-Astro pages, scripts, and stylesheets that the migration replaced, and moves the ones it did not replace out of the way. Deleted (32 files): app.js, responsive.css, landing.css, rules/app.js, rules/styles.css, skills/app.js, the ten route index.html files, and the root hands-on/ copy, which is byte-identical to public/hands-on/ -- the one the build actually ships. Moved to legacy/ (12 files): styles.css, full-guide/audit.css, chapters.css, skills/styles.css, skills-review/styles.css, skills-review/change-lens.css, and the skills-review/app.js module graph. These are not dead. The Astro pages import them and the build fails without them, which the plan had not accounted for. They go to legacy/ rather than src/ because check-tokens.mjs sweeps src, and these files are full of raw hex and unnamed breakpoints: moving one into src/ should mean migrating it to tokens in the same change, not adding a scan exclusion. The prettier, stylelint, and eslint ignore lists that already named these files at their old paths now name legacy/ instead. verify.mjs no longer reads app.js. The 102 Portuguese strings were extracted from its translations.pt object before deletion into .agents/snapshots/full-guide-pt.json -- a legacy capture, not a snapshot of the Astro build, so the assertion still compares against an independent source. The brace-matching helper's assertion is replaced by one that rejects an empty snapshot entry, without which trimming the snapshot would make the presence check pass vacuously. Count stays at 84. audit-ui.mjs reads the ten pages from dist/ and resolves Astro's base-absolute hrefs against it. Before deleting anything, rendered-text-diff was run across all ten routes plus both Portuguese pages: every one at parity, 0 missing and 0 extra. That comparison is not repeatable once the legacy files are gone. computed-style-diff on /full-guide/ stays at 32 differences, so the moves are style-neutral. Docs updated to match: README, AGENTS.md, GATES.md, the architecture context, the operations guide's lab instructions, and the three skills that told you to serve the vanilla site. Publishing is not part of this commit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
75 lines
2.5 KiB
Markdown
75 lines
2.5 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 `pnpm run preview`. To compare against the vanilla site, serve
|
|
a pre-cutover worktree on :4173 first — those files are no longer on `main`.
|
|
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.
|