diff --git a/specification/00-overview.md b/specification/00-overview.md index f000841..85d8cb3 100644 --- a/specification/00-overview.md +++ b/specification/00-overview.md @@ -1,40 +1,55 @@ # Diana Website — Specification Overview (v1) +## Brand +**Home Enhancement and Renovation — HER** +- Short-form: **HER** (used in logo/header) +- Full name: "Home Enhancement and Renovation" (footers, About, legal) + ## Purpose Build a **mobile-first, SEO-friendly, static website** for Diana (handywoman) that primarily **converts visitors into qualified quote requests**. -This document is the navigation map for the specification set. - ## Goals 1. **Generate qualified leads** via a lightweight quote/contact form. -2. Communicate Diana’s differentiation: **trustworthy, easy to work with, female handyman/handywoman**, strong **project coordination/mediation** skills. -3. **SEO-first information architecture**: separate service pages with clear local relevance (San Francisco + 50-mile radius). +2. Communicate Diana's differentiation: **trustworthy, easy to work with, female handyman/handywoman**, strong **project coordination/mediation** skills. +3. **SEO-first information architecture**: separate/grouped service pages with clear local relevance (San Francisco + 50-mile radius). 4. **Fast, mobile-first UX** (Core Web Vitals friendly, readable, tap-target safe). ## Non-goals / Out of scope (v1) - Blog - Booking / calendar scheduling - Payments -- Deployment/infrastructure work beyond “static site served behind Caddy reverse proxy” +- Analytics / tracking (no cookie consent banner required) +- Deployment/infrastructure work beyond "static site served behind Caddy reverse proxy" ## Key constraints - Language: **English**. - Site type: **static website**. - Content updates expected to be infrequent (maintained by owner/you). - Form should be **lightweight** (no file uploads in v1). +- Form backend: **existing AWS service** (details TBD — see OQ-3 / ADR-002). ## Primary user flows 1. Visitor lands on Home page → scans credibility/services → taps **Request a Quote** → submits form. -2. Visitor lands on a Service page (SEO) → sees what’s included + service area + CTA → submits form. +2. Visitor lands on a Service page (SEO) → sees what's included + service area + CTA → submits form. 3. Visitor checks About / Testimonials for trust → CTA → submits form. -## Intended information architecture (high level) -- Home -- Services (hub) -- Service detail pages (one per service) -- About Diana -- Testimonials -- Contact / Request a Quote +## Intended information architecture +| Page | URL slug | Notes | +|------|----------|-------| +| Home | `/` | Hero, positioning, services overview, CTA | +| Services hub | `/services/` | Links to all service pages | +| Painting | `/services/painting/` | | +| Tile Setting | `/services/tile-setting/` | | +| Drywall & Sheetrocking | `/services/drywall/` | | +| Minor Plumbing | `/services/plumbing/` | | +| Minor Electrical | `/services/electrical/` | | +| Carpentry & Mounting | `/services/carpentry-and-mounting/` | | +| Flooring & Wood Refinishing | `/services/flooring/` | | +| Security & Safety Equipment | `/services/security-safety/` | | +| Boat Work | `/services/boat-work/` | | +| About Diana | `/about/` | Story, experience, credibility | +| Testimonials | `/testimonials/` | Customer quotes | +| Contact / Request a Quote | `/contact/` | Form + secondary contact (email, phone) | ## Specification documents ### Core specs (Phase 2) @@ -47,5 +62,3 @@ This document is the navigation map for the specification set. - `33-frontend-spec.md` — pages, components, UX, mobile-first design, conversion flow - `37-seo-content-spec.md` — page structure, metadata, schema.org, sitemap/robots, content requirements per page - `38-lead-capture-spec.md` — form fields, validation, spam protection, delivery/routing, confirmation UX - -(If a themed spec requires an architectural decision, it will be captured in `02-architecture-decisions.md`. If uncertainty remains, it will be captured in `99-open-questions.md`.) diff --git a/specification/01-requirements.md b/specification/01-requirements.md index 2cdbf13..155f66d 100644 --- a/specification/01-requirements.md +++ b/specification/01-requirements.md @@ -9,64 +9,84 @@ ### Lead capture (primary) - **FR-1**: The site must provide a **Request a Quote / Contact** form accessible within 1–2 taps from any page (persistent CTA). -- **FR-2**: The form must be **lightweight** (no file upload requirement in v1). -- **FR-3**: The form must collect enough info to support **qualified leads**. - - Minimum fields TBD in `38-lead-capture-spec.md`. -- **FR-4**: After submission, the user must see a **clear confirmation** (and guidance on next steps). +- **FR-2**: The form must be **lightweight** (no file upload in v1). +- **FR-3**: The form must collect the following fields to support **qualified leads**: + - **Name** (required) + - **Address** (service location, required) + - **Phone** (required) + - **Email** (required) + - **Description** (description of work requested, required) +- **FR-4**: After submission, the user must see a **clear confirmation** and guidance on next steps (e.g., Diana will follow up within N days). +- **FR-5**: Form submissions are delivered via an **existing AWS service** (endpoint TBD — see ADR-002, OQ-3). + +### Contact channels +- **FR-6**: The site must prominently expose: + - **Primary**: quote request form + - **Secondary**: email address + - **Secondary**: phone number +- **FR-7**: Both secondary channels must appear in the site **header/footer** and in the **post-submission confirmation** copy. ### Content & pages -- **FR-5**: The site must be **English-only**. -- **FR-6**: The site must clearly state the **service area: San Francisco + 50 mile radius**. -- **FR-7**: The site must include a **Services hub page**. -- **FR-8**: The site must include **one page per service** (SEO-driven). - - Services list (current): - - Security & Safety Equipment - - Tile Setting - - Drywall / Sheetrocking - - Painting - - Minor Plumbing - - Minor Electrical - - Carpentry - - Mounting - - Flooring touch-ups - - Boat work -- **FR-9**: The site must include an **About Diana** page highlighting credibility, experience, and project coordination. -- **FR-10**: The site must include a **Testimonials** page using existing testimonial content as a base (source: https://spotlighthis.com/testimonials/). -- **FR-11**: The site must include a **Contact** page (may be the same as Request a Quote). +- **FR-8**: The site must be **English-only**. +- **FR-9**: The site must clearly state the **service area: San Francisco + 50 mile radius**. +- **FR-10**: The site must include a **Services hub page** (`/services/`). +- **FR-11**: The site must include **service detail pages**, grouped for SEO as follows: + + | Page | URL slug | + |------|----------| + | Painting | `/services/painting/` | + | Tile Setting | `/services/tile-setting/` | + | Drywall & Sheetrocking | `/services/drywall/` | + | Minor Plumbing | `/services/plumbing/` | + | Minor Electrical | `/services/electrical/` | + | Carpentry & Mounting | `/services/carpentry-and-mounting/` | + | Flooring & Wood Refinishing | `/services/flooring/` | + | Security & Safety Equipment | `/services/security-safety/` | + | Boat Work | `/services/boat-work/` | + +- **FR-12**: The site must include an **About Diana** page highlighting credibility, experience, and project coordination background. +- **FR-13**: The site must include a **Testimonials** page using existing testimonial content (source: https://spotlighthis.com/testimonials/). +- **FR-14**: The site must include a **Contact / Request a Quote** page (`/contact/`). ### Differentiation / brand messaging -- **FR-12**: The site must explicitly lean into “**female handyman/handywoman**” positioning. -- **FR-13**: The site must highlight Diana as **trustworthy, easy to work with**, and skilled at **project coordination/mediation**. -- **FR-14**: The site must incorporate proof points (e.g., **years of experience**, project coordination background). +- **FR-15**: Brand name: **"Home Enhancement and Renovation — HER"** (short-form: **HER**). +- **FR-16**: The site must explicitly lean into "**female handyman/handywoman**" positioning. +- **FR-17**: The site must highlight Diana as **trustworthy, easy to work with**, and skilled at **project coordination/mediation** between homeowners and construction crews. +- **FR-18**: The site must incorporate key proof points: **years of experience** and **project coordination background** (aerospace team lead). ## Non-functional requirements ### Mobile-first UX - **NFR-1**: The site must be designed **mobile-first**, with readable typography and touch-friendly controls. -- **NFR-2**: The quote/contact CTA must be prominent and accessible on mobile. +- **NFR-2**: The quote/contact CTA must be prominent and easily accessible on mobile. ### SEO -- **NFR-3**: The site must be **indexable** (server-rendered/static HTML; no content hidden behind client-only rendering). -- **NFR-4**: Each service page must have unique, descriptive metadata (title/description) and content targeting that service. -- **NFR-5**: The site must have sitemap and robots configuration (details in `37-seo-content-spec.md`). +- **NFR-3**: The site must be **indexable** (static/server-rendered HTML; no content hidden behind client-only rendering). +- **NFR-4**: Each service page must have unique, descriptive metadata (title/description) targeting that service and location. +- **NFR-5**: The site must include a sitemap and robots.txt (details in `37-seo-content-spec.md`). ### Performance - **NFR-6**: Pages must load quickly on mobile networks; images must be optimized and appropriately sized. +### Privacy / tracking +- **NFR-7**: **No analytics, tracking scripts, or cookie consent banner** in v1. No privacy policy page required at launch. + ### Maintainability -- **NFR-7**: The solution should be low-maintenance and suitable for infrequent updates by you. +- **NFR-8**: The solution should be low-maintenance and suitable for infrequent updates by the owner. ## Constraints / scope boundaries - **C-1**: Site must be a **static website**. -- **C-2**: Deployment/infrastructure is **out of scope** for v1 beyond the assumption it will be served behind **Caddy reverse proxy**. +- **C-2**: Deployment/infrastructure is **out of scope** beyond the assumption it will be served behind **Caddy reverse proxy**. - **C-3**: No blog, booking/calendar, or payments in v1. +- **C-4**: No file uploads on the contact form in v1. ## Acceptance criteria (v1) -- **AC-1**: A visitor can reach a quote request form from any page in 1–2 taps. -- **AC-2**: Service pages exist for each service in FR-8, and each has a clear CTA. -- **AC-3**: The site clearly states service area and core positioning. +- **AC-1**: A visitor can reach the quote request form from any page in 1–2 taps. +- **AC-2**: Service pages exist for each group in FR-11, each with a clear CTA and unique content. +- **AC-3**: The site clearly states service area and core brand positioning (HER). - **AC-4**: The site is usable on mobile (no horizontal scroll, readable text, accessible tap targets). - **AC-5**: The site is SEO-ready: indexable pages, unique metadata per service page, sitemap/robots present. +- **AC-6**: Secondary contact channels (email, phone) are visible in header/footer and post-form confirmation. ## Traceability notes - Lead capture specs → `38-lead-capture-spec.md` diff --git a/specification/02-architecture-decisions.md b/specification/02-architecture-decisions.md index 8494438..14ed581 100644 --- a/specification/02-architecture-decisions.md +++ b/specification/02-architecture-decisions.md @@ -2,53 +2,74 @@ This file records stable architectural decisions and their rationale. Items here should remain valid even as implementation details evolve. -## ADR-001 — Static website (SSG or plain static HTML) as the delivery model +## ADR-001 — Static website as the delivery model - **Status**: Accepted - **Context**: Site is primarily informational/lead-capture, needs strong SEO, and is expected to change infrequently. -- **Decision**: Build as a **static website** (pre-rendered HTML) suitable for hosting behind a reverse proxy. +- **Decision**: Build as a **static website** (pre-rendered HTML) suitable for hosting behind a Caddy reverse proxy. - **Rationale**: - - SEO-friendly (indexable content) + - SEO-friendly (fully indexable content) - Fast and reliable on mobile - Low maintenance - **Alternatives considered**: - WordPress/CMS: easier editing but higher maintenance/security surface - SPA-only: SEO/performance risks and complexity - **Consequences**: - - Contact form delivery must be handled via a static-compatible approach (see ADR-002, TBD) + - Contact form delivery must be handled via a static-compatible approach (see ADR-002) -## ADR-002 — Quote request form submission mechanism -- **Status**: Proposed (blocked) -- **Context**: Form is required (FR-1..FR-4), but the mechanism (email service, server endpoint, third-party form backend) is not yet selected. -- **Decision**: TBD. -- **Options to evaluate** (non-exhaustive): - 1. Static form backend service (e.g., Netlify Forms / Formspree / Basin) - 2. Self-hosted lightweight endpoint behind Caddy (out-of-scope per C-2 unless already existing) - 3. Email link fallback (mailto) — likely insufficient for qualified leads -- **Drivers**: - - Qualified lead capture - - Spam protection - - GDPR/cookie implications - - Operational simplicity -- **Next step**: Resolve in `99-open-questions.md` and specify in `38-lead-capture-spec.md`. +## ADR-002 — Form backend: existing AWS service +- **Status**: Partially accepted (details pending) +- **Context**: The site must collect quote request form submissions (FR-3, FR-5). The site is static, so a backend service is required. +- **Decision**: Use an **existing AWS service** owned/operated by the stakeholder. +- **Rationale**: + - Reuses existing infrastructure + - Avoids new third-party service dependencies +- **Remaining open items** (blocking `38-lead-capture-spec.md`): + - Which AWS service is used (e.g. SES, API Gateway + Lambda)? + - What is the form submission endpoint URL? + - What spam protection is in place or expected (e.g. honeypot, reCAPTCHA, AWS WAF)? +- **See also**: OQ-3 ## ADR-003 — Mobile-first, performance-first design - **Status**: Accepted - **Context**: Most traffic is expected on mobile; SEO and conversion depend on usability and speed. -- **Decision**: Adopt a **mobile-first** layout and performance budget mindset. +- **Decision**: Adopt a **mobile-first** layout and performance budget mindset throughout. - **Rationale**: - - Improves conversion + - Improves conversion on mobile - Supports SEO (Core Web Vitals) - **Consequences**: - - Images must be optimized; avoid heavy JS - - Ensure accessible typography and tap targets + - Images must be optimized (sized, compressed, lazy-loaded); avoid heavy JavaScript + - Ensure accessible typography and touch-friendly tap targets -## ADR-004 — SEO information architecture: one page per service +## ADR-004 — Service pages: grouped by search intent for SEO - **Status**: Accepted -- **Context**: SEO is important and services are distinct. -- **Decision**: Create **separate service pages** for each service category listed in FR-8. +- **Context**: Individual pages per service produce better SEO but only if pages have sufficient unique content. Some services (carpentry/mounting, flooring/wood refinishing) share search intent and image assets. +- **Decision**: Organize service pages into **9 grouped pages** (down from 10+ individual items), grouped by search intent: + + | Page | Slug | Services grouped | + |------|------|-----------------| + | Painting | `/services/painting/` | Interior & exterior painting, trim | + | Tile Setting | `/services/tile-setting/` | All tile types, all rooms | + | Drywall & Sheetrocking | `/services/drywall/` | Drywall, sheetrocking, patching | + | Minor Plumbing | `/services/plumbing/` | Sinks, toilets, showers | + | Minor Electrical | `/services/electrical/` | Lights, fans, fixtures | + | Carpentry & Mounting | `/services/carpentry-and-mounting/` | Carpentry, mounting, assembly | + | Flooring & Wood Refinishing | `/services/flooring/` | Flooring, decks, stairs, refinishing | + | Security & Safety Equipment | `/services/security-safety/` | Grab bars, locks, cameras | + | Boat Work | `/services/boat-work/` | Marine woodwork, paint, hardware | + - **Rationale**: - - Supports service-intent keywords - - Improves internal linking and topical relevance + - Grouped pages have richer content and avoid thin-page SEO penalties + - Carpentry + Mounting share the installation/assembly search intent + - Flooring touch-ups + Wood Refinishing share the surface/finishing search intent and asset library - **Consequences**: - - Requires unique content per page (avoid duplicate/thin pages) - - Requires a services hub and internal navigation + - Each grouped page must contain enough unique content to serve its target keywords + - Internal linking from the Services hub must cover all sub-topics + +## ADR-005 — No analytics or tracking in v1 +- **Status**: Accepted +- **Context**: Stakeholder decided against tracking for simplicity. +- **Decision**: **No analytics scripts, no ad pixels, no cookie consent banner** in v1. +- **Rationale**: Reduces complexity, avoids consent/privacy obligations at launch. +- **Consequences**: + - No data-driven iteration on traffic or conversions at launch + - Adding analytics later will require revisiting privacy policy needs diff --git a/specification/99-open-questions.md b/specification/99-open-questions.md index ab2ba60..f81ab99 100644 --- a/specification/99-open-questions.md +++ b/specification/99-open-questions.md @@ -3,40 +3,49 @@ This log tracks uncertainties and deferred decisions. Each item should be resolved before implementation in Phase 4. ## OQ-1 — Preferred contact method(s) beyond the contact form -- **Status**: Open -- **Context**: Contact form is a given, but preferred secondary channel(s) are not finalized. -- **Why it matters**: Influences CTA design, header/footer, and “next steps” after form submission. -- **Candidates**: phone, SMS/text, email. -- **Proposed resolution**: Decide primary + secondary channel(s) and when to encourage each. +- **Status**: Resolved +- **Resolution**: Secondary contact channels are **email** and **phone**. Both should appear in the site header/footer and in the confirmation copy after form submission. ## OQ-2 — GDPR/cookie consent and tracking requirements -- **Status**: Open -- **Context**: Need to know whether we will run analytics/ads pixels and whether consent banners are required. -- **Why it matters**: Affects scripts, cookie banner, privacy policy content, and SEO. -- **Proposed resolution**: - - Decide whether to use analytics (and which) - - If analytics, decide consent model and privacy policy needs +- **Status**: Resolved +- **Resolution**: **No analytics, no tracking scripts, no cookie consent banner** for v1. No privacy policy required at launch. Revisit if analytics are added later. ## OQ-3 — Form backend + spam protection approach (ADR-002) -- **Status**: Open -- **Context**: Static site requires an external or existing backend mechanism. -- **Why it matters**: Reliability, spam filtering, and operational workflow. -- **Proposed resolution**: Choose a form delivery method and specify validation + anti-spam. +- **Status**: Partially resolved +- **Resolution**: Form submissions will be handled via an **existing AWS service**. Specific service (e.g. SES, API Gateway + Lambda, or similar) and the endpoint URL/configuration need to be confirmed before `38-lead-capture-spec.md` implementation. See ADR-002. +- **Remaining**: Confirm which AWS service/endpoint and provide connection details. -## OQ-4 — Minimum quote form fields for “qualified leads” -- **Status**: Open -- **Context**: Goal is “more qualified leads”, but minimum qualifying information is not fully specified. -- **Why it matters**: Balances friction vs. lead quality. -- **Proposed resolution**: Define required vs optional fields in `38-lead-capture-spec.md`. +## OQ-4 — Minimum quote form fields for "qualified leads" +- **Status**: Resolved +- **Resolution**: Required form fields are: + - **Name** (full name) + - **Address** (service location) + - **Phone** + - **Email** + - **Description** (description of work requested) +- All fields are required. Detailed validation rules to be defined in `38-lead-capture-spec.md`. -## OQ-5 — Service taxonomy: separate pages vs grouping for carpentry/mounting/flooring -- **Status**: Open -- **Context**: Requirement says separate page per service, but some services overlap. -- **Why it matters**: SEO clarity and content uniqueness. -- **Proposed resolution**: Confirm final service list and page slugs. +## OQ-5 — Service taxonomy: separate pages vs grouping +- **Status**: Resolved +- **Resolution**: Services are grouped for best SEO relevance and content depth. Proposed groupings: + + | Page | Slug | Services included | + |------|------|-------------------| + | Painting | `/services/painting/` | Interior & exterior painting, trim work | + | Tile Setting | `/services/tile-setting/` | All tile types, kitchens, bathrooms, entryways, patios | + | Drywall & Sheetrocking | `/services/drywall/` | Removing, replacing, patching, sanding | + | Minor Plumbing | `/services/plumbing/` | Sinks, toilets, showers | + | Minor Electrical | `/services/electrical/` | Lights, fans, fixtures | + | Carpentry & Mounting | `/services/carpentry-and-mounting/` | Carpentry, furniture assembly, TV/shelf mounting | + | Flooring & Wood Refinishing | `/services/flooring/` | Flooring touch-ups, wood refinishing (floors, decks, stairs, cabinets) | + | Security & Safety Equipment | `/services/security-safety/` | Grab bars, lock bars, window mesh, security cameras | + | Boat Work | `/services/boat-work/` | Woodwork, spray paint, marine hardware | + +- **Rationale**: Carpentry and Mounting share the same installation/assembly search intent. Flooring touch-ups and Wood Refinishing share the same surface/finish search intent and existing image assets. ## OQ-6 — Brand naming and domain -- **Status**: Open -- **Context**: Current site uses “Spotlight Home Improvement Services”; new site may keep or adjust branding. -- **Why it matters**: Title tags, logo, copy, and SEO continuity. -- **Proposed resolution**: Confirm public-facing brand name for v1. +- **Status**: Resolved +- **Resolution**: New public-facing brand name is **"Home Enhancement and Renovation — HER"**. + - Use full name in footers, About page, and legal references. + - Use **"HER"** as the short-form logo/header identity. + - Update all spec documents and eventually title tags/metadata to reflect the new brand.