# Local-business conversion redesign and release QA

Use this playbook for established trades and regional-business websites where brand identity and verified content must be preserved while improving trust, mobile UX, conversion, performance, and release quality.

## 1. Establish a non-destructive baseline

- Inspect `git status -sb`, branch, remotes, local/remote log, and fetch before editing.
- Never reset, clean, checkout, or overwrite unknown local changes.
- Install dependencies, run the existing check/build, inventory pages/components/assets, and search for draft-language before restructuring.
- Record which animation libraries and global scripts are truly used; remove them only after replacing any required behavior.

## 2. Separate facts, proof, and presentation

Build a verified-facts inventory before writing trust copy:

- Safe: legal name, address, telephone, established year, services, locations, and project metadata already present in canonical project data.
- Unsafe without evidence: testimonials, project counts, response times, certifications, memberships, personnel, business hours, and project-specific image attribution.
- When an archived image is real but its project identity is uncertain, use it only as a neutral work/company image. Do not attach it to a named reference.
- Remove development-state copy rather than restyling it. Public pages must not mention placeholders, future server work, hosting decisions, assumptions, or disabled uploads.

## 3. Conversion architecture for a regional trades site

Prefer a short homepage sequence:

1. Hero with one primary conversion action, one secondary contact action, and an optional text link.
2. Compact trust strip using verified claims only.
3. Three core services; link secondary services rather than giving every service equal visual weight.
4. Real featured work/reference evidence.
5. Four-step process.
6. One consolidated company/working-method section.
7. Project inquiry.
8. Closing CTA.

Consolidate repetitive “tradition / philosophy / why us / personal / process” sections. Preserve meaning, not duplication.

## 4. Honest form architecture

A static marketing site must never claim a successful submission unless a real endpoint acknowledged it.

Recommended contract:

- Read a public build-time endpoint such as `PUBLIC_FORM_ENDPOINT`.
- Treat endpoint configuration as a privacy-sensitive release gate, not just a technical toggle. Do not activate an external processor unless the responsible provider, purpose, processing/storage location, retention, and required contractual disclosure are verified.
- A robust static-site guard is to require both the endpoint and a verified public disclosure value (for example `PUBLIC_FORM_PROCESSOR_DISCLOSURE`); if disclosure is absent, compile the honest email fallback instead of silently enabling POST submission. Render the same verified disclosure on the privacy page.
- If configured, POST a JSON payload and show success only after an OK response. Avoid vague claims such as “securely transmitted” unless the security properties were actually verified.
- If absent, label the action honestly (for example, “E-Mail-Anfrage vorbereiten”), provide a copyable summary, and explain the fallback.
- Do not render upload controls without a secured, working upload path.
- Persist wizard drafts in `localStorage`, restore them on reload, and clear them only after confirmed success.
- Validate each step field-by-field with `aria-invalid`, `aria-describedby`, and useful error text; require at least one reachable contact method.

## 5. Responsive navigation and contact flow

- Desktop: compact navigation, one simple services dropdown, direct contact link, and one primary inquiry CTA.
- Mobile: logo/name plus menu button; drawer with 48px touch targets, services accordion, focus trap, Escape and outside-click closing, scroll lock, and close-on-navigation.
- Hiding a drawer with opacity, transforms, `max-height`, or `pointer-events` does not remove its links from keyboard navigation. Use `visibility: hidden`, `inert`, or equivalent focus management in the closed state; restore focus to the trigger when closing.
- For desktop dropdowns opened by `:focus-within`, removing an `open` attribute on Escape may not visually close the menu because focus remains inside. Add an explicit forced-closed state, clear it on the next pointer/focus re-entry, and cover Escape → hidden → reopen with a browser test.
- Keep the mobile header available while scrolling.
- A bottom contact bar may expose Call / WhatsApp / Inquiry; account for `env(safe-area-inset-bottom)` and add content/footer clearance so it never covers controls.

## 6. Motion and image policy

- Remove intros, sheen loops, blur transitions, and global animation stacks that delay content or mimic a component demo.
- Keep native subtle transforms, restrained image zoom, and complete `prefers-reduced-motion` behavior.
- Use a responsive `<picture>` for the hero with an explicit fallback background, dimensions/aspect ratio, mobile crop, `fetchpriority="high"`, and no fixed background attachment.
- Generate right-sized 480/800px variants for card/gallery imagery; use `srcset`, `sizes`, fixed dimensions, and lazy loading outside the LCP image.
- Self-host only the required font families/weights and use `font-display: swap`.

## 7. Accessibility and performance QA

Add Playwright smoke coverage for:

- homepage and desktop navigation;
- mobile drawer open/close, Escape, focus containment, and scroll lock;
- service links and reference filters/query state;
- wizard progression, field errors, persistence/fallback behavior;
- mobile contact links;
- horizontal overflow at every requested viewport.

Run axe on desktop and mobile. Layered image heroes can trigger false contrast results when the tool ignores positioned media/overlays: give the hero a real dark fallback background first, then verify the hero manually and with Lighthouse. Exclude a hero from axe only when the false positive is understood and another audit/manual contrast check covers it.

Release gate:

1. `npm run check`
2. `npm run build`
3. full Playwright suite
4. `git diff --check`
5. dependency audit and non-breaking fixes
6. Lighthouse mobile with actual scores recorded
7. verify sitemap, robots, canonical, Open Graph, LocalBusiness, and breadcrumbs;
8. choose one canonical hostname (`www` or apex) and use it consistently in Astro `site`, canonical/OG/JSON-LD URLs, sitemap, and `robots.txt`; probe both live hosts, and add a deploy-appropriate permanent 301/308 from the alternate host when both answer 200;
9. inventory deployed `public/` assets by source references and remove only proven-unreferenced originals after the responsive variants are verified;
10. complete final review, fetch again, confirm divergence, push, fetch, and verify local HEAD equals remote HEAD.

A delegated review is not a pre-push gate until its result has actually returned. Background delegation cannot be polled: dispatch it early enough to finish while other checks run, or perform the blocking final review synchronously. If a late review returns after publication, treat valid findings as a required follow-up fix/test/commit/push rather than dismissing them as stale.

Treat skipped project-specific duplicate tests as intentional only when the complementary project runs the scenario. Report pass/skip counts and non-blocking compiler hints honestly.

## 8. Commit and reporting structure

Prefer reviewable commits by concern:

- visual system and draft-content cleanup;
- homepage trust/conversion structure;
- responsive header/contact flow;
- inquiry and reference UX;
- performance, accessibility, SEO, and tests.

The final report should state the actual form transport, whether animation dependencies remain, which image claims were intentionally withheld, exact check/build/test/Lighthouse results, tested viewports, commit IDs, push verification, and remaining data-dependent content gaps.