Skip to main content

Public Surface Standards

The Bespoke Web System doctrine says the public-facing website is a surface of the Hub, fed live from the same Worker + D1 + R2 — not a standalone artifact. This page is the quality bar for that served public surface, regardless of vertical.

  • It is: the measurable standard every public surface clears.
  • It is not: a page-by-page layout spec. Layout, page set, and content are vertical tissue, authored per vertical and fed by the Hub.

The standard is universal across verticals. A bike shop's public surface and a future vertical's public surface clear the same bar; they differ in structure and content, not in quality floor.

The two tiers​

Every public surface is built to one of two tiers. The tier is chosen per customer or per vertical and recorded in the project brief.

  • Baseline — the default quality bar. Fast, accessible, structured, secure enough for an ordinary commercial surface.
  • Strict Commercial-Plus — Baseline plus hardened accessibility, privacy, security, and process requirements. Used where the customer or jurisdiction demands it (regulated data, higher legal exposure, enterprise expectations).

Strict is a superset of Baseline. Everything in Baseline applies to Strict; the Strict-only items below are marked [Strict].

Performance​

Fast by construction, not by later optimization.

  • Lighthouse: 95+ on Performance, Accessibility, Best Practices; 100 on SEO.
  • First Contentful Paint under ~1s; Largest Contentful Paint under ~1.5s on a representative mid-tier mobile device.
  • Page weight kept well under ~500KB per page on initial load. The shared-store, server-rendered model (no SSR framework, no Astro — see Progressive Enhancement) keeps the JS bundle small by default.
  • Hero image under 100KB; thumbnails under 40KB.
  • Inline critical CSS; defer the rest.
  • System font stack — no web-font network fetch on the critical path.
  • Images: WebP, sized to their display dimensions, lazy-loaded below the fold.
  • No render-blocking third-party scripts.

Performance is a CI gate, not a guideline: a public surface that fails the Lighthouse thresholds fails the build.

HTML structure & SEO​

  • Semantic HTML5 — real landmarks (header, nav, main, footer, section, article), not div soup.
  • One <h1> per page; correct, unbroken heading hierarchy beneath it.
  • Title and meta description present and unique per page, following a consistent per-vertical formula.
  • Canonical URL on every page.
  • Open Graph + Twitter card tags on every page.
  • JSON-LD structured data appropriate to the vertical (e.g. BicycleStore for the bike vertical, with address, geo, opening hours, areaServed, and an OfferCatalog of services). The schema type is vertical tissue; the requirement to carry correct, complete schema is universal.
  • Favicon referenced consistently across all pages.
  • Clean, human-readable URLs; the URL is a source of truth for state.

Accessibility​

  • Baseline: WCAG AA — AA contrast minimums, all interactive elements keyboard-reachable, focus visible, images carry meaningful alt text (or empty alt when decorative), form fields labelled, a skip-to-content link, correct landmark structure.
  • [Strict] Hardened accessibility: a published accessibility statement page, verified screen-reader pass on primary flows, no reliance on colour alone to convey state, motion-reduction respected (prefers-reduced-motion), and AA maintained on every interactive state (hover/focus/active/disabled).

Accessibility is part of the quality gate, not a post-launch fix.

Privacy & data​

  • Baseline: collect only what the surface needs; no third-party analytics or trackers; first-party analytics only, fire-and-forget via sendBeacon, with environment guards that skip localhost / preview domains; a privacy policy present and accurate; cookie use minimized and the most privacy-preserving default chosen.
  • [Strict] Privacy-law-aligned handling (e.g. PIPEDA/PIPA, and where relevant Québec Law 25): explicit, accurate privacy policy and cookie policy; lawful basis for any personal data captured; a documented data-processing position for sub-processors (Cloudflare, Stripe, any transcription/telephony vendor); a written breach-notification procedure; data minimization enforced in the schema, not just in the policy text.

No personal data flows into URL parameters. No sensitive data is logged in plain text. These hold at both tiers.

Security​

  • Baseline: HTTPS everywhere (Cloudflare-managed); input validated at the Worker boundary (Zod, per the stack standard); output encoded to prevent injection; secrets in Worker secrets, never in source or client; the audit chain writes for any state-changing public action exactly as it does for operator actions (the public surface and Hub share one Worker and one audited store).
  • [Strict] Hardened headers (CSP, HSTS, X-Content-Type-Options, Referrer-Policy, frame-ancestors), explicit rate-limiting on public write endpoints, and a documented threat model for the public flows that write to D1 (bookings, form submissions, online orders).

The single-tenant model (one Worker + D1 + R2 per customer) is itself a security property: one customer's public surface cannot reach another's data because they do not share a store.

Code quality​

  • TypeScript throughout; Zod validation at every route boundary.
  • Integer-cents money; never floats. ISO TEXT timestamps; 0/1 booleans (canonical schema conventions across every KVICK build).
  • Soft deletes; the audit chain is append-only and tamper-evident.
  • Labels sourced from public/index.html per ADR-0028 — no database label override layer.
  • [Strict] Documented test coverage on the public write paths; no any in TypeScript on the public surface; lint/format gates green in CI.

Process & deployment​

  • The public surface deploys as part of the customer's single Worker; it is not a separately deployed static site.
  • CI gates run before deploy: Lighthouse thresholds, schema validation, accessibility checks. Failing any gate fails the build.
  • [Strict] Human review sign-off recorded before deploy; a documented rollback path; a post-launch verification that the public write paths (forms, bookings, orders) complete end-to-end into D1 and the audit chain.
  • Document in the same pass. Per bible discipline, any change to the public surface updates the affected documentation as part of the change, not later.

What is deliberately not here​

To keep this lean and accurate, the following are intentionally absent, because they are vertical tissue (authored per vertical, fed by the Hub) or belong to the discontinued tradesperson product:

  • Specific page sets ("home + services + area pages + about + contact"). Vertical tissue.
  • Emergency-service banners, click-to-call-as-the-product, SMS-to-owner routing. Tradesperson-product specifics.
  • Discovery-call → transcript → AI-generation → site pipeline. Belonged to the static-site product; superseded by the Hub-fed model.
  • Any fixed per-month price. Pricing lives in the business model and the Hub. If a price must appear on a public surface, it is fed from the Hub's data, not hard-coded into a standard.

See also​