diff --git a/docs/archive/marketing-voice-v2-proposal.md b/docs/archive/marketing-voice-v2-proposal.md new file mode 100644 index 0000000..e653ff6 --- /dev/null +++ b/docs/archive/marketing-voice-v2-proposal.md @@ -0,0 +1,422 @@ +# Marketing Voice v2 — Distillation Proposal + +Proposed copy changes across the site, measured against `marketing-voice.md`. Nothing applied yet — review, redline, then I'll commit the survivors. + +The aim: cut hedges, kill restated headings, collapse repetition across pages, and replace abstract phrasing with concrete nouns. Where two sentences carry one idea, one sentence wins. + +--- + +## 1. Cross-site naming + +### "1:1" still appears in 6+ places + +We already changed the FAQ heading on the dog-walking page. The phrase still lives in navigation, footer, mega menu, decision blocks, FAQs, and SEO metadata. It's calendar-speak — customers say "solo" or "one-on-one". + +| Location | Current | Proposed | +|---|---|---| +| `homepage.ts` mobileLinks | `1:1 Walks` | `Solo Walks` | +| `homepage.ts` megaMenuServices | `1:1 Walks` / `Personalised solo walks` | `Solo Walks` / `One dog. One walker.` | +| `homepage.ts` services[1] | `1:1 Walks` | `Solo Walks` | +| `homepage.ts` testimonials.service | `1:1 Walk` | `Solo Walk` | +| `homepage.ts` booking.serviceOptions | `1:1 Walks` | `Solo Walks` | +| `homepage.ts` footer.navigationLinks | `1:1 Walks` | `Solo Walks` | +| `pack-walks.ts` paragraphs[4] | `our 1:1 walks are the better fit` | `our solo walks are the better fit` | +| `dog-walking.ts` hero.eyebrow | `1:1 Walks` | `Solo Walks` | +| `dog-walking.ts` decision.title | `Is a 1:1 walk right for your dog?` | `Is a solo walk right for your dog?` | +| `dog-walking.ts` FAQ | `1:1 walks start from...` | `Solo walks start from...` | + +Open question: keep `1:1` in SEO `` / `description` if it carries search volume, or sweep that too? I'd keep it on `llms.txt` and meta titles where the keyword has weight, drop it in body copy. + +--- + +## 2. Homepage (`homepage.ts`) + +### Hero subtitle — already tight, leave it. + +✅ Current: "Reliable dog walking across Auckland Central. Happier dogs. Quieter evenings." Keep. + +### Intro + +Current: `"Professional dog walking services across Auckland."` + +Proposal: **`"Dog walking across Auckland Central."`** +Why: "Professional services" is filler — readers already assume it. The location is the real specificity; drop "Auckland", say "Auckland Central" since that's where we actually are. + +### Founder story body + +Current: +> "Most companies sell walks. We sell a calmer evening at home." +> "Same walker. Small groups. Real attention. Your dog learns to trust one face at the door — not a rotating roster." +> "You know who has your dog. Your dog knows who is collecting them. And you come home to a tired, happy one. Ready to" + +Proposal — line 3 is doing two jobs and stumbles into the CTA: +> "Most companies sell walks. We sell a calmer evening at home." +> "Same walker. Small groups. Real attention. Your dog learns one face at the door, not a rotating roster." +> "You know who has your dog. They know who's at the door. You come home to a tired, happy one. Ready to" + +Reasons: kill "trust one face" (abstract + redundant with later "tired, happy one"), trim "to trust" (we just said we sell trust). Contraction on "they know who's" makes it sound spoken. + +### How it works — phase benefits + +The "benefit" line under each phase is doing the job of the title. Right now both compete. + +| Phase | Current title + benefit | Proposal | +|---|---|---| +| Meet | `No pressure, just clarity` + `A proper Meet & Greet at home` | Drop the benefit subtitle. Title carries enough. | +| Settle | `A smoother start for nervous dogs` + `Your dog settles in. No rushing.` | Drop benefit subtitle. | +| Thrive | `The outcome you actually want` + `Then the routine does the work` | Drop benefit subtitle — it's meta-commentary. | + +Alternative if benefit subtitles are structural: rewrite as deliverables, not vibes. `Free, 30 mins, your home` / `Two walks before regulars` / `Photo updates, every walk`. + +### Values + +Current titles read OK. Bodies have a few hedges to fix: + +- `"4 to 8 dogs. Always. Calm, structured walks with real attention for every dog."` → **`"4 to 8 dogs. Always. Calm walks, real attention."`** (drop "for every dog" — implied) +- `"Pet first aid certified. Careful screening. Proactive handling. Not extras — the baseline."` → keep, but "proactive handling" is fluff. → **`"Pet first aid certified. Careful screening. Not extras — the baseline."`** +- `"You should not have to chase your dog walker. Consistent pickup. Clear communication. Nothing to manage."` → **`"You shouldn't have to chase a dog walker. Same pickup time. Clear updates. Nothing to manage."`** (contraction, "consistent pickup" → "same pickup time") + +### Booking subtitles + +Current generalSubtitle: `"A few details. We reply properly within 24 hours."` + +"Properly" is a hedge that sounds defensive. Drop it. +→ **`"A few details. We reply within 24 hours."`** + +### Locations & Hours intro + +Current: `"We cover most of Auckland Central's suburbs:"` + +Proposal: **`"We cover Auckland Central:"`** +"Most of" is a hedge that undercuts the long list of suburbs immediately below. + +--- + +## 3. Pack Walks (`pack-walks.ts`) + +### Hero — 5 paragraphs is too many + +The hero currently delivers: who it's for, how it works, walk length, coverage, who it isn't for. Five paragraphs. Most heroes earn their keep in 2-3. The "who it isn't for" line belongs in the decision block (and it's already there). + +Proposal — collapse to three paragraphs: + +> "Tiny Gang is built for small and medium dogs who like the right kind of company. 4 to 8 dogs, matched on size and energy." +> +> "Free Meet & Greet at home, then two assessment walks. Regular slot only once we know the fit is right." +> +> "60 to 75 minutes on the ground. We rotate Western Springs, Fowlds Park, Cornwall Park, Grey Lynn Park, and Oakley Creek — picked on the day for weather and group." + +Coverage line moves down to the Highlight or Pricing block where it does work. The "if your dog isn't a fit" line lives in the decision block — no need to preview it here. + +### Pricing intro + +Current: `"Right amount of exercise. Right amount of social time. Same walker every week."` + +Proposal: **`"Right exercise. Right social time. Same walker every week."`** Cut the repeated "amount of". Reads faster. + +### Pricing plan features + +The features hedge with "Best for…" which sounds product-y. Rewrite as straight facts: + +| Plan | Current 4th feature | Proposal | +|---|---|---| +| 1 Walk Per Week | `Best for dogs starting out` | `Good for dogs starting out` (or drop) | +| 2-3 Walks Per Week | `Best fit for busy owners` | `Most popular routine` (matches `popular: true` flag) | +| 4-5 Walks Per Week | `Best for high-energy social dogs` | `For high-energy social dogs` | +| Casual Pack Walk | `Higher rate than weekly routines` | Drop — price already shows it | + +### Benefits intro + +Current: `"Small groups. Compatible dogs. No chaos. That is why it works."` + +Proposal: **`"Small groups. Compatible dogs. No chaos. That's why it works."`** Contraction. (Same pattern repeats elsewhere — see § 6.) + +### Benefit titles — abstract vs concrete + +- `"No overwhelming dynamics"` → **`"No bigger dogs to dodge"`** (concrete) +- `"A routine you can rely on"` → **`"A weekly routine that sticks"`** (matches highlight block phrasing already used on the same page) +- `"Real individual attention"` → **`"Eyes on every dog"`** +- `"Safety, built in"` → **`"Safer than a one-size pack"`** + +### Booking dogIntro + +Current: `"Tell us about your dog. Where you are. Anything we should know. We will come back about whether Tiny Gang is the right fit."` + +Proposal: **`"Tell us about your dog. Where you are. Anything we should know. We'll come back about the fit."`** Contraction, drop "whether Tiny Gang is the right" (implied from page). + +--- + +## 4. Solo Walks (`dog-walking.ts`) + +### Hero — five paragraphs again, same pattern + +Current paragraphs 1-5 cover: who it's for, the dog types, walk length, coverage, honesty-at-Meet-&-Greet. Same compression opportunity. + +Proposal — three paragraphs: + +> "Built for dogs who do better one-on-one. Their pace. Their walk. Same walker every time." +> +> "Reactive on the lead. Recovering from surgery. A senior who needs it slower. An anxious rescue still finding their feet. These are the dogs solo walks are for." +> +> "30 minutes for seniors or lower energy. 45 for most. 60 for dogs who want a longer outing. Door-to-door, photo update after every walk." + +The "honesty at Meet & Greet" sentence is already said on every other page — it's a brand-wide promise, not a hero claim. + +### Highlight points + +- `"For larger or more sensitive dogs"` body: `"When your dog needs more space, more clarity, or more attention — this gives us room to do it properly."` → **`"For dogs who need more space, clarity, or attention. We have room to give it."`** (drop "When your dog needs" → just state who it's for) + +### Pricing intro + +Current: `"Shaped around your dog, not a group schedule. For dogs who need extra attention, a steadier pace, or a more personal routine."` + +Proposal: **`"Shaped around your dog. For dogs who need extra attention, a steadier pace, or more personal time."`** Cuts "not a group schedule" (over-explained by context), trims "more personal routine" → "more personal time" (concrete). + +### Pricing plan features + +Same pattern as pack-walks. Drop hedging "Best for…" labels or rewrite as facts. + +| Plan | Current 4th feature | Proposal | +|---|---|---| +| 30 Min | `Good fit for lower-energy dogs` | `For seniors and lower-energy dogs` | +| 45 Min | `Best fit for many routines` | `Most popular length` | +| 60 Min | `Best for dogs needing a fuller outing` | `For dogs who want a longer outing` | + +### Pricing scarcityNote + +Current: `"A limited number of 1:1 slots are available each week."` + +Proposal: **`"Solo slots are limited each week."`** Active, shorter, no passive "are available". + +### Benefits intro + +Current: `"More space. Steadier handling. A pace that fits. The whole week feels easier."` + +Already strong. Keep. + +### Benefit titles + +- `"Full attention. No competition."` — keep. Strong. +- `"The walk matches their pace"` → **`"A walk at their pace"`** (more direct) +- `"Room to relax"` body has 21 words and ends in "without group pressure" — third time the page implies group pressure. Compress: **`"Without group pressure, anxious dogs move through the world more easily."`** +- `"A routine built around you both"` body: `"1:1 gives us flexibility to build a routine that works for your dog and your week."` → **`"We shape the routine around your dog and your week."`** (drop "1:1 gives us flexibility" — meta-framing, redundant) + +### Booking dogIntro + +Current: `"Tell us about your dog. Where you are. Anything we should know. We will come back about the right fit."` + +Proposal: **`"Tell us about your dog. Where you are. Anything we should know. We'll come back about the fit."`** Match pack-walks pattern; contraction. + +--- + +## 5. Puppy Visits (`puppy-visits.ts`) + +### Hero subtitle + +Current: `"While you're at work, your puppy is fed, played with, and looked after. At home."` + +This is the v1 voice-doc's chosen example. Keep. + +### Hero paragraphs + +Currently four. Paragraph 3 is the strongest (the growth-plates / vet rationale) and is buried. Reorder + tighten: + +Proposal: +> "A visit means a toilet break, fresh water, a feed if scheduled, play, and calm settling time before we leave. Photo update lands in your phone." +> +> "Short visits beat long walks while your puppy is growing. Vets recommend low-impact exercise until growth plates settle — usually 12 to 18 months. Visits give them company and stimulation without the joint stress." +> +> "Visits are also where Goodwalk usually starts. We know your puppy early, so the move to solo walks or Tiny Gang later is smooth." + +Coverage line ("Across Auckland Central — Mt Eden, Ponsonby...") goes to the chip / FAQ. Three paragraphs, clearer order: what happens → why it's right for puppies → where it leads. + +### Highlight title + +Current: `"Calm routines now. A smoother Tiny Gang later."` + +Already nice. Keep. + +### Decision footnote + +Current: `"Free Meet & Greet first. Always."` + +Already nice. Keep. + +### Pricing intro + +Current: `"Built around your puppy. Real support now. Foundations for later, if Tiny Gang is the right fit."` + +Proposal: **`"Built around your puppy. Real support now. Foundations for whatever comes next."`** "If Tiny Gang is the right fit" hedges and over-explains. The "whatever comes next" implies the same thing without conditional language. + +### Plan features — same hedge pattern + +| Plan | Current 4th feature | Proposal | +|---|---|---| +| 20 Min | `Good for shorter midday support` | `For shorter midday support` | +| 45 Min | `Best fit for many puppies` | `Most popular visit length` | +| 60 Min | `Best for pups needing more time` | `For pups who need more time` | + +### scarcityNote + +Current: `"Puppy Visit spaces are limited so we can keep care consistent."` + +Proposal: **`"Puppy Visit spaces are limited."`** The reason is obvious and over-explained. + +### Benefits intro + +Current: `"The puppy stage moves fast. Daytime visits give your puppy support now — and build the routines that make later life easier."` + +Proposal: **`"The puppy stage moves fast. Daytime visits help now, and build routines that make later life easier."`** Drop "give your puppy support" (abstract), use "help now" (concrete verb). + +### Benefit body fixes + +- `"Foundations for Tiny Gang later"` body: `"For puppies who may join Tiny Gang one day, early visits build the confidence and routines that make the next step smooth."` — TWO hedges in one sentence ("may", "one day"). → **`"For puppies who'll join Tiny Gang later, early visits build the confidence and routines that make the next step smooth."`** +- `"Support for busy owners too"` body has `"during a demanding stage"` — vague. → **`"Real help when puppies are learning fast. Guidance from someone who's been through this stage with dozens of dogs."`** + +### FAQ "How long is each visit?" + +Current answer says "30 minutes — the sweet spot" but the pricing plan starts at **20 minutes**. Inconsistency — fix the FAQ, not the price. + +Proposal: **`"20 minutes for shorter midday support. 45 minutes for most puppies. 60 minutes if your pup needs more time."`** Matches the pricing plans exactly. + +### FAQ "Can Puppy Visits lead into Tiny Gang…" + +Current: `"Exactly what they are designed for. When your puppy is old enough and the right temperament fit, we already know them well. The next step is smooth, not new."` + +Proposal: **`"Exactly what they're for. By the time your puppy is old enough, we already know them. The next step is smooth, not new."`** Contraction, drop "and the right temperament fit" (implied), drop "designed for" (passive-corporate). + +### Booking dogIntro + +Current: `"Tell us about your puppy. Where you are. Their routine. Anything we should know — and we will plan the right visit."` + +Proposal: **`"Tell us about your puppy. Where you are. Their routine. We'll plan the right visit."`** Drop "Anything we should know — and we will" (redundant, hedging). + +--- + +## 6. About page (`about.ts`) + +### "Who we are" section + +Current: +> "Alessandra started Goodwalk because she could not find a walker she trusted. So she became one." +> "She walks every dog herself. Posts photos to Instagram so you can see your dog's day. Knows some of the Tiny Gang from ten weeks old." +> "Thirty-plus five-star Google reviews say the same thing: the dogs adore her, and their owners finally stop worrying." + +Line 1 is gold. Keep. Line 2 is fine. Line 3 has "say the same thing" which is filler. + +Proposal line 3: **`"Thirty-plus five-star Google reviews: the dogs adore her, and their owners stop worrying."`** Drop "say the same thing" and "finally" (mild hedge). + +### "How we do things" + +Current: +> "Calm handling. Positive reinforcement. A walker who already knows your dog. Same principles, every walk." +> "Small packs because attention matters. Free pickup and drop-off because your day should not work around us. First aid certified. Public liability insured. That part is not negotiable." + +Line 2 is doing six things at once. Split: + +Proposal: +> "Calm handling. Positive reinforcement. A walker who already knows your dog. Same principles, every walk." +> "Small packs because attention matters. Free pickup and drop-off because your day shouldn't work around ours." +> "First aid certified. Public liability insured. Not negotiable." + +Three paragraphs, three jobs. Contraction on "shouldn't". + +### "Meet the founder" — line 3 (Maya) + +Current: `"Maya is the reason small dogs sit at the centre of everything. A Cavalier King Charles cross Shih Tzu. Opinionated. Dramatic in the rain. Completely impossible to ignore on a walk — and the best argument we have for building a service around small dogs, not one that just makes room for them."` + +Strong texture, but ends with a 27-word sentence past the voice budget (max ~24). Split: + +Proposal: +> "Maya is the reason small dogs sit at the centre of everything. A Cavalier King Charles cross Shih Tzu. Opinionated. Dramatic in the rain. Impossible to ignore on a walk." +> "She's the best argument we have for a service built around small dogs — not one that just makes room for them." + +### FAQ "Why do you specialise in small dogs?" + +Current: `"Small dogs need different pace, different group dynamics, different handling. Goodwalk was built around that — not adapted from a generic dog-walking model."` + +Proposal: **`"Small dogs need a different pace, different group dynamics, different handling. We were built around that, not adapted from a generic model."`** Active voice ("We were built" instead of "Goodwalk was built"), trim "dog-walking" (implied). + +### FAQ "What suburbs do you cover?" + +Current has 16 suburb names listed inline. The map / chips already show them. Compress: + +Proposal: **`"Most of Auckland Central — Ponsonby, Grey Lynn, Mt Eden, Kingsland, Herne Bay, Remuera and surrounds. If you're nearby and unsure, just ask."`** Cuts the list to the highest-recognition six. The exhaustive list lives on the homepage Locations block and the coverage map. + +--- + +## 7. Locations (`locations.ts`) — sweeping pattern + +Every location intro is structured the same way: descriptive lead → "well-suited / natural home / ideal place for…" → Goodwalk services available → free pickup line. Three of these in a row, the pattern shows. + +### Park descriptions — universal cleanup + +The voice doc says "Replace abstract nouns with concrete verbs". Park blurbs lean on adjective-stacks: + +- `"offers wide open paths, panoramic views across Auckland, and a mix of gentle and steeper terrain"` → **`"Wide open paths, panoramic views, gentle and steep terrain."`** (drop "offers") +- `"Popular with local dog walkers and a staple route for the Tiny Gang"` → keep. +- `"A well-used neighbourhood park… with open grass areas and shade trees"` → **`"Neighbourhood park with open grass and shade."`** + +Recommend a pass on all 30+ park descriptions: cut every "offers", "provides", "with X and Y" sentence opener, and every "well-suited / ideal place / natural home". + +### Intro pattern — propose a template + +Right now Mt Eden's intro is 71 words. Most location intros are 50-80 words. Voice doc says "Body sentences: max ~24". Propose a 3-sentence template: + +> "[Suburb] [one specific thing — geography, vibe, dog density]. [Goodwalk fact — who from here is in the Tiny Gang / what we run here]. Free pickup and drop-off." + +Worked example, Mt Eden: + +> "Mt Eden's volcanic cone, leafy streets, and mix of reserves and quiet paths make it a daily-outing favourite. We run pack walks and solo walks here weekly, with several Tiny Gang regulars based in the suburb. Free pickup and drop-off included." + +53 words → still long, but every clause does work. Apply the template to all 17 suburbs in a follow-up pass. + +--- + +## 8. Repeated lines across pages + +The phrase **"Free pickup and drop-off across Auckland Central"** (or close variants) appears 14+ times: in hero chips, paragraph 4 of every service hero, FAQ answers, the coverage map, the locations page, and the about page. It's a real selling point — but said this often it stops landing. + +Proposal — vary the wording by surface: + +- **Chip** (compact): `"Free pickup & drop-off"` +- **Hero paragraph**: usually deletable since the chip is right there. If kept: `"Pickup and drop-off included, across Auckland Central."` +- **FAQ**: keep specific — that's where someone is actually checking. +- **Footer / coverage block**: `"Door-to-door across Auckland Central."` + +Save the full sentence for places where the suburb list matters. + +--- + +## 9. Summary of recurring fixes + +If we agree on the principles below, I can sweep these patterns site-wide without you reviewing each one: + +1. **Drop "Best for / Best fit"** in pricing features. State who it's for, or drop. +2. **Contractions** ("we'll", "shouldn't", "they're") where the surrounding tone is conversational. +3. **"1:1" → "Solo"** in body copy, navigation, decision blocks. Keep "1:1" in SEO meta/title where keyword volume might matter. +4. **Cut "properly", "actually", "genuinely", "really"** unless the sentence dies without them. +5. **Cut "we will come back about"** → "we'll reply about" / "we'll come back" (less corporate). +6. **Park descriptions**: rewrite the "offers / provides / well-suited / a mix of" sentences as concrete noun phrases. +7. **Service hero paragraphs**: target 3 paragraphs, not 5. Coverage and disqualifier lines move down the page. +8. **Drop reasons that are already obvious from context** — "so we can keep care consistent", "Higher rate than weekly routines", "in your home" after "in-home". + +--- + +## What this changes for the reader + +- Faster scan on every service page (3 hero paragraphs instead of 5). +- Consistent terminology between nav, body, and CTAs (no "1:1" / "Solo" / "one-on-one" mix). +- Pricing tables stop sounding like a SaaS comparison grid. +- Location pages stop reading like council brochures. + +## What it does NOT change + +- The brand voice from `marketing-voice.md` — this proposal is a stricter application of that voice, not a rewrite of it. +- SEO `<title>` / `meta description` / `llms.txt` keywords — those remain under a separate review (the "1:1" tradeoff lives there). +- Customer testimonials — never edited. +- Service names ("Tiny Gang", "Meet & Greet") — kept verbatim. + +--- + +**Next step**: redline this file. Strike the changes you don't want, mark anything that needs different phrasing, and I'll apply the rest in one sweep. Or pick a single section to start with (homepage? service heroes? locations?) so we can validate the voice before going site-wide. diff --git a/docs/archive/v3-design-audit.md b/docs/archive/v3-design-audit.md new file mode 100644 index 0000000..a73bb80 --- /dev/null +++ b/docs/archive/v3-design-audit.md @@ -0,0 +1,252 @@ +# Design Critique — Goodwalk + +Scope: read `variables.css` end-to-end, `ValuesSection.svelte` (open in IDE), `buttons.css`, and surveyed `HeroSection.svelte`. Citing concrete drift, not generalities. + +--- + +## Issue list + +### 1. Token system has decayed into noise — the design system is the problem + +**Inconsistency.** `variables.css` defines **7 near-identical grays** (`--gray #59606d`, `--text-muted #4c5056`, `--text-muted-strong #4a4f55`, `--text-subtle #5f6369`, `--text-soft #666`, `--text-softest #6a6d72`, `--text-heading-soft #34363a`) and **6 near-identical off-whites** (`--surface-panel-soft`, `--surface-panel-muted`, `--surface-panel-warm`, `--surface-panel-cream`, `--surface-light`, `--off-white`). They differ by 1–3 hex points. + +**Why it hurts.** A design system with this many close-but-different values is functionally no system at all. Every component author picks a slightly different one. This is the engine behind every other inconsistency in the codebase. + +**Recommendation.** Collapse to: 3 grays (heading / body / muted), 2 off-whites (page / panel), 2 brand greens (primary / hover). Run a codemod replacing the deprecated tokens. Lock the file with a comment header forbidding additions without review. + +**Good looks like.** Linear's full text scale is 4 grays. Stripe's surface scale is 3. + +**Severity: Critical.** + +--- + +### 2. No radius scale exists — `variables.css` has zero `--radius-*` tokens + +**Inconsistency.** Components hand-pick: `40px` (button), `28px` (photo card), `22px` (photo card mobile), `18px` (bento + caption), `16px` (bento mobile + caption mobile), `11px` (point icon), `999px` (eyebrow). 7 different radii on one page. + +**Why it hurts.** The eye notices radius mismatches more than almost any other inconsistency — it's the silhouette of every element. A 28px card next to an 18px card next to a 22px card reads as "ported from different templates." + +**Recommendation.** Add tokens: `--radius-sm 8`, `--radius-md 14`, `--radius-lg 20`, `--radius-pill 999`. Pick **one** card radius (recommend 20). Buttons stay pill. Eyebrow stays pill. Everything else uses the scale. + +**Severity: Critical.** + +--- + +### 3. `ValuesSection.svelte` bypasses the token system almost entirely + +**Inconsistency.** In ~480 lines of CSS in this single component: +- Hardcoded colors not in tokens: `#000` (×3), `#0d1a0d` (×2), `#102010`, `#5a605f`, `#3f4348`, `#fff` (×3), `#ede4d2`, `#fcfbf6`. +- Hardcoded shadows: `0 18px 34px rgba(17,20,24,0.08)` (line 227), `0 12px 24px rgba(...)` (line 262), `0 14px 34px rgba(...)` (line 295), `0 6px 16px rgba(33,48,33,0.18)` (line 505) — when `--shadow-card`, `--shadow-panel-strong`, `--shadow-badge` already exist for these. +- Spacing values not on the 4px scale: `padding: 0 50px`, `padding: 38px 36px`, `padding: 32px 30px`, `padding: 13px 0`, `margin-top: 32px / 36px / 52px / 26px`. +- One shadow token (`--shadow-panel-elevated`, line 479) — out of ~6 shadows. The other 5 are inline. + +**Why it hurts.** This is design system drift in action. The tokens exist; they're being ignored. Every other component will do the same and the system becomes a museum. + +**Recommendation.** Replace every literal in this file with a token. If a token doesn't exist, add it and use it everywhere it applies. Then add a stylelint rule blocking raw hex and raw shadow tuples in component CSS. + +**Severity: Critical.** + +--- + +### 4. Two `<h3>`s in the same section at totally different scales + +**Inconsistency.** `.values-contrast-cell h3` is `clamp(20px, 1.9vw, 25px)`. `.values-points-title` (also `<h3>`) is `clamp(24px, 2.4vw, 32px)`. They sit in the same section, 200px apart vertically. + +**Why it hurts.** Visual hierarchy breaks. The reader's brain expects the second H3 to be peer-level with the first. Instead it's larger than the first, then `.values-point h3` (also h3) drops back to 17px. Three H3s, three scales. + +**Recommendation.** Adopt a real type scale token set: `--text-display`, `--text-h2`, `--text-h3`, `--text-h4`, `--text-body`, `--text-small`. Map every heading to a token. The "values points" introduction is functionally a sub-section header — use the same scale as the contrast cell titles, or promote it to h2-tier visually with proper hierarchy. + +**Severity: Major.** + +--- + +### 5. Photo caption layout breaks when `detail` is empty + +**Inconsistency.** `.values-photo-caption` uses `justify-content: space-between` with two spans inside. Three of five photos have `detail: ''`. The result: an empty right-side gap and a left-pinned name in a half-empty pill. On mobile, the caption switches to `display: grid; justify-content: start` (line 569) which fixes it — but the desktop is broken. + +**Why it hurts.** Looks accidental. A premium product never ships pills that are half-empty for half their content. + +**Recommendation.** Either (a) make `detail` required, or (b) when detail is empty, render only the name and center it. Conditional class in Svelte: `class:values-photo-caption-solo={!photo.detail}`. + +**Severity: Major.** + +--- + +### 6. `.btn-yellow` uses pure black text + +**Inconsistency.** `buttons.css:65` — `.btn-yellow { color: var(--text-strong); }` where `--text-strong: #000`. Every other text surface in the app uses `--gw-green #213021` or `--text-heading #1f2421`. + +**Why it hurts.** Pure black on the brand yellow is the loudest color combo on the page. It pulls the eye like a warning sign and competes with the actual content. It's also the only place pure black appears outside `.values-inner .section-heading`. + +**Recommendation.** Use `var(--gw-green)` on `.btn-yellow`. Contrast is still well above AA (≈8:1 on `#ffd100`) and the button immediately feels intentional and on-brand. + +**Severity: Major.** + +--- + +### 7. No `:focus-visible` states defined for `.btn` + +**Inconsistency.** `buttons.css` defines `:hover` and `:active` only. No `:focus-visible`. Keyboard users get the browser default outline, which on a custom pill button with `border-radius: 40px` looks broken. + +**Why it hurts.** Accessibility failure + perceived quality drop for power users. Tab through the page once and the button outlines clip the radius. + +**Recommendation.** +```css +.btn:focus-visible { + outline: 2px solid var(--gw-green); + outline-offset: 3px; +} +.btn-green:focus-visible { outline-color: var(--yellow); } +``` + +**Severity: Major.** + +--- + +### 8. `.values-inner` uses hardcoded `padding: 0 50px` + +**Inconsistency.** Line 187. The codebase already defines `--space-container-x: clamp(24px, 4vw, 48px)`. The 50px here doesn't match any other section's container padding and breaks the visual gutter rhythm down the page. + +**Why it hurts.** When sections scroll past, the left/right gutters jitter by a few pixels between sections. Reads as cheap on a calibrated monitor. + +**Recommendation.** Replace with `padding: 0 var(--space-container-x)`. Audit every section component and do the same — almost certainly this is repeated elsewhere. + +**Severity: Major.** + +--- + +### 9. Mobile eyebrow font-size drops to 11px + +**Inconsistency.** Line 549 — `.values-eyebrow { font-size: 11px; }` on mobile. Combined with `letter-spacing: 0.08em` and uppercase, this is functionally close to unreadable on a real phone. + +**Why it hurts.** Mobile readability and accessibility. Apple HIG and Material both recommend 12px minimum for body-adjacent text; uppercase tracked text should be 12–13px+ for legibility. + +**Recommendation.** Mobile eyebrow: 12px, tracking ≤ 0.06em. Or drop uppercase on mobile entirely. + +**Severity: Major.** + +--- + +### 10. Featured photo card loses its prominence on mobile + +**Inconsistency.** Lines 558–560 — `.values-photo-card-featured { grid-row: auto; min-height: 178px; }` on mobile. The whole point of the "featured" card is its larger size; on mobile it becomes a peer to the rest, and the layout decision evaporates. + +**Why it hurts.** The featured card is the strongest brand image. On mobile (where the majority of traffic comes from for local services), it's neutered. + +**Recommendation.** On mobile, make the featured card span both columns of the first row (`grid-column: 1 / -1`) with a larger min-height (~240px). Visual lead image, not a peer. + +**Severity: Major.** + +--- + +### 11. Reveal animation is slow + +**Inconsistency.** Lines 645–647 — `opacity 0.55s, transform 0.7s` with a `translateY(24px)` reveal. The cubic-bezier is fine but the durations are dated. + +**Why it hurts.** Premium products (Linear, Apple, Vercel) settle reveal animations at 0.25–0.4s. 0.7s feels like a 2015 marketing site. + +**Recommendation.** `opacity 0.3s ease, transform 0.45s cubic-bezier(0.2, 0.8, 0.2, 1)`. Reduce `--reveal-distance` to 16px. + +**Severity: Minor.** + +--- + +### 12. The "with/without" contrast cell is the page's strongest moment but ends in a quiet brand voice mismatch + +**Inconsistency.** The "good" cell ends with: *"That is what people are really buying: peace of mind, routine, and a dog who feels cared for."* — yellow text on green, font-size 13px. The footer is the punchline but it's the smallest type in the cell. + +**Why it hurts.** Hierarchy inversion. The most quotable line is treated like a footnote. + +**Recommendation.** Promote the footer to 15–16px, maintain the yellow color and family. Add a small top divider only on the negative cell so the positive cell's footer reads as continuous emphasis. + +**Severity: Minor.** + +--- + +### 13. `.values-bento` uses a 1px gap + ink-tinted background trick for hairlines + +**Inconsistency.** Line 290 — `gap: 1px; background: rgba(17, 20, 24, 0.1);` to simulate dividers. This is fine technique but the resulting line color (`rgba(ink, 0.1)`) is darker than the actual borders elsewhere in the system (`--border-soft 0.05`, `--border-muted 0.08`). + +**Why it hurts.** Bento dividers read heavier than every other border on the page. The card looks "boxier" than its neighbors. + +**Recommendation.** Drop the gap-background trick to `rgba(var(--ink-rgb), 0.06)` or a real `--border-soft-strong` token. Match the rest of the system. + +**Severity: Polish.** + +--- + +### 14. `.values-contrast-num` ("01", "02") in `rgba(17, 20, 24, 0.22)` is barely visible + +**Inconsistency.** Decorative numbering at ~3:1 contrast. + +**Why it hurts.** If it's decorative, that's fine. But it's currently big enough to look like it's *supposed* to be read. Either commit to it being a design element (larger, more confident) or make it functional (numbered as a real step indicator). + +**Recommendation.** Either bump to 32px+ with the same low opacity (treats it as a visual mark, like editorial step numbering) or remove entirely. Half-measures are the worst outcome. + +**Severity: Polish.** + +--- + +## Global Design System Drift + +1. **Tokens written but not consumed.** `--shadow-card`, `--shadow-panel-strong`, `--surface-panel-warm`, `--text-muted`, `--border-soft` exist, but `ValuesSection.svelte` re-implements all of them inline. Likely repeated in every section component. +2. **Spacing scale (`--space-1` … `--space-14`) is ignored.** Every padding/margin in `ValuesSection` is a literal pixel value off the 4px grid (`50px`, `38px`, `36px`, `30px`, `26px`, `22px`, `18px`, `13px`, `9px`). +3. **No radius scale at all.** Every component invents its own. +4. **No type scale.** Headings use `clamp()` with different formulas everywhere. +5. **Seven grays, six off-whites, three greens** in the token file — the surface area of the system exceeds what any human can use consistently. +6. **Hardcoded shadows.** The shadow tokens are a *complete* shadow system that nobody is calling. +7. **Hover states use `translateY(-2px) scale(1.012)` everywhere on `.btn`** — but card hovers in `ValuesSection` use `transform: scale(1.06)`. No shared motion language. + +--- + +## Fast Wins + +1. **Find/replace every raw hex color in `ValuesSection.svelte`** with a token. ~30 minutes. Immediate consistency lift. +2. **Replace `.values-inner { padding: 0 50px }` with `padding: 0 var(--space-container-x)`** and do the same in every section component. ~20 minutes. Fixes the section-to-section gutter jitter. +3. **Add `--radius-sm/md/lg/pill` tokens and codemod components to use them.** Pick 20px as the universal card radius. ~1 hour. +4. **Switch `.btn-yellow` text to `var(--gw-green)`.** 5 minutes. Big perceived-quality lift — the page stops shouting. +5. **Add `:focus-visible` to `.btn`.** 5 minutes. Accessibility + polish. +6. **Fix the photo caption layout when `detail` is empty.** 10 minutes. Removes the only broken-looking element on the page. +7. **Bump mobile featured photo to `grid-column: 1 / -1`.** 2 minutes. Mobile hero moment. + +--- + +## Premiumisation Opportunities + +1. **Collapse the gray palette to 3 values** and the off-white palette to 2. Premium brands feel calm because their surface palette is small. +2. **Speed up all reveal/hover transitions to 0.25–0.4s.** Slower motion now reads as a slow site. +3. **Replace pure-black text (`#000`) with `var(--gw-green)` or `var(--text-heading)` everywhere.** True black on warm off-white feels harsh; the dark green keeps it editorial. +4. **Tighten letter-spacing on display headings** to `-0.03em`. Mid-2020s premium look. Bonus: add `text-wrap: balance` to all h2s. +5. **Replace the bento dividers** with `--border-soft` and add a barely-visible inner highlight (`inset 0 1px 0 rgba(255,255,255,0.5)`) for the elevated feel Linear uses on dark surfaces. +6. **Promote the "punchline" copy** (the contrast-footer lines) to body-lead size. Stop hiding the best writing in 13px. +7. **Inline social proof under the contrast cells.** "Joined by 200+ Auckland owners" or a row of three small testimonial avatars with rating. The section currently asserts emotional benefits without proof — easy E-E-A-T win. + +--- + +## Mobile Audit + +- **Eyebrow text is 11px** with uppercase + 0.08em tracking — sub-legible. Bump to 12px, drop tracking to 0.06em. +- **Featured photo loses its purpose** — collapses to peer-card. Fix with `grid-column: 1 / -1; min-height: 240px`. +- **Photo caption switches to vertical stack** (good) but `.values-photo-detail` runs through `-webkit-line-clamp: 2` even when detail is empty — leaves a weird invisible vertical reserve. Conditionally hide the element when empty. +- **Container padding** uses `--space-container-x-mobile` (24px). Other components on the site may use the desktop 50px hardcode plus naive scaling — verify all sections collapse to a consistent 24px gutter. +- **Tap targets** — the photo cards are large (~178px tall) and tappable hover scales aren't useful on touch. Hover scale lifts to `1.06` on tap-through devices look glitchy on iOS Safari. Wrap in `@media (hover: hover)` (already done — good) but verify the photo `:hover` rule is also gated (line 242 — good, it is). +- **No visible scroll affordance** between the contrast cells and the values-points header — 30px gap on mobile (line 617). Reads as cramped. +- **`.btn` padding `13px 28px`** on mobile yields ~44px tall tap targets only if line-height holds. Hero CTA stack untested in this audit but worth verifying tap area ≥48px on the primary booking CTA. + +--- + +## Final Verdict + +**What makes it feel inconsistent.** A real design system exists in `variables.css` but the components don't use it. Components ship with raw hex, raw pixels, raw shadow tuples, and inconsistent radii. The token file has too many near-duplicate values, which is what enabled the drift in the first place. + +**What is preventing it from feeling premium.** Loud black-on-yellow CTA, slow reveal animations, seven different gray tones in the same viewport, radius drift between cards, missing focus states, and one or two broken elements (empty captions, mobile featured card collapse) that read as accidental rather than intentional. + +**Top 5 highest-ROI changes:** + +1. **Collapse the token palette** (3 grays, 2 off-whites, add `--radius-*` scale) — this is the precondition for everything else holding. +2. **Codemod `ValuesSection.svelte` (and peer components) to consume tokens exclusively** — kills 80% of the visual inconsistency in one pass. +3. **Switch `.btn-yellow` text to `--gw-green` and add `:focus-visible`** — instant perceived-quality lift on the most-clicked element. +4. **Speed up reveal/hover transitions to 0.25–0.4s** — the single biggest "feels modern" lever. +5. **Fix the photo caption (empty-detail case) and the mobile featured card** — two small fixes that remove the only "homemade" moments on the section. + +These are systems-level fixes, not redesigns. The CLAUDE.md mandate to preserve the WordPress visual design is respected — none of this changes layout, color brand, or hierarchy. It tightens the existing system into something that holds together. diff --git a/docs/comparison-page-plan.md b/docs/comparison-page-plan.md new file mode 100644 index 0000000..611fee6 --- /dev/null +++ b/docs/comparison-page-plan.md @@ -0,0 +1,237 @@ +# Dog Walker vs Doggy Daycare vs Pet Sitter vs Dog Boarding — Comparison Page + +**Page type:** Service-type comparison (category, not named competitors) +**Target URL:** `/dog-walker-vs-daycare-vs-pet-sitter` (or `/blog/dog-walker-vs-daycare-vs-pet-sitter-auckland`) +**Word count target:** 1,800–2,200 words +**Last updated:** 2026-05-17 +**Author:** Alessandra (Goodwalk founder) + +--- + +## Why this page exists (strategy note — not for publication) + +A service-type comparison captures research-stage Auckland owners who are still deciding *what kind of care* their dog needs before they decide *who to book*. It is high-intent, not transactional, but it qualifies the reader and feeds them into the booking flow once they self-identify as needing a dog walker. + +This page is safer than a named-competitor comparison because every claim is about service categories, not specific businesses, so there is no fairness or defamation risk. It also has broader search volume — "dog walker vs daycare" is searched far more than any "Goodwalk vs X" phrase ever will be. + +--- + +## Primary keyword + +`dog walker vs doggy daycare` + +## Secondary keywords + +- `doggy daycare vs dog walker` +- `dog walker vs pet sitter` +- `dog boarding vs daycare` +- `do I need a dog walker or daycare` +- `is a dog walker better than daycare` +- `best dog care option while at work auckland` + +## Long-tail / question keywords (for FAQ / H3s) + +- "How often should my dog go to daycare vs a walker" +- "Is daycare too much for an anxious dog" +- "Pet sitter or dog walker for a puppy" +- "Cheapest reliable dog care while at work Auckland" + +## Title tag (under 60 chars) + +`Dog Walker vs Daycare vs Pet Sitter: Which One Fits Your Dog?` + +## Meta description (under 155 chars) + +`Auckland dog owners compare dog walking, daycare, pet sitting and boarding side by side — costs, energy fit, socialisation, and which works for working owners.` + +## H1 + +`Dog Walker vs Doggy Daycare vs Pet Sitter vs Dog Boarding — Which One Actually Fits Your Dog?` + +--- + +## Page structure + +### 1. Hero / Above-the-fold summary (120–180 words) + +- One sentence that names all four options. +- Two-sentence honest verdict: "For most working Auckland owners with a healthy adult dog, a midday dog walker is the calmest and most cost-effective option. Daycare and boarding suit specific cases — high-energy dogs, long trips, multi-day absences — and pet sitters fill the in-home-care gap." +- Primary CTA above fold: **"See Goodwalk's pack walk and puppy visit options"** → links to `/our-services` or booking section. +- Trust line: "Written by Alessandra, founder of Goodwalk, walking dogs across Auckland Central." + +### 2. Quick decision matrix (the headline feature) + +A scannable table that answers the question in 10 seconds. This is the section that earns featured snippets and AI Overview citations. + +| What you need | Best fit | Why | +|---|---|---| +| Midday break while you're at work, calm dog | **Dog walker** | One-on-one or small group, short absence from home, no overstimulation | +| Highly social, high-energy dog who hates being alone | **Doggy daycare** | All-day stimulation and dog-on-dog play | +| You're away overnight or longer | **Dog boarding** or **in-home pet sitter** | Overnight care and feeding | +| You're away 1–3 nights and want your dog at home | **Pet sitter (in-home)** | Familiar environment, lower stress | +| Anxious, reactive, senior or recovering dog | **Dog walker (solo or tiny group)** | Predictable, low-stimulation routine | +| Puppy mid-day toilet break + socialisation | **Puppy visit / short walk** | Daycare often too much before 6 months | + +### 3. Side-by-side feature comparison (the matrix the skill calls for) + +Word count target for this section + surrounding prose: ~400 words. + +| Factor | Dog walker | Doggy daycare | Pet sitter (in-home) | Dog boarding | +|---|:---:|:---:|:---:|:---:| +| Duration per session | 30–60 min | 4–10 hrs | Multiple visits / overnight at your home | Overnight at sitter's home or facility | +| Dog stays in own home | ✅ | ❌ | ✅ | ❌ | +| Overnight care | ❌ | ❌ | ✅ | ✅ | +| Dog-on-dog socialisation | ⚠️ Small group only | ✅ High | ❌ Minimal | ⚠️ Varies | +| Suitable for anxious / reactive dogs | ✅ Often | ❌ Usually not | ✅ Yes | ⚠️ Depends on setup | +| Suitable for puppies under 6 months | ✅ Short visits | ⚠️ Some daycares accept, many don't | ✅ Yes | ⚠️ Varies | +| Typical Auckland price (per session/day) | ~$30–$50 | ~$45–$70 | ~$60–$90/night | ~$55–$95/night | +| Booking flexibility | High (recurring or ad-hoc) | Often needs membership | Medium | Low (peak periods book out) | +| Stimulates without exhausting | ✅ | ⚠️ Can over-stimulate | ⚠️ Depends | ⚠️ Varies | + +> **Pricing disclaimer:** Indicative Auckland market ranges as of May 2026. Always confirm current rates directly with each provider. + +### 4. Detailed sections on each service type (~300 words each) + +#### 4a. What a dog walker actually does + +- One-on-one or tiny-group walks (Goodwalk runs "Tiny Gang" pack walks — max 4 dogs). +- Typical Auckland Central session: pickup → walk → drop-off, 60 minutes including travel. +- Best fit profile: dog who lives in an apartment or small section, owner working 8–6, needs one structured outdoor break a day. +- Honest limitation: doesn't solve all-day separation if your dog has severe separation anxiety — pair with daycare or sitter on long days. +- **Internal link:** to `/services/dog-walking` and `/services/pack-walks`. + +#### 4b. What doggy daycare actually does + +- All-day group play in a facility. +- Best fit: high-drive, highly social adult dogs who genuinely enjoy busy environments. +- Honest limitation: not every dog enjoys daycare even if they "love other dogs" on walks — sustained group play is a different intensity. Many trainers caution against daycare for under-6-month puppies due to over-stimulation and inconsistent play partners. +- Cost: usually the most expensive recurring weekday option in Auckland. +- No Goodwalk service in this category — acknowledge that openly. This builds trust. + +#### 4c. What a pet sitter does + +- Visits your home (or stays overnight) to feed, toilet, play, and check on your dog. +- Best fit: short trips (1–4 nights), dogs who don't travel well, multi-pet households. +- Honest limitation: less physical exercise than a walker provides; usually pair-able with a dog walking service for longer absences. +- **Internal link:** to `/services/puppy-visits` (closest Goodwalk offering — short check-in visits). + +#### 4d. What dog boarding actually does + +- Your dog stays overnight at a boarder's home or kennel facility. +- Best fit: longer absences (1+ weeks), owners without an in-home sitter option. +- Honest limitation: change of environment is stressful for some dogs; book ahead — Auckland boarders fill up over school holidays and summer. + +### 5. Cost comparison over a typical month (~150 words) + +Example scenario: working owner, healthy 3-year-old labrador, gone 9–5 weekdays. + +| Option | Frequency | Monthly cost (indicative) | +|---|---|---| +| Dog walker, 3x/week | 12 sessions | ~$360–$600 | +| Daycare, 3x/week | 12 days | ~$540–$840 | +| Daycare 1x + dog walker 2x | mixed | ~$300–$600 | +| Dog walker 5x/week | 20 sessions | ~$600–$1,000 | + +The "daycare 1x + walker 2x" hybrid is what many Auckland owners settle on — one social day and two calmer walking days per week. + +### 6. Decision flowchart (short, ~100 words + visual) + +A simple text flow that AI search engines can lift verbatim: + +> 1. Are you away for more than 24 hours? → **Pet sitter or boarder.** +> 2. Is your dog highly social and high-energy? → **Daycare 1–2 days/week + walker on quiet days.** +> 3. Is your dog anxious, reactive, senior or under 6 months? → **Dog walker, solo or tiny group.** +> 4. Standard adult dog, normal energy, working hours? → **Dog walker, 2–5x/week.** + +### 7. FAQ section (5–7 questions, each 50–90 words) + +Designed for FAQPage schema and AI Overview citations. + +1. **Is a dog walker enough if I work 9–5?** +2. **Is daycare too stimulating for puppies?** +3. **Can I combine a dog walker with daycare?** +4. **What's cheapest: walker, daycare, or sitter?** +5. **Which option is best for an anxious or reactive dog?** +6. **Do I need a dog walker every day?** +7. **What's the difference between a pet sitter and a dog walker?** + +### 8. Closing CTA + author bio (~120 words) + +- One-paragraph honest summary: "If you've read this far and your dog is a normal-energy adult or a puppy who lives in Auckland Central, a midday dog walker is almost always the right starting point. Daycare and boarding are real options for specific cases — but the default answer for most owners is a walker." +- CTA block: **"Book a Tiny Gang pack walk"** + secondary "See pricing". +- Author bio: 2–3 lines on Alessandra, with a photo. Credibility signal for E-E-A-T. + +--- + +## Conversion / CTA placement + +- **Above fold:** soft CTA — "See our walks" (not a booking ask yet, since they're still researching). +- **End of section 4a (dog walker explainer):** strong CTA — "Book a Goodwalk walk". +- **End of decision flowchart:** medium CTA — "See pricing and walk options". +- **Footer of page:** final CTA + "Questions? Text Aless on [number]". + +Avoid any CTA inside sections 4b/4c/4d (daycare, sitter, boarding) — that's where the page earns trust by *not* trying to convert. + +--- + +## Internal linking plan + +**Outbound from this page:** +- `/our-services` (services overview) +- `/services/dog-walking` (slug-driven service page) +- `/services/pack-walks` +- `/services/puppy-visits` +- `/our-pricing` +- `/contract` (for owners ready to onboard) + +**Inbound to this page (add links from):** +- Homepage FAQ section +- `/our-services` page footer ("Not sure which service fits? Read our comparison") +- Each individual service landing page sidebar/below-the-fold +- Blog posts that mention service trade-offs + +**Cross-links to build next:** +- "Pack walks vs solo walks — which is right for your dog?" (Goodwalk-internal comparison) +- "When should I start dog walks with my puppy?" (FAQ-style) +- "Auckland Central dog walking suburbs we cover" (already in `/locations`) + +--- + +## E-E-A-T signals to include on the page + +- Author byline with Alessandra's photo and 2-line bio +- "Last updated: [date]" near the top +- Methodology sentence: "Pricing ranges reflect publicly listed Auckland rates surveyed May 2026 and are indicative only." +- At least one customer quote (from existing testimonials) about *why they chose a walker over daycare* +- Link to Auckland Council dog registration page (existing trust signal already on site) + +--- + +## Fairness checklist (skill requirement) + +- [x] No named-competitor claims — service-category comparison only +- [x] Pricing flagged "as of May 2026, indicative" +- [x] Acknowledges where Goodwalk doesn't compete (daycare, boarding) +- [x] Recommends combining services where genuinely best for the dog +- [x] No exaggerated claims about walker superiority — recommendation is conditional on dog profile + +--- + +## Content gaps vs typical Auckland search results + +Most existing Auckland-region comparison content is either: +1. **Generic global content** with US/UK pricing and no local relevance. +2. **Daycare-operator pages** that always conclude "daycare is the answer." +3. **Aggregator listings** with no genuine comparison. + +Goodwalk's advantage: written by a working Auckland walker with first-hand knowledge of which dogs thrive in which service. The honest "we don't do daycare and here's when daycare is actually the right call" framing is the differentiator. + +--- + +## Recommendations (next steps after this page ships) + +1. **Add FAQPage schema** (see `comparison-schema.json`) so the FAQ block is eligible for rich results. +2. **Build the two cross-link pages** ("pack walks vs solo walks", "when to start puppy walks") to strengthen the cluster. +3. **Add a comparison shortcut from the homepage hero** — a small "Not sure which service fits?" link → this page. +4. **Quarterly review reminder** — update pricing ranges and any factual claims every 3 months. +5. **Consider a downloadable one-pager** of the decision flowchart for email-list signups (lead magnet). diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..cac9354 --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,341 @@ +# Deployment + +## Hosts served by this stack + +The Goodwalk Svelte stack serves three subdomains from the same SvelteKit app +container, routed by Host header at nginx: + +| Hostname | Purpose | +|-----------------------------|--------------------------------------------| +| `goodwalk.co.nz` / `www.…` | Public marketing site | +| `clients.goodwalk.co.nz` | New-client onboarding + contract portal | +| `cp.goodwalk.co.nz` | Owner admin dashboard (Aless only) | + +The shared nginx container reads TLS material from its host bind mount at +`/docker/certbot/conf`, exposed inside the container as `/etc/letsencrypt`. +The deploy scripts now auto-bootstrap any missing certificates referenced by +the shared nginx config, including `clients.goodwalk.co.nz`, +`cp.goodwalk.co.nz`, and the legacy HTTPS redirect aliases +`onboarding.goodwalk.co.nz` and `admin.goodwalk.co.nz`. They do that by +temporarily loading an HTTP-only nginx config and running `certbot/certbot` +against the mounted ACME webroot. The only prerequisite is that each +hostname's DNS A record already points at the droplet and port `80` is +reachable. + +The dashboard's data (`client_profiles`, `allowed_emails`, `drafts`) lives in +the shared postgres database alongside the marketing site content, in a single +`admin_kv` table created by `docker/postgres/init/002-admin-kv.sql`. The +mail-api connects with the same `DATABASE_URL` the SvelteKit app uses. + +### Seeding admin_kv from the old JSON files + +Existing installs have admin data in `client_profiles.json`, +`allowed_emails.json`, and `drafts.json` on the mail-api Docker volume. To copy +that data into postgres on the next deploy, run: + +```powershell +./deploy.ps1 -SeedAdminData +``` + +That sets `ADMIN_DATA_SEED_FROM_JSON=force` for the mail-api container, which +overwrites `admin_kv` from the JSON files on the next boot. Subsequent deploys +default back to `auto` (seed only when `admin_kv` is empty), so they are no-ops +for the seed. Use `-SeedAdminData` again if you ever need to force a re-seed. + +## Server layout confirmed + +The production server currently runs multiple separate Docker Compose projects: + +- Main public site WordPress stack: + - project: `goodwalkconz` + - path: `/docker/wordpress/goodwalk.co.nz` +- Legacy onboarding WordPress stack: + - project: `onboardinggoodwalkconz` + - path: `/docker/wordpress/onboarding.goodwalk.co.nz` +- Shared nginx: + - project: `nginx` + - path: `/docker/nginx` +- Shared mysql: + - project: `mysql` + - path: `/docker/mysql` + +The deployment scripts in this repo are set up to deploy the new Svelte site as a +separate stack at: + +- remote path: `/docker/goodwalk-svelte` +- compose file: `docker-compose.prod.yml` +- docker project: `goodwalk-svelte` + +This leaves the onboarding site, shared nginx, shared mysql, and other unrelated +containers untouched. + +## Files involved + +- [deploy.ps1](deploy.ps1) + - Windows entrypoint for packaging the repo, uploading it, and running the + remote deployment helper over SSH. +- [scripts/deploy.ps1](scripts/deploy.ps1) + - Deprecated compatibility wrapper that forwards to the repo-root + `deploy.ps1`. Keep using the root script directly. +- [scripts/deploy-remote.sh](scripts/deploy-remote.sh) + - Server-side helper that updates only the `goodwalk-svelte` compose project. +- [scripts/deploy-from-git.sh](scripts/deploy-from-git.sh) + - Standalone server-side entrypoint that pulls from Git, then runs the same + compose/nginx deployment steps on the server. +- [docker-compose.prod.yml](docker-compose.prod.yml) + - Production compose file for the new Svelte app, mail API, and Postgres. +- `scripts/export-homepage-content.mjs` + - Local helper that exports the current `src/lib/content/homepage.ts` into a + deployable JSON payload before each deployment. +- `scripts/sync-homepage-content.mjs` + - Runtime helper that upserts the exported homepage content into PostgreSQL + after deploys that affect the app/database. +- [ssh-config](ssh-config) + - Repo-local SSH config used by the deployment script. +- [nginx/goodwalk.co.nz.svelte.conf.example](nginx/goodwalk.co.nz.svelte.conf.example) + - Example shared-nginx config for routing the main public site to the new + Svelte app and mail API, including the `clients` and `cp` subdomains. + +## First-time server preparation + +1. Fill in [ssh-config](ssh-config) with the real host details. + +2. Create the deployment directory on the server: + +```bash +mkdir -p /docker/goodwalk-svelte +``` + +3. The first deployment will auto-create the production env file on the server at: + +```bash +/docker/goodwalk-svelte/.env +``` + +It is created from [deploy.env.template](deploy.env.template). Current template contents: + +```env +APP_VERSION=4.0.1 +ENABLE_GENERAL_ENQUIRIES=false +PUBLIC_ENABLE_MOBILE_CTA_BUTTON=false +PUBLIC_ENABLE_ENHANCED_CONTENT_IMAGES=false +TZ=Pacific/Auckland + +POSTGRES_DB=goodwalk +POSTGRES_USER=goodwalk +POSTGRES_PASSWORD=gw_Pg_7Jm9!Qx4#Ld2@Vr8 +POSTGRES_PASSWORD_URLENCODED=gw_Pg_7Jm9%21Qx4%23Ld2%40Vr8 + +RESEND_API_KEY=replace-me +OWNER_EMAIL=replace-me +SECONDARY_CP_EMAIL= +SECONDARY_CP_EMAILS= +FROM_EMAIL=GoodWalk <bookings@goodwalk.co.nz> +REPLY_TO=aless@goodwalk.co.nz +MAIL_API_DATA_DIR=/app/data + +FORM_MIN_SECONDS=4 +FORM_MAX_SECONDS=7200 +RATE_LIMIT_WINDOW_SECONDS=900 +RATE_LIMIT_MAX_PER_IP=5 +RATE_LIMIT_MAX_PER_EMAIL=3 +RATE_LIMIT_MIN_INTERVAL_SECONDS=20 +EMAIL_SEND_TIMEOUT_SECONDS=20 +``` + +After the first deploy, edit `/docker/goodwalk-svelte/.env` on the server and replace: + +- `RESEND_API_KEY=replace-me` +- `OWNER_EMAIL=replace-me` + +Optional CP dashboard admins: + +- `SECONDARY_CP_EMAIL=person@example.com` +- `SECONDARY_CP_EMAILS=bob@smith.com;bobsmith2@smith.com` + +`OWNER_EMAIL` always keeps CP access. The secondary values are optional and may be +semicolon-, comma-, or whitespace-separated. + +Frontend flags: + +- `PUBLIC_ENABLE_MOBILE_CTA_BUTTON=false` keeps the sticky mobile booking CTA hidden. +- Set `PUBLIC_ENABLE_MOBILE_CTA_BUTTON=true` to show it again. +- `PUBLIC_ENABLE_ENHANCED_CONTENT_IMAGES=false` skips eager `@sveltejs/enhanced-img` processing for content images during production builds. Turn it on only if you intentionally want non-WebP images from `src/lib/images` to go through the imagetools pipeline. + +4. Confirm the shared Docker network already exists: + +```bash +docker network ls | grep webnet +``` + +Your server already uses `webnet`, so this should already be present. + +5. Confirm the shared nginx compose mounts still point at the host certbot + paths expected by the deploy scripts: + +```yaml +- /docker/certbot/conf:/etc/letsencrypt:ro +- /docker/certbot/www:/var/www/certbot:ro +``` + +The scripts inspect the running `nginx` container to derive those host paths +before checking or issuing certificates. + +## First deploy + +From Windows PowerShell in the repo root: + +```powershell +powershell -ExecutionPolicy Bypass -File .\deploy.ps1 +``` + +This is the single supported deployment entrypoint. If you see +`scripts/deploy.ps1`, that file now just forwards to the root script so the +deployment logic only lives in one place. + +Or skip the confirmation prompt: + +```powershell +powershell -ExecutionPolicy Bypass -File .\deploy.ps1 -Force +``` + +To rebuild and restart only one service, for example the mail API: + +```powershell +powershell -ExecutionPolicy Bypass -File .\deploy.ps1 -Force -Service mail-api +``` + +## Remote Git deploy + +If you want the production server to pull straight from Gitea instead of +receiving an uploaded tarball from Windows, use +[scripts/deploy-from-git.sh](scripts/deploy-from-git.sh) on the server. + +Recommended credential setup for a private HTTPS repo: + +```bash +umask 077 +cat > ~/.netrc <<'EOF' +machine g.sublogue.com +login YOUR_GITEA_USERNAME +password YOUR_READ_ONLY_TOKEN +EOF +chmod 600 ~/.netrc +``` + +Install the script on the server and make it executable: + +```bash +install -m 0755 scripts/deploy-from-git.sh /usr/local/bin/goodwalk-deploy +``` + +The remote host must have `git` and `docker`. A host-level `node` install is +optional; if it is missing, the script will export homepage content using a +temporary `node:22-alpine` container instead. + +Run a full deploy from the repo: + +```bash +/usr/local/bin/goodwalk-deploy \ + --repo-url https://g.sublogue.com/admin/gw-svelte.git \ + --branch main \ + --deploy-path /docker/goodwalk-svelte \ + --compose-file docker-compose.prod.yml \ + --project-name goodwalk-svelte \ + --nginx-source nginx/goodwalk.co.nz.svelte.conf.example \ + --nginx-target /docker/nginx/conf.d/goodwalk.co.nz.conf \ + --nginx-compose-file /docker/nginx/docker-compose.yml \ + --nginx-project-name nginx \ + --maintenance-host-dir /docker/nginx/maintenance \ + --maintenance-flag /docker/nginx/conf.d/maintenance.flag +``` + +Deploy a specific commit or tag: + +```bash +/usr/local/bin/goodwalk-deploy \ + --repo-url https://g.sublogue.com/admin/gw-svelte.git \ + --branch main \ + --ref <commit-or-tag> \ + --deploy-path /docker/goodwalk-svelte \ + --compose-file docker-compose.prod.yml \ + --project-name goodwalk-svelte \ + --nginx-source nginx/goodwalk.co.nz.svelte.conf.example \ + --nginx-target /docker/nginx/conf.d/goodwalk.co.nz.conf \ + --nginx-compose-file /docker/nginx/docker-compose.yml \ + --nginx-project-name nginx \ + --maintenance-host-dir /docker/nginx/maintenance \ + --maintenance-flag /docker/nginx/conf.d/maintenance.flag +``` + +## Homepage content sync + +Local development can feel fresher than production because production reads the +homepage/shared content from PostgreSQL whenever `DATABASE_URL` is set. + +The deployment flow now handles that automatically: + +1. `deploy.ps1` exports the current `src/lib/content/homepage.ts` into + `deploy-data/homepage-content.json`. +2. The deploy archive uploads that JSON payload with the app source. +3. After the Goodwalk stack is updated, the remote helper runs a content sync + inside the app container. +4. That sync upserts the `homepage` row in `site_content`. + +This means future deploys will carry your latest file-based homepage/navigation/ +shared content changes into production PostgreSQL automatically. + +## Mail auth persistence + +The mail API stores auth state in `DATA_DIR`, including: + +- `allowed_emails.json` +- `client_profiles.json` +- `drafts.json` + +Both compose files now mount a named Docker volume at `MAIL_API_DATA_DIR` +(default `/app/data`) so previously registered client emails and saved drafts +survive container rebuilds and redeploys. + +## Cutover nginx + +After the new Svelte stack is up and healthy, update the shared nginx config on +the server for the main site. + +Current live file: + +```bash +/docker/nginx/conf.d/goodwalk.co.nz.conf +``` + +Use the repo example as the new target config: + +```bash +nginx/goodwalk.co.nz.svelte.conf.example +``` + +Important: +- `deploy.ps1` now copies the repo nginx config to `/docker/nginx/conf.d/goodwalk.co.nz.conf` and reloads the shared nginx container as part of deployment. +- The repo nginx config uses Docker's internal resolver so future app/mail container rebuilds will not leave nginx pinned to stale upstream IPs. +- The same nginx config now also routes `clients.goodwalk.co.nz` to the Svelte app and `/api/onboarding-submit` to the shared mail API. +- The owner dashboard is now served on `cp.goodwalk.co.nz`. +- `onboarding.goodwalk.co.nz` and `admin.goodwalk.co.nz` should be kept only as redirect aliases once their DNS and TLS are in place. +- The deploy script will attempt to issue any missing certificates for `clients.goodwalk.co.nz`, `cp.goodwalk.co.nz`, and `onboarding.goodwalk.co.nz` before the final nginx reload. + +Manual nginx commands, if you ever need them: + +```bash +docker compose -p nginx -f /docker/nginx/docker-compose.yml exec nginx nginx -t +docker compose -p nginx -f /docker/nginx/docker-compose.yml exec nginx nginx -s reload +``` + +## Important notes + +- Do not deploy the top-level `docker-compose.yml` to this server for production. + It includes its own nginx service and does not match the shared nginx setup on + the host. +- The deployment scripts do not stop or remove the onboarding WordPress stack. +- The deployment scripts do not touch the shared mysql compose project. +- The deployment scripts preserve the remote `.env` file. +- The site check in `deploy.ps1` targets `https://www.goodwalk.co.nz/api/health`. + Before nginx cutover, use `-SkipSiteCheck` or expect that check to fail. diff --git a/docs/design-audit.md b/docs/design-audit.md new file mode 100644 index 0000000..a512d00 --- /dev/null +++ b/docs/design-audit.md @@ -0,0 +1,455 @@ +# Design Audit — Goodwalk (Codebase-wide) + +Re-audited beyond ValuesSection. Read `sections.css` (1130 lines), `typography.css`, `responsive.css`, `variables.css`, and surveyed each major surface (Hero, Intro, PageHeader, Footer, FAQ, Instagram, Mobile Menu, Testimonial card). Findings below cite actual files/lines. + +--- + +## Critical issues + +### 1. Three different "eyebrow" components exist, sharing no DNA +**Problem.** The same UX element — small uppercase intro label above a heading — is rendered three incompatible ways: +- `.eyebrow` (typography.css:100): font-body, 12px, 700, `0.09em`, green text, no background. +- `.hero-kicker` (sections.css:69): font-body, 12px, 700, `0.08em`, yellow text in a *yellow pill with yellow border*. +- `.intro-kicker` (sections.css:408): font-body, 12px, 600 (weight differs), `0.18em` (tracking differs — over 2× the others), white-58% text with a *yellow rule prefix*. + +Plus `.values-eyebrow`, `.booking-eyebrow`, `.footer-col-label`, `.intro-meta` are all variants. + +**Root cause.** No eyebrow primitive in the system. Each section author re-implemented from scratch. +**Perception.** Reader senses different sections were designed at different times. Brand voice fragments. +**Fix.** One `<Eyebrow variant="default|inverse|accent" />` component. Three variants only. Migrate all six existing implementations. +**Class: System debt.** + +--- + +### 2. Six different primary heading scales +**Problem.** +| Selector | Scale | Weight | Tracking | +|---|---|---|---| +| `.section-heading` | clamp(30, 4.6vw, 44) | 800 | -0.035em | +| `.hero-text h1` | clamp(34, 4vw, 56) | 800 | -0.045em | +| `.intro-headline` | clamp(30, 4.4vw, 54) | **500** | -0.02em | +| `.ph-title` | clamp(34, 4vw, 56) | 800 | -0.04em | +| `.info-block h2` | clamp(28, 2.4vw, 32) | 700 | -0.02em | +| `#instagram h2` | clamp(30, 3vw, 36) | 700 | -0.02em | + +Six clamp formulas. Five tracking values. Weights ranging 500→800. The base `h2 { font-weight: 700 }` (typography.css:58) conflicts with `.section-heading { font-weight: 800 }` (typography.css:79) — actual rendered weight depends on whether the heading author remembered to apply the class. + +**Root cause.** No `--text-display`, `--text-h1`, `--text-h2` tokens. Every author authors a fresh clamp. +**Perception.** Headings jump in size and weight as you scroll. The 500-weight `.intro-headline` reads as a different brand from the 800-weight `.hero h1` directly above it. +**Fix.** Define type tokens: `--text-display` (52/800/-0.04), `--text-h1` (44/800/-0.035), `--text-h2` (32/700/-0.02), `--text-h3` (22/700/-0.02), `--text-body-lead` (17/500/0), `--text-body` (16/400/0). Map every heading. Delete the per-section clamps. +**Class: Design debt + System debt.** + +--- + +### 3. The Instagram section is a chromatic anomaly +**Problem.** Section background sequence on the homepage: +`#hero` (green) → `#intro` (green) → `#promise/#values` (off-white) → `#services` (white) → `#testimonials` (white) → `#info` (white) → `#newlead` (white) → `#instagram` (**solid #ffd100 full-bleed**) → `footer` (green). + +The Instagram block is the only place brand yellow is used as a *page section*. It's also where pure black-on-yellow body text appears at `rgba(0, 0, 0, 0.6)` (sections.css:738). + +**Root cause.** Brand yellow was treated as both an accent (CTAs, highlights) AND a surface (this section). Premium products pick one. +**Perception.** Reads as advertising, not editorial. Breaks the calm green/off-white rhythm. The user scrolls into a marketing banner mid-page. +**Fix.** Either (a) demote to a green section with yellow accents inside, or (b) shrink to a narrow card-on-off-white block. Reserve `var(--yellow)` for accents only. +**Class: Design debt + Conversion debt** (it sits right before footer — possibly the last impression). + +--- + +### 4. Hero animation system runs on a different clock than the rest of the page +**Problem.** Hero entry: image 1.6s, text rise 0.85s, underline draw 0.9s @ 900ms delay, star pop 0.45s starting at 820ms. Total animation completes ~1.7s after load. + +Rest of page: reveal-block now 0.3s opacity / 0.45s transform. +Mobile menu: 180–220ms. +Button hover: 0.16–0.22s. + +**Root cause.** Hero was authored before the reveal/motion system existed. Never reconciled. +**Perception.** The hero feels heavy and ceremonial; the rest of the page feels snappy. Two products bolted together. +**Fix.** Cap all hero animations at 0.5s. Reduce delays — first text element by 80ms, each subsequent +60ms. Drop the underline-draw delay from 900ms to 350ms. Keep the elegance, lose the lethargy. +**Class: Polish debt.** + +--- + +### 5. `--space-container-x-tablet` breaks the gutter rhythm +**Problem.** variables.css:145 — `--space-container-x-tablet: 30px`. Desktop value is `clamp(24px, 4vw, 48px)`. At 1024px width (the tablet breakpoint), 4vw = 41px. The tablet override drops gutters to 30px, then back up to 41–48px on desktop. A user resizing a window or rotating an iPad sees the gutters *narrow* then *widen*. + +**Root cause.** A patch fix applied at the tablet breakpoint that doesn't share the desktop formula. +**Perception.** Visible engineering. Anyone who notices the layout shift on resize loses trust. +**Fix.** Either delete `--space-container-x-tablet` and let the clamp handle the breakpoint, or make tablet = `clamp(20px, 3vw, 32px)` so the curve is continuous. +**Class: System debt.** + +--- + +### 6. Card system doesn't exist — each section invents its own +**Problem.** Same UX primitive (an elevated content card), shipped four ways: +| Component | Radius | Padding | Background | Shadow | +|---|---|---|---|---| +| `.testimonial-card` | 28px | 36px 32px | gradient panel→panel-soft | inset + shadow-md | +| `.faq details` | 16px | 18px 22px | surface-page | shadow-lg on open only | +| `.values-photo-card` | 28px → md mobile | n/a | beige | inset + card | +| `.booking-field-card` | 24px | 24px 22px | (varies) | (varies) | + +Plus `.values-point` (no radius, pure surface), `.mobile-menu-links a` (16px radius), `.ph-media` (28px), `.intro-google` (pill). +**Root cause.** No `<Card />` primitive. Every author re-decides. +**Perception.** Adjacent sections feel like they were copy-pasted from different Behance projects. +**Fix.** One Card system: `--radius-lg` (20px) for cards, `--space-7` (32px) padding, `--shadow-card` standard. Variants: `card`, `card-elevated`, `card-quiet`. Migrate all four. +**Class: System debt + Design debt.** + +--- + +### 7. Footer typography is a four-size jumble +**Problem.** Within the footer alone: 14px (`.footer-brand p`, `.footer-nav a`), 13px (`.footer-bottom`, `.footer-contact-link`), 12px (`.footer-back-top`, `.footer-social-invite`), 10px (`.footer-col-label`), plus 14px (`footer h4`). Five sizes in a quiet auxiliary surface. + +Add opacities: `.footer-brand p` 0.72, `.footer-nav a` 0.72, `.footer-contact-link` 0.7, `.footer-bottom` 0.6, `.footer-back-top` 0.5, `.footer-col-label` 0.5. + +**Root cause.** Each footer column was sized independently to hit visual targets, not to scale. +**Perception.** The footer feels busy in a quiet way — many small elements clamoring for slightly different attention. +**Fix.** Two sizes: 14px (links/copy) + 12px (label/legal). Two opacities: 0.85 (active text) + 0.55 (labels). Delete the rest. +**Class: Polish debt + UX debt.** + +--- + +### 8. `.section-heading` color is pure `#000`, used on warm off-white backgrounds +**Problem.** typography.css:82 — `.section-heading { color: var(--text-strong); }` where `--text-strong: #000`. Promise, Values, Testimonials, Services, Info all render their primary heading in pure black on a warm `--off-white #f8f7f2`. Same pattern as the `.btn-yellow` issue I already fixed: pure black against a warm surface reads as harsh and clinical. + +**Root cause.** `--text-strong` is a "darkest-possible" token used reflexively for headings instead of a heading-specific token. +**Perception.** Headings shout. The rest of the type — body in `var(--text)` (#2e3031), muted in green-cast grays — is warm. Headings are not. +**Fix.** `.section-heading { color: var(--text-heading); }` (which is `#1f2421`, near-black with a green cast). Or `var(--gw-green)` for full editorial treatment. The dark-green-on-warm-cream pairing is the brand's most premium register. +**Class: Design debt.** + +--- + +### 9. Two Google trust-mark components live as duplicates +**Problem.** `.hero-trust-mark` (sections.css:153) and `.intro-google-mark` (sections.css:491). Same Google "G" circle, same white background, same shadow recipe with slightly different parameters (`0 2px 8px rgba(0,0,0,0.25)` vs `0 4px 12px rgba(0,0,0,0.25)`). Different sizes (28px vs 36px). Different parent chip layouts (`.hero-trust-chip` vs `.intro-google`). + +**Root cause.** Copy-paste authoring. The second one was built without abstracting the first. +**Perception.** A user who scrolls hero → intro sees the same trust signal twice in slightly different sizes. Either feels redundant or sloppy depending on attention level. +**Fix.** One `<GoogleTrustMark size="sm|md" />` component. Two clean sizes (24, 36). Single shadow token. +**Class: System debt + Conversion debt** (trust signals matter; redundant ones dilute). + +--- + +### 10. Letter-spacing on headings has four values +**Problem.** `-0.02em` (h2/h3, intro-headline, info-block h2), `-0.035em` (section-heading), `-0.04em` (ph-title), `-0.045em` (hero h1). Four bespoke tracking values. + +**Root cause.** Each heading was tuned visually without a tracking scale. +**Perception.** Headings at similar sizes (`.intro-headline` 54px at `-0.02em` vs `.hero h1` 56px at `-0.045em`) feel like they're set in *different fonts*, when they're actually both Unbounded. +**Fix.** Two tracking values: `-0.035em` for display (36px+), `-0.02em` for everything else. Lock in the type tokens. +**Class: Design debt.** + +--- + +### 11. Hero text relies on hand-numbered nth-child animation delays +**Problem.** sections.css:272–278 — `.hero-text > :nth-child(1) { animation-delay: 160ms; }` through `:nth-child(7)`. Seven hardcoded children. If the hero content shape changes (e.g., remove the kicker, add a phone CTA), the choreography breaks silently. + +**Root cause.** Animation was authored against current markup, not against generic children. +**Perception.** Probably invisible to most users *until* it breaks — at which point an element pops in without animation while others slide. +**Fix.** Use CSS counter or a Svelte action that applies `--reveal-delay` per child. Or accept staggered delays via `:nth-child(n)` formula: `animation-delay: calc(160ms + (var(--i, 0)) * 100ms)`. +**Class: System debt + Polish debt.** + +--- + +### 12. Mobile hero CTA shrinks to 12px font, 9px horizontal padding under 480px +**Problem.** responsive.css:767–774 — primary `.btn-yellow` becomes `padding: 13px 9px; font-size: 12px; line-height: 1.1` on iPhone SE-class widths. This is the *primary booking CTA* — the conversion target. + +**Root cause.** Two CTAs side-by-side in a row at very narrow widths. Author chose to squeeze both rather than stack. +**Perception.** On a 320px screen, the booking button reads as cramped, low-confidence. CTA hierarchy collapses. +**Fix.** Keep buttons stacked under 480px (already done at 768px — extend the rule). Primary CTA: full-width, 14px font, 14px vertical padding. Secondary link below. +**Class: Conversion debt.** + +--- + +### 13. Hardcoded shadows everywhere despite a complete shadow token set +**Problem.** Beyond ValuesSection, the same pattern repeats: +- `.testimonial-card:hover` — `0 8px 40px rgba(0, 0, 0, 0.08)` (sections.css:620). Not a token. +- `.hero-trust-mark` — `0 2px 8px rgba(0, 0, 0, 0.25)` (line 161). Not a token. +- `.intro-google-mark` — `0 4px 12px rgba(0, 0, 0, 0.25)` (line 499). Not a token. +- `.ph-media` — `0 16px 40px rgba(var(--ink-rgb), 0.08)` (line 1027). Not a token. +- `.intro-google` — uses inset shadow tuples directly (lines 470, 482). + +**Root cause.** Authors didn't know which token to grab from 18 shadow options. +**Perception.** Elevations feel inconsistent — some cards lift more, some less, even when visually they're the same depth. +**Fix.** Five tokens, not eighteen: `--shadow-flat`, `--shadow-card`, `--shadow-elevated`, `--shadow-floating`, `--shadow-modal`. Migrate everything. +**Class: System debt.** + +--- + +### 14. The `.intro-kicker` heading-overline pattern is design-y; nothing else on the page uses it +**Problem.** `.intro-kicker` (sections.css:408) uses a horizontal rule + uppercase text pattern (line + word). It's stylish. But it appears nowhere else. Adjacent sections use pill eyebrows, naked uppercase, or nothing. + +**Root cause.** Section author drew inspiration that didn't propagate. +**Perception.** The intro feels visually distinct in a way that disconnects it from the rest of the page — over-designed compared to its neighbors. +**Fix.** Pick one: either commit and use the rule pattern in 2-3 more sections (rhythm); or drop it and use the standard `.eyebrow`. +**Class: Design debt.** + +--- + +### 15. FAQ details radius (16px) doesn't match testimonial card (28px), values bento (20px), or photo card (28px) — they all sit on the same page +**Problem.** Cumulative effect of issue #6. The Info section has FAQ cards next to other cards with completely different silhouettes. +**Perception.** Visual rhythm dissolves. +**Fix.** All cards at `--radius-lg` (20px). Period. +**Class: Polish debt.** + +--- + +### 16. Footer container padding doesn't share the global gutter system +**Problem.** sections.css:600 — `footer { padding: 60px 50px 32px; }`. The 50px is hardcoded. The mobile override at responsive.css:678 uses `var(--space-container-x-mobile)` — correct. But desktop is a literal. +**Same problem** at `#instagram { padding: 60px 50px; }` (sections.css:732) and `.ph-inner { padding: 0 50px; }` (line 949). +**Perception.** Footer/instagram/page-header gutters jitter against section gutters by a few pixels — the same issue I documented for ValuesSection, repeated across the codebase. +**Fix.** Replace every `50px` desktop gutter with `var(--space-container-x)`. +**Class: System debt.** + +--- + +### 17. Section vertical rhythm collapses on mobile to a single value +**Problem.** variables.css:172–178 — on mobile, all four section padding tiers (`--space-section-featured-y`, `--space-section-support-y`, `--space-section-form-y`, `--space-section-page-y`) collapse to `--space-section-mobile-y` (40px). On desktop, featured sections breathe more than supporting. On mobile, every section has identical vertical padding. + +**Root cause.** Pragmatic — mobile space is scarce. But the *intent* (featured sections feel more important) disappears. +**Perception.** Mobile users get a "flat" page where every section has equal visual weight. Hero → Intro → Promise → Services all feel like peers. +**Fix.** Two mobile tiers: `--space-section-featured-y-mobile: 56px`, `--space-section-mobile-y: 40px`. Featured sections get 16px more breathing room. Still respects mobile constraints. +**Class: Design debt.** + +--- + +### 18. `#hero::after` gradient mask has a 4-stop gradient with literal RGB +**Problem.** sections.css:32–45 — a four-stop gradient `transparent 18% → 26% brand → 78% brand → solid brand 86%`. Plus a mobile-only override at lines 293–303 with *different* stops (`22% → 45% → 88% → 78%`). The math doesn't read as deliberate; it reads as tuned by trial and error. + +**Root cause.** Hero image overlay was fine-tuned to one image asset. Different images won't behave the same. +**Perception.** Probably invisible. But if the hero photo ever changes (winter scene, different dog), the overlay won't land right. +**Fix.** Reduce to 2 stops: `transparent 30% → solid brand 95%`. Test against multiple photos. +**Class: Polish debt.** + +--- + +### 19. Hero kicker mobile color is `rgba(white, 0.48)` on dark green +**Problem.** responsive.css:358 — `color: rgba(var(--white-rgb), 0.48)` for the kicker on mobile. At 10px uppercase 0.13em on a dark green-tinted gradient, that's somewhere around 4–5:1 contrast against the gradient. Borderline AA. + +**Root cause.** Designer wanted the kicker quiet against the loud headline. But mobile users get a small device + outdoor sunlight + decreased contrast. +**Perception.** Some users won't read the kicker. Those who do will strain. +**Fix.** `rgba(white, 0.72)` at 11px on mobile. Still quiet, properly accessible. +**Class: UX debt.** + +--- + +### 20. Three styling paradigms cohabit +**Problem.** The codebase uses: +1. **Global utility classes** (`.btn`, `.eyebrow`, `.section-heading`, `.testimonial-card`, `.faq`) defined in `src/lib/styles/*.css`. +2. **Component-scoped styles** inside Svelte `<style>` blocks (ValuesSection, BookingSection, etc.). +3. **`:global()` overrides inside component-scoped styles** that effectively re-globalize CSS. + +**Root cause.** Migration in progress between approaches, no policy decision. +**Perception.** Invisible to users — but the codebase resists consistent change. Every refactor has to reckon with three rule systems. +**Fix.** Pick one. Recommend: **component-scoped** for component-specific styles, **global utility classes** for cross-component primitives (`.btn`, `.eyebrow`, `.card`, `.section-heading`). Forbid `:global()` overrides except for action-injected classes (`reveal-*`). +**Class: System debt.** + +--- + +## Systemic Drift Map (grouped by root cause) + +**Root cause A — No token-driven scales for type, radius, motion, shadow.** +Issues: #2, #6, #10, #13, #15. Authors invent each value fresh because there's no canonical "use this." + +**Root cause B — Primitive components were never extracted.** +Issues: #1, #9, #6 (cards), #14 (intro-kicker). Same UX element re-implemented in multiple places. + +**Root cause C — Container padding system is incomplete on desktop.** +Issues: #5, #16. Mobile uses tokens; desktop hardcodes 50px and tablet hardcodes 30px. + +**Root cause D — Hero was authored on a separate timeline than the rest of the page.** +Issues: #4, #11, #18, #19, #12. The Hero composition predates the reveal system, predates current motion language. + +**Root cause E — Pure black `#000` is treated as "the heading color."** +Issues: #8, plus the original `.btn-yellow` issue I already fixed. The system has a warmer near-black available; it's not the default. + +**Root cause F — Brand yellow is used both as accent and surface.** +Issues: #3 (Instagram section). Premium brands choose one role per color. + +**Root cause G — Mobile breakpoints collapse intent.** +Issues: #17, #12, #7. Mobile flattens hierarchy that desktop carefully built. + +--- + +## Premiumisation Roadmap + +**To increase calmness:** +1. Collapse shadows to 5 tokens. Use them everywhere. +2. Replace `#000` with `--text-heading` or `--gw-green` across all headings. +3. Demote the Instagram section from full-yellow to a green section with yellow accents. +4. Section vertical rhythm: two tiers on mobile, not one (Issue #17). + +**To increase trust:** +1. Single Google trust-mark component (Issue #9). +2. Consolidate footer typography to 2 sizes (Issue #7). +3. Fix mobile hero kicker contrast (Issue #19). +4. Add `last-updated` and author byline to comparison and any FAQ-style pages. + +**To increase sophistication:** +1. Adopt a type scale (Issue #2). Six display sizes is amateur; three is grown-up. +2. One letter-spacing scale, two values (Issue #10). +3. Replace `.intro-kicker` rule pattern with the unified `.eyebrow` — or commit to it and repeat it in three other places. No one-offs (Issue #14). +4. Hero animation: cap everything at 0.5s. Restraint reads as confidence (Issue #4). + +**To increase conversion confidence:** +1. Mobile hero CTA: stack and grow, never shrink (Issue #12). +2. Trust mark consolidation reinforces — not repeats — social proof (Issue #9). +3. Instagram section: if removed/demoted, the path from `#newlead` → footer is uninterrupted. Currently `#newlead` (the booking form) bleeds into a yellow billboard, which dilutes the form's gravity (Issue #3). + +**To increase perceived engineering quality:** +1. Solve the tablet gutter shift (Issue #5). +2. Eliminate the nth-child animation hardcode (Issue #11). +3. Eliminate hardcoded shadows in global CSS (Issue #13). +4. Pick one styling paradigm (Issue #20). + +--- + +## Design System Refactor Priority + +**Now (this week):** +1. **Type scale tokens.** `--text-display/h1/h2/h3/body-lead/body/small` with weight + tracking. Migrate `.section-heading`, `.hero h1`, `.intro-headline`, `.ph-title`, `.info-block h2`, `#instagram h2` to consume them. This single change subsumes issues #2 and #10. +2. **Eyebrow primitive.** One Svelte component, three variants. Migrate `.eyebrow`, `.hero-kicker`, `.intro-kicker`, `.values-eyebrow`, `.booking-eyebrow`, `.footer-col-label`. Issue #1. +3. **Replace `--text-strong` with `--text-heading` in `.section-heading`.** One-line change, large perceived impact. Issue #8. +4. **Container gutter cleanup.** Find/replace `padding: 0 50px` → `padding: 0 var(--space-container-x)` across `footer`, `#instagram`, `.ph-inner`. Re-evaluate `--space-container-x-tablet`. Issues #5, #16. + +**Next (this month):** +5. **Card primitive.** `<Card variant="default|quiet|elevated" />`. Migrate testimonial, FAQ, photo, booking field. Issue #6. +6. **Shadow consolidation.** 18 tokens → 5. Migrate all hardcoded shadows. Issue #13. +7. **Hero animation pass.** Cap durations, dynamic delays. Issues #4, #11. +8. **Instagram section redesign.** Either demote or recompose. Issue #3. + +**Eventually (next quarter):** +9. **Google trust-mark component.** Issue #9. +10. **Footer typography pass.** Two sizes, two opacities. Issue #7. +11. **Mobile vertical rhythm tiers.** Issue #17. +12. **Pick one styling paradigm.** Document. Issue #20. + +--- + +## Visual Cohesion Score + +Scored against what a principal-designer-led product (Linear, Stripe, Apple marketing) would ship. + +| Axis | Score | Note | +|---|---|---| +| **Typography** | **4/10** | Six heading scales, four trackings, weight conflicts between base h2 and `.section-heading`. The font choices (Unbounded + Readex Pro) are good; their application is uneven. | +| **Spacing** | **5/10** | A 4px scale exists and is partly respected, but desktop container padding is hardcoded (50px) and the tablet override breaks the curve. Section vertical rhythm collapses on mobile. | +| **Colour** | **5/10** | The brand palette (green + yellow + cream) is strong. Execution: too many near-identical grays/off-whites in tokens, pure black where warmer would serve, yellow used as both accent and surface. | +| **Motion** | **4/10** | Three speed regimes coexist (180–220ms, 300–450ms, 850–1600ms). Hero choreography is heavy compared to a snappy rest-of-page. Mobile menu motion is the best-tuned. | +| **Hierarchy** | **6/10** | Within each section, hierarchy generally reads. Across the page, section weights compete — Instagram outshouts the booking form that precedes it. Headings have inconsistent weight signaling. | +| **Responsiveness** | **6/10** | Mobile is genuinely handled (good `iOS-zoom-on-focus` awareness, 44px tap targets, sticky book bar). But mobile flattens hierarchy that desktop built, and the <480px CTA squeeze undermines the conversion target. | +| **Premium feel** | **4/10** | Several premium gestures (warm beige photo frames, Google trust mark, restrained eyebrows in some places) are undone by harsh black headings, the yellow Instagram billboard, the 1.6s hero entry, and visible engineering drift between sections. | + +**Overall: 4.9 / 10.** + +--- + +## Final read + +This product is **two design languages glued together**. The first is *editorial-warm*: cream surfaces, dark-green accents, photographic cards with beige frames, restrained typography. The second is *marketing-loud*: yellow billboards, black-on-yellow CTAs, 1.6s hero animations, sub-12px footer captions, hand-numbered choreography. + +The brand voice (`CLAUDE.md` says "preserve the WordPress visual design") implicitly rewards both. But premium products converge. Right now Goodwalk is asking the visitor to switch reading modes every two scrolls. + +**The single highest-leverage move:** adopt a real type-scale token set this week. Issues #2, #8, #10, and large parts of #1 and #7 dissolve. Headings stop fighting each other. The page begins to feel like one product. + +**The second-highest:** abolish the yellow Instagram section as a section. Yellow becomes a pure accent. The path from hero → booking → footer becomes uninterrupted green-and-warm. The site immediately reads more grown-up. + +Everything else is downstream of those two. + +--- + +# Changelog + +Concrete from→to changes, grouped by file. Each row references the issue it resolves. + +## `src/lib/styles/variables.css` + +| # | From | To | +|---|---|---| +| 2 | _(no type tokens)_ | Add `--text-display: clamp(40px, 5vw, 56px)`, `--text-h1: clamp(34px, 4vw, 44px)`, `--text-h2: clamp(28px, 3vw, 36px)`, `--text-h3: clamp(20px, 2vw, 24px)`, `--text-body-lead: 17px`, `--text-body: 16px`, `--text-small: 13px` | +| 2 | _(no weight tokens)_ | Add `--weight-display: 800`, `--weight-heading: 700`, `--weight-body: 400`, `--weight-emphasis: 600` | +| 10 | _(no tracking tokens)_ | Add `--tracking-display: -0.035em`, `--tracking-heading: -0.02em`, `--tracking-eyebrow: 0.08em` | +| 5 | `--space-container-x-tablet: 30px` | Delete; rely on the desktop clamp at tablet widths | +| 13 | 18 shadow tokens (`--shadow-xs/sm/md/lg/xl/2xl/float/press/panel/panel-strong/panel-soft/card/card-hover/badge/badge-hover/menu/menu-soft/...`) | Collapse to 5: `--shadow-flat`, `--shadow-card`, `--shadow-elevated`, `--shadow-floating`, `--shadow-modal`. Alias old names to the 5 during migration. | +| 17 | `--space-section-mobile-y: var(--space-8)` (single mobile tier) | Add `--space-section-featured-y-mobile: var(--space-10)` (56px); keep `--space-section-mobile-y: var(--space-8)` (40px) for support tiers | + +## `src/lib/styles/typography.css` + +| # | From | To | +|---|---|---| +| 8 | `.section-heading { color: var(--text-strong); }` (#000) | `.section-heading { color: var(--text-heading); }` (#1f2421) | +| 2 | `.section-heading { font-size: var(--heading-section-size); font-weight: 800; letter-spacing: -0.035em; }` | `.section-heading { font-size: var(--text-h1); font-weight: var(--weight-display); letter-spacing: var(--tracking-display); }` | +| 2 | `.hero-text h1 { font-size: clamp(34px, 4vw, 56px); font-weight: 800; letter-spacing: -0.045em; }` | `.hero-text h1 { font-size: var(--text-display); font-weight: var(--weight-display); letter-spacing: var(--tracking-display); }` | +| 2 | `h2 { font-weight: 700 }` _(conflicts with `.section-heading` 800)_ | `h2 { font-weight: var(--weight-heading); }` — and remove the duplicate weight from `.section-heading` (token already encodes it) | +| 2 | `.info-block h2 { font-size: clamp(28px, 2.4vw, 32px); }` | `.info-block h2 { font-size: var(--text-h2); }` | +| 2 | `#instagram h2 { font-size: clamp(30px, 3vw, 36px); }` | `#instagram h2 { font-size: var(--text-h2); }` | +| 10 | Four tracking values (-0.02 / -0.035 / -0.04 / -0.045) across headings | Two: `var(--tracking-display)` for h1/display, `var(--tracking-heading)` for h2/h3 | +| 1 | `.eyebrow { font-size: 12px; font-weight: 700; letter-spacing: 0.09em; color: var(--gw-green); }` | Becomes the single source of truth. Same selector, but `letter-spacing: var(--tracking-eyebrow)`. Add `.eyebrow--inverse` (white) and `.eyebrow--accent` (yellow) modifiers. | + +## `src/lib/styles/sections.css` + +| # | From | To | +|---|---|---| +| 1 | `.hero-kicker { ... yellow pill, yellow text, font-size 12px, weight 700, tracking 0.08em ... }` | Replace with `<span class="eyebrow eyebrow--accent">`. Delete the `.hero-kicker` rules. | +| 1 | `.intro-kicker { ... yellow rule prefix, weight 600, tracking 0.18em, white-58% text ... }` | Replace with `<span class="eyebrow eyebrow--inverse">`. Delete `.intro-kicker-rule` and the `.intro-kicker` rules. _(Issue #14 — the rule pattern is a one-off; remove it.)_ | +| 16 | `footer { padding: 60px 50px 32px; }` | `footer { padding: var(--space-11) var(--space-container-x) var(--space-7); }` | +| 16 | `#instagram { padding: 60px 50px; }` | `#instagram { padding: var(--space-section-support-y) var(--space-container-x); }` | +| 16 | `.ph-inner { padding: 0 50px; }` | `.ph-inner { padding: 0 var(--space-container-x); }` | +| 3 | `#instagram { background: var(--yellow); }` with `.instagram-blurb { color: rgba(0, 0, 0, 0.6); }` | `#instagram { background: var(--gw-green); color: var(--text-inverse); }`. `#instagram .btn { background: var(--yellow); color: var(--gw-green); }`. Yellow becomes accent inside the green section, not the surface. | +| 13 | `.testimonial-card:hover { box-shadow: ..., 0 8px 40px rgba(0,0,0,0.08); }` | `.testimonial-card:hover { box-shadow: ..., var(--shadow-elevated); }` | +| 13 | `.hero-trust-mark { box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25); }` | `.hero-trust-mark { box-shadow: var(--shadow-card); }` | +| 13 | `.intro-google-mark { box-shadow: 0 4px 12px rgba(0, 0, 0, 0.25); }` | `.intro-google-mark { box-shadow: var(--shadow-card); }` _(then deleted — see #9)_ | +| 13 | `.ph-media { box-shadow: 0 16px 40px rgba(var(--ink-rgb), 0.08); }` | `.ph-media { box-shadow: var(--shadow-elevated); }` | +| 9 | `.hero-trust-mark` (28px circle) + `.intro-google-mark` (36px circle) as separate rule blocks | Both replaced by `<GoogleTrustMark size="sm|md" />`. Component owns one shadow, one shape, two size variants. Delete both CSS blocks. | +| 6, 15 | `.testimonial-card { border-radius: 28px; padding: 36px 32px; background: linear-gradient(180deg, var(--surface-page), var(--surface-panel-soft)); }` | `.testimonial-card { border-radius: var(--radius-lg); padding: var(--space-7); background: var(--surface-panel); }` | +| 6, 15 | `.faq details { border-radius: 16px; }`, `.faq summary { border-radius: 16px; padding: 18px 22px; }` | `.faq details { border-radius: var(--radius-lg); }`, `.faq summary { border-radius: var(--radius-lg); padding: var(--space-5) var(--space-6); }` | +| 6 | `.ph-media { border-radius: 28px; }` | `.ph-media { border-radius: var(--radius-lg); }` | +| 18 | `#hero::after` four-stop gradient (`transparent 18% → 26% → 78% → 86%`) | Two-stop: `linear-gradient(to bottom, transparent 30%, var(--surface-brand) 95%)` | +| 4, 11 | `.hero-text > :nth-child(1..7) { animation-delay: 160ms..760ms; }` (seven hardcoded) | Single rule: `.hero-text > * { animation-delay: calc(120ms + var(--i, 0) * 80ms); }`. Inject `--i` via Svelte `style:--i={index}`. Max stagger reduced from 760ms to ~500ms. | +| 4 | `.hero-text > * { animation: heroRise 0.85s cubic-bezier(0.22, 1, 0.36, 1) forwards; }` | `animation: heroRise 0.45s cubic-bezier(0.22, 1, 0.36, 1) forwards;` | +| 4 | `.hero-img img { animation: heroImageEnter 1.6s cubic-bezier(0.16, 1, 0.3, 1) forwards; }` | `animation: heroImageEnter 0.5s cubic-bezier(0.16, 1, 0.3, 1) forwards;` | +| 4 | `.hero-title-highlight::after { animation: heroUnderlineDraw 0.9s ...; animation-delay: 900ms; }` | `animation: heroUnderlineDraw 0.4s ...; animation-delay: 350ms;` | +| 7 | Five footer text sizes (14/13/12/10) and six opacities (0.5/0.6/0.7/0.72/0.8/0.85) | Two sizes: 14px (links/copy) + 12px (labels/legal). Two opacities: 0.85 (active) + 0.55 (labels). Apply across `.footer-brand p`, `.footer-nav a`, `.footer-bottom`, `.footer-contact-link`, `.footer-back-top`, `.footer-col-label`. | + +## `src/lib/styles/responsive.css` + +| # | From | To | +|---|---|---| +| 19 | `.hero-kicker { color: rgba(var(--white-rgb), 0.48); font-size: 10px; letter-spacing: 0.13em; }` (mobile) | `.hero-kicker { color: rgba(var(--white-rgb), 0.72); font-size: 11px; letter-spacing: var(--tracking-eyebrow); }` (mobile) | +| 12 | `@media (max-width: 480px) { .hero-buttons { flex-direction: row; gap: 8px; } .hero-buttons .btn-yellow { padding: 13px 9px; font-size: 12px; line-height: 1.1; flex: 1; width: 0; } }` | Delete the entire `@media (max-width: 480px) .hero-buttons` block. Let the 768px stacked layout extend down — primary CTA stays full-width, 14px font, 14px vertical padding. | +| 5 | `@media (max-width: 1024px) { .services-inner, .values-inner, ... { padding-left: var(--space-container-x-tablet); } }` | Delete the tablet padding override entirely. Components use `var(--space-container-x)` which already clamps appropriately. | + +## `src/lib/components/Header.svelte` and section components + +| # | From | To | +|---|---|---| +| 1 | `<span class="eyebrow values-eyebrow">…</span>` (Values + Booking + others) | `<Eyebrow>…</Eyebrow>` Svelte component, default variant. Delete `.values-eyebrow`, `.booking-eyebrow` rules. | +| 9 | Inline `.hero-trust-mark` markup in `HeroSection.svelte` and `.intro-google-mark` markup in `IntroStrip.svelte` | `<GoogleTrustMark size="sm" />` and `<GoogleTrustMark size="md" />` in their respective parents. | +| 11 | `<div class="hero-text"> <p class="hero-kicker">…</p> <h1>…</h1> … </div>` (children animate via nth-child) | `<div class="hero-text"> {#each items as item, i} <div style:--i={i}>…</div> {/each} </div>` — explicit index per child, animation reads `--i`. | +| 3 | `<section id="instagram">…</section>` background defined in CSS via `#instagram { background: var(--yellow); }` | Same markup, but section now reads green (CSS-only change in sections.css above). | + +## New components to create + +| # | Component | Purpose | +|---|---|---| +| 1 | `<Eyebrow variant="default|inverse|accent" />` | Single eyebrow primitive. Replaces 6 implementations. | +| 6 | `<Card variant="default|quiet|elevated" />` | Single card primitive. Migrates testimonial, FAQ, photo, booking field, point. | +| 9 | `<GoogleTrustMark size="sm|md" />` | Single Google "G" mark. Replaces hero + intro duplicates. | + +## Migration table — what consumes the new tokens + +| Token | Consumers (must migrate) | +|---|---| +| `--text-display` | `.hero-text h1` | +| `--text-h1` | `.section-heading`, `.ph-title` | +| `--text-h2` | `.intro-headline`, `.info-block h2`, `#instagram h2` | +| `--text-h3` | `.service-card h3`, `.info-block h3`, `.values-points-title`, `.values-point h3` | +| `--tracking-display` | All h1-tier headings | +| `--tracking-heading` | All h2/h3-tier headings | +| `--radius-lg` | All cards (testimonial, FAQ, photo, booking field, ph-media) | +| `--shadow-card` | Hero/intro trust marks, trust chip elevations | +| `--shadow-elevated` | Testimonial hover, ph-media, FAQ open state | +| `--shadow-floating` | Buttons on hover, intro-google on hover | + +## Out of scope (deliberately not in this changelog) + +- Collapsing the 7 gray tokens to 3 — separate codebase-wide codemod; ship after type scale lands. +- Collapsing the 6 off-white tokens to 2 — same reasoning. +- Stylelint rule blocking raw hex / raw shadow tuples — adds after the migration is complete; otherwise too noisy. +- Picking one styling paradigm (Issue #20) — architectural decision, separate PR. diff --git a/docs/design-language.md b/docs/design-language.md new file mode 100644 index 0000000..f100d3a --- /dev/null +++ b/docs/design-language.md @@ -0,0 +1,730 @@ +# Goodwalk Design Language (2026 Refined Edition) + +This document is the source of truth for Goodwalk’s visual design system. It defines the visual language, emotional tone, interaction philosophy, and implementation rules used across the website and future digital products. + +The goal is not trend-chasing. The goal is to create a calm, trustworthy, modern experience that feels premium without becoming cold, corporate, or overly “tech”. + +--- + +## Core Principles + +## 1. Warmth over perfection +Goodwalk is a human service business. The experience should feel: +- calm +- warm +- trustworthy +- emotionally safe +- premium without arrogance + +Avoid interfaces that feel: +- clinical +- overly corporate +- aggressive +- “SaaS-like” +- excessively polished + +Slight softness and imperfection are intentional. + +--- + +## 2. Refinement over redesign +The brand identity already works. + +Modernisation should happen through: +- spacing +- typography +- image treatment +- motion +- surface depth +- consistency +- restraint + +Do not redesign for novelty. + +--- + +## 3. Emotion before decoration +Visual decisions must support: +- trust +- clarity +- calmness +- conversion + +Do not add visual effects simply because they are modern. + +Every effect must have emotional purpose. + +--- + +## 4. Mobile-first experience +The site must feel premium on: +- 375px width +- average brightness outdoors +- thumb-driven interaction +- imperfect network conditions + +Mobile is not a secondary layout. + +--- + +## 5. Quiet luxury +The site should feel: +- expensive +- intentional +- calm +- understated + +Not: +- flashy +- loud +- hyper-animated +- trend-driven + +Modern premium design in 2026 is increasingly about restraint. + +--- + +## Colour System + +Defined in: +`src/lib/styles/variables.css` + +| Token | Hex | Purpose | +|---|---|---| +| `--gw-green` | `#213021` | Primary brand colour | +| `--green-mid` | `#2d4230` | Hover states, elevated surfaces | +| `--green-soft` | `#344b38` | Optional softer elevated green | +| `--yellow` | `#ffd100` | Primary CTA accent | +| `--yellow-soft` | `#f2bf2f` | Premium warm accent alternative | +| `--off-white` | `#fbfbfb` | Primary background | +| `--surface-light` | `#f7f8f6` | Elevated light surface | +| `--text` | `#2e3031` | Default text | +| `--gray` | `#59606d` | Secondary copy | +| `--beige` | `#e5d6c2` | Warm neutral accent | + +--- + +## Colour Philosophy + +## Greens +The green palette represents: +- safety +- reliability +- groundedness +- nature +- professionalism + +Greens should feel deep and organic rather than synthetic. + +Avoid: +- saturated emerald tones +- neon greens +- cold blue-greens + +--- + +## Yellow usage +Yellow is an accent, not a dominant UI colour. + +Yellow should: +- guide attention +- signal warmth +- create optimism + +Yellow should NOT: +- overpower sections +- become large reading surfaces +- create visual fatigue + +For premium applications: +```css +background: +linear-gradient( +135deg, +#ffd54a, +#f2bf2f +); +``` + +This creates a warmer, more refined feel. + +--- + +## Surface Design + +## Philosophy +Modern interfaces should feel layered rather than flat. + +Depth should come from: +- tonal separation +- soft gradients +- atmospheric shadows +- subtle edge highlights + +NOT heavy shadows or strong borders. + +--- + +## Surface Rules + +### Avoid pure white +Never use: +```css +#ffffff +``` + +Prefer: +```css +#fbfbfb +#f7f8f6 +#f5f6f3 +``` + +--- + +## Avoid pure black +Never use: +```css +#000000 +``` + +Prefer: +```css +#0f1115 +#16181d +#1b1d21 +``` + +--- + +## Micro gradients +Large flat surfaces should contain extremely subtle tonal variation. + +Example: +```css +background: +linear-gradient( +180deg, +rgba(255,255,255,0.95), +rgba(247,248,246,0.95) +); +``` + +These gradients should be nearly invisible. + +--- + +## Typography + +Defined in: +`src/lib/styles/typography.css` + +| Token | Family | Purpose | +|---|---|---| +| `--font-head` | Unbounded | Headlines | +| `--font-body` | Readex Pro | Body text | + +--- + +## Typography Philosophy + +Typography should create: +- confidence +- calmness +- readability +- rhythm + +Avoid: +- excessive weight changes +- overly dense layouts +- tiny text +- over-stylised headings + +--- + +## Typography Rules + +## Body copy +Desktop: +```css +font-size: 15px; +line-height: 1.65; +``` + +Mobile: +```css +font-size: 16px; +line-height: 1.7; +``` + +--- + +## Headings +Hero headings: +```css +letter-spacing: -0.04em; +``` + +Section headings: +```css +letter-spacing: -0.02em; +``` + +Large headings should feel: +- compact +- intentional +- editorial + +--- + +## Weight restraint +Prefer: +- 400 +- 500 +- 700 + +Avoid excessive font-weight variety. + +Spacing should create hierarchy more than font weight. + +--- + +## Spacing System + +## Philosophy +Modern premium interfaces feel expensive because they are under-filled. + +Whitespace is a feature. + +Do not compress layouts simply to fit more information. + +--- + +## Spacing Scale + +Only use: +- 4 +- 8 +- 12 +- 16 +- 24 +- 32 +- 48 +- 64 +- 72 +- 96 + +Avoid arbitrary spacing values. + +--- + +## Border Radius + +| Context | Radius | +|---|---| +| Standard cards | `28px` | +| Large feature containers | `32px` | +| Pills | `999px` | +| Small UI surfaces | `16px` | + +The system should feel soft and approachable. + +Avoid: +- sharp corners +- overly circular “bubble UI” + +--- + +## Shadows & Depth + +## Philosophy +Modern depth is atmospheric, not dramatic. + +Shadows should feel: +- diffused +- soft +- realistic + +Avoid: +- heavy elevation +- dark shadows +- obvious floating cards + +--- + +## Standard shadows + +### Definition shadow +```css +inset 0 0 0 1px rgba(17,20,24,0.045); +``` + +### Ambient depth +```css +0 8px 40px rgba(0,0,0,0.06); +``` + +### Inner edge highlight +```css +inset 0 1px 0 rgba(255,255,255,0.04); +``` + +--- + +## Texture & Grain + +## Philosophy +Digital flatness feels artificial. + +Subtle texture adds: +- realism +- warmth +- richness + +Very subtle grain is encouraged on: +- hero sections +- dark surfaces +- footers +- large empty areas + +Texture must never become visibly noisy. + +--- + +## Motion System + +## Philosophy +Motion should feel calm and physical. + +Avoid: +- excessive movement +- bouncing +- playful overshoot +- aggressive transitions + +--- + +## Preferred transition timing + +```css +220ms cubic-bezier(0.22, 1, 0.36, 1) +``` + +--- + +## Hover behaviour + +Modern hover effects should rely more on: +- brightness shifts +- opacity +- slight elevation +- subtle glow + +Less: +```css +translateY(-6px) +``` + +More: +```css +translateY(-2px) +filter: brightness(1.02) +``` + +--- + +## Cards + +## Philosophy +Cards should not feel disconnected from the layout. + +Modern premium layouts use: +- softer separation +- lower contrast +- quieter surfaces + +Avoid: +- harsh borders +- obvious “dashboard card” styling +- excessive shadowing + +--- + +## Photography Direction + +## This is one of the most important parts of the brand. + +Photography should feel: +- candid +- warm +- emotionally genuine +- lightly cinematic +- calm +- naturally lit + +Avoid: +- harsh HDR +- over-sharpening +- fake bokeh +- obvious AI look +- cluttered backgrounds + +--- + +## Image treatment + +Preferred: +- shallow depth of field +- warm colour grading +- natural greens +- soft contrast +- realistic shadows + +Images should feel: +“premium lifestyle” +not: +“local flyer advertisement” + +--- + +## Layout Philosophy + +## Editorial rhythm +Not every section should feel identical. + +The site should alternate between: +- dense +- airy +- emotional +- informational + +This creates pacing and reduces fatigue. + +--- + +## Controlled asymmetry +Small asymmetry is encouraged: +- offset images +- uneven crops +- staggered alignment +- imperfect positioning + +This creates humanity and visual interest. + +Avoid perfect grid rigidity everywhere. + +--- + +## Interaction Design + +## Buttons +Buttons should feel: +- tactile +- confident +- soft + +Never aggressive. + +--- + +## Hover states +Hover should: +- reward +- guide +- reassure + +Not distract. + +--- + +## Navigation + +The navigation should feel: +- lightweight +- stable +- unobtrusive + +Avoid: +- oversized sticky headers +- excessive blur +- flashy dropdowns + +The navigation exists to support trust and conversion. + +--- + +## Mobile UX Principles + +## Thumb-first interaction +Primary actions should remain reachable. + +Spacing should prevent accidental taps. + +--- + +## Reduced visual noise +Mobile layouts should: +- simplify aggressively +- reduce simultaneous options +- preserve emotional tone + +Not simply shrink desktop layouts. + +--- + +## Accessibility + +Always support: +- reduced motion +- readable contrast +- large tap targets +- visible focus states +- scalable text + +Accessibility should feel integrated, not bolted on. + +--- + +## Design Language Keywords + +The Goodwalk experience should feel: + +- calm +- premium +- trustworthy +- editorial +- grounded +- warm +- modern +- understated +- human +- emotionally safe +- refined +- spacious + +Never: +- corporate +- loud +- trendy +- hyper-minimal +- cold +- sterile +- flashy + +--- + +## What To Prioritise Next + +Highest impact improvements: + +1. Better photography consistency +2. Softer surface contrast +3. More atmospheric depth +4. Grain/texture implementation +5. Reduced hover movement +6. More editorial layouts +7. More restrained motion +8. More premium CTA treatment +9. Improved mobile spacing rhythm +10. More subtle card separation + +--- + +## Final Rule + +If a design decision looks impressive but reduces: +- clarity +- warmth +- trust +- calmness + +Do not ship it. + +Goodwalk should feel premium because it feels thoughtful — not because it feels flashy. + +--- + +## Implementation Reference + +Technical specs for what is currently live. Update this section when the codebase changes. + +## Colour tokens (variables.css) + +| Token | Hex | Status | +|---|---|---| +| `--gw-green` | `#213021` | ✅ Live | +| `--green-mid` | `#2d4230` | ✅ Live | +| `--green-soft` | `#344b38` | ✅ Live | +| `--yellow` | `#ffd100` | ✅ Live | +| `--yellow-soft` | `#f2bf2f` | ✅ Live | +| `--gray` | `#59606d` | ✅ Live | +| `--beige` | `#e5d6c2` | ✅ Live | +| `--off-white` | `#fbfbfb` | ✅ Live | +| `--surface-light` | `#f7f8f6` | ✅ Live — use where a surface sits above `--off-white` | +| `--text` | `#2e3031` | ✅ Live | + +## Typography (live values) + +| Context | Size | Weight | Tracking | Line-height | +|---|---|---|---|---| +| Hero h1 | `clamp(34px, 4vw, 56px)` | 800 | `-0.04em` | `1.05` | +| Section headings | `42px` | 700 | `-0.02em` | `1.08` | +| Body (desktop) | `15px` | 400 | — | `1.65` | +| Body (mobile) | `16px` | 400 | — | `1.70` | +| Buttons | `14px` | 700 | `0.01em` | `1.2` | +| Eyebrow | `13px` | 700 | `0.08em` | — | + +## Section padding rhythm (live values) + +| Section | Padding | +|---|---| +| `#promise`, `#services` | `96px 0` | +| `#values`, `#testimonials`, `#info` | `72px 0` | +| `#newlead` | `80px 0` | +| `#instagram` | `60px` | + +## Card hover behaviour (live values) + +```css +/* Service and testimonial cards */ +transform: translateY(-2px); +filter: brightness(1.02); +box-shadow: inset 0 0 0 1px rgba(17,20,24,0.06), 0 8px 40px rgba(0,0,0,0.08); +``` + +Reduced from `translateY(-6px)` — calmer, more restrained per design philosophy. + +## Service icon bubble gradient (live) + +```css +background: linear-gradient(135deg, #ffd54a, var(--yellow-soft)); +``` + +Angled, warmer gradient — replaces the flat vertical yellow. + +## Testimonial card surface (live) + +```css +background: linear-gradient(180deg, #ffffff 0%, var(--off-white) 100%); +``` + +Micro-gradient — avoids flat pure white per surface design rules. + +## Scroll reveals (live) + +JS (`+layout.svelte`): `IntersectionObserver` targets `.section-heading`, `.service-card`, `.testimonial-card`, `.value-card`. Adds `data-reveal` attribute on mount, toggles `.is-visible` when the element crosses `40px` from the viewport bottom. + +CSS (`base.css`): `opacity 0 → 1`, `translateY(20px) → none`, `0.5s`. Wrapped in `prefers-reduced-motion: no-preference`. + +## Hero image gradient (live) + +`#hero::after` pseudo-element: `linear-gradient(to top, var(--gw-green), transparent)`, `height: 120px`, covering the right 58% of the section. Hidden on mobile. + +## Not yet implemented + +| Item | Notes | +|---|---| +| Grain / texture | Needs a noise SVG or canvas overlay — skip until photography is consistent | +| `--surface-light` usage | Token is defined; not yet applied to any component | +| `--green-soft` usage | Token is defined; candidate for mega-menu icon hover state | +| More editorial layouts | Structural work — needs a design pass per page | diff --git a/docs/homepage-flow-audit.md b/docs/homepage-flow-audit.md new file mode 100644 index 0000000..aafe1ee --- /dev/null +++ b/docs/homepage-flow-audit.md @@ -0,0 +1,278 @@ +# Homepage Section Flow Audit + +Evaluating each section of the Goodwalk homepage against one question: **does this section move a researching dog owner closer to booking, or does it just take up scroll?** + +Scope: `src/routes/+page.svelte` (the homepage). Findings drawn from reading the actual section components and copy. + +--- + +## The current sequence + +``` +1. Header +2. HeroSection ── hook + primary CTA +3. ValuesSection ── photo gallery + before/after + values points (3 sub-blocks) +4. ServicesSection ── service grid +5. HowItWorksSection ── 3-4 step process +6. TestimonialsSection ── reviews +7. FounderStorySection ── 4 paragraphs + 2 CTAs + portrait +8. InfoSection ── locations + hours + FAQ (2 sub-blocks) +9. BookingSection ── lead form (THE conversion target) +10. InstagramSection ── follow CTA +11. Footer +``` + +**9 content sections**, but really **13+ sub-blocks** once you unpack Values (3), FounderStory (dense), and Info (2). The booking form sits 8th in sequence — a user who's "sold" by Testimonials still has to scroll through two more sections before they can ask to book. + +--- + +## Section-by-section verdict + +### 1. HeroSection — **KEEP as-is** + +The hero is doing its job: photographic hook, headline, primary "Book a walk" CTA, Google trust chip, three subtitle proof chips. This is the only section a 5-second-attention user actually sees, and the primary CTA + Google rating are in it. + +**One nit:** the seoHeading (`<h2>` below `<h1>`) is yellow Unbounded at 18px on green. Reads to humans as a subtitle but ships as an H2 for SEO. Fine, but a careful eye spots it as "two headings of equal importance" — that's why mobile bumps it to 15px to quiet it. Acceptable trade-off. + +**Verdict:** earns its place outright. + +--- + +### 2. ValuesSection — **TRIM AGGRESSIVELY** + +This is the worst offender for overload. It's three sections stacked under one `<section id="values">`: + +| Sub-block | Content | Job | +|---|---|---| +| Photo gallery | 5 client dog photos with names | Visual proof, decorative | +| Before/after contrast | Two cells: "Without the right routine" vs "With Goodwalk" + bullets each | Emotional pitch | +| Values points | 6 icon cards | Rational claims | + +That's three different rhetorical moves — photographic warmth → emotional contrast → rational checklist — packed into one section. The user is asked to switch modes twice within ~1500px of scrolling. + +**Friction created:** +- Photo gallery is the third visual moment in 1500px of page (after hero photo and any micro-imagery in the hero chips). It doesn't *add* social proof — Testimonials at section 6 will do that with quotes + faces. It's redundant. +- Before/after is genuinely the strongest copy on the page. *That's the section that earns its place.* The yellow "With Goodwalk" cell carries the brand-emotional payload of the homepage in two short paragraphs. +- Values points are claims the FounderStory section will later repeat ("Little groups, never a crowded van" / "The same friendly face at the door"). Duplicate. + +**Proposal:** +- **Cut the photo gallery from this section entirely.** Move it to a thin band *under* the hero (or kill it; Testimonials photos cover the same emotional ground). +- **Keep the before/after contrast as the entire section.** Rename `id="values"` → `id="why-goodwalk"`. Make it shorter (drop "What we stand for" subheader and the 6-point grid). +- **Either kill the values points OR collapse them into a 3-icon strip embedded inside the Hero or Services section** as inline reassurance. + +**Cognitive load saved:** ~50% reduction in section height. The strongest copy gets isolated. The user reaches Services faster. + +--- + +### 3. ServicesSection — **KEEP, MAYBE PROMOTE** + +Services answers the question the user came to the site asking: "what do you actually offer and what does it cost?" In local-services SEO research, this is the highest-intent section on the page. + +**Currently 4th in the scroll order.** Most local-service homepages put services 2nd or 3rd because intent-driven visitors want to confirm fit *before* reading testimonials. Consider promoting to position 2 (immediately after Hero). + +**Verdict:** earns its place, **but order matters** — see proposed reordering below. + +--- + +### 4. HowItWorksSection — **KEEP, possibly MERGE with Services** + +Process clarity is a real conversion accelerator for a service that requires giving someone a key to your house. Three steps ("Book in → Meet & greet → Regular walks" or similar) reduces the perceived commitment. + +**Watch for:** if HowItWorks duplicates the messaging in Services or FounderStory ("you'll meet Aless first"), it stops being a friction-reducer and becomes a third "trust us" pitch. + +**Proposal:** keep as a separate section unless the steps are <3. If <3 steps, fold into a strip inside the Booking section as "what happens after you submit this form" reassurance. + +**Verdict:** earns its place if it shows *process* (steps with icons), not values. + +--- + +### 5. TestimonialsSection — **KEEP** + +Social proof is the highest-converting section type in local services. Five-star reviews with names and dog photos do real work. + +**Watch for:** card padding (36px 32px), 28px radius (just fixed to 20px). 3-up grid → 1-up on mobile is correct. + +**One question:** how many testimonials show? If it's 6+, that's overload too. 3 is the sweet spot. 5 max. + +**Verdict:** earns its place. May need a content trim (count of cards), not a structure change. + +--- + +### 6. FounderStorySection — **TRIM HARD** + +Currently: +- Eyebrow "A note from Aless" +- Greeting "Hi, I'm Aless." +- Heading with main + sub +- "What owners notice first" trust strip with 3 bullets +- **Four paragraphs of body copy** (≈ 250 words) +- Closing line in bold +- Two CTAs (email-Aless + book CTA) +- Signoff with name, tagline, portrait + +This is the densest section on the page. It re-pitches values that Values + Services + HowItWorks have already pitched. + +**The problem:** a user who reached this section is *already convinced or already gone*. The 250-word essay is for the still-convinced reader, but they're scrolling for the form. + +**Proposal:** +- **Cut to 2 paragraphs.** Para 1: "Why I started Goodwalk." Para 2: "The Tiny Gang philosophy + sign-off." +- **Remove the "What owners notice first" trust strip.** It duplicates values content already on the page. +- **Remove the email-Aless secondary CTA.** Founder pages with two CTAs split attention. Keep only the primary booking CTA. +- **Keep the portrait + signoff** — that's the emotional payoff for the section's existence. + +**Word-count target:** ≤ 120 words of body copy + signature. Reader spends 30 seconds here, not 90. + +--- + +### 7. InfoSection — **SPLIT + DEMOTE** + +This section is bundling two unrelated jobs: + +| Block | Content | Real job | +|---|---|---| +| Block 1 | Suburb chips + nearby card + hours | "Do you cover my area?" — qualifying signal | +| Block 2 | FAQ accordion | "What if X?" — friction reducer | + +These should not be in the same section. They serve different reader states. + +**Block 1 (suburbs/hours)** is a *qualifier* — it tells the user whether to even bother with the booking form. It belongs **inside or directly above the BookingSection**, where it removes the "do you walk in [my suburb]" objection right at the point of conversion. + +**Block 2 (FAQ)** is the only place to address objections like "what about wet weather," "what's your cancellation policy." It belongs **after** the booking form OR collapsed-by-default near the bottom of the page. FAQ before the form is friction; FAQ after the form catches the not-yet-convinced. + +**Proposal:** +- Split InfoSection into two components. +- Move suburb chips + hours into a slim band ABOVE the BookingSection. +- Keep FAQ as a section, but move it BELOW the BookingSection (right before Instagram or Footer). + +--- + +### 8. BookingSection — **KEEP and PROMOTE in flow** + +This is *the* conversion target. Currently it sits 8th on a 9-section page. On mobile this is at least 6+ screens of scrolling. The sticky `MobileBookBar` helps, but desktop has no equivalent. + +**Watch:** the BookingSection currently uses the `card-stepper` variant (saw in `+page.svelte`), which is a multi-step card form. Step forms convert well when the steps are short, badly when they feel like a survey. Verify the first step is *radically* lightweight (1 field max). + +**Proposal:** +- **Promote BookingSection to position 5 or 6** (after social proof, before founder-story-as-trust-confirmation). +- Add suburb chip band immediately above. +- Add the 3-step "how it works" strip immediately below. +- Remove redundant section padding that double-spaces it from neighbors. + +--- + +### 9. InstagramSection — **DEMOTE or KILL** + +Currently the last content section before footer. Yellow billboard (until just reverted) with a "Follow us on Instagram" CTA. + +**Hard question:** how many homepage visitors will Goodwalk *acquire* by getting them to follow the Instagram instead of booking? Almost none. The Instagram link is a *brand-discovery* mechanism, not a conversion path. It belongs in the footer as a social icon, not as a section. + +**Proposal options:** +| Option | Effort | Trade-off | +|---|---|---| +| **A. Kill the section.** Move Instagram link to footer social icons only. | 1 hour | Loses a real estate moment for users who want to lurk-research before booking. | +| **B. Demote to a thin strip** above the footer — Instagram icon + grid of 4-6 recent photos as a passive link. No yellow background. | Half day | Less in-your-face; lets visual lurkers find it. | +| **C. Keep as-is but move ABOVE the BookingSection.** | 5 min | Probably worst option: yellow billboard interrupts the path to conversion. | + +**Recommend B.** A subtle Instagram strip — six recent posts, no copy, link out — gives the brand-discovery user what they want without competing with the booking CTA. + +--- + +### Header & Footer — out of scope here + +Header (sticky nav + mobile menu + book CTA) is fine. Footer carries the legal/contact/social/locations real estate well after the typography pass. + +--- + +## Proposed new sequence + +``` +1. Header +2. HeroSection (hook + Google trust) +3. ServicesSection (PROMOTED ↑ — answers intent) +4. TestimonialsSection (PROMOTED ↑ — social proof) +5. WhyGoodwalkSection (= old Values, before/after only) (TRIMMED — emotional payoff) +6. HowItWorksSection (process clarity) +7. FounderStorySection (TRIMMED to 120 words) +8. LocationsBand (= old Info block 1) (NEW slim qualifier band) +9. BookingSection (PROMOTED ↑ — the conversion) +10. FaqSection (= old Info block 2) (catches not-yet-convinced) +11. InstagramStrip (= demoted Instagram) (RECOMPOSED — passive) +12. Footer +``` + +**Net: 10 sections instead of 9, but ~30% less total scroll height** because Values lost 2 sub-blocks and FounderStory lost half its body copy. + +**Story arc:** +1. Hook +2. Offering ("what can I get") +3. Proof ("who else gets it") +4. Promise ("what changes for my dog") +5. Process ("how does it work") +6. Trust ("who runs this") +7. Qualification ("do you cover me") +8. **Action** ("book") +9. Objection handling ("what if X") +10. Brand discovery ("see more") + +The booking form sits 8th in the new flow vs 8th in the current flow — same numeric position, but with ~40% less scroll above it. + +--- + +## Conversion-flow analysis + +### Friction points in the current page + +| # | Issue | Impact | +|---|---|---| +| 1 | Booking form below 7 sections of content | Desktop users without sticky CTA must scroll a long way to convert. | +| 2 | FounderStory has 2 CTAs (email + book) | Splits attention at a high-conviction moment. | +| 3 | InfoSection FAQ before BookingSection | FAQ before the form makes the form feel optional. FAQ after the form catches the abandoners. | +| 4 | Values + FounderStory both run the "Tiny Gang philosophy" pitch | Diminishing returns on emotional copy. | +| 5 | InstagramSection competes with BookingSection's CTA | Section after form siphons attention from the form. | +| 6 | Values gallery + Testimonials = duplicate photographic social proof | One earns its keep; the other dilutes. | + +### Conversion-flow wins from the proposal + +| Win | Mechanism | +|---|---| +| Faster to "where do I book" | Services 3rd, Booking 9th (in a shorter page). | +| Stronger social proof early | Testimonials at 4 instead of 6. Confidence cascades into the rest of the read. | +| Pre-qualification | Suburb chips immediately above the form reduce "do you walk in my area" abandon. | +| Single CTA per section | FounderStory loses its email link. Every emotional moment funnels to the booking form. | +| Objection-handling at the right place | FAQ moves below the form so it catches the hesitant, not the eager. | + +--- + +## What I'd actually ship first (highest ROI) + +If you only do three things from this audit: + +1. **Cut the Values photo gallery.** 30 minutes. Removes the most redundant block and saves a screen of scroll. (Just delete the `clientPhotos` constant and the `.values-photo-grid` figure block in `ValuesSection.svelte` — confirmed the rest of the section stands on its own.) + +2. **Move suburb chips above the BookingSection.** 1 hour. Pre-qualifies the lead inline at the highest-conviction moment. Best single-shot conversion-rate move on the page. + +3. **Trim FounderStory body copy from 4 paragraphs to 2 and remove the email-Aless CTA.** 30 minutes. Restores the section's tempo. Single CTA = stronger conversion path. + +Everything else (Services promotion, Instagram demotion, Info split, FAQ relocation) is good follow-up work but those three deliver the bulk of the win. + +--- + +## What NOT to cut + +- **Hero.** Untouchable. +- **Testimonials.** Local services live and die on five-star reviews. Trim count if needed, never remove. +- **BookingSection.** It's the conversion target. +- **Google trust chips in the Hero.** Smallest UI on the page; biggest conversion signal. + +--- + +## Notes on implementation order + +If you decide to proceed, recommended PR sequence to keep risk low: + +1. **PR 1 — Values cut.** Photo gallery + values points removed. Section keeps the before/after contrast only. Update homepage to match new section size. *Visual: -1 screen.* +2. **PR 2 — Founder trim.** Reduce body copy to 2 paragraphs. Remove email CTA. *Visual: -300px.* +3. **PR 3 — Info split.** New `<LocationsBand />` + new `<FaqSection />`. Update `+page.svelte` to render them in new positions. +4. **PR 4 — Section reorder + Instagram recompose.** Last because it touches `+page.svelte` order, has the most visual impact, and benefits from the earlier trims already being in. + +Each PR is independently shippable and visually reviewable. None block the others. None require a redesign of any individual section — just structural surgery on what's bundled where. diff --git a/docs/marketing-principles.md b/docs/marketing-principles.md new file mode 100644 index 0000000..dbcdad8 --- /dev/null +++ b/docs/marketing-principles.md @@ -0,0 +1,185 @@ +# Marketing Principles for Goodwalk + +A working reference for the Goodwalk site rebuild and ongoing marketing decisions. Drawn from Chris Do (The Futur) and Debbie Millman (Design Matters), applied to the goal of acquiring 10 new clients. + +## Checklist +* Prioritise emotional trust before visual impressiveness. +* Reduce cognitive load on every screen and interaction. +* Every page should answer: “Am I in the right place?” +* Use whitespace intentionally to create calmness and confidence. +* Interfaces should feel predictable, stable, and effortless. +Avoid clutter, excessive animations, and visual noise. +Design for clarity first, aesthetics second. +Premium experiences rely on restraint, not excess. +Typography hierarchy must immediately guide the eye. +Use fewer colours, but apply them consistently. +Every component should have a clear purpose. +Remove unnecessary borders, labels, and UI chrome. +Make primary actions visually obvious within 2 seconds. +Ensure pages feel fast even before fully loading. +Consistent spacing creates perceived quality and trust. +Use authentic photography over generic stock imagery. +Human faces increase emotional connection and trust. +Testimonials should feel personal and believable, not corporate. +Buttons and CTAs should sound conversational and reassuring. +Interfaces should feel welcoming, not technical. +Avoid overwhelming users with too many choices. +Users should never wonder what happens next. +Design layouts around scanning behaviour, not reading behaviour. +Mobile layouts should feel intentionally designed, not compressed desktop pages. +Use subtle depth, shadows, and contrast to create hierarchy. +Premium brands often use less content, but communicate more clearly. +Calm interfaces increase perceived professionalism. +Align visuals, copy, and interaction style into one consistent tone. +The homepage should communicate trust before features. +Every visual element should reinforce simplicity and confidence. +Reduce form friction wherever possible. +Users should be able to understand the business in under 5 seconds. +Make service quality visually obvious through imagery and spacing. +Avoid sharp transitions or jarring visual elements. +Consistency across pages matters more than visual complexity. +Good UX feels invisible to the user. +Use natural language instead of corporate wording. +Remove anything that feels “template-like”. +Create visual breathing room around important content. +Make interactions feel human, warm, and intentional. +Ensure hover states and animations feel subtle and refined. +Use imagery that reflects real customers and real experiences. +Trust is built through consistency, polish, and predictability. +Pages should feel curated, not crowded. +Premium experiences rely heavily on pacing and rhythm. +Focus attention using contrast, spacing, and hierarchy. +Design should lower anxiety and decision fatigue. +Avoid overexplaining when visuals already communicate meaning. +The best interfaces feel calm, simple, and inevitable. +Every redesign decision should improve trust, clarity, or emotional comfort. + +--- + +## Chris Do's Principles + +### 1. Sell the transformation, not the service + +People don't buy "dog walking" — they buy peace of mind at work, a tired happy dog, not feeling guilty. + +The headline shouldn't be "Professional Dog Walking in Wellington." It should speak to the outcome: + +- "Come home to a happy, exercised dog" +- "Your dog's best part of the day, while you're at work" + +### 2. Niche down to stand out + +"Dog walker" competes with everyone. "Dog walker for working professionals in [suburb] with anxious or reactive dogs" competes with almost no one — and can charge more. + +Pick a wedge. + +### 3. Price on value, not time + +Don't lead with "$25 per walk." Lead with packages and outcomes: + +> **The Working Professional Plan** — 3 walks/week, GPS updates, photo reports + +Hide the hourly rate. Make it about what they get, not what you do. + +### 4. Show, don't tell + +Testimonials and proof crush adjectives. "Reliable and caring" is meaningless. + +A photo of a muddy grinning dog with a one-line quote from the owner sells: + +> "Bowie pulls me to the door when he sees Sarah's car." + +### 5. Free is a magnet + +Most dog walking sites just have a contact form — that's a closed door. Open one with: + +- A free first walk +- A free meet-and-greet +- A downloadable "Is your dog getting enough exercise?" checklist + +Get people into the funnel. + +--- + +## Debbie Millman's Principles + +### 1. Brand is a story people tell themselves about you + +Branding is deliberate differentiation through storytelling. + +What's the Goodwalk story? Why do you do this? Are you the ex-vet-nurse who only walks small dogs? The runner who takes high-energy breeds on actual trail runs? + +That story belongs on the homepage, not buried on About. + +### 2. Consistency builds trust + +One voice, one visual identity, everywhere: + +- Website +- Instagram +- Car magnet +- The message sent when running 5 minutes late + +Owners are handing you keys to their house and the life of their dog. Visual and verbal consistency signals "I am organised and reliable" before you've said a word. + +### 3. Design is a tool for clarity, not decoration + +Debbie often quotes Massimo Vignelli — design should make the message clearer. + +In 3 seconds, can a stranger answer: + +- What do you do? +- Who is it for? +- How do I book? + +If they have to scroll or think, you're losing them. + +--- + +## Applied: A Plan for 10 New Clients + +A site rewrite with these principles in mind. + +### 1. Homepage hero + +- Outcome-focused headline +- One strong photo of a happy dog mid-walk +- One button: **"Book a free meet-and-greet"** + +### 2. Pick a niche and say it out loud + +Even just "for [your suburb] working professionals" narrows the field and helps you rank. + +### 3. Three packages, not an hourly rate + +Make the middle one the obvious choice (the "decoy effect" — Chris talks about this). + +### 4. Three testimonials with photos and dog names + +Real names, real dogs. Not "J.S. — Customer." + +### 5. One story section + +Who you are, why you do this, why someone should trust you with their dog and their house key. + +### 6. Lead magnet + +A free PDF like "How much exercise does your dog actually need?" in exchange for an email. Then you have a list to follow up with. + +### 7. Kill booking friction + +One-click to a calendar or a WhatsApp link. Not a 7-field form. + +--- + +## Quick Reference Checklist + +- [ ] Headline sells the outcome, not the service +- [ ] Niche is named explicitly on the homepage +- [ ] Pricing presented as packages, not hourly +- [ ] At least 3 testimonials with real names, dog names, and photos +- [ ] Founder story visible on homepage +- [ ] Lead magnet (PDF or free meet-and-greet) above the fold +- [ ] Booking is one click — calendar link or WhatsApp +- [ ] Visual and verbal identity consistent across site, Instagram, and comms +- [ ] In 3 seconds: what / who / how-to-book is obvious diff --git a/docs/marketing-voice.md b/docs/marketing-voice.md new file mode 100644 index 0000000..6da0810 --- /dev/null +++ b/docs/marketing-voice.md @@ -0,0 +1,197 @@ +# Goodwalk Marketing Voice + +A practical guide for writing site copy that sells without sounding like it's selling. + +## The voice in one line + +**A trusted neighbour who happens to be brilliant at this.** Calm, certain, warm, specific. Not corporate. Not chirpy. Not over-promising. + +## What we're borrowing from Apple + +Apple's marketing works because it does three things ruthlessly: + +1. **Leads with the outcome, not the process.** "A thousand songs in your pocket" — not "5GB of solid-state storage." +2. **Makes the decision feel small.** Confident, declarative sentences. No hedging. +3. **Cuts every word the meaning doesn't need.** Short. Then one longer line for texture. Then short again. + +For a service business, the equivalent is selling the **evening** (calm dog, settled house, no guilt), not the **walk** (60 minutes, pickup included, group size 4–8). + +## Voice attributes + +| Attribute | What it means | What it isn't | +|---|---|---| +| **Calm** | Even cadence. No exclamation marks. No "amazing!" or "incredible!" | Hyped, sales-y | +| **Certain** | "We do X." Not "We try to X" or "We may be able to X." | Arrogant, brash | +| **Warm** | Real feeling for dogs and owners. "Your dog comes home tired and happy." | Saccharine, cutesy ("fur babies", "pawsome") | +| **Specific** | Names suburbs, parks, times. Numbers when they help. | Vague ("various", "a wide range", "we offer") | +| **Honest** | If a service isn't right for a dog, we say so. | False scarcity, manipulative urgency | + +## Principles + +### 1. Lead with the customer's win, not your feature + +Open every section with what the **owner gets** or what the **dog feels**. The mechanism comes second. + +> ❌ "Tiny Gang Pack Walks are built for Auckland Central owners of small and medium dogs who want a reliable weekly routine." +> +> ✅ "Your dog comes home tired and happy. You stop worrying through the workday. That's the whole point." + +### 2. Cut every hedge + +Search-and-destroy these words: *can, may, might, try to, more, genuinely, properly, generally, often, typically, possibly.* Each one quietly weakens the sentence. + +> ❌ "Walks tailored to your dog's pace, confidence, and routine." +> +> ✅ "Built around your dog. Their pace. Their walk." + +### 3. Short. Then long. Then short. + +Vary the rhythm. A wall of medium-length sentences is the most boring possible cadence. + +> ❌ "Goodwalk Tiny Gang Pack Walks are built for Auckland Central owners of small and medium dogs who want a reliable weekly routine, a well-exercised dog, and more peace of mind during the workday." +> +> ✅ "A walk your dog looks forward to. A routine you don't have to manage. Pickup, walk, drop-off, photo update — every time, without you having to ask." + +### 4. Active voice, present tense + +Things happen. We do them. Your dog enjoys them. Avoid "are designed to" / "is intended for" / "can be tailored." + +> ❌ "Our visits are intended to provide enrichment and support during the day." +> +> ✅ "We visit. We play. We feed. You get a photo when we leave." + +### 5. Replace abstract nouns with concrete verbs + +"Provide structure" → "settles them." "Build confidence" → "they stop pulling on the lead." "Ensure consistency" → "same walker, every time." + +### 6. Specifics build trust faster than adjectives + +"A well-loved local park" tells me nothing. "Western Springs at 9:15, Cornwall Park on Wednesdays" tells me you're real. + +### 7. Sell the relief + +Owners aren't buying a walk. They're buying: a quieter evening, a guilt-free workday, one fewer thing to manage. Name those. + +### 8. One idea per sentence + +If you wrote a comma, ask whether it should be a full stop. + +## Patterns we use + +### Headlines + +Two flavours, used purposefully: + +- **Outcome line:** "Come home to a calm, happy dog." +- **Definitional line:** "Pack walks for small dogs that actually suit small dogs." + +Avoid: "Welcome to Goodwalk." / "About Us." / "Our Services." + +### Subheads / leads + +One sentence. Says what the section delivers, not what it is. + +> ❌ "About our pack walks" +> +> ✅ "Four to eight dogs. Same walker every time. Home by mid-afternoon." + +### Body copy + +- 1–3 short paragraphs max per section +- Lead sentence is the most important; treat it like a headline +- One link or CTA per paragraph, max + +### CTAs + +Action + outcome, never just "Submit" or "Learn more." + +| ❌ | ✅ | +|---|---| +| Submit | Book a free Meet & Greet | +| Learn more | See if Tiny Gang fits your dog | +| Contact us | Talk to Aless | +| Get started | Start with a Meet & Greet | + +### FAQ answers + +- First sentence answers the question completely +- Second sentence (if any) adds the texture +- No "Great question!" / "Glad you asked" + +> Q: How big are the pack walks? +> +> ✅ "4–8 dogs, carefully matched on size and energy. We never run oversized packs — the small group size is the whole point." + +## Words and phrases + +### Use + +- **You / your dog** — far more than "owners" or "clients" +- **We** — direct, owned. Not "the team" or "our walkers" +- **Walk, visit, pickup, drop-off** — the customer's words +- **Tiny Gang** — our signature, use sparingly so it stays distinct +- **Auckland Central** — anchors local intent +- Concrete park names, suburb names, times + +### Avoid + +- "Solutions" — never. We're not enterprise software. +- "Services" as a noun in body copy — too distant. Name the thing. +- "Pet parents" / "fur babies" / "pup parents" — twee +- "Pawsome" / "pawfect" / any pun — never +- "We are passionate about" — show, don't tell +- "Industry-leading" / "best in class" / "premium" — empty +- "Reach out" — say "email" or "text" or "call" +- Exclamation marks in headlines or body copy + +## Sentence length budget + +- **Headlines:** ≤ 8 words +- **Subheads:** ≤ 14 words +- **Body sentences:** average 12–16 words, max ~24 +- **First sentence of any section:** ≤ 12 words + +If you wrote a 30-word sentence, it's two sentences. + +## Before / after, from the live site + +### Hero subtitle (homepage) + +> ❌ "Reliable dog walking for busy Auckland owners who want happier dogs, calmer evenings, and a team they can trust." +> +> ✅ "Reliable dog walking across Auckland Central. Happier dogs. Quieter evenings." + +### Pack walks intro paragraph + +> ❌ "Goodwalk Tiny Gang Pack Walks are built for Auckland Central owners of small and medium dogs who want a reliable weekly routine, a well-exercised dog, and more peace of mind during the workday." +> +> ✅ "Tiny Gang is built for small and medium dogs who like the right kind of company. Small groups. Same walker. A real walk, every time." + +### Puppy visits subtitle + +> ❌ "Toilet breaks, play, feeding, and calm one-on-one attention — at home, while you're out." +> +> ✅ "While you're at work, your puppy is fed, played with, and looked after. At home." + +### Benefits-section intro + +> ❌ "Small, compatible groups give dogs the exercise, confidence, and routine they need without the chaos of oversized pack walks." +> +> ✅ "Small groups. Compatible dogs. No chaos. That's why it works." + +## A 60-second editing pass + +Before any new copy ships, run it through this: + +1. **Cut 20%.** If you can't, cut 10%. +2. **First sentence test.** Could it be a headline? If not, rewrite. +3. **Hedge sweep.** Delete every *can/may/might/try to/generally/typically* and re-read. Most are improvements. +4. **Active voice check.** Search for "is/are [verb-ed] by" or "is intended to" and rewrite. +5. **Specific vs vague.** Replace one vague phrase per paragraph with a real name, number, or detail. +6. **Read it aloud.** If you take a breath mid-sentence, it's too long. + +## When to break these rules + +- **Legal pages, contracts, privacy.** Be precise and complete, not punchy. +- **Onboarding instructions.** Clarity > rhythm. +- **Genuine warmth moments.** A short, slightly longer line about a dog or a moment is allowed — it's the texture. Just don't make it the default. diff --git a/docs/mobile-polish.md b/docs/mobile-polish.md new file mode 100644 index 0000000..22103dc --- /dev/null +++ b/docs/mobile-polish.md @@ -0,0 +1,332 @@ +# Mobile Polish — Conversion & Comfort Audit Tracker + +## New Rescan Items — Mobile Conversion Opportunities + +Fresh opportunities from a second mobile-first pass over the main site. +These are intentionally only the new items, kept separate from the +existing audit below. + +### High — conversion strategy and flow + +- [ ] **Hero CTA hierarchy still prioritises browsing over booking** + - Files: `src/lib/content/homepage.ts:37-39`, `src/lib/components/HeroSection.svelte` + - Current: the yellow primary CTA is `Explore our services →`, while + `Book a Meet & Greet` is secondary. + - Why: on mobile, high-intent users should be able to choose the next + step immediately. Making the exploratory path more visually dominant + adds friction before the user reaches the lead form. + - Opportunity: test flipping the hierarchy on mobile so booking + becomes the primary CTA and service exploration becomes secondary. + +- [ ] **Homepage social proof appears too late in the scroll** + - File: `src/routes/+page.svelte:143-147` + - Current order: `Services -> Values -> Testimonials -> Booking`. + - Why: testimonials are one of the strongest conversion levers, but + on mobile they arrive after several large sections. Users are asked + to keep scrolling before seeing the strongest emotional proof. + - Opportunity: move testimonials above values on the homepage, or + surface one featured review snippet earlier in the page. + +- [ ] **Hero still relies on the next section for trust** + - Files: `src/lib/content/homepage.ts:43-49`, `src/lib/components/HeroSection.svelte`, + `src/lib/components/IntroStrip.svelte` + - Current: the hero presents the headline and CTAs, but the review + proof sits in the intro strip below. + - Why: on mobile, the hero needs to answer both "what is this?" and + "can I trust them?" before the user scrolls away. Separating those + two jobs weakens the first decision moment. + - Opportunity: add a compact review/trust chip directly under the + hero subtitle or near the hero CTAs on mobile. + +- [ ] **Booking flow asks for dog details before it captures the lead** + - File: `src/lib/components/BookingSection.svelte:298-441` + - Current: step 1 asks for dog name, location, message, and services; + contact details are only requested in step 2. + - Why: this is a higher-friction sequence on mobile. Users often feel + more comfortable giving owner details first, then expanding into pet + specifics once they have mentally committed. + - Opportunity: test reversing the step order so step 1 captures name, + email, and phone first, then dog details second. + +### Medium — mobile persuasion and CTA timing + +- [ ] **Sticky mobile CTA appears on a fixed pixel threshold rather than page context** + - File: `src/lib/components/MobileBookBar.svelte:26-37` + - Current: visibility is driven by `SHOW_AFTER_PX = 480` and + `HIDE_BELOW_PX = 120`. + - Why: a fixed threshold will feel early on some phones and late on + others. It also ignores whether the hero or booking section is + actually in view. + - Opportunity: switch to an `IntersectionObserver` tied to the hero or + booking section so the bar appears based on user context rather than + raw scroll position. + +- [ ] **Testimonials section pushes users off-site before finishing the proof story** + - File: `src/lib/components/TestimonialsSection.svelte:128-134` + - Current: the Instagram CTA appears near the top of the testimonials + section, before the user has fully consumed the review content. + - Why: on mobile, sending users to Instagram this early interrupts the + conversion journey and competes with the booking path. + - Opportunity: demote the Instagram CTA below the carousel, or replace + it with a tighter trust-oriented proof CTA higher up. + +- [ ] **Mobile pricing pages lose the consultative "not sure?" nudge** + - File: `src/lib/components/PricingPage.svelte:12-19` + - Current: the meet-and-greet reminder prompt is gated behind + `min-width: 769px`, so desktop gets a tailored nudge and mobile + does not. + - Why: mobile users are more likely to feel overwhelmed by stacked + pricing cards, not less. Removing the consultative reassurance on + the smallest screens is directionally backwards for conversion. + - Opportunity: add an inline mobile prompt after the first pricing + section that says, in effect, "Not sure which option fits? Book a + free Meet & Greet and we’ll help you choose." + +### Medium — stacked-page CTA noise + +- [ ] **Stacked pricing/service cards repeat the same CTA too many times** + - Files: `src/lib/components/PricingPage.svelte:141-159`, + `src/lib/components/ServiceLandingPage.svelte:94-112` + - Current: when cards collapse to one column on mobile, each card + keeps a full "Book a Meet & Greet" button. + - Why: the repetition turns persuasive choice architecture into visual + noise. Instead of helping the user decide, the page starts feeling + like a stack of repeated asks. + - Opportunity: treat this as a shared mobile pattern across pricing + and service pages. Keep one strong CTA per section, let the popular + card carry the primary action, and demote the rest. + +Findings from a focused mobile-experience review (≤768px, with extra +attention to 375px small-phones). Desktop is considered done. Each item +records the where, why, and the concrete change. + +> Important context for prioritisation: a dog-walking business is a +> jobs-to-be-done service that users research on the couch. Mobile +> conversion lower-bound is "they Meet & Greet". So the dial-movers +> are: thumb-reach for the booking CTA, legibility, friction-free +> form, and trust signals visible on the first scroll. + +--- + +## High — direct conversion impact + +- [x] **Hero buttons stack awkwardly at ~375px** + - File: `src/lib/styles/responsive.css` (new ≤480px block) + - Implementation: At `@media (max-width: 480px)` the hero buttons + flip to `flex-direction: column; gap: 12px;` and each button + becomes full-width with padding `16px 24px`. The 768px-specific + `padding-right: 18px` on the buttons row and the + `margin-right: 12px` on `:last-child` are both reset so the two + CTAs read as a clean stacked stack. + - Why: At 375px the side-by-side primary + outline CTAs were wrapping + unevenly and the primary's prominence collapsed. + +- [x] **Mobile header phone button is low-contrast and small** + - File: `src/lib/styles/responsive.css:88-100` + - Implementation: Background bumped from `rgba(33, 48, 33, 0.06)` → + `0.10`; padding 9px 12px → 11px 14px (and at ≤480px, 10px 12px); + `font-weight: 600`; `min-height: 44px` to meet the touch-target + minimum; icon size also bumped from 13px → 14px. + - Why: The tap-to-call on the mobile header is one of the highest + intent actions on the site. It now reads as a button rather than a + barely-visible label. + +- [x] **Booking form inputs trigger iOS zoom-on-focus** + - File: `src/lib/styles/responsive.css:453-462` + - Implementation: Input `font-size: 15px` → `16px` at ≤768px. Comment + added explaining the iOS-Safari 16px threshold so a future edit + doesn't accidentally drop it again. + - Why: Below 16px Safari auto-zooms on focus; the page jolts every + time a field is tapped. Critical at the booking conversion step. + +- [ ] **Testimonial carousel arrows hard to reach at 375px** + - File: `src/lib/components/TestimonialsSection.svelte` (mobile rules + lines ~640-660) + - Current: arrows pinned to `bottom: 24px` inside a stage with + `padding-bottom: 116px`. Visually at the bottom of a tall card — + requires deliberate stretching. + - Why: The carousel feels passive. Users don't realise they can advance + it; testimonials sell — losing that engagement matters. + - Fix: Lift arrows on small screens: + ```css + @media (max-width: 480px) { + .testimonial-arrow { bottom: 80px; } + } + ``` + +- [x] **No persistent "Book Meet & Greet" CTA on mobile after hero scrolls past** + - Files: `src/lib/components/MobileBookBar.svelte` (new), + `src/routes/+layout.svelte` (mount), `src/lib/styles/responsive.css` + (`body { padding-bottom: 64px }` at ≤768px). + - Implementation v2 — *Airbnb-style soft-container, scroll-triggered*: + - **Soft container**: a translucent white tray (`rgba(255, 255, + 255, 0.96)` with backdrop-filter blur) sits flush at the bottom + with a thin top hairline and a soft shadow. The brand-yellow CTA + pill lives *inside* the tray, not as the tray itself — so the + action stays unmistakable but the surrounding chrome is calm. + - **Scroll-triggered**: the bar slides up + fades in only after the + user has scrolled ~480px (≈ one mobile viewport, hero out of + view). Slides back out below ~120px to avoid flicker near the + top. `prefers-reduced-motion` respected — the slide is dropped, + only the opacity fade remains. + - **Hidden on `/contact-us` and `/booking`** (already in the form). + - **Resets on navigation**: `afterNavigate` resets `visible = false` + so each new page starts hidden until the user has earned it again. + - **Accessibility**: `aria-hidden` toggles with visibility; CTA + `tabindex` flips to `-1` while hidden so keyboard users don't + stumble onto an off-screen control; `pointer-events: none` while + hidden so the user can't accidentally tap it during the fade. + - **Safe-area aware**: `env(safe-area-inset-bottom)` so iPhones + with the home-bar gesture area get correct spacing. + - Body bottom-padding of 64px on mobile keeps the footer from sitting + behind the bar when it's visible at the bottom of long pages. + - Why: Sticky mobile CTAs are a validated conversion pattern (Airbnb, + Booking.com, etc.), but the v1 full-yellow bar was tonally wrong + for Goodwalk — it competed with the calm brand voice and dominated + the screen permanently. v2 keeps the conversion benefit (one-tap + booking, always one swipe away after engagement) without yelling. + +## Medium — legibility & polish + +- [x] **Hero title can wrap awkwardly at 375px** + - File: `src/lib/styles/responsive.css` (≤480px block) + - Implementation: At ≤480px the desktop H1 drops to 32px / + line-height 1.12 and the dedicated `.hero-heading-mobile` element + drops to 30px / 1.12 (it was 33.5px). The two-line "Unleashing Fun + in / Your Dog's Day!" now sits comfortably with breathing room + above the subtitle. + - Why: Previous 38px / 33.5px sizings were a hair too big for 375px; + line-2 felt cramped against the subtitle. + +- [x] **Body text 15px feels small on mobile (and on ultra-wide desktop)** + - File: `src/lib/styles/responsive.css` (≤768px body rule) + - Implementation: `body { font-size: 16px; }` at ≤768px, with a + comment noting the iOS-Safari 16px zoom threshold so this rule + isn't accidentally undone. + - Desktop (≥769px) still inherits 15px from `base.css` for now — the + ultra-wide bump is tracked separately at the bottom of this file + so it can be reasoned about independently (clamp vs. breakpoint). + - Why: 16px is the modern legibility standard on mobile, dovetails + with the iOS zoom-on-focus rule for inputs, and reduces read + fatigue on long pages (about, FAQ answers, legal). + +- [ ] **FAQ summary tap target too small** + - File: `src/lib/styles/sections.css` (`.faq summary` rules) + - Current: just text height (~22-26px) — below the 44px minimum. + - Fix: + ```css + .faq summary { + padding: 12px 0; + min-height: 44px; + display: flex; align-items: center; + } + ``` + +- [ ] **Booking service-option chips wrap awkwardly at 375px** + - File: `src/lib/styles/responsive.css:468-470` + - Fix at ≤480px: 2-up grid with tighter gap: + ```css + .booking-service-options { gap: 10px 12px; } + .booking-toggle-option { flex: 1 1 calc(50% - 6px); } + ``` + +- [ ] **Footer social icons spaced too tight for thumbs** + - File: `src/lib/styles/sections.css` (`.social-links { gap: 14px }`) + - Current 14px gap with 40px icons → centres are 54px apart. Apple + HIG wants 8px+ between targets after the 44px minimum. + - Fix: + ```css + @media (max-width: 768px) { .social-links { gap: 18px; } } + ``` + +- [ ] **Pricing cards stack to 1-col with multiple "Book" buttons in a row** + - File: `src/lib/components/PricingPage.svelte` (and ServiceLandingPage + plan grids) + - Why: After stacking, the user sees Plan → Book → Plan → Book → Plan + → Book in vertical sequence. The repetition reads as noise rather + than choice; the "popular" anchor disappears. + - Fix (opinionated): on mobile, only the popular plan keeps its CTA + button. Other plans show a smaller "Choose this plan" link instead, + or no per-card CTA at all (a single CTA appears under the grid): + ```css + @media (max-width: 768px) { + .pricing-plan-card:not(.pricing-plan-popular) .pricing-plan-cta { + display: none; + } + } + ``` + Then keep the existing under-grid `.service-plan-reassurance` pill + and add a single "Book a Meet & Greet" button below it. + +- [ ] **Mobile nav header is too tall — eats above-the-fold real estate** + - File: `src/lib/styles/responsive.css:74` + - Current: `nav { padding: 20px 24px; }` + 25px logo = ~65px header. + On iPhone 13 (844px), this leaves ~380px for hero before scroll — + less than what the Goodwalk dog-image needs to feel like a hero. + - Fix at ≤480px: + ```css + nav { padding: 14px 20px; } + .logo img { height: 22px; } + ``` + +## Low — incremental polish + +- [ ] **Hero top padding generous at 375px** + - File: `src/lib/styles/responsive.css:179` + - Reduce hero `padding-top` from 50px to 32px at ≤480px. + +- [ ] **Intro trust badge feels edge-to-edge at 375px** + - File: `src/lib/styles/responsive.css:296-301` + - Add `padding: 18px 16px; margin: 0 12px;` at ≤480px. + +- [ ] **Testimonial quote mark too large at 375px** + - File: `src/lib/components/TestimonialsSection.svelte:~595` + - Current: 44px. Reduce to 36px at ≤480px. + +- [ ] **Booking form labels could shrink slightly at 375px** + - File: `src/lib/styles/responsive.css:450` + - Optional: 16px → 15px at ≤480px to give field width back to the + input value (where it actually matters for legibility). + +- [ ] **No scroll-to-top affordance on long pages (booking, pricing)** + - Currently absent. Low priority but helpful when users have scrolled + past the booking form and want to re-read service details. Could be + folded into the same sticky-book-bar work above (one bar, both jobs). + +## Open from elsewhere + +- [ ] **Ultra-wide desktop body font feels small** *(noted by user)* + - Currently `body { font-size: 15px }` ([base.css:15](src/lib/styles/base.css#L15)). + On ≥1800px screens with the `--max-w` already widening (per the + 1800px breakpoint), 15px in long-form sections (about, FAQ answers, + legal) becomes uncomfortable. + - Suggested fix: bump to `clamp(15px, 0.95vw, 17px)` on `body`, OR + introduce a `@media (min-width: 1600px) { body { font-size: 17px; } }`. + Either keeps the desktop ≤1599px experience identical and only + expands type when there's genuinely more reading width. + +## Deliberately not actioning + +- **Drop reveal animations on mobile to "save bandwidth".** They're + IntersectionObserver-driven, cost nothing perceivable, and add brand + polish. Removing them would make the mobile site feel cheaper for no + measurable performance gain. +- **Replace the testimonial carousel with a stacked list on mobile.** + Tempting (carousels famously hide content), but the carousel is + central to the brand's "see real dogs" pitch. Better to fix the arrow + reachability and let the autoplay do the work. + +--- + +## Suggested order of attack + +If you want one batch that moves the dial: **High items 1, 2, 3, 5** +together is roughly an hour of work — they hit the hero, the header +tap-to-call, the booking form's biggest mobile bug (zoom-on-focus), and +add the sticky CTA. That's the package I'd ship first. Item 4 (carousel +arrows) is a one-line fix once you're already in `responsive.css`. + +The Medium list is best as a second pass — body-text bump, +header-padding reduction, FAQ tap-target, and pricing-card-CTA dedupe +all compound into a noticeably more "intentional on mobile" feel +without any structural change. diff --git a/docs/nz-citations.md b/docs/nz-citations.md new file mode 100644 index 0000000..1ec5feb --- /dev/null +++ b/docs/nz-citations.md @@ -0,0 +1,58 @@ +# NZ Citations — Submission Sheet (C3) + +Use the exact NAP block below for every directory. Consistency is the whole +point — even small variations (brackets in phone, trailing punctuation, +`Ltd.` vs `Limited`) split your local trust signals. + +## Canonical NAP + +| Field | Value | +|---|---| +| Business name | `Goodwalk` | +| Phone (visible) | `022 642 1011` | +| Phone (E.164 / forms that ask for international) | `+64 22 642 1011` | +| Email | `info@goodwalk.co.nz` | +| Website | `https://www.goodwalk.co.nz` | +| Service area | Auckland Central (list 17 suburbs if a field allows: Morningside, Kingsland, Ponsonby, Grey Lynn, Mt Albert, Mt Eden, Sandringham, Mt Roskill, Arch Hill, Freemans Bay, Herne Bay, Pt Chevalier, Avondale, Three Kings, Hillsborough, Eden Terrace, Balmoral) | +| Address | Service-area business — do **not** publish a home address. If a directory mandates an address, use a postcode-only entry where possible (e.g. Auckland 1021). | +| Hours | Mon–Fri 8:00am–4:00pm | +| Category (primary) | Dog Walker | +| Category (secondary, where allowed) | Pet Sitter / Pet Care Service | +| Short description (160 chars) | Goodwalk runs Tiny Gang pack walks, 1:1 walks, and puppy visits across Auckland Central. Small-dog specialists, free pickup and drop-off. | +| Long description (use where 500+ chars allowed) | Goodwalk is an Auckland Central dog walking service run personally by Alessandra, a small-dog specialist. We offer Tiny Gang pack walks (4–8 dogs, from $49.50), one-on-one walks (from $45), and in-home puppy visits (from $39). Free pickup and drop-off across 17 inner-west suburbs including Ponsonby, Grey Lynn, Mt Eden, Kingsland and Morningside. Every walker holds public liability insurance and a current pet first aid certificate. New clients begin with a free, no-obligation Meet & Greet. 30+ five-star Google reviews. | +| Logo | `/static/images/goodwalk-auckland-dog-walking-logo.png` (export at 600×600 for directories) | +| Instagram | `https://www.instagram.com/goodwalk.nz/` | +| Google Business Profile | `https://g.page/r/CUsvrWPhkYrAEB0` | + +## Directories to claim (in priority order) + +| # | Directory | URL | Cost | Notes | +|---|---|---|---|---| +| 1 | **Google Business Profile** | already claimed | Free | Verify category is "Dog Walker"; add 8+ photos; respond to all reviews | +| 2 | **Yellow.co.nz** | https://yellow.co.nz/add-a-business | Free tier | NZ's largest directory — non-negotiable | +| 3 | **Finda.co.nz** | https://www.finda.co.nz/add-business | Free | Crawled by every local SEO tool | +| 4 | **Localist.co.nz** | https://www.localist.co.nz/business/add | Free | Auckland-focused, high local relevance | +| 5 | **Neighbourly.co.nz** | https://www.neighbourly.co.nz | Free | Suburb-level visibility — critical for pet services where locals ask "anyone know a good dog walker in Ponsonby?" | +| 6 | **NZS.com** | https://www.nzs.com | Free | General NZ directory, broad backlink value | +| 7 | **Facebook Business Page** | https://business.facebook.com | Free | Footer already links here — make sure the page actually exists with NAP matching | +| 8 | **NoCowboys** | https://www.nocowboys.co.nz | Free + paid | Reputation-focused; aim to gather a few reviews here too | +| 9 | **DogFriendly NZ** | https://dogfriendly.co.nz | Free | Industry-specific, low competition | +| 10 | **Pet Directory NZ** | https://www.petdirectory.co.nz | Free | Pet-specific authority signal | + +## After each citation goes live + +1. Save the public profile URL in a spreadsheet (you'll need the list to + update `sameAs` in the LocalBusiness JSON-LD on the homepage — + `src/routes/+page.svelte`). +2. Re-run `/seo local https://goodwalk.co.nz` after ~2 weeks to confirm + crawler discovery. + +## Anti-patterns to avoid + +- Do **not** vary the business name ("Goodwalk Auckland", "Goodwalk Ltd", + "Goodwalk Dog Walking") across listings. Pick `Goodwalk` and stick with it. +- Do **not** publish a home street address anywhere. SAB = service-area only. +- Do **not** use a tracking phone number — Google penalises NAP mismatches. +- Do **not** auto-syndicate via paid "submit to 50 directories" services — + they typically use slightly different NAP per source and create the exact + inconsistency you're trying to avoid. diff --git a/docs/product.md b/docs/product.md new file mode 100644 index 0000000..2d2a341 --- /dev/null +++ b/docs/product.md @@ -0,0 +1,33 @@ +# Product + +## Register + +brand + +## Users + +Busy Auckland dog owners, especially working professionals in the inner-west and nearby suburbs, who need dependable weekday care for dogs they treat like family. They are usually short on time, want a calmer home routine, and need to trust both the walker and the experience before booking. + +## Product Purpose + +Goodwalk exists to turn weekday dog care into a source of confidence rather than guilt or logistical stress. The site should quickly show what Goodwalk does, who it is for, why the service feels safer and more personal than generic dog walking, and how to book a free meet-and-greet with minimal friction. + +## Brand Personality + +Warm, grounded, premium. The voice should feel calm, reassuring, and human, with clear expertise but no corporate distance. The emotional goal is peace of mind: owners should feel that their dog will be known, safe, and genuinely looked after. + +## Anti-references + +Avoid generic SaaS landing-page patterns, loud pet-industry gimmicks, and clinical service-business layouts. This should not look hyper-animated, overly polished, corporate, cold, bargain-oriented, or like a template full of interchangeable cards and stock-style marketing language. + +## Design Principles + +1. Lead with trust before features. +2. Show the emotional outcome, not just the operational service. +3. Use restraint to signal quality: fewer, better elements with generous space. +4. Make booking feel easy, personal, and low-pressure. +5. Keep every page grounded in real dogs, real routines, and real care. + +## Accessibility & Inclusion + +Target clear, readable contrast, large tap targets, visible focus states, and strong mobile usability in outdoor and on-the-go conditions. Support reduced motion, preserve legibility at larger text sizes, and keep copy plain enough to reduce decision fatigue for anxious or time-poor users. diff --git a/docs/ux-polish.md b/docs/ux-polish.md new file mode 100644 index 0000000..f7345f8 --- /dev/null +++ b/docs/ux-polish.md @@ -0,0 +1,143 @@ +# UX Polish — Conversion Audit Tracker + +Findings from the senior-marketing-lens audit, with completion status. Each +item has a one-line rationale and the file/line where the change lives (or +will live). + +> Only commit to "We'll reply within 24 hours" if Aless can actually hold +> to it. If response time is more like 1-2 business days, soften to +> "within one business day". + +--- + +## High — direct conversion impact + +- [x] **Hero primary CTA: "Learn more" → "Explore our services →"** + - File: `src/lib/content/homepage.ts:38` + - Why: "Learn more" is the lowest-intent CTA that exists. + +- [x] **Promise CTA: "See our services" → "Book a free Meet & Greet"** + - File: `src/lib/content/homepage.ts:59` + - Also: target changed from `#services` to `/contact-us` so the CTA goes + to the booking page instead of bouncing back up to a service list. + - Why: After the value prop + happy-dog photo, sending visitors to the + services list is a step backwards. Push them to book. + +- [x] **Booking subtitle now states response time** + - File: `src/lib/content/homepage.ts:159-162` + - Old: *"...so we can reach out to arrange your free, no-obligation Meet & Greet."* + - New: *"...We'll reply within 24 hours to arrange your free, no-obligation Meet & Greet."* + - General-enquiry variant updated to match. + - Why: Open-ended "we'll reach out" creates anxiety at submit time. + +- [x] 1 **Pricing page — Google rating trust signal above plan grid** + - File: `src/lib/components/PricingPage.svelte` + - Implementation: Pill-styled trust badge inside the green hero, + directly under the subtitle — five yellow stars + "30+ five-star + Google reviews" label + arrow, links out to Google. Styled to read + against the green hero (semi-transparent white pill) rather than + reusing the cream IntroStrip, which would have clashed. + - Why: Visitors land on pricing mid-decision; trust signal now appears + before the plan grid. + +- [x] 2 **Service plan CTAs — add free / no-obligation reassurance** + - File: `src/lib/components/ServiceLandingPage.svelte` + - Implementation: A subtle green pill *"Every booking starts with a + free, no-obligation Meet & Greet."* (yellow shield-heart icon) sits + centred directly under the plan grid on every service page, above the + Extras block. Reuses the brand-tinted-pill aesthetic so it feels + native, not tacked on. + - Why: The "Book a Meet & Greet" buttons under each plan didn't carry + risk-reversal phrasing in their immediate context. Now they do. + +## Medium — trust + polish + +- [x] 3 **Quantify the Google rating wherever it appears** + - Files: `src/lib/content/homepage.ts:46`, + `src/lib/components/Footer.svelte:89`, + `src/lib/components/TestimonialsSection.svelte:200`, + `src/lib/components/PricingPage.svelte` (new pricing-trust pill). + - Implementation: "All 5 star reviews on Google!" → "30+ five-star + Google reviews" everywhere. Aless confirmed 30+ as the count. + - Why: A specific number is dramatically more credible than "all". + +- [x] 4 **Lean into the "limited spots" angle** + - File: `src/lib/content/pack-walks.ts` (added `scarcityNote` to the + `pricing` block); `src/lib/types.ts` (added optional `scarcityNote?: + string` to ServicePageContent.pricing); rendered in + `src/lib/components/ServiceLandingPage.svelte` directly under the + plan grid as a yellow-tinted pill with a clock icon. + - Copy: *"We keep packs small (4-8 dogs) — popular days fill up fast."* + - Only set on Pack Walks (the 4-8 number is specific to that service); + the field is optional so 1:1 Walks and Puppy Visits get nothing. + - Why: Real, honest scarcity. The 4-8 cap is already a fact; saying it + out loud nudges decision-making. + +- [ ] **About page — quantify Aless's expertise** + - File: `src/lib/content/about.ts:29-30` + - Why: "years of experience" is the weakest possible claim. Replace with + concrete numbers Aless can stand behind: years operating, dogs in + rotation, first-aid certification. + +- [x] 5 **Pack Walks pricing intro — lead with the differentiator** + - File: `src/lib/content/pack-walks.ts:23-24` + - Implementation: Old intro led with "Our pack walks are a permanent + booking of at least one walk day a week..." (commitment ask first). + New intro leads with the benefits: *"Small packs of 4-8 dogs, 2-hour + outings at Auckland's scenic dog parks and beaches, with free pick-up + and drop-off included. We reinforce recall, car manners, and leash + etiquette while your dog plays. Booked as a permanent weekly slot — + gift your dog the best life!"* + - Why: Buyers scan for benefits before commitments. Lead-with-policy + framing creates resistance; lead-with-benefit framing builds desire. + +- [ ] **FAQs — reframe from policy to reassurance** + - File: `src/lib/content/homepage.ts:180-205` + - Why: Answers are correct but read like terms & conditions. Lead with + the *why* (the benefit/reassurance), then the *what*. + +## Low — incremental polish + +- [x] **Home services-card CTAs: "Learn more" → outcome-oriented** + - File: `src/lib/components/ServicesSection.svelte:29` + - Implementation: Visible label is now derived from the service title — + *"See Pack Walks pricing →"*, *"See 1:1 Walks pricing →"*, *"See + Puppy Visits pricing →"*. The previously-added screen-reader-only + "about <Service>" span was removed since the visible label now carries + that context for everyone, not just assistive tech users. + - Why: "Learn more" was the lowest-intent CTA on the page; the new + label states the destination and the next step. + +- [x] **Testimonials intro blurb — sharper jobs-to-be-done framing** + - File: `src/lib/components/TestimonialsSection.svelte:10-11` + - Old: *"Happy owners, even happier dogs. Our Auckland dog walking + clients love what the Tiny Gang brings to their dog's routine — and + you can see why. Follow along on Instagram for daily adventures..."* + - New: *"Busy parents get peace of mind. Dogs come home tired and + happy. See why 30+ Auckland families trust the Tiny Gang — follow + along on Instagram for daily adventures, wagging tails and the odd + zoomie."* + - Why: Leads with the two outcomes buyers actually care about (peace of + mind for them, exercise for the dog), keeps the brand voice + 30+ + review proof point, then makes the Instagram nudge feel like a + follow-on rather than the lead. + +- [x] **Surface "Reliability / on-time" earlier** + - File: `src/lib/content/homepage.ts:37` (hero subtitle) + - Old: *"Trusted, professional dog walking across Auckland Central..."* + - New: *"Trusted, on-time dog walking across Auckland Central..."* + - Why: Reliability/punctuality is the #1 anxiety for busy parents + booking a service that visits their home. Pulling "on-time" into the + hero subtitle (one-word swap, no length cost) puts the reassurance + above the fold. + +## Deliberately not actioning + +- **Pack Walks H1 rewrite to "Small-dog pack walks designed for calm, + confident groups."** *"Join our Tiny Gang!"* is doing brand work — it's + memorable and reinforces a phrase used everywhere else. Rewriting kills + the most distinctive asset for marginal headline clarity. +- **Booking submit button: "Send" → "Book my Meet & Greet".** The form + also handles general enquiries, so a "book my…" label would feel wrong + on a complaint email. Better fix would be to switch the label by + `enquiryType` — keep "Send my booking" / "Send my enquiry" contextually. diff --git a/docs/webp-conversion.md b/docs/webp-conversion.md new file mode 100644 index 0000000..9c68461 --- /dev/null +++ b/docs/webp-conversion.md @@ -0,0 +1,56 @@ +# WebP Conversion (C5) — One-time setup + +The hero `<picture>` element in `src/lib/components/HeroSection.svelte` now +supports WebP sources. Once you generate the WebP files, add the URL fields +to the hero content block — the markup will start serving WebP automatically +to supporting browsers (every browser currently in use). + +## 1. Generate WebP variants + +From the project root, with `cwebp` installed (`brew install webp` / +`choco install webp` / `apt install webp`): + +```bash +# Mobile hero (already 1536x1024 — optimise + convert) +cwebp -q 82 static/images/maya-mascot.png -o static/images/maya-mascot.webp + +# Three new untracked images visible in git status +cwebp -q 82 static/images/happy-dogs-in-travel-ready-suv.jpg -o static/images/happy-dogs-in-travel-ready-suv.webp +cwebp -q 82 static/images/playful-dog-pack-in-park.jpg -o static/images/playful-dog-pack-in-park.webp +cwebp -q 82 static/images/testimonial-freddy-eating-stick-in-park.png -o static/images/testimonial-freddy-eating-stick-in-park.webp +``` + +Target file sizes: +- Hero (mobile): under 150 KB +- Hero (desktop): under 300 KB +- Testimonials/inline: under 80 KB + +## 2. Wire up the WebP source + +In `src/lib/content/homepage.ts`, uncomment and set: + +```ts +hero: { + // ...existing fields + imageWidth: 1536, + imageHeight: 1024, + imageWebpUrl: '/images/maya-mascot.webp' +} +``` + +If you also produce a desktop-specific variant, add `desktopImageUrl` and +`desktopImageWebpUrl`. + +## 3. Verify + +Open the homepage in Chrome DevTools → Network → filter `Img`. You should +see `maya-mascot.webp` being served with `Type: webp`. The `.png` is the +fallback `<img>` and should only load if WebP is somehow unsupported. + +## Why this matters + +The codebase ships PNG/JPG hero assets. WebP at quality 82 typically lands +30–50% smaller than the equivalent PNG/JPG with no perceptible quality +difference. For the LCP element on a mobile homepage, that's a 0.5–1.5s +improvement on slow 4G — directly relevant to the `largest-contentful-paint` +Core Web Vital.