create-website-build-kit 0.1.0

package/template/src/pages/accessibility.astro

@@ -0,0 +1,128 @@
+---
+/**
+ * Accessibility statement.
+ *
+ * A **required published artefact** under the European Accessibility Act, the
+ * UK PSBAR and the EU Web Accessibility Directive. Not required in the US, and
+ * still worth publishing everywhere: it is dated evidence of a deliberate
+ * process, which is exactly what a demand letter is fishing for the absence of.
+ *
+ * ── FILL IN AND KEEP CURRENT. ──────────────────────────────────────────────
+ *  - `reviewed` must be a real date. An undated statement reads as abandoned.
+ *  - `knownGaps` must be honest. Naming a real gap is worth more than a clean
+ *    claim — it is the difference between a documented backlog and an
+ *    undiscovered failure. If the list is genuinely empty, say so explicitly.
+ *  - Never write "fully accessible" or "fully compliant". Conformance is
+ *    per-page, per-state, at a point in time, and one content edit can break it.
+ *  - `enforcement` is required in EU/UK statements. Delete the block elsewhere.
+ */
+import Base from '../layouts/Base.astro';
+import { business } from '../data/business';
+
+const TARGET = 'WCAG 2.2 Level AA';
+const prepared = '2 August 2026';
+const reviewed = '2 August 2026';
+const responseDays = 5;
+
+/** Be specific. "Some images" is not a gap, it is a shrug. */
+const knownGaps: string[] = [
+  'Third-party embeds (map, booking widget) are outside our control and may not meet the target.',
+];
+
+/** Delete this block outside the EU and UK. */
+/*
+ * `as` rather than a plain annotation: TypeScript narrows a `const` to its
+ * initialiser, so `const x: T | null = null` is exactly `null` forever and the
+ * `enforcement &&` block below becomes unreachable `never` — the type error
+ * arrives at the fill-in, not at the empty default.
+ */
+type Enforcement = { body: string; url: string } | null;
+const enforcement = null as Enforcement;
+---
+
+<Base
+  title={`Accessibility - ${business.name}`}
+  description={`Our accessibility statement: the standard we build to, how we test, what we know is not yet right, and how to tell us about a problem.`}
+  canonical="/accessibility/"
+>
+  <section class="section under-header">
+    <div class="container container--text prose">
+      <h1>Accessibility</h1>
+
+      <p class="statement__lede">
+        {business.name} wants everyone to be able to use this website, whatever technology they
+        browse with. This page says what we aim for, how we check it, and what to do if
+        something does not work for you.
+      </p>
+
+      <h2>The standard we build to</h2>
+      <p>
+        We build and test this site against <strong>{TARGET}</strong>, the international
+        standard for web accessibility. We aim to meet it throughout, but we do not claim the
+        site is perfect — conformance is measured page by page, and content changes over time.
+      </p>
+
+      <h2>How we test</h2>
+      <ul>
+        <li>Automated checks against every page, run as part of each release</li>
+        <li>
+          A keyboard pass by hand on one page of each type — every control reachable, focus
+          visible, nothing trapped
+        </li>
+        <li>Text scaled to 200% and 400%, and a 320&nbsp;pixel-wide screen</li>
+        <li>A screen reader pass using VoiceOver and NVDA</li>
+        <li>Colour contrast checked at the design-token level, so it holds across the site</li>
+      </ul>
+
+      <h2>What we know is not yet right</h2>
+      {
+        knownGaps.length > 0 ? (
+          <ul>{knownGaps.map((gap) => <li>{gap}</li>)}</ul>
+        ) : (
+          <p>
+            We are not currently aware of any part of this site that fails the standard above.
+            That is not the same as there being none — if you find something, please tell us.
+          </p>
+        )
+      }
+
+      <h2>Tell us about a problem</h2>
+      <p>
+        If you cannot use part of this site, or you need something in a different format, please
+        contact us and we will put it right.
+      </p>
+      <ul>
+        <li>Email: <a href={business.email.href}>{business.email.display}</a></li>
+        <li>Phone: <a href={business.phone.href}>{business.phone.display}</a></li>
+      </ul>
+      <p>
+        We aim to reply within <strong>{responseDays} working days</strong>. If the fix will take
+        longer than that, we will tell you when to expect it.
+      </p>
+
+      {
+        enforcement && (
+          <>
+            <h2>If you are not happy with our response</h2>
+            <p>
+              You can raise it with <a href={enforcement.url}>{enforcement.body}</a>.
+            </p>
+          </>
+        )
+      }
+
+      <h2>About this statement</h2>
+      <p>
+        Prepared on {prepared}. Last reviewed on {reviewed}.
+      </p>
+    </div>
+  </section>
+</Base>
+
+<style>
+  .statement__lede {
+    font-size: var(--step-1);
+    color: var(--text-muted);
+    max-inline-size: var(--measure);
+  }
+</style>

package/template/src/pages/api/contact.ts

@@ -0,0 +1,191 @@
+import type { APIRoute } from 'astro';
+import { validateLead, leadKey, type LeadRecord } from '../../lib/lead';
+import { notifyTeam } from '../../lib/brevo';
+import { site } from '../../data/site';
+import { kv, secret } from '../../lib/runtime';
+import { business } from '../../data/business';
+
+/**
+ * Where the no-JavaScript path lands. One place, because these are routes and
+ * a route that only exists in a redirect string is a route nobody notices has
+ * gone — the first version of this file pointed at /contact-us/ and /thank-you/
+ * from a different project, and both were 404s in a fresh build.
+ */
+const FORM_PAGE = '/contact/';
+const FORM_ANCHOR = '#quote';
+const SUCCESS = `${FORM_PAGE}?sent=1${FORM_ANCHOR}`;
+
+// This is the one route that needs a runtime. Everything else is static.
+export const prerender = false;
+
+const json = (body: unknown, status: number) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+  });
+
+/**
+ * A native form POST — no JavaScript — must not land on a page of raw JSON.
+ * The enhanced path sends `accept: application/json`; anything else is a
+ * browser submitting the form directly and gets a redirect it can follow.
+ */
+const wantsHtml = (request: Request) => {
+  const accept = request.headers.get('accept') ?? '';
+  return accept.includes('text/html') && !accept.includes('application/json');
+};
+
+const seeOther = (location: string) =>
+  new Response(null, { status: 303, headers: { location, 'cache-control': 'no-store' } });
+
+/**
+ * Refuse a POST that came from someone else's page.
+ *
+ * A browser always sends `Origin` on a cross-origin POST, so comparing it to
+ * our own host blocks the case this is for: another site putting a form in
+ * front of visitors that writes into this site's lead store.
+ *
+ * ⚠ WHAT IT DOES NOT STOP, so nobody reads more into it than it does: a script
+ * posting directly can simply omit the header, and `Origin` is absent on a
+ * same-origin form post from some privacy tooling — so absent has to be
+ * allowed, or the no-JavaScript path breaks for real people. Spam is the
+ * honeypot's job, not this.
+ *
+ * This check must run BEFORE validation. Ordering it after means a
+ * cross-origin post with a well-formed body is processed and stored, and the
+ * refusal only ever fires for submissions that were going to be rejected
+ * anyway — which looks identical in a status-code test.
+ */
+const sameOrigin = (request: Request) => {
+  const origin = request.headers.get('origin');
+  if (!origin) return true;
+  try {
+    return new URL(origin).host === new URL(request.url).host;
+  } catch {
+    return false;
+  }
+};
+
+export const POST: APIRoute = async ({ request, clientAddress }) => {
+  if (!sameOrigin(request)) {
+    return json({ ok: false, error: 'Cross-origin submissions are not accepted.' }, 403);
+  }
+
+  const contentType = request.headers.get('content-type') ?? '';
+  let input: Record<string, string>;
+
+  try {
+    if (contentType.includes('application/json')) {
+      input = (await request.json()) as Record<string, string>;
+    } else {
+      const form = await request.formData();
+      input = Object.fromEntries([...form.entries()].map(([k, v]) => [k, String(v)]));
+    }
+  } catch {
+    return json({ ok: false, error: 'Could not read the submission.' }, 400);
+  }
+
+  /*
+   * Honeypot. Accept silently — telling a bot it was caught just teaches it to
+   * try again without the field.
+   *
+   * ⚠ IT MUST NOT LAND ON `SUCCESS`. That URL is the conversion: the form page
+   * fires `generate_lead` on `?sent=1` for the no-JavaScript path. Sending
+   * caught spam there lets any bot that runs JavaScript inflate the only
+   * conversion the website owns — silently, in a shape that looks like the site
+   * performing unusually well, which nobody investigates.
+   *
+   * It goes to the plain form page instead: same 303, no error, nothing a bot
+   * can read as detection.
+   */
+  if (input.company) {
+    return wantsHtml(request) ? seeOther(FORM_PAGE) : json({ ok: true, id: 'accepted' }, 200);
+  }
+
+  const { ok, errors, values } = validateLead(input);
+  if (!ok) {
+    if (wantsHtml(request)) {
+      // Carry the failing field names back in the query string so the form can
+      // highlight them without JavaScript having to re-post anything.
+      return seeOther(`${FORM_PAGE}?invalid=${encodeURIComponent(Object.keys(errors).join(','))}${FORM_ANCHOR}`);
+    }
+    return json({ ok: false, errors }, 422);
+  }
+
+  const receivedAt = new Date().toISOString();
+  const id = crypto.randomUUID();
+  const lead: LeadRecord = {
+    id,
+    receivedAt,
+    env: site.leadTag,
+    ...values,
+    page: (input.page ?? '').slice(0, 300),
+    userAgent: (request.headers.get('user-agent') ?? '').slice(0, 300),
+    country: request.headers.get('cf-ipcountry') ?? '',
+    ip: clientAddress ?? '',
+  };
+
+  // ── Durable first, third party second ──────────────────────────────────
+  // The KV write happens BEFORE the Brevo call, so a provider outage costs a
+  // notification rather than a lead. If KV itself fails we still try to send,
+  // because an email in an inbox beats losing the enquiry entirely.
+  const store = kv(site.leadsBinding);
+
+  let stored = false;
+  if (store) {
+    try {
+      /*
+       * `expirationTtl` is the retention policy, enforced by the store. See
+       * site.leadRetentionDays — without it KV keeps a lead forever, which is
+       * not a defensible answer to "how long do you hold this data".
+       *
+       * Metadata carries NO personal data. It used to duplicate name and email
+       * here, which put them in `list()` — an operation that returns metadata
+       * without reading values, so the PII was available through the cheaper
+       * call. Nothing consumed it: the CSV export does a `get()` per key and
+       * reads the full record. Duplicated personal data with no reader is all
+       * cost and no benefit.
+       */
+      await store.put(leadKey(receivedAt, id), JSON.stringify(lead), {
+        expirationTtl: site.leadRetentionDays * 24 * 60 * 60,
+        metadata: { env: lead.env },
+      });
+      stored = true;
+    } catch (error) {
+      console.error('lead kv write failed', { id, error: String(error) });
+    }
+  } else {
+    console.error('lead kv binding missing', { binding: site.leadsBinding });
+  }
+
+  let emailed = false;
+  const apiKey = secret('BREVO_API_KEY');
+  if (apiKey) {
+    const result = await notifyTeam(apiKey, lead);
+    emailed = result.ok;
+    if (!result.ok) console.error('lead email failed', { id, error: result.error });
+  } else {
+    console.error('BREVO_API_KEY not set');
+  }
+
+  // Only a total loss is reported as failure to the visitor. If either channel
+  // captured it, the enquiry reached us and the visitor should not retry.
+  if (!stored && !emailed) {
+    if (wantsHtml(request)) return seeOther(`${FORM_PAGE}?failed=1${FORM_ANCHOR}`);
+    return json(
+      {
+        ok: false,
+        // From business.ts. A phone number written into an error string is the
+        // last place anyone looks, and the first place a previous client's
+        // number survives a copy-paste.
+        error: `We could not record your request. Please call us at ${business.phone.display}.`,
+      },
+      502,
+    );
+  }
+
+  if (wantsHtml(request)) return seeOther(SUCCESS);
+  return json({ ok: true, id, stored, emailed }, 200);
+};
+
+/** A GET here is almost always a person pasting the URL. Send them to the form. */
+export const GET: APIRoute = () => new Response(null, { status: 303, headers: { location: FORM_PAGE } });

package/template/src/pages/api/leads.csv.ts

@@ -0,0 +1,82 @@
+import type { APIRoute } from 'astro';
+import type { LeadRecord } from '../../lib/lead';
+import { site } from '../../data/site';
+import { kv, secret } from '../../lib/runtime';
+
+export const prerender = false;
+
+const COLUMNS: (keyof LeadRecord)[] = [
+  'receivedAt',
+  'name',
+  'email',
+  'phone',
+  'service',
+  'message',
+  'page',
+  'country',
+  'env',
+  'id',
+];
+
+/** RFC 4180: quote everything, double internal quotes. Excel-safe. */
+const cell = (value: unknown) => `"${String(value ?? '').replace(/"/g, '""')}"`;
+
+/**
+ * Every lead as a CSV, newest last (KV lists keys in lexicographic order and
+ * the key is `lead:<iso-timestamp>:<uuid>`).
+ *
+ *   curl -H "Authorization: Bearer $LEADS_EXPORT_TOKEN" \
+ *        https://example.com/api/leads.csv -o leads.csv
+ */
+export const GET: APIRoute = async ({ request }) => {
+  const expected = secret('LEADS_EXPORT_TOKEN');
+
+  if (!expected) {
+    return new Response('Export is not configured.\n', { status: 503 });
+  }
+
+  const url = new URL(request.url);
+  const presented =
+    request.headers.get('authorization')?.replace(/^Bearer\s+/i, '') ?? url.searchParams.get('token') ?? '';
+
+  // Constant-time-ish: compare full length, never short-circuit on first byte.
+  const ok =
+    presented.length === expected.length &&
+    presented.split('').reduce((acc, char, i) => acc | (char.charCodeAt(0) ^ expected.charCodeAt(i)), 0) === 0;
+
+  if (!ok) {
+    return new Response('Unauthorized\n', {
+      status: 401,
+      headers: { 'www-authenticate': 'Bearer realm="leads"' },
+    });
+  }
+
+  const store = kv(site.leadsBinding);
+  if (!store) return new Response('Lead storage is not bound.\n', { status: 503 });
+
+  const rows: string[] = [COLUMNS.join(',')];
+  let cursor: string | undefined;
+
+  do {
+    const page = await store.list({ prefix: 'lead:', cursor, limit: 1000 });
+    const values = await Promise.all(
+      page.keys.map((key) => store.get(key.name, 'json') as Promise<LeadRecord | null>),
+    );
+    for (const lead of values) {
+      if (!lead) continue;
+      rows.push(COLUMNS.map((column) => cell(lead[column])).join(','));
+    }
+    cursor = page.list_complete ? undefined : page.cursor;
+  } while (cursor);
+
+  const stamp = new Date().toISOString().slice(0, 10);
+  // BOM so Excel opens UTF-8 accents correctly instead of mojibake.
+  return new Response('' + rows.join('\r\n') + '\r\n', {
+    status: 200,
+    headers: {
+      'content-type': 'text/csv; charset=utf-8',
+      'content-disposition': `attachment; filename="leads-${stamp}.csv"`,
+      'cache-control': 'no-store',
+    },
+  });
+};

package/template/src/pages/contact.astro

@@ -0,0 +1,112 @@
+---
+import Base from '../layouts/Base.astro';
+import PageHero from '../components/PageHero.astro';
+import ContactForm from '../components/ContactForm.astro';
+import { business, addressOneLine } from '../data/business';
+
+/**
+ * Rendered per request, not prerendered — the API redirects back here with
+ * ?invalid=… when a no-JavaScript form POST fails validation, and a static
+ * page has no query string to read.
+ *
+ * Structure only. The layout of this page is a project decision.
+ */
+export const prerender = false;
+
+const invalidFields = (Astro.url.searchParams.get('invalid') ?? '').split(',').filter(Boolean);
+const submitFailed = Astro.url.searchParams.has('failed');
+/** The no-JavaScript success landing. Keep in step with SUCCESS in
+ *  src/pages/api/contact.ts — without this the native POST 303s to a page that
+ *  looks exactly like the one the visitor just submitted. */
+const submitted = Astro.url.searchParams.has('sent');
+---
+
+<Base
+  title={`Contact - ${business.name}`}
+  description={`Get in touch with ${business.name}. Call ${business.phone.display} or send us a message.`}
+  canonical="/contact/"
+  breadcrumbs={[{ name: 'Home', href: '/' }, { name: 'Contact', href: '/contact/' }]}
+>
+  <PageHero
+    title="Contact"
+    lede={`Send a message and we will come back to you. For anything urgent, call ${business.phone.display}.`}
+    breadcrumbs={[{ name: 'Home', href: '/' }, { name: 'Contact', href: '/contact/' }]}
+  />
+
+  <section class="section--tight">
+    <div class="container contact__grid">
+      <div>
+        <h2>Details</h2>
+        <ul role="list" class="contact__details">
+          <li><a href={business.phone.href}>{business.phone.display}</a></li>
+          <li><a href={business.email.href}>{business.email.display}</a></li>
+          <li>{addressOneLine}</li>
+          <li>{business.hours.display}</li>
+        </ul>
+      </div>
+
+      <div id="quote">
+        <h2>Send a message</h2>
+        {
+          submitted && (
+            <p role="status" class="contact__sent">
+              Thank you — your message is in. We will come back to you shortly.
+            </p>
+          )
+        }
+        {
+          invalidFields.length > 0 && (
+            <p role="alert" class="contact__alert">Please check the highlighted fields.</p>
+          )
+        }
+        {
+          submitFailed && (
+            <p role="alert" class="contact__alert">
+              Something went wrong — please call {business.phone.display} instead.
+            </p>
+          )
+        }
+        <div class="contact__form">
+          <ContactForm invalidFields={invalidFields} />
+        </div>
+      </div>
+    </div>
+  </section>
+</Base>
+
+<style>
+  .contact__grid {
+    display: grid;
+    gap: var(--space-2xl);
+  }
+
+  @media (min-width: 55rem) {
+    .contact__grid {
+      grid-template-columns: 1fr 1.4fr;
+    }
+  }
+
+  .contact__details {
+    display: grid;
+    gap: var(--space-2xs);
+    margin-block-start: var(--space-m);
+    padding: 0;
+    color: var(--text-muted);
+  }
+
+  .contact__alert {
+    margin-block-start: var(--space-s);
+    color: var(--danger);
+  }
+
+  .contact__sent {
+    margin-block-start: var(--space-s);
+    padding: var(--space-s) var(--space-m);
+    border: 1px solid var(--border-strong);
+    border-radius: var(--radius-s);
+  }
+
+  .contact__form {
+    margin-block-start: var(--space-l);
+  }
+</style>

package/template/src/pages/index.astro

@@ -0,0 +1,84 @@
+---
+import Base from '../layouts/Base.astro';
+import { business } from '../data/business';
+
+/**
+ * SCAFFOLD — replace this file entirely.
+ *
+ * There is no starter home page here on purpose. A home page that arrives with
+ * the template is a page shape nobody chose, and it is what makes two sites
+ * built from the same starter look like the same site.
+ *
+ * What decides this page:
+ *   - the ONE action that counts as a win  → what the opening block must do
+ *   - the archetype it implies             → section order and proof model,
+ *                                            references/archetypes.md
+ *   - the Round 3 visual direction         → what any of it looks like
+ *
+ * The archetype fixes the order; the direction fixes the appearance; they are
+ * independent, and neither is in this repository.
+ *
+ * Delete `unbuilt` below once this is a real page — `npm run tells` fails
+ * while a scaffold marker is still in a page that also has real content.
+ */
+const unbuilt = true;
+
+const checklist = [
+  'Round 1: name the one action that counts as a win',
+  'Pick the archetype it implies (references/archetypes.md) and write the section order down',
+  'Clear --unset in src/styles/tokens.css: brand ramp, then the two faces',
+  'Fill src/data/business.ts, then src/data/nav.ts with the real routes',
+  'Build the opening block and one content section in two directions, deploy both, let the client choose',
+  'Replace this file with the chosen direction',
+];
+---
+
+<Base
+  title={`${business.name}`}
+  description={business.description}
+  canonical="/"
+  schemaType="home"
+  noindex={unbuilt}
+>
+  <section class="section under-header">
+    <div class="container container--text">
+      <h1>This page has not been built yet.</h1>
+      <p class="scaffold__lede">
+        The template ships without a home page. Section order comes from the archetype, and
+        appearance from the design direction — both are project decisions, so neither is here.
+      </p>
+
+      <ol class="scaffold__list">
+        {checklist.map((step) => <li>{step}</li>)}
+      </ol>
+
+      <p class="scaffold__note">
+        This page is <code>noindex</code> while <code>unbuilt</code> is set, so a staging deploy
+        cannot leak it. See <code>docs/design.md</code> and <code>npm run tells</code>.
+      </p>
+    </div>
+  </section>
+</Base>
+
+<style>
+  .scaffold__lede {
+    margin-block-start: var(--space-m);
+    font-size: var(--step-1);
+    color: var(--text-muted);
+    max-inline-size: var(--measure);
+  }
+
+  .scaffold__list {
+    margin-block-start: var(--space-xl);
+    padding-inline-start: var(--space-m);
+    display: grid;
+    gap: var(--space-2xs);
+    max-inline-size: var(--measure);
+  }
+
+  .scaffold__note {
+    margin-block-start: var(--space-xl);
+    font-size: var(--step--1);
+    color: var(--text-muted);
+  }
+</style>

package/template/src/pages/robots.txt.ts

@@ -0,0 +1,38 @@
+import type { APIRoute } from 'astro';
+import { site } from '../data/site';
+
+/**
+ * Generated, not a static file — so staging is disallow-all without anyone
+ * having to remember to swap a file at go-live.
+ */
+export const GET: APIRoute = ({ site: siteUrl }) => {
+  const body = site.indexable
+    ? [
+        'User-agent: *',
+        'Allow: /',
+        'Disallow: /api/',
+        '',
+        `Sitemap: ${new URL('/sitemap-index.xml', siteUrl).href}`,
+        '',
+      ].join('\n')
+    : [
+        '# Staging — not for indexing.',
+        '#',
+        '# ⚠ Disallow is a CRAWLING instruction, not an indexing one. Blocking the',
+        '# crawler means it never fetches the page and never reads the `noindex`',
+        '# every page here carries — so a staging URL that gets linked anywhere can',
+        '# still be indexed as a bare URL competing with production.',
+        '#',
+        '# Put staging behind Cloudflare Access. That is the actual answer, it is free',
+        '# at this scale, and it makes this file irrelevant. If staging must stay',
+        '# public, delete the Disallow below so the noindex is actually read.',
+        '# See docs/traps.md.',
+        'User-agent: *',
+        'Disallow: /',
+        '',
+      ].join('\n');
+
+  return new Response(body, {
+    headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'public, max-age=3600' },
+  });
+};

package/template/src/pages/rss.xml.ts

@@ -0,0 +1,27 @@
+import rss from '@astrojs/rss';
+import type { APIRoute } from 'astro';
+import { getPosts } from '../lib/posts';
+import { business } from '../data/business';
+import { site } from '../data/site';
+
+export const GET: APIRoute = async (context) => {
+  // Staging must not publish a feed a reader could subscribe to.
+  if (!site.indexable) return new Response('Not found\n', { status: 404 });
+
+  const posts = await getPosts();
+
+  return rss({
+    title: `${business.name} — Insights`,
+    description: business.description,
+    site: context.site!,
+    trailingSlash: true,
+    items: posts.map((post) => ({
+      title: post.data.title,
+      description: post.data.description,
+      pubDate: post.data.publishedAt,
+      link: `/${post.id}/`,
+      categories: post.data.categories,
+    })),
+    customData: '<language>en-us</language>',
+  });
+};