WebDev — Master Astro Template

The starter template that every site this pipeline produces is generated from. Drives Lighthouse 95+/100/100 builds out of the box, ships ~zero JS by default, and takes its content from a single brief.json.

What's in here

template/
├── astro.config.mjs            # site URL from env, sitemap + tailwind integrations
├── tailwind.config.mjs         # CSS-variable-driven brand colours
├── tsconfig.json               # strict mode + @/ path aliases
├── lighthouserc.cjs            # Perf >=95, SEO/A11y =100 build gate
├── brief.schema.json           # JSON Schema for brief.json
├── brief.schema.md             # human-readable explainer
├── brief.example.json          # working sample (gavingeorge.co.uk)
├── public/
│   └── robots.txt
└── src/
    ├── components/
    │   ├── SEO.astro           # title, meta, canonical, OG, Twitter
    │   ├── JsonLd.astro        # generic schema.org JSON-LD emitter
    │   └── LeadForm.astro      # markup-only form (Worker comes Wed 2026-05-13)
    ├── content/
    │   ├── config.ts           # locations, services, blog collection schemas
    │   ├── locations/example.md
    │   ├── services/example-service.md
    │   └── blog/welcome.md
    ├── layouts/
    │   └── BaseLayout.astro    # uses SEO + JsonLd, sticky mobile phone CTA
    ├── pages/
    │   ├── index.astro         # WebSite + LocalBusiness JSON-LD
    │   ├── about.astro
    │   ├── contact.astro
    │   ├── 404.astro
    │   ├── services/{index,[slug]}.astro    # Service + FAQPage JSON-LD
    │   ├── locations/{index,[slug]}.astro   # LocalBusiness JSON-LD per area
    │   └── blog/{index,[slug]}.astro        # Article JSON-LD
    └── styles/
        └── global.css          # Tailwind directives + brand tokens + reduced-motion

Commands

npm install                  # one-time
npm run dev                  # local dev server
npm run build                # static build to dist/
npm run preview              # preview the built dist/
npm run build:gated          # build + run Lighthouse CI assertions (Phase 1+ only)

Driving a build from brief.json

The site-generator script (Mon 2026-05-11) takes a brief.json, clones this template, populates the content collections, replaces brand tokens, and commits a fresh repo. Until then, manually edit:

• Brand: tailwind.config.mjs (CSS-variable defaults already wired) and src/styles/global.css (:root tokens).
• NAP / phone / email: .env with PUBLIC_SITE_NAME, PUBLIC_PHONE, PUBLIC_EMAIL, PUBLIC_TAGLINE. astro.config.mjs reads SITE_URL for the canonical base.
• Pages: Markdown files in src/content/{locations,services,blog}/. Frontmatter shape is enforced by src/content/config.ts.

See brief.schema.md for the full brief shape.

SEO scaffolding (out-of-the-box)

• Per-page <title>, meta description, canonical URL, OG, Twitter — src/components/SEO.astro.
• JSON-LD per page type: WebSite + LocalBusiness on home, Service + FAQPage on service pages, LocalBusiness per location, Article per blog post — src/components/JsonLd.astro.
• sitemap-index.xml + sitemap-0.xml generated by @astrojs/sitemap.
• robots.txt allows everything and points at the sitemap.
• Lighthouse CI gate in lighthouserc.cjs blocks builds below 95/100/100.

Lead capture

LeadForm.astro posts to /api/lead (a Cloudflare Pages Function — wired Wed 2026-05-13). Includes:

• Honeypot field (company_website)
• Cloudflare Turnstile mount point (sitekey injected at deploy time)
• Required-on-client validation, autofill hints
• Privacy-notice microcopy + 1-working-day promise

What's deliberately NOT in here yet

Layer	When
Cloudflare Pages deploy wiring	Thu 2026-05-07
Form Worker (CF Pages Function → Emailer + LeadCatcherCore)	Wed 2026-05-13
generate_site.py script that consumes brief.json	Mon 2026-05-11
/web-new, /web-deploy, /web-audit skills	2026-05-15 onward
GEO content rules (capsule guard, two-layer context scaffolding)	Mon 2026-05-18
webdev-architect agent (Phase 1/2/3 content generation)	Wed 2026-05-20
Claude Design / Stitch / Nano Banana stage docs	Mon 2026-05-25
GSAP hero animation component	Wed 2026-05-27
Decap CMS overlay (saleable sites only)	Deferred

Phase 1 acceptance — the spine

The spine ships when:

1. npm install && npm run build produces a clean dist/ ✓ (done 2026-05-04)
2. Every page in dist/ has title + meta + canonical + OG + the right JSON-LD type ✓
3. Sitemap and robots are generated ✓
4. The site can deploy to Cloudflare Pages and load over HTTPS — due Thu 2026-05-07
5. Lighthouse CI passes 95/100/100 against the deployed URL — due Fri 2026-05-08

Steps 1–3 done. 4–5 are this week's targets.