Small-Business Website Template - Chronological Implementation TODO Plan (Template repo: ai-eng-template-small-business-website) ============================================================================== INTENT ============================================================================== A polished, mobile-first, content-driven marketing website template for small businesses, personal brands, studios, and local service providers. The template ships with a structured page taxonomy, MDX-powered content, a contact pipeline wired to Firebase, an SEO-first metadata strategy, and a one-edit rebrand surface. It is the studio's default starting point for any non-app website engagement and must integrate cleanly with the public `/showcase` module. OUT OF SCOPE: dynamic SaaS surfaces, login walls, complex CMS dashboards, multi-tenant content, e-commerce checkout (use the e-commerce template), or booking surfaces (use the booking template). High-level summary - Goal: a forkable Next.js + MDX + Firebase marketing site that a small business can launch in 1-3 weeks. - Platform target: Next.js App Router with static rendering by default, Firebase Hosting + Cloud Functions for the contact pipeline, MDX for content, Tailwind + design tokens for styling. - Backend mechanics: content is in-repo MDX (or optionally a lightweight Firestore-backed editor); the only server-side mutation is the contact form, handled by a Cloud Function with App Check enforcement. - Performance/security target: Core Web Vitals green on mobile 4G, LCP < 1.2s, CLS < 0.05, a11y >= 95. - Rough delivery estimate: 1-3 weeks per customer customization. Phase 0 - Scope freeze, product definitions, and delivery guardrails (Effort: Small) Dependencies: customer discovery workshop output. [ ] Freeze template scope: - [ ] confirm the template ships with: landing, services, about, team, testimonials, case studies, FAQ, contact, imprint, privacy, cookies, and a blog/news section. - [ ] confirm explicit OUT-OF-SCOPE: shopping cart, login walls, member-only pages, and any flow that needs a backend dashboard. [ ] Define delivery guardrails: - [ ] all content lives in `content/` (MDX) - one file per page or article. - [ ] one brand-config file (`src/content/brand.ts`) controls colors, fonts, and copy that varies per customer. Potential gotchas: - [ ] customers will ask for "just a small admin area" mid-build; redirect that conversation to a different engagement and template. Phase 1 - Repository skeleton, tooling, and CI (Effort: Small) Dependencies: scope freeze. [ ] Repository: - [ ] create `ai-eng-template-small-business-website` on GitHub. - [ ] root `README.md` describes how to rebrand in under one hour. [ ] Tooling: - [ ] Node 20 LTS, pnpm 9, Next.js 15, TypeScript, MDX, Tailwind, Vitest, Playwright, Firebase CLI. - [ ] `next.config.ts` with `output: 'export'` toggleable for fully static deployments. [ ] CI: - [ ] lint, typecheck, unit tests, Playwright smoke on every PR. - [ ] preview deploy via Firebase Hosting preview channels. Potential gotchas: - [ ] `output: 'export'` disables every dynamic feature including server actions; check that the contact form has a static-friendly fallback (`mailto:` link plus optional Cloud Function). Phase 2 - Design system and token foundation (Effort: Small) Dependencies: Phase 1. [ ] Tokens and primitives: - [ ] color, type scale, spacing, radius, shadow tokens in a single CSS file. - [ ] primitives: Button, Link, Card, Section, Grid, Stack, Hero, Eyebrow. - [ ] one component per common marketing section (FeatureGrid, TestimonialRow, PricingTable, FAQAccordion, CTA, NewsList). Potential gotchas: - [ ] avoid spreading brand colors across many files; one customer rebrand should be a single-file edit. Phase 3 - Content model and MDX pipeline (Effort: Medium) Dependencies: Phase 2. [ ] Content model: - [ ] `content/pages/*.mdx` - one MDX file per public page; frontmatter declares `title`, `slug`, `description`, `published`, `ogImage`. - [ ] `content/articles/*.mdx` - blog posts with the same shape plus `publishedAt`, `tags`, `author`. - [ ] `content/case-studies/*.mdx`. [ ] MDX rendering: - [ ] `next-mdx-remote-client` or built-in MDX support; restrict MDX components to a curated list of design-system primitives only (no arbitrary HTML/JS). - [ ] reading-time and last-updated metadata computed at build time. Potential gotchas: - [ ] customers will paste random HTML into MDX; whitelist allowed components and surface a clear MDX lint error for anything else. Phase 4 - Page surface and routing (Effort: Medium) Dependencies: Phases 2-3. [ ] Routes: - [ ] `/`, `/services`, `/services/[slug]`, `/about`, `/team`, `/case-studies`, `/case-studies/[slug]`, `/blog`, `/blog/[slug]`, `/contact`, `/faq`, `/imprint`, `/privacy`, `/cookies`. [ ] Static generation: - [ ] every dynamic route uses `generateStaticParams` so the entire site is statically rendered. - [ ] OpenGraph images generated at build time using the Next.js Image API. [ ] Navigation: - [ ] header with primary nav and a mobile drawer. - [ ] footer with secondary nav, social links, and legal pages. Potential gotchas: - [ ] hard-coded nav lists drift from real pages; derive the primary nav from a single `siteNav.ts` so a missing page is impossible. Phase 5 - Contact pipeline (Effort: Medium) Dependencies: Phase 4. [ ] Frontend: - [ ] `/contact` form with name, email, message, optional company, and a honeypot field; client-side validation with zod. [ ] Backend: - [ ] `submitContactInquiry` Cloud Function callable + HTTP endpoint (callable for the form, HTTP for a fallback `mailto:` integration). - [ ] App Check enforced. - [ ] persists to Firestore under `contactInquiries/{inquiryId}` with `submittedAt`, `email` (hashed for analytics), `ip` (hashed), and `userAgent`. - [ ] sends a transactional email through a configurable provider (SendGrid or Resend), behind a feature flag. - [ ] rate-limits per IP and per email; honeypot field auto-rejects. Potential gotchas: - [ ] never store raw IP addresses; hash with a per-environment salt and document the salt rotation policy. Phase 6 - SEO, metadata, and structured data (Effort: Medium) Dependencies: Phase 4. [ ] Metadata: - [ ] App Router metadata API per route; canonical URL on every page. - [ ] OpenGraph and Twitter card images per page. [ ] Structured data: - [ ] JSON-LD `Organization`, `WebSite`, `BreadcrumbList`, `Article`, `FAQPage`, `LocalBusiness` (if a physical address is configured). [ ] sitemap and robots: - [ ] `sitemap.ts` covers every static and dynamic route. - [ ] `robots.ts` blocks `/admin`, `/api`, and any preview channel host. Potential gotchas: - [ ] canonical URLs must point at the production origin, not a preview channel; drive canonical from a `SITE_URL` env var and assert it in CI. Phase 7 - Internationalization (Effort: Medium, optional) Dependencies: Phase 4. [ ] If the customer requests multiple languages: - [ ] enable Next.js i18n routing with locale prefixes. - [ ] each MDX content file has per-locale copies under `content/pages/{locale}/...`. - [ ] language switcher in header; locale persisted in a cookie. Potential gotchas: - [ ] one missing translation breaks the whole locale; CI must fail on missing content keys. Phase 8 - Performance and accessibility (Effort: Medium) Dependencies: Phases 4-6. [ ] Performance: - [ ] LCP < 1.2s, CLS < 0.05, INP < 200ms on mobile 4G. - [ ] all images go through `next/image`; no raw `` tags. - [ ] fonts self-hosted with `font-display: swap`. [ ] Accessibility: - [ ] every interactive element keyboard-reachable. - [ ] color contrast >= 4.5:1 for body text. - [ ] Lighthouse a11y >= 95 in CI. Potential gotchas: - [ ] hero videos kill LCP; use a poster image and load the video lazily. Phase 9 - Analytics and cookie consent (Effort: Medium) Dependencies: Phase 4. [ ] Cookie consent banner with reject-by-default behavior. [ ] Analytics provider plug: - [ ] default: Firebase Analytics (only after consent). - [ ] alternative: Plausible / Fathom (cookieless, defaults on). [ ] Privacy and cookie policy MDX pages auto-list the cookies the site actually sets, derived from a single `cookies.ts` registry. Potential gotchas: - [ ] German/EU customers require strict reject-by-default; do not preload any analytics script until consent is granted. Phase 10 - Testing strategy (Effort: Small) Dependencies: Phases 1-9. [ ] Vitest unit tests on every utility and MDX component. [ ] Playwright smoke per release: load home, navigate to contact, submit form against emulators, confirm Firestore document, assert success state. Potential gotchas: - [ ] static export builds will skip server actions; assert this in CI when `output: 'export'` is enabled. Phase 11 - Customization handbook (Effort: Small per customer) Dependencies: Phases 0-10. [ ] `docs/customization.md` records, per customer: - [ ] brand identity (name, logo, primary/secondary colors, typography). - [ ] which pages are kept, which are removed, which are renamed. - [ ] custom content blocks beyond the default set. - [ ] language list and translation status. - [ ] domain, DNS, and hosting plan (Firebase Hosting vs Vercel vs static export to another host). - [ ] contact pipeline destination (email forward only, email + Firestore, email + CRM webhook). - [ ] analytics provider and cookie strategy. Potential gotchas: - [ ] over-customization defeats the template; track every deviation in `docs/deviations.md`. Phase 12 - Public showcase integration (Effort: Small) Dependencies: this plan, ecosystem Phase 26. [ ] Showcase metadata: - [ ] register this template in `apps/web/src/lib/showcase.ts` with id `small-business-website`, hero copy, feature list, "what you get" list, and a CTA into the estimator. [ ] Live preview: - [ ] a public, unbranded staging instance of the template is deployed and embedded as a sandboxed iframe on `/showcase/small-business-website`. - [ ] iframe sandbox: `allow-scripts allow-same-origin allow-forms`. - [ ] the preview shows a permanent "Template preview" banner. [ ] Source visibility: - [ ] the template repository's public README is surfaced on the detail page. - [ ] no real customer data ever appears in the showcase preview. Potential gotchas: - [ ] the showcase preview is the studio's most-visited template; budget a monthly rotation that updates copy, images, and metrics so the showcase never feels stale.