gspec 1.6.0 → 1.10.0

package/starters/features/home-page.md

@@ -0,0 +1,103 @@
+---
+gspec-version: 1.8.0
+description: Hero section, service highlights, testimonials, and CTA
+---
+
+# Home Page
+
+## Overview
+
+A home page for a professional services business that introduces the brand, communicates its value proposition, and presents its service offerings. The page serves as the primary entry point for prospective clients researching the business, giving them enough information to understand what the firm does and why it is credible.
+
+## Users & Use Cases
+
+**Primary users:** Prospective clients visiting the website for the first time.
+
+**Key use cases:**
+
+1. A prospective client arrives from a search engine and needs to quickly understand what the business does and whether it is relevant to their needs.
+2. A referral visits the site to validate the recommendation they received, looking for professionalism and evidence of expertise.
+3. A returning visitor navigates back to the home page to review service offerings before engaging further.
+
+## Scope
+
+**In scope:**
+
+- Hero banner section with headline, supporting text, and optional imagery
+- Value proposition section summarizing the firm's core differentiators
+- Services overview section listing the primary service offerings with brief descriptions
+- Responsive layout that works across desktop, tablet, and mobile devices
+- Static content coded directly into the page
+
+**Out of scope:**
+
+- Calls-to-action, buttons, or conversion flows (handled by a separate feature)
+- Blog, news, or dynamic content feeds
+- Client portal or authenticated experiences
+- Search engine optimization tooling or analytics integration
+
+**Deferred ideas:**
+
+- Testimonials or social proof section
+- Team or leadership section
+- Partner or client logo bar
+- Animation or scroll-based interactions
+
+## Capabilities
+
+- [ ] **P0**: Hero banner displays a prominent headline and supporting text that communicates what the business does
+  - Headline and supporting text are visible immediately on page load without scrolling
+  - Text is legible across viewport sizes (desktop, tablet, mobile)
+  - Section accommodates an optional background image or visual element
+
+- [ ] **P0**: Value proposition section presents 2-4 core differentiators of the business
+  - Each differentiator has a short title and brief description
+  - Differentiators are visually distinct and scannable (not a wall of text)
+  - Section is visually separated from the hero and services sections
+
+- [ ] **P0**: Services overview section lists the primary service offerings
+  - Each service has a name and a brief description (1-3 sentences)
+  - Services are presented in a consistent, repeatable layout pattern
+  - The section accommodates 3-6 service items without feeling cluttered
+
+- [ ] **P0**: Page is fully responsive across common device sizes
+  - Layout adapts cleanly to desktop (1024px+), tablet (768px), and mobile (375px) viewports
+  - No horizontal scrolling on any viewport
+  - Text remains readable and images scale appropriately at all sizes
+
+- [ ] **P1**: Page loads quickly with static content
+  - Page is usable within 2 seconds on a standard broadband connection
+  - Images are appropriately sized and optimized for web delivery
+
+- [ ] **P2**: Semantic page structure supports accessibility
+  - Page uses proper heading hierarchy (single h1, logical h2/h3 nesting)
+  - Images include descriptive alt text
+  - Content is navigable via keyboard
+
+## Dependencies
+
+None. This is a foundational page with no dependencies on other features.
+
+## Assumptions & Risks
+
+**Assumptions:**
+
+- The business has established branding (name, logo, colors) available for use.
+- Service offerings are defined and can be summarized in 1-3 sentences each.
+- Static content is acceptable for the initial version; content updates will be infrequent and handled by developers.
+
+**Key risks:**
+
+- **Content readiness:** The page cannot launch without finalized copy for the hero, value proposition, and services sections. Mitigation: use realistic placeholder content during development so layout and structure can be validated independently.
+- **Scope creep into conversion flows:** Without clear CTAs, stakeholders may push to add contact forms or booking widgets to this feature. Mitigation: CTA functionality is explicitly scoped to a separate feature.
+
+## Success Metrics
+
+1. Visitors can identify the business name, what it does, and its core services within 10 seconds of landing on the page.
+2. The page renders correctly and is fully usable across desktop, tablet, and mobile viewports.
+3. Page load time is under 2 seconds on a standard broadband connection.
+4. All content sections (hero, value proposition, services) are present and display without layout issues.
+
+## Implementation Context
+
+> This feature PRD is portable and project-agnostic. During implementation, consult the project's `gspec/profile.md` (target users, positioning), `gspec/style.md` (design system), `gspec/stack.md` (technology choices), and `gspec/practices.md` (development standards) to resolve project-specific context.

package/starters/features/responsive-navbar.md

@@ -0,0 +1,113 @@
+---
+gspec-version: 1.8.0
+description: Responsive navigation bar with mobile hamburger menu
+---
+
+# Responsive Navbar
+
+## Overview
+
+A persistent, top-of-viewport navigation bar that anchors the site identity on the left and presents navigation destinations on the right, adapting its layout across viewport sizes. Without a consistent navigation element, visitors must rely on back buttons or memorized URLs to move between pages — increasing friction and reducing discoverability of key sections.
+
+## Users & Use Cases
+
+**Primary users:** All site visitors navigating between pages.
+
+**Key use cases:**
+
+1. A first-time visitor lands on any page and uses the navbar to discover and navigate to other sections of the site without scrolling back to the top or returning to the home page.
+2. A visitor on a mobile device taps the hamburger menu to access the full set of navigation destinations that would otherwise not fit in the narrow viewport.
+3. A visitor on any page clicks the site identity (icon/name) in the navbar to return to the home page as a familiar orientation point.
+4. A visitor scrolls down a long page and uses the pinned navbar to navigate elsewhere without scrolling back to the top.
+
+## Scope
+
+**In scope:**
+
+- Site identity element (icon and/or name) pinned to the left side of the navbar, functioning as a home link
+- Horizontal navigation links displayed on the right side at wider viewports
+- Hamburger menu trigger that replaces the horizontal links at narrow viewports, revealing a flat list of all navigation destinations
+- Sticky positioning so the navbar remains visible during scrolling
+- Responsive transition between expanded links and collapsed hamburger menu
+
+**Out of scope:**
+
+- Context-aware action slots (edit/view toggles, page-specific controls) — handled by individual page features
+- Nested or multi-level dropdown menus within the hamburger
+- Search bar or search functionality within the navbar
+- User account controls, login/logout, or authentication-related UI
+- Notification badges or indicators
+- Breadcrumb navigation
+
+**Deferred ideas:**
+
+- Animated transitions for hamburger menu open/close
+- Active state highlighting for the current page's link
+- Dropdown sub-menus for grouped navigation at desktop widths
+- Secondary navbar or sub-navigation bar below the primary navbar
+
+## Capabilities
+
+- [ ] **P0**: Site identity element is displayed on the left side of the navbar and links to the home page
+  - An icon, name, or combination of both is visible on the left edge of the navbar at all viewport sizes
+  - Clicking or tapping the identity element navigates to the home page
+  - The identity element has an accessible label describing its purpose as a home link
+
+- [ ] **P0**: Navigation destinations are displayed as horizontal links on the right side at wide viewports
+  - All defined navigation destinations are visible as individual, clickable links
+  - Links are displayed in a consistent, stable order
+  - Each link navigates to the correct destination page
+
+- [ ] **P0**: Navigation destinations collapse into a hamburger menu at narrow viewports
+  - A recognizable hamburger icon (three horizontal lines or equivalent) replaces the horizontal links below a defined breakpoint
+  - Tapping the hamburger icon reveals a flat list of all navigation destinations
+  - Tapping a destination in the list navigates to that page
+  - Tapping the hamburger icon again or navigating away closes the menu
+
+- [ ] **P0**: Navbar remains pinned to the top of the viewport during scrolling
+  - The navbar stays visible at the top of the screen as the user scrolls down the page
+  - Page content scrolls beneath the navbar without overlapping or obscuring it
+  - The navbar does not cause content at the top of the page to be hidden behind it on initial load
+
+- [ ] **P0**: Navbar is fully responsive across common device sizes
+  - Layout adapts cleanly to desktop (1024px+), tablet (768px), and mobile (375px) viewports
+  - The site identity element remains visible and legible at all sizes
+  - No horizontal scrolling is introduced by the navbar at any viewport width
+
+- [ ] **P1**: Hamburger menu is accessible to keyboard and screen reader users
+  - The hamburger trigger is keyboard-focusable and activatable via Enter or Space
+  - The expanded menu can be navigated with keyboard (Tab, Escape to close)
+  - The trigger has an accessible label (e.g., "Navigation menu") that communicates its purpose
+  - Screen readers announce the expanded/collapsed state of the menu
+
+- [ ] **P2**: Navigation destination order remains stable across viewport transitions
+  - The sequence of links in the expanded horizontal layout matches the sequence in the hamburger menu
+  - Resizing the viewport does not reorder or drop navigation destinations
+
+## Dependencies
+
+- **Home Page** ([home-page.md](home-page.md)): The site identity element links to the home page; the home page must exist as a navigation destination.
+
+## Assumptions & Risks
+
+**Assumptions:**
+
+- The site has a defined identity (icon, name, or both) available for use in the navbar.
+- Navigation destinations are statically defined and change infrequently; developer-managed updates are acceptable.
+- The number of navigation destinations is small enough (3-6 items) that a flat list in the hamburger menu is sufficient without grouping or nesting.
+
+**Key risks:**
+
+- **Content overflow at medium viewports:** If the number of navigation links grows, the horizontal layout may overflow before reaching the narrow-viewport breakpoint. Mitigation: define the responsive breakpoint based on content width rather than a fixed pixel value, or set a maximum number of supported links in the horizontal layout.
+- **Sticky positioning conflicts:** The pinned navbar may conflict with other fixed or sticky elements on the page (e.g., cookie banners, chat widgets). Mitigation: establish a clear stacking order convention so the navbar's layer priority is predictable.
+
+## Success Metrics
+
+1. Visitors can navigate to any primary page from any other page using the navbar without scrolling to the top of the page.
+2. The navbar renders correctly with site identity visible and links accessible across desktop, tablet, and mobile viewports.
+3. On narrow viewports, the hamburger menu reveals all navigation destinations and each link functions correctly.
+4. The navbar remains visible and functional during page scroll on all supported viewport sizes.
+
+## Implementation Context
+
+> This feature PRD is portable and project-agnostic. During implementation, consult the project's `gspec/profile.md` (target users, positioning), `gspec/style.md` (design system), `gspec/stack.md` (technology choices), and `gspec/practices.md` (development standards) to resolve project-specific context.

package/starters/features/services-page.md

@@ -0,0 +1,103 @@
+---
+gspec-version: 1.8.0
+description: Service offerings with descriptions, icons, and pricing tiers
+---
+
+# Services Page
+
+## Overview
+
+A dedicated Services page that presents the business's service offerings in detail beyond the brief overview on the home page. Prospective clients who are evaluating whether the business can meet their specific needs require more than a one-line summary — this page gives each service enough space to communicate what it involves and why it matters, helping visitors self-qualify before making contact.
+
+## Users & Use Cases
+
+**Primary users:** Prospective clients evaluating the business's service offerings in detail.
+
+**Key use cases:**
+
+1. A prospective client clicks through from the home page services overview to understand a specific service in more depth before deciding to reach out.
+2. A visitor comparing multiple firms reviews the Services page to assess breadth and relevance of offerings against their needs.
+3. A referral who was told the business handles a specific type of work visits the Services page to confirm that service is offered and understand what it entails.
+
+## Scope
+
+**In scope:**
+
+- Individual section for each service with a heading and short descriptive paragraph (3-5 sentences)
+- Introductory text at the top of the page framing the overall service offering
+- Support for 3-6 service items
+- Responsive layout that works across desktop, tablet, and mobile devices
+- Static content coded directly into the page
+
+**Out of scope:**
+
+- Pricing, rates, or cost information
+- Calls-to-action, contact forms, or conversion elements (handled by a separate feature)
+- Individual dedicated pages per service
+- Case studies, project examples, or portfolio items tied to services
+- Dynamic or CMS-managed content
+- Filtering, search, or categorization of services
+
+**Deferred ideas:**
+
+- Individual service detail pages linked from each service section
+- Icons or illustrations accompanying each service
+- Client testimonials or case studies associated with specific services
+- Service comparison table or feature matrix
+- FAQ section addressing common questions about the services
+
+## Capabilities
+
+- [ ] **P0**: Page displays an introductory section framing the overall service offering
+  - Section includes a heading and a brief paragraph (1-3 sentences) that sets context for the services listed below
+  - Introductory text is visible immediately on page load without scrolling on desktop viewports
+  - Section is visually distinct from the individual service sections
+
+- [ ] **P0**: Each service is presented with a heading and descriptive paragraph
+  - Each service has a clear, distinct heading (service name)
+  - Each service includes a descriptive paragraph of 3-5 sentences explaining what the service involves and the value it provides
+  - Services are presented in a consistent, repeatable layout pattern
+  - The page accommodates 3-6 services without feeling cluttered or requiring excessive scrolling
+
+- [ ] **P0**: Page is fully responsive across common device sizes
+  - Layout adapts cleanly to desktop (1024px+), tablet (768px), and mobile (375px) viewports
+  - No horizontal scrolling on any viewport
+  - Text remains readable and sections are well-spaced at all sizes
+
+- [ ] **P1**: Services are visually scannable and well-structured
+  - A visitor can identify all available services by name within 10 seconds of viewing the page
+  - Each service section is visually separated from adjacent sections with adequate spacing
+  - Clear visual hierarchy distinguishes service headings from descriptive text
+
+- [ ] **P2**: Semantic page structure supports accessibility
+  - Page uses proper heading hierarchy (single h1, logical h2/h3 nesting)
+  - Content is navigable via keyboard
+  - Sufficient color contrast for all text elements
+
+## Dependencies
+
+- **Home Page** ([home-page.md](home-page.md)): The home page includes a services overview section. The Services page expands on that overview. Navigation between pages should be consistent, and the home page services section should link to this page for visitors wanting more detail.
+
+## Assumptions & Risks
+
+**Assumptions:**
+
+- The business has 3-6 defined service offerings that can each be described in 3-5 sentences.
+- Service offerings are stable and change infrequently; developer-managed updates are acceptable.
+- The brief home page services overview is sufficient as a summary, and this page serves as the next level of detail without needing individual service pages.
+
+**Key risks:**
+
+- **Content readiness:** Each service requires a descriptive paragraph beyond what the home page provides. Mitigation: use realistic placeholder content during development so layout and structure can be validated independently.
+- **Redundancy with home page:** Visitors may feel the Services page duplicates the home page overview if the additional detail is not meaningfully different. Mitigation: ensure the home page overview uses shorter summaries (1-2 sentences) while this page provides fuller descriptions (3-5 sentences) with distinct value-oriented content.
+
+## Success Metrics
+
+1. Visitors can identify all available services by name within 10 seconds of viewing the page.
+2. Each service description provides enough detail that a visitor can determine whether the service is relevant to their needs without contacting the business.
+3. The page renders correctly and is fully usable across desktop, tablet, and mobile viewports.
+4. All service sections display in a consistent layout without visual issues or excessive whitespace.
+
+## Implementation Context
+
+> This feature PRD is portable and project-agnostic. During implementation, consult the project's `gspec/profile.md` (target users, positioning), `gspec/style.md` (design system), `gspec/stack.md` (technology choices), and `gspec/practices.md` (development standards) to resolve project-specific context.

package/starters/features/site-footer.md

@@ -0,0 +1,121 @@
+---
+gspec-version: 1.8.0
+description: Site footer with nav links, social icons, and copyright
+---
+
+# Site Footer
+
+## Overview
+
+A standard informational footer rendered at the bottom of every page, providing consistent brand identity, copyright information, and site-wide navigation and legal links. Without a persistent footer, visitors lack a reliable anchor for finding key links and verifying they are on a legitimate, professional site — reducing trust and increasing navigation friction.
+
+## Users & Use Cases
+
+**Primary users:** All site visitors, regardless of their entry point or intent.
+
+**Key use cases:**
+
+1. A visitor reaches the bottom of any page and wants to navigate to another section of the site without scrolling back to the top — the footer provides quick links to key pages.
+2. A visitor wants to review legal or policy information (privacy policy, terms of use) and looks to the footer as the conventional location for these links.
+3. A first-time visitor glances at the footer to confirm the business identity, read a brief description, and see a copyright notice — reinforcing legitimacy and professionalism.
+
+## Scope
+
+**In scope:**
+
+- Business identity display (name and short tagline or description)
+- Copyright notice with current year
+- Navigation links to main site pages
+- Legal and support links (privacy policy, terms of use, accessibility)
+- Consistent rendering across all pages
+- Responsive layout across device sizes
+
+**Out of scope:**
+
+- Contact forms, email signup forms, or interactive input elements
+- Embedded maps or dynamic content
+- Page-specific content or messaging that varies by page
+- CMS or admin interface for managing footer content
+
+**Deferred ideas:**
+
+- Social media profile icon links
+- Certification badges or trust seals
+- Micro-CTA buttons (e.g., "Get a Quote")
+- Newsletter signup field
+- Secondary tagline or seasonal messaging
+
+## Capabilities
+
+- [ ] **P0**: Footer displays the business name and a short tagline or description
+  - Business name is visible and prominent within the footer
+  - A brief tagline or description (1 sentence) accompanies the name
+  - Identity text is legible at all viewport sizes
+
+- [ ] **P0**: Footer displays a copyright notice
+  - Copyright notice includes the current year and business name
+  - Notice is positioned in a conventional footer location (typically bottom of the footer)
+  - Text is legible but visually secondary to navigation and identity content
+
+- [ ] **P0**: Footer includes navigation links to main site pages
+  - Links to all primary site pages (Home, About, Contact) are present
+  - Links are clearly labeled with readable text
+  - Each link navigates to the correct page when activated
+
+- [ ] **P0**: Footer includes legal and support links
+  - Links for privacy policy, terms of use, and accessibility statement are present
+  - Legal links are visually grouped or separated from main navigation links to indicate their distinct purpose
+  - Each link navigates to the correct destination when activated
+
+- [ ] **P0**: Footer renders consistently on every page
+  - The footer appears at the bottom of the page content on all site pages
+  - Footer content and layout are identical regardless of which page the visitor is on
+  - Footer does not overlap or interfere with page-specific content or sticky navigation elements
+
+- [ ] **P0**: Footer is fully responsive across common device sizes
+  - Layout adapts cleanly to desktop (1024px+), tablet (768px), and mobile (375px) viewports
+  - No horizontal scrolling caused by the footer on any viewport
+  - Links remain legible and tappable (adequate touch target size) on mobile devices
+
+- [ ] **P1**: Footer content is organized with clear visual hierarchy
+  - Business identity, navigation links, legal links, and copyright are visually distinct sections or groups
+  - A visitor can distinguish between navigation and legal links without reading every label
+  - Layout uses spacing and grouping to prevent the footer from feeling cluttered
+
+- [ ] **P2**: Footer structure supports accessibility
+  - Footer uses a semantic landmark element so assistive technologies can identify it
+  - All links are keyboard-navigable and have accessible labels
+  - Sufficient color contrast for all text and link elements
+
+## Dependencies
+
+- **Home Page** ([home-page.md](home-page.md)): Footer navigation links include a link to the home page.
+- **About Page** ([about-page.md](about-page.md)): Footer navigation links include a link to the about page.
+- **Contact Page** ([contact-page.md](contact-page.md)): Footer navigation links include a link to the contact page.
+
+Note: The footer can be built before these pages exist by using placeholder destinations. The dependency is on the link targets being available at launch.
+
+## Assumptions & Risks
+
+**Assumptions:**
+
+- The business has an established name and can provide a short tagline or description for footer use.
+- Legal pages (privacy policy, terms of use, accessibility statement) will exist as link destinations by launch, even if as simple placeholder pages.
+- Footer content (identity info, links) is stable and changes infrequently; developer-managed updates are acceptable.
+- A single, shared footer is sufficient — no page-specific footer variations are needed.
+
+**Key risks:**
+
+- **Legal page readiness:** The footer links to legal pages that may not yet exist. Mitigation: links can point to placeholder pages during development; the footer layout is not blocked by legal content.
+- **Navigation consistency with header:** If a separate header or navigation bar exists, the footer's navigation links must stay in sync. Mitigation: both should draw link destinations from a shared configuration or data source to avoid drift.
+
+## Success Metrics
+
+1. The footer is present and visually consistent on every page of the site.
+2. All footer links (navigation and legal) navigate to their correct destinations without errors.
+3. Visitors can identify the business name and find at least one navigation link within 3 seconds of viewing the footer.
+4. The footer renders correctly across desktop, tablet, and mobile viewports with no layout issues.
+
+## Implementation Context
+
+> This feature PRD is portable and project-agnostic. During implementation, consult the project's `gspec/profile.md` (target users, positioning), `gspec/style.md` (design system), `gspec/stack.md` (technology choices), and `gspec/practices.md` (development standards) to resolve project-specific context.

package/starters/features/theme-switcher.md

@@ -0,0 +1,124 @@
+---
+gspec-version: 1.8.0
+description: Light/dark mode toggle with system preference detection
+---
+
+# Theme Switcher
+
+## Overview
+
+A light/dark theme switcher that allows visitors to toggle between light and dark color schemes across all pages of the site. Many users prefer dark interfaces for comfort, reduced eye strain, or personal taste — and increasingly expect websites to respect their system-level preference. Without theme support, the site forces a single visual mode on all visitors regardless of context or preference.
+
+## Users & Use Cases
+
+**Primary users:** All site visitors.
+
+**Key use cases:**
+
+1. A visitor browsing at night prefers a dark interface to reduce eye strain and toggles to dark mode using the switcher in the header.
+2. A visitor whose operating system is set to dark mode arrives at the site and sees it automatically rendered in dark mode without needing to take any action.
+3. A visitor who previously selected light mode returns to the site days later and finds their preference preserved — the site loads in light mode without requiring them to toggle again.
+4. A visitor who normally uses OS-level dark mode wants the site specifically in light mode, so they override the default using the toggle — and the override sticks on future visits.
+
+## Scope
+
+**In scope:**
+
+- Toggle between a light theme and a dark theme
+- Detection of the visitor's operating system color scheme preference
+- User override of the OS default via manual toggle
+- Persistence of the user's theme preference across browser sessions using client-side storage
+- A toggle control placed in the site header/navigation bar, visible on all pages
+- Theming applied consistently across all existing pages (home, about, contact)
+- Smooth visual transition when switching themes (no jarring flash)
+
+**Out of scope:**
+
+- Multiple color themes beyond light and dark
+- Custom user-defined themes or color pickers
+- Server-side or account-based theme preference storage
+- Theming of third-party embedded content (maps, widgets, iframes)
+- High-contrast or accessibility-specific themes (separate feature)
+
+**Deferred ideas:**
+
+- Additional predefined color themes (e.g., sepia, high-contrast)
+- Scheduled auto-switching based on time of day
+- Per-page theme overrides
+- Animated theme transition effects beyond a simple crossfade
+
+## Capabilities
+
+- [ ] **P0**: Visitor can toggle between light and dark themes using a control in the site header
+  - A toggle or icon button is visible in the header/navigation bar on all pages
+  - Clicking the toggle switches the entire page between light and dark color schemes
+  - The current theme state is visually indicated by the toggle (e.g., sun icon for light, moon icon for dark)
+  - The toggle is reachable and operable via keyboard
+
+- [ ] **P0**: Theme is applied consistently across all pages and components
+  - All text, backgrounds, borders, and interactive elements reflect the active theme
+  - No unstyled or mismatched elements remain when switching themes
+  - Theme applies to the home page, about page, and contact page without page-specific overrides
+
+- [ ] **P0**: Site detects and respects the visitor's operating system color scheme preference on first visit
+  - If the OS is set to dark mode, the site renders in dark mode on the first visit (before any manual toggle)
+  - If the OS is set to light mode or has no preference, the site renders in light mode
+  - Detection happens before the initial page paint to avoid a flash of the wrong theme
+
+- [ ] **P0**: Visitor's manual theme preference is persisted in client-side storage
+  - After toggling, the selected theme is saved and survives browser tab closure and reopening
+  - On subsequent visits, the persisted preference takes priority over the OS preference
+  - If no persisted preference exists, the OS preference is used as the default
+
+- [ ] **P1**: Theme switch occurs without a flash of unstyled or incorrect-theme content
+  - On page load, the correct theme is applied before the page becomes visible to the visitor
+  - Toggling themes mid-session produces a smooth transition without a jarring flicker
+  - Navigation between pages does not cause a momentary flash of the wrong theme
+
+- [ ] **P1**: Toggle control is responsive and works across all device sizes
+  - Toggle is visible and tappable on mobile viewports without being obscured by other header elements
+  - Toggle does not break header layout on any supported viewport size (desktop, tablet, mobile)
+
+- [ ] **P2**: Theme preference is accessible
+  - Toggle has an accessible label describing its function (e.g., "Switch to dark mode" / "Switch to light mode")
+  - Theme colors maintain sufficient contrast ratios for text readability in both light and dark modes
+  - Toggle state change is announced to screen readers
+
+## Dependencies
+
+- **Home Page** ([home-page.md](home-page.md)): Theme must apply to all home page sections (hero, value proposition, services).
+- **About Page** ([about-page.md](about-page.md)): Theme must apply to all about page content.
+- **Contact Page** ([contact-page.md](contact-page.md)): Theme must apply to all contact page content.
+
+The theme switcher depends on a shared site header/navigation existing across pages. If no shared header exists yet, one must be established for the toggle to have a consistent location.
+
+> **Compatibility note**: This feature requires client-side JavaScript for toggle interaction, OS preference detection (`prefers-color-scheme`), localStorage persistence, and flash-of-wrong-theme prevention. Stacks that default to zero client-side JS (e.g., static site generators with island architecture) will need an interactive component or inline script for the toggle, plus a blocking inline script in `<head>` to apply the saved theme before first paint. Consult `gspec/stack.md` Section 15 (Technology-Specific Practices) for the framework's approach to client-side interactivity.
+
+## Assumptions & Risks
+
+**Assumptions:**
+
+- The site uses a design approach where colors are defined as variables or tokens, making it feasible to swap between two palettes.
+- A shared header or navigation component exists (or will be created) across all pages.
+- Client-side storage is available in the visitor's browser (virtually universal in modern browsers).
+
+**Open questions:**
+
+- Exact contrast ratios and color values for the dark theme will need validation during implementation against accessibility standards.
+
+**Key risks:**
+
+- **Flash of incorrect theme on load:** If the theme preference is read too late in the page load process, visitors may see a brief flash of the wrong theme. Mitigation: apply the theme preference as early as possible in the page rendering pipeline, before the main content is painted.
+- **Inconsistent theming across pages:** If pages are styled independently, some elements may not respond to the theme toggle. Mitigation: define theme colors as shared design tokens or variables referenced by all page styles.
+- **Dark theme readability:** Poorly chosen dark theme colors can reduce readability or make the site feel amateurish. Mitigation: follow established dark theme design conventions (muted backgrounds, appropriate contrast, desaturated accent colors).
+
+## Success Metrics
+
+1. Visitors can switch between light and dark themes with a single click/tap and see the change applied immediately across the entire page.
+2. The site loads in the visitor's preferred theme (OS-detected or previously saved) without a visible flash of the wrong theme.
+3. A visitor's manually selected theme preference persists across at least 3 return visits over multiple days.
+4. Both light and dark themes meet WCAG AA contrast requirements for all body text.
+
+## Implementation Context
+
+> This feature PRD is portable and project-agnostic. During implementation, consult the project's `gspec/profile.md` (target users, positioning), `gspec/style.md` (design system), `gspec/stack.md` (technology choices), and `gspec/practices.md` (development standards) to resolve project-specific context.