Files

T

Marcos Paulo 580293867d refactor: retire the hand-written site

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>

2026-09-06 08:30:27 +00:00

2.5 KiB

Raw Blame History

name, description

name	description
visual-regression	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.

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

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.

2.5 KiB Raw Blame History