tom/diana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
329afc049aaae26abb4f3b5f94dd5e781eda118a
diana/specification/33-frontend-spec.md

69 KiB
Raw Blame History

33 — Frontend Specification

HER — Home Enhancement and Renovation

Version: 1.0
Phase: 3 — Themed Specification
Status: Implementation-ready
Depends on: 01-requirements.md, 02-architecture-decisions.md
Referenced by: 37-seo-content-spec.md, 38-lead-capture-spec.md

Table of Contents

  1. Purpose & Scope
  2. Design Tokens
  3. Responsive Breakpoints
  4. Navigation
  5. Page Specifications
  6. Component Inventory
  7. Animation & Motion
  8. Image Treatment
  9. Accessibility
  10. Requirements Traceability

1. Purpose & Scope

This document specifies the complete frontend design and layout for the HER static website. It is the authoritative reference for page structure, visual language, component behavior, and copy direction. It does not contain implementation code; it constrains and guides the implementation phase.

Site purpose: Convert visitors into qualified quote requests through a credible, mobile-first, trustworthy presentation of Diana's handywoman services in the San Francisco Bay Area.

Primary user flows (from 00-overview.md):

  1. Home → scans hero + services → taps "Request a Quote" → submits form.
  2. Service page (organic search) → reads what's included → taps CTA → submits form.
  3. About/Testimonials → validates trust → taps CTA → submits form.

Technology constraints: Static HTML/CSS/JS output. No framework assumed. No CMS. Served behind Caddy. (ADR-001)

2. Design Tokens

All tokens are defined as CSS custom properties on :root. Token names are the canonical references throughout this spec. No hardcoded values appear in components.

2.1 Color Tokens

Token Value Role
--col-graphite #252B30 Headers, nav background, footer background, primary dark surface
--col-linen #F4F1EB Main page background, default section background
--col-copper #B5622A Primary CTA accent, HER wordmark, interactive highlights
--col-copper-hover #9A4E20 Button/link hover state; darker variant of copper
--col-slate #5C7080 Secondary text, metadata, tags, bylines
--col-mist #E8ECF0 Alternating section backgrounds, card surfaces, service card fill
--col-chalk #EDEDEB Borders, dividers, horizontal rules
--col-ink #1A1A1A Body text, primary readable content

Contrast compliance (see §9 Accessibility):

  • --col-ink on --col-linen: ≥ 12:1 — passes WCAG AA and AAA.
  • --col-graphite on --col-linen: ≥ 9:1 — passes.
  • --col-copper on --col-linen: Must be verified; use only for large text or decorative elements if contrast falls below 4.5:1. Copper buttons must have sufficient contrast between white label and --col-copper background (verify ≥ 3:1 for large button text).
  • White text on --col-graphite: ≥ 10:1 — passes.
  • White text on --col-copper CTA band: verify at implementation (white on #B5622A is approximately 3.0:1 — meets WCAG AA for large text at ≥ 24px or bold ≥ 18.67px; button label must be at least --text-base bold).

2.2 Typography

Font loading: Both fonts loaded from Google Fonts via a single <link> preconnect + stylesheet in <head>. Subset to Latin. font-display: swap on both.

Font Source Weights / Axes Usage
Fraunces Google Fonts, variable opsz axis, weight 400; style: italic Display only — H1, H2, hero headline, section headlines, pull quotes, HER wordmark
DM Sans Google Fonts, variable Weights 400, 500 All other text: H3, H4, nav, buttons, body, labels, eyebrows, captions

Usage rules:

  • Fraunces is never used at sizes smaller than --text-xl (22px).
  • Fraunces is always set in italic (font-style: italic).
  • DM Sans 400 = body, secondary text, form fields.
  • DM Sans 500 = eyebrows, labels, buttons, utility text (uppercase, letter-spacing: 0.08em).
  • Do not mix Fraunces and DM Sans on the same line of a heading.
  • Line height for Fraunces headings: 1.1.
  • Line height for DM Sans body: 1.6.
  • Line height for DM Sans small/label: 1.4.

Eyebrow / Section tag style (used across all pages):

  • Font: DM Sans 500
  • Size: --text-xs
  • Transform: uppercase
  • Letter-spacing: 0.08em
  • Color: --col-copper
  • No decorative marks above/below (no rules, no dots) — text only

2.3 Type Scale

Token rem px Role
--text-xs 0.75rem 12px Captions, tags, card metadata
--text-sm 0.875rem 14px Secondary body, form hints, breadcrumbs
--text-base 1rem 16px Body copy, paragraph text
--text-lg 1.125rem 18px Lead paragraph (first paragraph of section or page hero)
--text-xl 1.375rem 22px H4, card headings
--text-2xl 1.75rem 28px H3, subsection headings, HER wordmark in nav
--text-3xl 2.25rem 36px H2, section headings (mobile)
--text-4xl 3rem 48px H1 (mobile), pull quotes
--text-5xl 4rem 64px H1 (desktop)

Responsive heading rules:

  • H1 uses --text-4xl at mobile, steps up to --text-5xl at lg breakpoint.
  • H2 uses --text-3xl at mobile, stays at --text-3xl (no change needed; already impactful).
  • H3 uses --text-2xl at all breakpoints.
  • H4 uses --text-xl at all breakpoints.

2.4 Spacing Scale (8-point grid)

Token rem px Common use
--space-1 0.5rem 8px Icon gaps, inline padding, tight label spacing
--space-2 1rem 16px Component internal padding, form field gap
--space-3 1.5rem 24px Card padding, between stacked elements
--space-4 2rem 32px Section sub-element spacing
--space-6 3rem 48px Section top/bottom padding (mobile)
--space-8 4rem 64px Section top/bottom padding (desktop), hero vertical rhythm
--space-12 6rem 96px Large section separators, hero vertical padding (desktop)
--space-16 8rem 128px Maximum-impact spacing (above fold hero only)

Grid gutters: --space-3 (24px) horizontal gutter between columns in all grid layouts.

2.5 Other Tokens

Token Value Role
--radius-sm 4px Input fields, tags, small elements
--radius-md 8px Cards, buttons
--radius-lg 16px Image containers, modals
--shadow-card 0 2px 8px rgba(37,43,48,0.08) Service cards, testimonial cards, hover lift
--shadow-card-hover 0 6px 20px rgba(37,43,48,0.13) Card hover state (elevated)
--max-width 1160px Maximum content width for all sections
--nav-height 64px (mobile) / 72px (desktop) Sticky nav height; used for scroll-offset calculations

3. Responsive Breakpoints

Breakpoint Token Min-width Description
Mobile (default) — 0px Base styles; single-column
Small sm 480px Wider mobile; minor layout adjustments
Medium md 768px Tablet; 2-column grids begin
Large lg 1024px Desktop; 3-column grids, full nav
Extra large xl 1160px Content width cap (--max-width)

All styles are written mobile-first: base styles target mobile, breakpoints progressively enhance for larger screens.

4. Navigation

The navigation bar appears at the top of every page and is sticky (fixed to the top on scroll). It has two states: default and scroll-compact.

4.1 Mobile Navigation (below lg)

Default state (top of page):

┌─────────────────────────────────────────┐
│  HER (italic copper)   [☎]   [☰]       │  height: 64px
└─────────────────────────────────────────┘
  • Left: "HER" wordmark — Fraunces italic, --text-2xl, --col-copper.
  • Center-right: Phone icon — inline SVG phone handset, --col-graphite; links to tel: URI (click-to-call). Minimum 44×44px touch target.
  • Right: Hamburger icon — 3 horizontal lines, --col-graphite. Minimum 44×44px touch target. Opens mobile menu overlay.
  • Background: --col-graphite.
  • Logo links to /.

Scroll-compact state (after scrolling down ≥ 80px):

  • Nav height smoothly transitions to 52px.
  • Wordmark + phone icon + hamburger remain visible; no layout change otherwise.
  • Transition: height 200ms ease, background-color 200ms ease (if background opacity is modified).
  • On scroll-up ≥ 20px: return to default height.

Mobile menu overlay (hamburger pressed):

  • Full-screen overlay, --col-graphite background, slides down from top (transform: translateY, 250ms ease-out).
  • Close button (×) top-right, same position as hamburger.
  • Links stacked vertically, centered, --text-2xl, DM Sans 400, --col-linen, with --space-6 between items:
    • About
    • Services
    • Testimonials
    • Contact
    • Request a Quote (copper button, full-width)
  • Phone number and email displayed at the bottom of the overlay, --col-slate, --text-sm.
  • Pressing any link or the close button dismisses the overlay.
  • Focus trap: keyboard focus must cycle within the overlay while it is open.
  • aria-expanded on the hamburger button reflects open/closed state.

4.2 Desktop Navigation (at lg and above)

┌────────────────────────────────────────────────────────────────────┐
│  HER (italic copper)    About  Services  Testimonials  Contact    [Request a Quote]  │  height: 72px
└────────────────────────────────────────────────────────────────────┘
  • Left: "HER" wordmark — Fraunces italic, --text-2xl, --col-copper. Links to /.
  • Center: Nav links — DM Sans 500, --text-sm, uppercase, letter-spacing 0.08em, --col-linen. Active page link: --col-copper. Hover: --col-copper. Gap between links: --space-4.
  • Right: "Request a Quote" button — primary button (copper), --text-sm, DM Sans 500, --radius-md.
  • Background: --col-graphite.
  • Content width constrained to --max-width, centered.
  • Nav links: About (/about/), Services (/services/), Testimonials (/testimonials/), Contact (/contact/).

Scroll-compact state (desktop):

  • Height transitions from 72px to 60px.
  • Logo scales slightly smaller (transform: scale(0.9)).
  • All links remain visible.

4.3 Nav Accessibility

  • <nav> element with aria-label="Main navigation".
  • Landmark nav is the first interactive region after <body>.
  • Skip link: <a href="#main-content" class="skip-link">Skip to main content</a> — positioned before the nav, visible only on focus. Style: copper background, white text, --radius-sm, top-left corner.
  • Current page link has aria-current="page".

5. Page Specifications

Each page shares the sticky NavBar and Footer components. The <main> element receives id="main-content" (skip link target). All sections are padded --space-6 top/bottom on mobile, --space-12 on desktop unless noted otherwise.

5.1 Home (/)

Page goal: Establish trust, convey service breadth and local relevance, drive quote requests.
FR coverage: FR-1, FR-6, FR-7, FR-9, FR-10, FR-15, FR-16, FR-17, FR-18 | NFR-1, NFR-2

Section 1 — Navigation

Sticky nav as specified in §4.

Section 2 — Hero

Background: --col-linen
Padding: --space-8 top / --space-6 bottom on mobile; --space-12 top / --space-12 bottom on desktop.

Mobile wireframe:

╔════════════════════════════════════╗
║  [HER]           [☎]       [☰]   ║  ← sticky nav (64px)
╠════════════════════════════════════╣
║                                    ║
║  SAN FRANCISCO HANDYWOMAN          ║  ← SectionEyebrow
║                                    ║
║  Fix it right.                     ║
║  The first time.                   ║  ← H1: Fraunces italic, --text-4xl
║                                    ║
║  Precise, reliable, and easy to    ║
║  work with — Diana brings          ║
║  aerospace-level project           ║  ← Lead: DM Sans 400, --text-lg
║  coordination to your home         ║     color: --col-ink
║  improvement project.              ║
║                                    ║
║  ┌──────────────────────────────┐  ║
║  │       Request a Quote        │  ║  ← Button (primary), full-width mobile
║  └──────────────────────────────┘  ║
║                                    ║
║  ☎  (415) XXX-XXXX                ║  ← tel: link, --col-slate, --text-base
║                                    ║
╠════════════════════════════════════╣
║  ┌──────────────────────────────┐  ║
║  │                              │  ║
║  │                              │  ║
║  │    diana_photo-min-1-        │  ║  ← 3:4 aspect ratio, object-fit: cover
║  │    scaled.webp               │  ║     loading="eager"
║  │                              │  ║     border-radius: --radius-lg
║  │  (Diana on sailboat,         │  ║     full bleed to section edges on mobile
║  │   Golden Gate Bridge)        │  ║
║  │                              │  ║
║  └──────────────────────────────┘  ║
║                                    ║
╚════════════════════════════════════╝

Desktop wireframe (lg and above, 2-column layout):

╔══════════════════════════════════════════════════════════════════╗
║ [HER italic]    About  Services  Testimonials  Contact  [Quote] ║  ← nav (72px)
╠══════════════════════════════════════════════════════════════════╣
║                                         ║                        ║
║  SAN FRANCISCO HANDYWOMAN               ║   ╔════════════════╗  ║
║                                         ║   ║                ║  ║
║  Fix it right.                          ║   ║                ║  ║
║  The first time.                        ║   ║  diana_photo   ║  ║
║                                         ║   ║  -min-1-       ║  ║
║  Precise, reliable, and easy to work    ║   ║  scaled.webp   ║  ║
║  with — Diana brings aerospace-level    ║   ║                ║  ║
║  project coordination to your home      ║   ║  1:1 aspect    ║  ║
║  improvement project.                   ║   ║  ratio, square ║  ║
║                                         ║   ║  --radius-lg   ║  ║
║  [ Request a Quote ]   ☎ (415) XXX-XXXX║   ║                ║  ║
║                                         ║   ╚════════════════╝  ║
║  ←────── ~58% content column ──────────→←── ~42% image col ──→ ║
╚══════════════════════════════════════════════════════════════════╝

Layout details:

  • Desktop: CSS grid, 2 columns, approximately 1fr 0.72fr ratio. Image column is right-aligned.
  • The desktop image container is a fixed 1:1 (square) aspect-ratio box within the right column. Image fills it with object-fit: cover, positioned center-center.
  • On mobile, text stack appears first (top), image appears below, full section width, 3:4 aspect ratio.
  • CTA button on desktop is inline (auto width), followed by the phone number as a secondary tel: link on the same line. Phone link: --col-slate, DM Sans 400.

Copy (exact):

Element Content
Eyebrow SAN FRANCISCO HANDYWOMAN
H1 Fix it right. The first time.
Lead Precise, reliable, and easy to work with — Diana brings aerospace-level project coordination to your home improvement project.
CTA label Request a Quote
Secondary link Phone number (Diana's actual phone, formatted as (415) XXX-XXXX)

Image:

  • File: assets/diana_photo-min-1-scaled.webp
  • Alt: "Diana, San Francisco handywoman, aboard a sailboat with the Golden Gate Bridge in the background"
  • loading="eager" (above the fold on all viewports)
  • fetchpriority="high"

Section 3 — Services Grid

Background: --col-mist
Section eyebrow: OUR SERVICES
Section heading (H2): "What Diana can do for you" — Fraunces italic, --text-3xl, --col-graphite
Layout: 2-column grid on mobile/sm; 3-column grid at md and above. Gap: --space-3. 9 cards total.

Each card uses the ServiceCard component (see §6). Cards are arranged left-to-right, top-to-bottom, in the order below.

Service card definitions:

# Service Name URL Thumbnail One-line description
1 Painting /services/painting/ painting-1-min.png Interior and exterior painting, trim, and cabinet refinishing.
2 Tile Setting /services/tile-setting/ tile-setting-1-min.png Kitchen, bathroom, entryway, and patio tile installation.
3 Drywall & Sheetrocking /services/drywall/ sheetrocking-1-min.png Patching, finishing, and full sheetrocking to paint-ready surfaces.
4 Minor Plumbing /services/plumbing/ plumbing-2-min.png Faucets, toilets, showers, and under-sink connections.
5 Minor Electrical /services/electrical/ electrical-1-min.jpg Fixtures, ceiling fans, outlets, and dimmer switches.
6 Carpentry & Mounting /services/carpentry-and-mounting/ (see note) Furniture assembly, TV mounting, shelving, and trim work.
7 Flooring & Wood Refinishing /services/flooring/ wood-refinishing-1-min.png Hardwood refinishing, deck restoration, and new flooring.
8 Security & Safety Equipment /services/security-safety/ grab-bar-min.png Grab bars, lock upgrades, security cameras, and safety installs.
9 Boat Work /services/boat-work/ boat-work-min-scaled.jpg Marine woodwork, painting, and hardware for Bay Area boats.

Note — Card 6 (Carpentry & Mounting): No dedicated carpentry image assets exist in the current asset library. Use wood-refinishing-3-min.png as a placeholder for v1, and flag with Diana for a dedicated photo shoot. Document as a known gap.

Section footer: A "View all services →" text link (DM Sans 500, --col-copper) centered below the grid, linking to /services/. This is supplementary — all 9 services are already shown.

Section 4 — Why HER (Trust Pillars)

Background: --col-linen
Section eyebrow: WHY HER
Section heading (H2): "Built on trust. Delivered with precision." — Fraunces italic, --text-3xl, --col-graphite
Layout: Single column on mobile; 3-column at md and above. Each pillar uses the TrustPillar component.

Pillar definitions:

Pillar name Icon Body copy (2 sentences)
Reliable & Accountable Shield with checkmark (inline SVG, --col-copper, 40×40px) Diana shows up when she says she will and finishes what she starts. No ghosting, no last-minute cancellations — just dependable work, every time.
Project Coordination Clipboard with checklist (inline SVG, --col-copper, 40×40px) With an aerospace background managing complex multi-phase projects, Diana coordinates materials, schedules, and trades on your behalf. She keeps your project moving and your stress low.
Honest Communication Speech bubble with checkmark (inline SVG, --col-copper, 40×40px) You will know the scope, the timeline, and the price before any work begins. If anything changes, Diana tells you immediately — no surprises on your invoice.

Icon treatment: Monochromatic, line-style SVG icons. --col-copper stroke. Icons sit above the pillar name; name is DM Sans 500 --text-xl --col-graphite; body is DM Sans 400 --text-base --col-ink. Each pillar is center-aligned on mobile, left-aligned at md and above.

Section 5 — Testimonials Strip

Background: --col-mist
Section eyebrow: CLIENT TESTIMONIALS
Section heading (H2): "Trusted by San Francisco homeowners" — Fraunces italic, --text-3xl, --col-graphite
Layout: Single column on mobile; 2-column at md and above.

Displays exactly 2 featured testimonials using the TestimonialCard component:

# Client name Attribution / City
1 Wendy Brummer San Francisco, CA
2 David Snyder San Francisco, CA

Copy direction: Use the testimonial text verbatim from the existing testimonials source (see FR-13, 01-requirements.md). Do not paraphrase.

Section footer: A "Read all testimonials →" text link (DM Sans 500, --col-copper) centered below the cards, linking to /testimonials/.

Section 6 — Service Area Callout

Background: --col-linen
Layout: Single column, centered, max-width 720px (narrower than --max-width for readability).
Section eyebrow: SERVICE AREA
Heading (H2): "Serving San Francisco and the Bay Area" — Fraunces italic, --text-3xl, --col-graphite
Lead text: "Diana serves San Francisco and surrounding communities within a 50-mile radius. If you are unsure whether you are in the service area, reach out — she will let you know." — DM Sans 400, --text-lg, --col-ink

City/area list: Displayed as an inline comma-separated list or a compact 2-column flex-wrap pill list (DM Sans 500, --text-sm, --col-slate):

San Francisco · Oakland · Berkeley · Marin County · Daly City · San Mateo · Palo Alto · Fremont · Hayward · Walnut Creek · Concord · Alameda · Napa · and more

Cross-reference: FR-9, NFR-1.

Section 7 — Final CTA Band

Uses the CTABand component.

Background: --col-copper
Text color: #FFFFFF (white)
Padding: --space-8 top/bottom on mobile; --space-12 top/bottom on desktop.
Layout: Centered, single column, max-width 640px.

Element Content Style
Heading (H2) "Ready to get started?" Fraunces italic, --text-3xl, white
Subheading "Let's talk about your project." DM Sans 400, --text-lg, white, opacity 0.9
CTA Button Request a Quote Button (ghost-white variant): white background, --col-copper text, --radius-md; hover: white bg darkens slightly (rgba(255,255,255,0.9)), copper text
Button link /contact/ —

Section 8 — Footer

Uses the Footer component.

Background: --col-graphite
Text color: --col-linen (primary), --col-slate (secondary/metadata)
Padding: --space-8 top/bottom.

Mobile layout (single column, left-aligned):

[HER wordmark — Fraunces italic, --text-2xl, --col-copper]

About · Services · Testimonials · Contact

☎ (415) XXX-XXXX
✉ diana@example.com

© 2026 Home Enhancement and Renovation — HER. All rights reserved.

Desktop layout (2-column):

  • Left column: HER wordmark + copyright line.
  • Right column: nav links (inline) + contact info (phone, email).

Nav links in footer: DM Sans 400, --text-sm, --col-linen. Hover: --col-copper. Separated by · or | character.

Contact links: Phone as tel: link, email as mailto: link. Both --col-linen. Hover: --col-copper.

Copyright: DM Sans 400, --text-xs, --col-slate. Exact text: © 2026 Home Enhancement and Renovation — HER. All rights reserved.

FR coverage: FR-7 (secondary contact in footer), FR-15 (full brand name in footer).

5.2 Services Hub (/services/)

Page goal: Provide an indexed overview of all 9 services; funnel visitors to the right detail page.
FR coverage: FR-10, NFR-3, NFR-4

<title>: Deferred to 37-seo-content-spec.md.

Section 1 — Nav

Sticky nav, as specified in §4. Active link: "Services".

Section 2 — Page Hero

Background: --col-graphite
Text color: white / --col-linen
Padding: --space-8 top/bottom.
Layout: Single column, centered, max-width 720px.

Element Content Style
Eyebrow HANDYWOMAN SERVICES SectionEyebrow, --col-copper
H1 "Services" Fraunces italic, --text-4xl mobile / --text-5xl desktop, white
Lead "Diana offers a wide range of home improvement services in San Francisco and the Bay Area. Browse below and tap through to learn what's included in each service — or request a quote directly." DM Sans 400, --text-lg, --col-linen opacity 0.85

No hero image on this page. The dark --col-graphite hero provides visual contrast with the card grid below.

Section 3 — Services Grid

Background: --col-linen
Padding: --space-8 top/bottom.
Layout: 2-column at mobile/sm; 3-column at md and above. Gap: --space-3. 9 ServiceCard components.

Cards on the hub page have extended description (1–2 sentences instead of 1 line):

Service Extended description
Painting Interior and exterior painting, cabinet refinishing, trim work, and deck staining. Clean, precise results on every surface.
Tile Setting Kitchen backsplashes, bathroom tile, shower surrounds, entryways, and patios — all tile types and rooms. Over 200 satisfied tile customers.
Drywall & Sheetrocking Full sheetrocking, patching, skim coating, sanding, and texture matching — surfaces left paint-ready.
Minor Plumbing Faucet, toilet, and shower fixture replacement; garbage disposal installation; and minor leak repair.
Minor Electrical Light fixture and ceiling fan installation, outlet and switch replacement, dimmer installation, and smoke detector setup.
Carpentry & Mounting Furniture assembly, TV and shelf mounting, cabinet hardware repair, crown molding, and door adjustment.
Flooring & Wood Refinishing Hardwood floor refinishing, deck and stair restoration, laminate and vinyl installation, and cabinet refinishing.
Security & Safety Equipment ADA-compliant grab bars, lock upgrades, security camera installation, and window security reinforcement.
Boat Work Marine woodwork, painting, hardware installation, and teak deck maintenance for Bay Area boats.

Section 4 — Service Area + CTA

Same service area callout as Homepage §6 (reuses the same component, same copy). Followed immediately by the CTABand (same as Homepage §7).

Section 5 — Footer

As specified in §4/5.1.

5.3 Service Detail Template (/services/[slug]/)

Purpose: SEO-targeted landing page for each of the 9 services. Content is unique per service (see table in §5.3.6). This document defines the template structure; per-service content is specified in §5.3.6.
FR coverage: FR-11, NFR-3, NFR-4 | ADR-004

Section 1 — Nav

Sticky nav. Active link: "Services".

Section 2 — Breadcrumb

Immediately below nav, inside a <nav aria-label="Breadcrumb">.

Format: Home › Services › [Service Name]

Segment Link Style
Home / DM Sans 400, --text-sm, --col-copper
› separator — --col-chalk, --text-sm
Services /services/ DM Sans 400, --text-sm, --col-copper
› separator — --col-chalk, --text-sm
[Service Name] No link (current page) DM Sans 500, --text-sm, --col-ink, aria-current="page"

Background: --col-linen. Padding: --space-2 top/bottom.

Section 3 — Service Hero

Background: --col-linen
Padding: --space-8 top/bottom on mobile; --space-12 top/bottom on desktop.
Layout: Single column (centered), max-width 800px.

Element Content Style
Eyebrow [CATEGORY LABEL — e.g. "HOME IMPROVEMENT SERVICE"] SectionEyebrow
H1 Service name (see §5.3.6) Fraunces italic, --text-4xl mobile / --text-5xl desktop, --col-graphite
Lead One-paragraph description (see §5.3.6) DM Sans 400, --text-lg, --col-ink, max 3 sentences
CTA Button Request a Quote Button (primary), links to /contact/

Section 4 — Image Gallery

Background: --col-mist
Padding: --space-8 top/bottom.
Layout: 2 images side-by-side on mobile (sm); 3 images in a row at md and above.

Uses the ImageGallery component:

  • All images: 4:3 aspect ratio, object-fit: cover, --radius-md, loading="lazy".
  • No captions required (decorative context).
  • Images separated by --space-2 gap.
  • Full bleed to section edges on mobile; constrained to --max-width on desktop.
  • Each image has descriptive alt text (see §5.3.6 per service).

On mobile, show 2 images side-by-side if 3 are available; do not use a horizontal scroll carousel. The third image is hidden on mobile (display: none below md) to avoid a cramped 3-up on small screens.

Section 5 — What's Included

Background: --col-linen
Padding: --space-8 top/bottom.
Section heading (H2): "What's included" — Fraunces italic, --text-3xl, --col-graphite.
Layout: Single column, max-width 640px, left-aligned.

Bulleted list (<ul>) of specific tasks (see §5.3.6 per service):

  • Bullets: custom --col-copper filled circle (CSS ::before pseudo-element), not browser default.
  • List item text: DM Sans 400, --text-base, --col-ink.
  • Line height: 1.6.
  • Vertical gap between items: --space-2.

Note box (below the list, optional): A short <aside> box in --col-mist background, --radius-md, --space-3 padding, with copy like: "Not sure if your project is in scope? Describe it in the quote request and Diana will follow up." — DM Sans 400, --text-sm, --col-slate.

Section 6 — Service Area Mention

Background: --col-mist
Layout: Single column, max-width 640px, centered.

Simple inline paragraph — no heading:

"Diana serves [Service Name] customers throughout San Francisco and within a 50-mile radius of the city, including Oakland, Berkeley, Marin County, and the Peninsula. Request a quote to confirm your area." — DM Sans 400, --text-base, --col-slate, centered.

FR coverage: FR-9.

Section 7 — Repeated CTA

Same CTABand as Homepage §7 (copper background, white text, Request a Quote button).

Section 8 — Footer

As specified in §4/5.1.

5.3.6 Per-Service Content Table

Asset path prefix: assets/. All image paths are relative to site root.

Painting · /services/painting/

Field Content
H1 Painting
Eyebrow PAINTING SERVICES — SAN FRANCISCO
Lead From single rooms to full interiors and exteriors, Diana delivers clean, precise paint jobs that transform your San Francisco home. She handles prep, application, and cleanup — so you get professional results without the hassle.
Gallery images painting-1-min.png, painting-3-min.jpg, painting-5-min.jpg
Gallery alt text "Interior wall freshly painted in warm white — San Francisco home" · "Exterior trim painting on a Victorian-style home" · "Painted kitchen cabinets in soft grey"
What's included Interior wall painting (single rooms or whole-home) · Exterior painting and touch-ups · Trim, baseboard, and door painting · Cabinet painting and refinishing · Deck and fence painting and staining · Texture and color matching

Tile Setting · /services/tile-setting/

Field Content
H1 Tile Setting
Eyebrow TILE SETTING SERVICES — SAN FRANCISCO
Lead With over 200 tile installation customers, Diana brings precision and a practiced eye to every kitchen, bathroom, and entryway project. Whether you need a full shower surround or a single backsplash, the result is level, clean, and built to last.
Gallery images tile-setting-1-min.png, tile-setting-3-min.png, tile-setting-5-min.png
Gallery alt text "Newly installed ceramic tile backsplash in a San Francisco kitchen" · "Bathroom floor tile set in a herringbone pattern" · "Outdoor patio tile installation"
What's included Kitchen backsplash installation · Bathroom floor and wall tile · Shower surround tile and waterproofing · Entryway and hallway tile · Patio and outdoor tile · Grouting, caulking, and sealing · Tile removal and replacement

Drywall & Sheetrocking · /services/drywall/

Field Content
H1 Drywall & Sheetrocking
Eyebrow DRYWALL SERVICES — SAN FRANCISCO
Lead From patching a nail hole to installing new drywall in a remodeled room, Diana produces smooth, paint-ready surfaces that look like they were never touched. All patching and finishing work is matched to existing texture.
Gallery images sheetrocking-1-min.png, sheetrocking-2-min.png, sheetrocking-3-min.png
Gallery alt text "Freshly installed drywall in a San Francisco home renovation" · "Drywall patch blended seamlessly into existing wall" · "Skim-coated wall surface ready for paint"
What's included New drywall installation · Drywall patching (holes, cracks, water damage) · Full sheetrocking and taping · Sanding and skim coating · Texture matching (smooth, orange peel, knockdown) · Paint-ready surface prep

Minor Plumbing · /services/plumbing/

Field Content
H1 Minor Plumbing
Eyebrow PLUMBING SERVICES — SAN FRANCISCO
Lead Diana handles the minor plumbing repairs and installations that keep your home running — faucet replacements, toilet installs, shower fixtures, and more. She works cleanly, tests every connection, and leaves no drips.
Gallery images plumbing-2-min.png, plumbing-4-min.png, plumbing-6-min.png
Gallery alt text "New kitchen faucet installed under granite countertop" · "Bathroom vanity plumbing connections" · "Shower fixture replacement in a tiled shower"
What's included Faucet and fixture replacement · Toilet installation and repair · Shower head and valve replacement · Under-sink plumbing connections · Garbage disposal installation · Minor leak detection and repair

Minor Electrical · /services/electrical/

Field Content
H1 Minor Electrical
Eyebrow ELECTRICAL SERVICES — SAN FRANCISCO
Lead Diana installs and replaces lighting fixtures, ceiling fans, outlets, and switches — the kind of focused electrical work that makes a real difference in how a room looks and functions, done safely and up to code.
Gallery images electrical-1-min.jpg, electrical-3-min.jpg, electrical-5-min.jpg
Gallery alt text "Modern pendant light fixture installed in a San Francisco dining room" · "Ceiling fan installation in a bedroom" · "New dimmer switch installed on painted wall"
What's included Light fixture installation and replacement · Ceiling fan installation · Outlet and switch replacement · Dimmer switch installation · Under-cabinet and accent lighting · Smoke and carbon monoxide detector installation

Carpentry & Mounting · /services/carpentry-and-mounting/

Field Content
H1 Carpentry & Mounting
Eyebrow CARPENTRY & MOUNTING — SAN FRANCISCO
Lead From assembling flat-pack furniture to mounting a 75-inch TV securely on the wall, Diana handles the installation and carpentry details that turn a space from a work-in-progress to a finished home.
Gallery images No dedicated assets exist. Use wood-refinishing-3-min.png as placeholder for v1. Flag for Diana to supply 2–3 original carpentry/mounting photos before launch.
Gallery alt text (placeholder) "Wood carpentry detail — placeholder until dedicated photo is supplied"
What's included Flat-pack furniture assembly (IKEA, and other brands) · TV wall mounting (all wall types and screen sizes) · Shelf, bookcase, and storage installation · Cabinet hardware, hinge, and door adjustment · Crown molding and trim installation · Door installation, hanging, and adjustment

Open item: Carpentry & Mounting page requires original photography. This is a known gap. Add to pre-launch checklist.

Flooring & Wood Refinishing · /services/flooring/

Field Content
H1 Flooring & Wood Refinishing
Eyebrow FLOORING SERVICES — SAN FRANCISCO
Lead Diana brings out the natural beauty of your home's wood surfaces — refinishing hardwood floors, restoring decks and stairs, installing new flooring, and refinishing cabinets. The result is a surface that looks and feels brand new.
Gallery images wood-refinishing-1-min.png, wood-refinishing-3-min.png, wood-refinishing-5-min.png
Gallery alt text "Refinished hardwood floors gleaming in natural light" · "Restored wood deck with fresh finish" · "Refinished wood staircase in a San Francisco home"
What's included Hardwood floor sanding and refinishing · Deck and stair sanding and refinishing · Cabinet and furniture wood refinishing · Laminate and vinyl plank flooring installation · Flooring repairs, patching, and touch-ups · Surface prep and sealing

Security & Safety Equipment · /services/security-safety/

Field Content
H1 Security & Safety Equipment
Eyebrow SAFETY & SECURITY SERVICES — SAN FRANCISCO
Lead Diana installs safety and security upgrades that help you feel confident and protected at home — from ADA-compliant grab bars for aging-in-place to lock upgrades, cameras, and reinforced windows.
Gallery images grab-bar-min.png, security-garage-door-min.png. A third image is needed; flag as open item.
Gallery alt text "ADA-compliant grab bar installed in a bathroom — aging-in-place safety" · "Garage door hardware and security upgrade"
What's included Grab bar installation (ADA-compliant placement guidance) · Window and door lock upgrades · Security camera installation and basic setup · Window security mesh and reinforcement bars · Garage door hardware maintenance and adjustment · Door reinforcement and deadbolt installation

Open item: Security & Safety page requires a third gallery photo. Request from Diana or substitute with a grab bar in a different setting.

Boat Work · /services/boat-work/

Field Content
H1 Boat Work
Eyebrow MARINE SERVICES — SAN FRANCISCO BAY AREA
Lead Diana brings the same precision and attention to detail she applies to homes to Bay Area boats — marine woodwork, painting, hardware installation, and teak deck maintenance. If your boat is docked in the Bay Area, she can help.
Gallery images boat-work-min-scaled.jpg. Two additional images are needed; flag as open item.
Gallery alt text "Boat deck woodwork and maintenance — San Francisco Bay Area marine services"
What's included Marine woodwork repairs and finishing · Boat painting and gel coat touch-up · Hardware installation and replacement · Teak deck cleaning, maintenance, and refinishing · Interior marine finishing and trim · Bilge and storage area work

Open item: Boat Work page requires 2 additional gallery photos. Request from Diana.

5.4 About Diana (/about/)

Page goal: Build personal trust, humanize the brand, communicate credentials.
FR coverage: FR-12, FR-16, FR-17, FR-18

Section 1 — Nav

Sticky nav. Active link: "About".

Section 2 — Page Hero

Background: --col-linen
Layout: Single column on mobile; 2-column (image left, text right) at md and above. Same grid ratio as homepage hero (~58% text, ~42% image).

Element Content Style
Eyebrow ABOUT DIANA SectionEyebrow
H1 "Meet Diana" Fraunces italic, --text-4xl mobile / --text-5xl desktop, --col-graphite
Lead "Handywoman. Project coordinator. Aerospace veteran. Diana brings precision and reliability to every job — and an honest, easy-to-work-with approach that sets her apart." DM Sans 400, --text-lg, --col-ink

Hero image:

  • File: assets/diana_photo-min-1-scaled.webp
  • Alt: "Diana, San Francisco handywoman, aboard a sailboat with the Golden Gate Bridge in the background"
  • 3:4 aspect ratio on mobile (below text); 1:1 on desktop (left column).
  • loading="eager", fetchpriority="high".

Section 3 — Bio

Background: --col-linen
Layout: Single column, max-width 720px, left-aligned.

Copy direction (to be written by Diana, lightly edited for web):

  • Paragraph 1: Origin story — what led Diana to handywoman work. Mention aerospace background and what transferable skills she brings (precision, coordination, project management).
  • Paragraph 2: Scale of experience — specifically call out 200+ tile installation customers, multimillion-dollar aerospace projects managed. Make these numbers human: "Over 200 tile installation customers later..." not a bullet point list.
  • Paragraph 3: What makes her different — the female handywoman angle, the "easy to work with" reputation, how she communicates and handles scope changes.
  • Paragraph 4: San Francisco connection — why she loves this city, where she works, community aspect.

Each paragraph: DM Sans 400, --text-base, --col-ink, line-height 1.7.

Section 4 — Pull Quote

Background: --col-mist
Padding: --space-12 top/bottom.
Layout: Single column, centered, max-width 800px.

   ─────────────────────────────────────
   "Over 200 tile installation customers.
    Multimillion-dollar aerospace projects.
    Now she's working on yours."
   ─────────────────────────────────────
Element Style
Quote text Fraunces italic, --text-3xl mobile / --text-4xl desktop, --col-graphite, centered
Top rule 2px solid --col-chalk, full width
Bottom rule 2px solid --col-chalk, full width
Padding (above/below text) --space-6

No attribution line on this pull quote — it is a brand/proof statement, not a client testimonial.

Section 5 — Proof Points Grid

Background: --col-linen
Padding: --space-8 top/bottom.
Layout: 3-column at sm and above; single column on mobile.

3 stat-style proof points (not numbered, icon-led):

Icon Headline Subtext
Tool / wrench SVG 200+ Tile Customers Installations across San Francisco homes
Aerospace badge SVG Aerospace Team Lead Multimillion-dollar project coordination
Star SVG 4-Star Reviews From real clients throughout the Bay Area

Headline: DM Sans 500, --text-xl, --col-graphite.
Subtext: DM Sans 400, --text-sm, --col-slate.
Icon: --col-copper, 36×36px inline SVG, centered above headline.

Section 6 — CTA

Same CTABand component as Homepage §7 (copper background, "Ready to get started?" heading, "Request a Quote" button).

Section 7 — Footer

As specified in §4/5.1.

5.5 Testimonials (/testimonials/)

Page goal: Social proof — validate trust for hesitant visitors.
FR coverage: FR-13, FR-17

Section 1 — Nav

Sticky nav. Active link: "Testimonials".

Section 2 — Page Hero

Background: --col-graphite
Text color: White / --col-linen
Padding: --space-8 top/bottom.
Layout: Single column, centered, max-width 640px.

Element Content Style
Eyebrow CLIENT TESTIMONIALS SectionEyebrow, --col-copper
H1 "What clients say" Fraunces italic, --text-4xl mobile / --text-5xl desktop, white
Lead "Diana's clients speak for themselves. Here's what real San Francisco homeowners say about working with HER." DM Sans 400, --text-lg, --col-linen opacity 0.85

Section 3 — All Testimonials

Background: --col-linen
Padding: --space-8 top/bottom.
Layout: Single column on mobile; 2-column at md and above. Gap: --space-4.

All 4 testimonials are displayed using the TestimonialCard component.

# Client City Notes
1 Wendy Brummer San Francisco, CA Featured (appears first)
2 E. Blake Davis San Francisco, CA —
3 David Snyder San Francisco, CA Featured (appears in Homepage strip)
4 Alice L. Harron San Francisco, CA —

Ordering: Wendy Brummer and David Snyder appear first (positions 1 and 2) as the highest-impact testimonials. E. Blake Davis and Alice L. Harron follow (positions 3 and 4).

Copy: Use testimonial text verbatim from the source (spotlighthis.com/testimonials/). Do not paraphrase or summarize.

TestimonialCard anatomy (on this page, full width):

  • Opening quotation mark: " — Fraunces italic, 4rem, --col-copper, leading visually.
  • Quote body: DM Sans 400, --text-base, --col-ink, line-height 1.7.
  • Attribution line: — [Name], [City] — DM Sans 500, --text-sm, --col-slate. City in --col-slate with lighter weight if multi-part.
  • Card surface: --col-mist, --shadow-card, --radius-md, --space-4 padding.

Section 4 — CTA

Same CTABand as Homepage §7.

Section 5 — Footer

As specified in §4/5.1.

5.6 Contact / Request a Quote (/contact/)

Page goal: Capture qualified leads. This is the primary conversion page.
FR coverage: FR-1, FR-2, FR-3, FR-4, FR-5, FR-6, FR-7 | NFR-1, NFR-2

Form spec authority: Field definitions, validation rules, error states, spam protection, and API integration are fully specified in 38-lead-capture-spec.md. This section defines the page layout and UX context only.

Section 1 — Nav

Sticky nav. Active link: "Contact".

Section 2 — Page Hero

Background: --col-linen
Padding: --space-8 top / --space-4 bottom.
Layout: Single column, max-width 640px, left-aligned.

Element Content Style
Eyebrow REQUEST A QUOTE SectionEyebrow
H1 "Request a Quote" Fraunces italic, --text-4xl mobile / --text-5xl desktop, --col-graphite
Lead "Tell Diana about your project. She'll follow up within 1–2 business days." DM Sans 400, --text-lg, --col-ink

Section 3 — Contact Form

Background: --col-linen
Padding: --space-4 top / --space-8 bottom.
Form container: max-width 560px; left-aligned on desktop (not centered).

Layout — mobile: All fields stack vertically, full width. Submit button full width.

Layout — desktop (md and above):

  • Row 1: Name (50%) + Phone (50%), side by side. Gap: --space-3.
  • Row 2: Email (100%).
  • Row 3: Address / service location (100%).
  • Row 4: Description textarea (100%), min-height 140px, resizable vertically only.
  • Row 5: Submit button, right-aligned, auto width, min-width 200px.

Form fields (5 required fields per FR-3, OQ-4):

Field Label Type Placeholder hint Required
Name Full name text e.g. Jane Smith Yes
Phone Phone number tel e.g. (415) 555-0123 Yes
Email Email address email e.g. jane@example.com Yes
Address Service address text e.g. 123 Market St, San Francisco, CA Yes
Description Describe the work textarea Tell Diana what needs to be done — the more detail, the better. Yes

All fields use the FormField component (see §6). Submit button uses Button (primary), label "Send Request".

FormFeedback states (see 38-lead-capture-spec.md for full logic):

  • Success: Replace form with FormFeedback (success) — green/copper icon, heading "Request received!", body "Diana will follow up within 1–2 business days. In the meantime, you can also reach her at [phone] or [email]." Both contact methods are clickable links. (FR-4, FR-7)
  • Error: Inline FormFeedback (error) above the submit button — "Something went wrong. Please try again, or contact Diana directly at [phone] or [email]." (FR-4, FR-7) Form remains filled so user does not lose their input.

Section 4 — Secondary Contact Info

Background: --col-mist
Padding: --space-6 top/bottom.
Layout: Single column, centered, max-width 640px.

Heading (H3): "Prefer to reach out directly?" — DM Sans 500, --text-xl, --col-graphite.

Two contact items displayed vertically (mobile) or inline (desktop):

Channel Display Link
Phone (415) XXX-XXXX tel: URI
Email diana@example.com mailto: URI

Each item: icon (inline SVG phone/envelope, --col-copper) + link text (DM Sans 500, --text-base, --col-copper). Hover: --col-copper-hover.

FR coverage: FR-6, FR-7.

Section 5 — Footer

As specified in §4/5.1.

6. Component Inventory

Each component is defined by its visual anatomy, states, and token usage. No code — this is a design and behavior contract.

6.1 Button

Three variants. All buttons:

  • Font: DM Sans 500, uppercase, letter-spacing 0.05em.
  • Size: --text-base label, --space-2 top/bottom padding, --space-4 left/right padding.
  • Border-radius: --radius-md.
  • Min touch target: 44×44px.
  • Transition: background-color 150ms ease, transform 100ms ease, box-shadow 150ms ease.
  • Hover: transform: scale(1.02).
  • Focus: outline: 2px solid --col-copper; outline-offset: 2px.
  • Disabled: opacity 0.45, cursor: not-allowed, no hover effects.

Primary Button:

  • Background: --col-copper. Text: white.
  • Hover: background --col-copper-hover.
  • Used for all main CTAs: "Request a Quote", "Send Request".

Secondary Button (outline):

  • Background: transparent. Border: 2px solid --col-graphite. Text: --col-graphite.
  • Hover: background --col-graphite, text white.
  • Used for lower-priority actions: "Learn more", "View all services".

Ghost-White Button (for use on copper CTABand):

  • Background: white. Text: --col-copper.
  • Hover: background rgba(255,255,255,0.9), text --col-copper-hover.
  • Used exclusively inside the CTABand component.

6.2 ServiceCard

Used in the homepage services grid and the Services Hub page.

Anatomy (top to bottom):

  1. Thumbnail: 4:3 aspect ratio, object-fit: cover, --radius-md top corners only, loading="lazy".
  2. Card body: --space-3 padding on all sides.
  3. Service name: DM Sans 500, --text-xl, --col-graphite.
  4. Description: DM Sans 400, --text-sm, --col-slate, 1–2 lines.
  5. Arrow link: "Learn more →" — DM Sans 500, --text-sm, --col-copper. On hover: underline.

Card styles:

  • Background: --col-mist.
  • Border-radius: --radius-md.
  • Box-shadow: --shadow-card.
  • Entire card is a link (wraps in <a>). Hover: box-shadow: --shadow-card-hover, transform: translateY(-2px).
  • Transition: box-shadow 200ms ease, transform 200ms ease.

Scroll animation (see §7): fade-up on scroll entry.

6.3 TestimonialCard

Anatomy (top to bottom):

  1. Opening quotation mark: " — Fraunces italic, 3.5rem, --col-copper. Leading decorative only (aria-hidden="true").
  2. Quote body: DM Sans 400, --text-base, --col-ink, line-height 1.7. Wrapped in <blockquote>.
  3. Attribution: — [Name], [City] — DM Sans 500, --text-sm, --col-slate. Inside <cite>.

Card styles:

  • Background: white (on --col-mist section backgrounds) or --col-mist (on --col-linen backgrounds).
  • Border-left: 4px solid --col-copper.
  • Border-radius: --radius-md.
  • Box-shadow: --shadow-card.
  • Padding: --space-4.

6.4 TrustPillar

Anatomy (top to bottom):

  1. Icon: 40×40px inline SVG, --col-copper. aria-hidden="true".
  2. Pillar name: DM Sans 500, --text-xl, --col-graphite.
  3. Body copy: DM Sans 400, --text-base, --col-ink, 2 sentences, line-height 1.6.

Layout:

  • Mobile: centered. Icon → name → body, stacked.
  • Desktop: left-aligned within its grid column.
  • No card surface (transparent background — inherits section background).
  • No border or shadow.
  • Gap between pillar name and body: --space-1.
  • Gap between icon and pillar name: --space-2.

6.5 NavBar

See §4 for full specification. Component encapsulates:

  • Desktop layout (wordmark + nav links + CTA button).
  • Mobile layout (wordmark + phone icon + hamburger).
  • Mobile menu overlay (full-screen, animated).
  • Scroll-compact state (JS scroll listener, class toggle).
  • Skip link (always first child).

States: Default, scroll-compact, mobile-menu-open.

6.6 Footer

See §5.1 Section 8 for full specification. Component encapsulates:

  • HER wordmark (links to /).
  • Nav links row.
  • Contact info row (phone + email).
  • Copyright line.

Responsive behavior: single column mobile, 2-column desktop.

6.7 FormField

A labeled input or textarea, paired with optional helper/error message.

Anatomy:

  1. <label>: DM Sans 500, --text-sm, --col-graphite. Always visible (never placeholder-only). for attribute links to input id.
  2. <input> or <textarea>: DM Sans 400, --text-base, --col-ink. Background: white. Border: 1px solid --col-chalk. Padding: --space-2. Border-radius: --radius-sm. Width: 100%.
    • Focus: border-color: --col-copper; outline: 2px solid --col-copper; outline-offset: 2px.
    • Error state: border-color: #C0392B; box-shadow: 0 0 0 3px rgba(192,57,43,0.15).
  3. Error message (conditionally rendered): DM Sans 400, --text-xs, #C0392B. Linked via aria-describedby. Appears below the input, --space-1 margin-top.

6.8 FormFeedback

Two variants, rendered in place of or adjacent to the form:

Success variant:

  • Container: --col-mist background, --radius-md, --space-4 padding, border-left: 4px solid --col-copper.
  • Icon: Checkmark circle SVG, --col-copper, 32×32px. role="img", aria-label="Success".
  • Heading: DM Sans 500, --text-xl, --col-graphite. "Request received!".
  • Body: DM Sans 400, --text-base, --col-ink. Includes clickable phone and email links.
  • role="alert", aria-live="polite" on the container (announced to screen readers on render).

Error variant:

  • Container: white background, --radius-md, --space-3 padding, border-left: 4px solid #C0392B.
  • Icon: Warning triangle SVG, #C0392B, 24×24px.
  • Heading: DM Sans 500, --text-base, #C0392B. "Something went wrong.".
  • Body: DM Sans 400, --text-sm, --col-ink. Includes clickable phone and email fallback links.
  • role="alert", aria-live="assertive" (immediately announced).

6.9 Breadcrumb

See §5.3 Section 2. Encapsulates <nav aria-label="Breadcrumb"> with ordered links and aria-current="page" on the final segment.

6.10 SectionEyebrow

Reusable label component placed above section headings.

  • Element: <p> or <span>.
  • Font: DM Sans 500, --text-xs, uppercase, letter-spacing 0.08em.
  • Color: --col-copper.
  • Margin bottom: --space-2 (below eyebrow, above heading).
  • No icon, no decorative elements.

6.11 ImageGallery

Responsive image grid used on Service Detail pages.

  • Container: CSS grid, auto-fill columns, min 200px, gap --space-2.
  • Mobile: 2 images visible (3rd hidden below md).
  • Desktop: 3 images in a row.
  • All images: 4:3 aspect ratio, object-fit: cover, --radius-md, loading="lazy".
  • No lightbox or zoom in v1.
  • Images are decorative context; no captions required, but alt text is mandatory.
  • The gallery section has role="region" and aria-label="[Service Name] project photos".

6.12 CTABand

Full-width section, copper background. Used at the bottom of every page (above footer).

  • Background: --col-copper.
  • Text: white.
  • Centered content, max-width 640px.
  • Heading (H2): Fraunces italic, --text-3xl, white.
  • Subheading: DM Sans 400, --text-lg, white 90% opacity.
  • Button: Ghost-White variant (see §6.1).
  • Padding: --space-8 top/bottom mobile, --space-12 desktop.
  • No scroll animation on this band (it is a persistent conversion element, not a discovery element).

7. Animation & Motion

All motion is subtle and purposeful. No animation that distracts from content or delays interactivity.

7.1 Scroll-triggered Fade-up

Applied to: ServiceCard, TestimonialCard, TrustPillar.

Behavior:

  • Cards begin at opacity: 0; transform: translateY(24px).
  • On entering the viewport (IntersectionObserver threshold: 0.1), transition to opacity: 1; transform: translateY(0).
  • Transition: opacity 400ms ease, transform 400ms ease.
  • Stagger delay within grid: 0ms, 80ms, 160ms per card (left to right, each row).
  • Implementation: CSS classes toggled by a small JS IntersectionObserver. The observer is added only when prefers-reduced-motion is not reduce.

Reduced motion: When @media (prefers-reduced-motion: reduce) applies:

  • Remove all opacity and transform transition effects.
  • Elements appear immediately at full opacity and correct position.
  • No stagger delays.

7.2 Navigation Scroll-compact Transition

  • height transition on the <header> element: height 200ms ease.
  • Logo transform: scale() transition: transform 200ms ease.
  • Only the layout properties transition; no opacity or color animation.

7.3 Button Hover

  • background-color: 150ms ease.
  • transform: scale(1.02): 100ms ease.
  • box-shadow (for card links): 200ms ease.

7.4 Mobile Menu Overlay

  • Entry: transform: translateY(-100%) → transform: translateY(0), 250ms ease-out.
  • Exit: reverse, 200ms ease-in.
  • Reduced motion: instant show/hide, no transform animation.

7.5 Form Error States

  • Error borders and messages: no animation. Appear/disappear instantly.
  • FormFeedback success/error: instant render (motion would delay the user's perception of success/failure).

7.6 Summary Table

Element Property animated Duration Reduced motion
ServiceCard, TestimonialCard, TrustPillar opacity, translateY 400ms Disabled
Nav scroll-compact height, scale 200ms Disabled
Button hover background-color, scale 100–150ms background-color only
Mobile menu overlay translateY 200–250ms Disabled (instant)
Card hover box-shadow, translateY 200ms box-shadow only

8. Image Treatment

8.1 Loading Strategy

Context loading attribute fetchpriority
Hero image (Homepage, About) eager high
All other images lazy (default)

8.2 Aspect Ratios

Context Aspect ratio object-fit Notes
Hero — Diana's photo (mobile) 3:4 (portrait) cover Full-width, stacks below text
Hero — Diana's photo (desktop) 1:1 (square) cover Right column of hero grid
Service card thumbnails 4:3 cover Consistent grid appearance
Service detail gallery 4:3 cover Uniform across 2–3 gallery images

8.3 Border Radius

  • Hero image containers: --radius-lg (16px).
  • Card thumbnails: --radius-md applied to top corners only (card bottom is flush with card body).
  • Gallery images: --radius-md on all corners.

8.4 Alt Text Requirements

All images must have descriptive alt text. Decorative icons used as aria-hidden="true" do not need alt text. The following alt text is specified:

Asset Alt text
diana_photo-min-1-scaled.webp Diana, San Francisco handywoman, aboard a sailboat with the Golden Gate Bridge in the background
painting-1-min.png Interior wall freshly painted in warm white — San Francisco home painting project
painting-3-min.jpg Exterior trim painting on a San Francisco Victorian-style home
painting-5-min.jpg Painted kitchen cabinets in soft grey — cabinet refinishing project
tile-setting-1-min.png Newly installed ceramic tile backsplash in a San Francisco kitchen
tile-setting-3-min.png Bathroom floor tile set in a herringbone pattern
tile-setting-5-min.png Outdoor patio tile installation in a San Francisco Bay Area home
sheetrocking-1-min.png Freshly installed drywall in a San Francisco home renovation
sheetrocking-2-min.png Drywall patch blended seamlessly into an existing wall
sheetrocking-3-min.png Skim-coated wall surface ready for paint
plumbing-2-min.png New kitchen faucet installed under granite countertop
plumbing-4-min.png Bathroom vanity plumbing connections
plumbing-6-min.png Shower fixture replacement in a tiled bathroom
electrical-1-min.jpg Modern pendant light fixture installed in a San Francisco dining room
electrical-3-min.jpg Ceiling fan installation in a bedroom
electrical-5-min.jpg New dimmer switch installed on a painted wall
wood-refinishing-1-min.png Refinished hardwood floors gleaming in natural light
wood-refinishing-3-min.png Restored wood deck with fresh finish — Bay Area outdoor woodwork
wood-refinishing-5-min.png Refinished wood staircase in a San Francisco home
grab-bar-min.png ADA-compliant grab bar installed in a bathroom — aging-in-place safety improvement
security-garage-door-min.png Garage door hardware and security upgrade
boat-work-min-scaled.jpg Boat deck woodwork and maintenance — San Francisco Bay Area marine services

Open items: Alt text for carpentry & mounting placeholder, and any future photos (boat work, security) must be written at the time those images are added.

8.5 File Format and Optimization

  • All existing .webp assets should be served as-is (already optimized format).
  • .jpg and .png assets: if not already optimized at production time, run through a lossless/lossy compressor targeting <150KB per image.
  • Hero image (diana_photo-min-1-scaled.webp): serve a responsive srcset with at least two sizes — 600px wide (mobile) and 1000px wide (desktop).
  • Service card thumbnails: serve at 600px wide maximum; no need for retina on cards given their small rendered size.

FR coverage: NFR-6.

9. Accessibility

The site must meet WCAG 2.1 Level AA as a minimum.

9.1 Color Contrast

Foreground Background Ratio (approx.) Min required Pass?
--col-ink (#1A1A1A) --col-linen (#F4F1EB) ~12:1 4.5:1 body ✓
--col-graphite (#252B30) --col-linen (#F4F1EB) ~9:1 4.5:1 body ✓
White (#FFFFFF) --col-graphite (#252B30) ~11:1 4.5:1 body ✓
White (#FFFFFF) --col-copper (#B5622A) ~3.0:1 3:1 large text ✓ (large text only; verify button label size)
--col-slate (#5C7080) --col-linen (#F4F1EB) ~3.8:1 4.5:1 body ⚠ Borderline — use only for secondary/supplemental text (never primary body); or darken --col-slate to #4A5F6D at implementation
--col-copper (#B5622A) --col-linen (#F4F1EB) ~3.3:1 3:1 large text ✓ for large text / DM Sans 500 ≥ 18.67px; fail for small body text

Rule: --col-copper and --col-slate must never be used for primary body text on --col-linen background. They are acceptable for eyebrows (DM Sans 500, uppercase, ≥12px), large headings (Fraunces ≥24px), and decorative elements only.

9.2 Focus Indicators

All interactive elements must display a visible focus ring on keyboard navigation:

  • Style: outline: 2px solid var(--col-copper); outline-offset: 2px;
  • Applies to: all <a>, <button>, <input>, <textarea>, <select>.
  • Never outline: none without a custom replacement.
  • The default browser focus ring is overridden with the copper custom style globally.

9.3 Touch Targets

  • Minimum: 44×44px for all tappable elements.
  • Nav links, hamburger, phone icon, form buttons, card links, footer links — all must meet this minimum.
  • If the visible element is smaller (e.g., an icon), extend the touch target with padding or a pseudo-element.

9.4 Form Accessibility

  • Every field has a <label> element with a matching for/id pair.
  • Error messages are associated via aria-describedby linking the input to its error <span>.
  • Required fields are indicated with aria-required="true" (in addition to HTML required attribute).
  • Do not rely on placeholder text as the only label.
  • The form submit button has a descriptive accessible name (Send Request, not Submit).
  • After form submission, FormFeedback uses role="alert" so screen readers announce the result.

9.5 Semantic HTML

  • Landmark regions: <header>, <nav>, <main>, <footer>.
  • Section headings follow a logical hierarchy: H1 appears exactly once per page; H2 for sections; H3 for sub-sections; H4 for card headings.
  • <ul> / <li> for navigation links, service lists, city lists.
  • <blockquote> + <cite> for testimonials.
  • <figure> + <figcaption> is optional for gallery images (omit figcaption if no caption is displayed).

9.6 Skip Navigation

A skip link <a href="#main-content">Skip to main content</a> is the first element in <body>. It is visually hidden until focused, at which point it appears in the top-left corner (copper background, white text, --radius-sm). The <main> element has id="main-content" and tabindex="-1" to ensure focus is received.

9.7 Images

  • Decorative icons (inline SVG used for visual purposes only): aria-hidden="true", no alt or title.
  • All <img> elements must have a descriptive alt attribute (see §8.4).
  • Background images (if any are used via CSS): must not convey content that is not otherwise available in the HTML.

10. Requirements Traceability

Spec section Requirement IDs Requirement summary
§4 Navigation (CTA in nav) FR-1, NFR-2 Quote form accessible within 1–2 taps from any page
§4.1 Mobile nav (phone icon) FR-6 Phone prominently exposed
§4.3 Nav accessibility NFR-1, AC-4 Mobile usability, accessible tap targets
§5.1 Hero CTA FR-1, NFR-2 Quote form accessible within 1–2 taps
§5.1 Hero copy FR-15, FR-16, FR-17 Brand name HER; female handywoman positioning; trustworthy/easy to work with
§5.1 Hero (Diana photo) FR-16, FR-18 Personal credibility, aerospace background
§5.1 Services Grid FR-10 Services hub accessible from home
§5.1 Why HER (Trust Pillars) FR-17, FR-18 Trustworthy, project coordination proof points
§5.1 Testimonials Strip FR-13, FR-17 Social proof from real clients
§5.1 Service Area Callout FR-9, AC-3 50-mile service area clearly stated
§5.1 Final CTA Band FR-1, NFR-2 Persistent conversion path
§5.1 Footer (phone + email) FR-6, FR-7, AC-6 Secondary contact visible in footer
§5.1 Footer (brand name) FR-15 Full brand name in footer
§5.2 Services Hub FR-10, NFR-3, NFR-4 Services hub page; SEO-indexable
§5.3 Service Detail Template FR-11, NFR-3, NFR-4, ADR-004, AC-2 9 grouped service pages, unique content, CTA on each
§5.3.2 Breadcrumb NFR-3 Navigable structure for search engines and users
§5.3.6 Per-service content FR-11, NFR-4 Unique content per service for SEO
§5.4 About Diana FR-12, FR-16, FR-17, FR-18 About page with credibility, female handywoman framing, proof points
§5.5 Testimonials FR-13, FR-17 Full testimonials page, all 4 clients
§5.6 Contact form FR-1, FR-2, FR-3 Lightweight quote form, 5 fields
§5.6 Form confirmation FR-4, FR-7 Clear confirmation, secondary contacts in success/error states
§5.6 Form backend FR-5 AWS API Gateway + Lambda → SES (ADR-002)
§5.6 Secondary contact FR-6, FR-7, AC-6 Phone and email below form
§6 Components NFR-1 Mobile-first, touch-friendly controls
§7 Animation NFR-1, AC-4 No distraction; reduced-motion respected
§8 Image treatment NFR-6 Optimized images, lazy loading, eager for LCP
§8 Alt text AC-4, WCAG AA Accessible images
§9 Accessibility AC-4, NFR-1 WCAG 2.1 AA; no horizontal scroll; readable text; tap targets
§9.7 Semantic HTML NFR-3 Indexable, structured HTML content
All pages — no analytics ADR-005, NFR-7 No tracking scripts, no cookie banner
All pages — English only FR-8 English-only content
All pages — static output C-1, ADR-001 Static HTML/CSS/JS, no client-only rendering

End of 33-frontend-spec.md

Reference in New Issue View Git Blame Copy Permalink