sahin.io

All skills and agents

ui-before-after

Capture and show the owner side-by-side BEFORE/AFTER screenshots of every UI change (desktop + mobile). Use after ANY change that affects what a page looks like — static pages from server/seoRouteManifest.ts, server/publicChrome.ts, CSS, React pages/components, copy, layout, logos — before reporting the work as done or asking to ship.

Source file
.claude/skills/ui-before-after/SKILL.md

UI before/after screenshots

The owner wants to see the old and new UI for every visual change, and to approve it before anything is committed, pushed or deployed. Order for every UI change:

  1. Build the change in a scratch worktree (not the shared main checkout).
  2. Capture BEFORE and AFTER (steps 1-3 below).
  3. Show the owner the side-by-side PNGs and name every page that changed.
  4. Stop and wait for the owner's yes on that change. Do not commit, push or deploy it before then. Auto-ship applies only after the approval.

Owner, 2026-10-17: "anytime there is change in UI show me first … i will approve it before". The approval gate is per change; an earlier yes does not cover the next UI change.

1. Serve the NEW version locally

Static public pages (anything rendered by server/seoRouteManifest.ts, server/coInvestorPages.ts, server/listPages.ts, server/publicChrome.ts):

pnpm build:cloudflare   # astro build + scripts/astro-postbuild.ts (assets, manifest, worker)

Then start static-cloudflare from .claude/launch.json with preview_start (wrangler on port 8788). For a pixel comparison against origin/main instead of production, pnpm parity builds both and diffs them (scripts/parity.ts).

React-only changes: the same build (React pages are rendered by Astro).

2. Capture

npx tsx scripts/ui-compare.ts --out <scratchpad>/ui \
  --path "/#pi-companies" \
  --path "/ai#taxonomy-companies"
  • BEFORE defaults to production (https://sahin.io/angel-investments), AFTER to http://localhost:8788/angel-investments. Override with --old / --new.
  • Production is the right baseline only while it matches origin/main. If main has undeployed commits, build origin/main in a worktree, serve it on another port, and pass that as --old.
  • #id crops each side to the changed element (#.class / #[attr] take any CSS selector). Anchor on something that exists in BOTH versions, such as the heading or section just above the change, never an id the change introduces. If a selector is new, the BEFORE label says "not found, showing top".
  • Cover every page type the change touches (one representative page per type), at desktop and mobile (default; --desktop-only / --mobile-only exist).
  • Write output to the session scratchpad, never into the repo.

3. Check, then show

  • Read each PNG yourself first. If AFTER looks wrong (blank, broken layout, overflow), fix the change before showing anything.
  • Send the PNGs with SendUserFile (display: "render"), with a one-line caption per page saying what changed.
  • One screenshot per file, never a contact sheet (owner rule, 2026-11-04: "never create an image with all the screenshots, always show them separately; this should be 8 images instead of one"). Do not compose before/after pairs, grids or sheets into one PNG. Send each capture (theme × before/after × desktop/mobile) as its own file; many files in one SendUserFile call are fine. The user-level screenshots-one-per-file skill holds the same rule for every project.
  • In the reply, list which pages/viewports were captured. If a page could not be captured, say so rather than skipping it silently.

Visual regression tests (pixel-perfect)

pnpm test:visual (Playwright toHaveScreenshot, config playwright.visual.config.ts) compares 12 pages and 8 shared components, desktop and mobile, against committed baselines in tests/visual/__screenshots__/<platform>/ with at most 0.02% of pixels differing (glyph anti-aliasing noise), plus health checks (broken images, failed requests, console errors, horizontal overflow, invisible text, one <h1>). It serves dist/cloudflare behind the production prefix proxy (tests/visual/serve.ts), so build first. When a UI change is intended, run pnpm test:visual:update, review the new PNGs in the diff, and commit them with the change; npx playwright show-report tests/visual/report shows expected/actual/diff. Add new page families to tests/visual/routes.ts.

GitHub CI (.github/workflows/visual-regression.yml) runs the same suite on Linux, against tests/visual/__screenshots__/linux/, only when dispatched (gh workflow run visual-regression.yml); a failed run's visual-report artifact has the diffs. Linux baselines cannot be made on a Mac: after an intended UI change, dispatch it with "update baselines" ticked (gh workflow run visual-regression.yml -f update=true) and it commits them. It does not block the deploy.

Where a visual regression run happens: the owner decides

Owner, 2026-10-17: "all visual regression tests should be run in the local or github actions (i will decide which one) if it is small, github actions and if it is big then in local". Every visual regression run (pnpm test:visual, test:visual:update, the workflow, pnpm parity in any mode) runs either locally or on GitHub Actions, and the owner picks which. Before starting one, tell the owner its size and your recommendation, then wait for the answer:

Size What Recommend
Small the committed suite or part of it (--grep), about 40 screenshots, one run; a Linux baseline update GitHub Actions: gh workflow run visual-regression.yml (~4 billed minutes)
Big more than the committed suite: pnpm parity (builds origin/main too), --templates (~100 pages and every theme), --all, or repeated runs while fixing a failure Local: pnpm test:visual / pnpm parity … (no Actions minutes, macOS baselines)

Nothing starts a visual run on its own: the workflow has no push or pull_request trigger, and the deploy gate does not run it (server/visual-regression-placement.test.ts). The before/after screenshots above are not regression runs and need no decision. The general rule is the user-level visual-regression-placement skill.