visual-check

name

visual-check

description

Use this skill to visually verify the pig-baron-site (Astro) in a REAL browser - it drives Chromium headless to screenshot routes, check responsive layouts at mobile and desktop widths, detect horizontal overflow, catch console/page errors, confirm every route returns 200 and images load, and smoke-test the interactions (FAQ accordion, gallery lightbox, quote-form submit→success swap, mobile nav). ALWAYS reach for it - a clean `astro build` does NOT prove the pages look right - whenever the user wants to screenshot, smoke-test, "check it in a browser", verify pages render, or look at the site; whenever they ask if a page is responsive, "looks right", "looks off", or "is squished on mobile"; whenever they worry an edit broke the layout or want to "check my work"; and proactively after you touch any page, component, global.css, or styling, and before pushing or deploying - even if they never say "Playwright", "screenshot", or "visual". Prefer it over the generic local-visual-test skill for this repo. It never opens a visible browser window.

Visual check - pig-baron-site

This project is a static Astro marketing site (warm, smoky, editorial; charcoal / cream / terracotta). A green astro build proves the templates compile - it does not prove they look right. Layout regressions (a collapsed grid, an overflowing section, a hero image that 404s, a client-side JS error that breaks the lightbox) all pass the build and only show up in a real browser. This skill is how you look, headlessly, so you can verify fidelity without asking the user to open anything.

When to use

Reach for it after touching anything visual - a page in src/pages/, a component in src/components/, src/styles/global.css, or image wiring - and any time the user asks to see, screenshot, smoke-test, or "check in a browser." Prefer it over the global local-visual-test skill for this repo: it already knows the routes, the server, and what "correct" looks like here.

One-time setup

Needs Playwright + a Chromium binary:

npm i -D playwright && npx playwright install chromium

(The browser is cached under ~/Library/Caches/ms-playwright and shared across projects, so the install is usually instant.)

Workflow

1. Start a server (build output is the source of truth for a final check):

   npm run build && npm run preview     # serves dist/ at http://localhost:4321
   # - or, mid-development -
   npm run dev                          # http://localhost:4321
   

   Start it in the background and wait for the "ready"/Local line before capturing.

2. Capture + validate with the bundled script:

   node .claude/skills/visual-check/scripts/visual-check.mjs
   

   It screenshots every route (see scripts/routes.json) at desktop (1280) and mobile (390), collects console/page errors, writes PNGs + report.json to /tmp/pb-visual/, prints a per-capture summary, and exits non-zero if any route didn't return 200 or logged an error.

   Useful flags: --all (capture EVERY built route, enumerated from dist/ - use this for "smoke-test all the pages"; the default routes.json is a fast 12-route sample, one per template), --only=/menu/,/faq/ to narrow, --viewport=mobile, --out=/tmp/pb-after (distinct dirs to compare before/after a fix), --base=http://localhost:4321.

3. Test the interactions - screenshots only prove pages render; this proves the JS works (it catches bugs a static build and a screenshot both miss, like a form that sets hidden but stays visible under a CSS display rule):

   node .claude/skills/visual-check/scripts/interaction-check.mjs
   

   It exercises the FAQ accordion, gallery lightbox, the quote form's submit→success swap, and the mobile nav toggle, asserting on real DOM/computed state. Run it whenever a change touched a component's behaviour.

4. Read the screenshots back into context and assess them against the checklist below. Reading the PNG paths is what lets you actually judge fidelity - don't stop at the text summary.

5. If something computes wrong, the global local-visual-test skill bundles a diagnose-css.mjs (node diagnose-css.mjs <url> <selector> --prop=...) that lists matched CSS rules in cascade order - handy for "why is this margin/grid wrong" once a screenshot shows the symptom.

What to validate

Hard fails (the script flags these):

• Any route not returning 200.
• Any browser console error or uncaught page error (a real JS bug - e.g. the gallery/lightbox or form script throwing). report.json has the messages.

Look for (visual judgement on the PNGs):

• Responsive: at mobile width every multi-column grid collapses to one column and nothing overflows horizontally; the header shows the hamburger.
• Section rhythm: backgrounds alternate charcoal → cream → deep-red → terracotta down the page; never two deep-red bands adjacent.
• Images render (real food photography, not empty placeholder boxes) and hero/banner images sit behind a legible gradient, not washing out the text.
• Type + palette: display headings in Bricolage Grotesque (tight, heavy), Space Mono eyebrows, the terracotta/amber accents - not fallback fonts.
• No overlap / clipping: sticky header doesn't cover content; the sticky feast price card behaves; cards don't bleed past their section.

Interactions - run interaction-check.mjs (step 3). It asserts the FAQ accordion opens one item at a time (first open on load), the gallery lightbox opens/advances/closes, the quote form shows inline errors on empty submit and swaps to the success state (form actually hidden by computed display, not just the hidden attribute) on a valid one, and the mobile nav toggles. Extend it when you add a new interaction.

Design intent (what "correct" means here)

• Palette: charcoal #181210, card-dark #221A16, cream #F2E7D5, card-cream #FBF4E7, terracotta #CB5A2E, amber #E2A33C, deep-red #5E1B14.
• Type: Bricolage Grotesque (display/headings), Hanken Grotesk (body), Space Mono (eyebrows/prices/meta, uppercase, wide tracking).
• Layout: 1240px max container, 32px gutters, pill buttons, 18px-radius cards with 1px hairline borders, generous section padding.

Full reference: docs/design_handoff_pig_baron_website/DESIGN_SYSTEM.md.

Notes

• Base path: locally the site serves at /. For a project-page deploy (/<repo>/) point --base at the right origin, or just check locally.
• CI: the deploy workflow does not run this - it stays a dev/agent tool, so the Pages build stays fast. Run it before pushing UI changes.
• Always headless. Never launch a visible browser on the user's machine.