gspec 1.7.0 → 1.11.0

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.

package/starters/practices/tdd-pipeline-first.md

@@ -0,0 +1,192 @@
+---
+gspec-version: 1.8.0
+description: TDD, pipeline-first CI/CD, DRY principles, and clean code standards
+---
+
+# Development Practices Guide
+
+## 1. Overview
+
+**Context**: This guide serves as the strict instruction set for AI agents and developers working on the project.
+**Goal**: Maintain a high-velocity, high-quality codebase through rigorous adherence to Test-Driven Development (TDD), DRY principles, and clean code standards.
+
+> **Precedence rule**: Where this document conflicts with technology-specific practices in `gspec/stack.md`, the stack's technology-specific practices take precedence for framework-specific concerns (e.g., file naming conventions dictated by a framework, framework-specific component patterns). This document governs general engineering principles.
+>
+> **Tooling authority**: This document defines testing *philosophy* (TDD, coverage targets, test organization). The specific testing *tools* (Vitest, Playwright, Cypress, etc.) are defined in `gspec/stack.md`. This document defines CI/CD pipeline *structure* (stages, gates, ordering). The specific CI/CD *platform* (GitHub Actions, GitLab CI, etc.) is defined in `gspec/stack.md`.
+
+## 2. Core Development Practices
+
+### Pipeline-First Development
+
+> [!IMPORTANT]
+> **The CI/CD pipeline MUST be established immediately after scaffolding the project, before any application-specific features are implemented.**
+> A working pipeline is the foundation that validates every subsequent change.
+
+#### Implementation Order
+
+After the initial project scaffold (framework setup, dependency installation, basic configuration), the following must be completed in order:
+
+1.  **Lint stage**: Configure the project's linter and formatter. Verify linting passes on the scaffolded codebase.
+2.  **Typecheck stage**: Ensure static type checking passes with strict mode enabled.
+3.  **Test stage**: Set up the unit test runner (as specified in `gspec/stack.md`) with a single trivial passing test (e.g., a smoke test that asserts `true`). Configure the E2E test runner (as specified in `gspec/stack.md`) with a minimal test that loads the index page. Both unit and E2E test commands must pass.
+4.  **Build stage**: Confirm the production build completes successfully.
+5.  **CI pipeline**: Configure the CI/CD platform (as specified in `gspec/stack.md`) with pipeline stages for lint, typecheck, test, build, and deploy. The pipeline must pass end-to-end on the scaffolded project before any feature work begins.
+
+#### Acceptance Criteria
+
+*   All pipeline stages are configured and green.
+*   The pipeline runs automatically on every push and merge request.
+*   Pre-commit hooks are installed and functional, running the linter and formatter on staged files.
+*   No feature branch may be started until the pipeline is verified on the default branch.
+
+#### Rationale
+
+*   **Catch regressions from the first commit**: Every change, no matter how small, is validated.
+*   **Avoid pipeline debt**: Retrofitting CI/CD after features are built leads to a batch of failures that are harder to triage.
+*   **Enforce quality gates early**: Developers and AI agents build the habit of writing code that passes all checks from day one.
+
+### Testing Standards (TDD)
+
+> [!IMPORTANT]
+> **Test-Driven Development (TDD) is MANDATORY.**
+> Strict adherence to the Red-Green-Refactor cycle is required for all logic changes.
+
+1.  **Red**: Write a failing test for the smallest possible unit of functionality.
+2.  **Green**: Write the minimum amount of code required to pass the test.
+3.  **Refactor**: Improve the code structure without changing behavior, ensuring tests remain green.
+
+*   **Scope**:
+    *   **Unit Tests**: Required for all utility functions, helpers, and complex components. Target 100% coverage for business logic.
+    *   **Integration Tests**: Required for API routes and critical user flows.
+    *   **End-to-End Tests**: Headless E2E tests are required for all critical pages to verify they load and render correctly. These tests ensure that routing, layout rendering, and key UI elements are functional from the user's perspective.
+*   **Location**: Dedicated `tests/` directory at the project root or module level, mirroring the source structure. DO NOT colocate tests with source files. E2E tests live in a separate directory (e.g., `e2e/`).
+*   **Naming**: `[filename].spec.*` exclusively. E2E tests use `[page-name].spec.*`.
+*   **E2E Configuration**:
+    *   **Headless by default**: All E2E tests MUST run in headless mode in CI and during standard test runs.
+    *   **Critical Page Coverage**: Every user-facing route must have at minimum a "page loads successfully" E2E test that asserts the page renders without errors and key elements are visible.
+    *   **No Flaky Tests**: E2E tests must be deterministic. Stub external API calls where needed to avoid flakiness.
+
+### Code Quality Standards
+
+#### DRY (Don't Repeat Yourself)
+*   **Rule**: Do not duplicate business logic or complex styling.
+*   **Action**: Extract reusable logic into shared functions, helpers, or modules.
+*   **Exceptions**: Minor duplication (3-4 lines) is acceptable if abstraction increases complexity significantly (WET - Write Everything Twice, but not thrice).
+
+#### Nesting & Complexity
+*   **Max Nesting Depth**: 3 levels.
+    *   *Violation*: `if (...) { for (...) { if (...) { ... } } }`
+    *   *Fix*: Extract the inner logic into a named private function or guard clause.
+*   **Function Length**: Keep functions under 30 lines where possible. Single Responsibility Principle (SRP) applies strictly.
+*   **Cognitive Load**: Use "Early Return" pattern to reduce indentation.
+
+### Code Organization
+
+#### Typing & Safety
+*   **Strict Typing**: If the project uses a statically typed language, enable the strictest available type checking mode. Avoid escape hatches (e.g., `any` in TypeScript, `Object` in Java) — use narrower types or generics instead.
+
+#### Naming Conventions
+*   **Variables/Properties**: `camelCase` (e.g., `userProfile`, `isValid`)
+*   **Functions**: `camelCase` (e.g., `calculateTotal`, `fetchUserData`)
+*   **Types/Interfaces/Classes**: `PascalCase` (e.g., `UserProfile`, `AuthResponse`)
+*   **Constants**: `UPPER_SNAKE_CASE` for global constants (e.g., `MAX_RETRY_COUNT`); `camelCase` for local constants.
+*   **Files**: `kebab-case` (e.g., `user-profile`) for general source files; `PascalCase` for component files where idiomatic for the framework.
+*   **Descriptive Naming**:
+    *   *Bad*: `val = getData(d)`
+    *   *Good*: `userProfile = fetchUserProfile(date)`
+    *   Boolean variables should ideally be prefixed with `is`, `has`, `should` (e.g., `isValid`, `hasAccess`).
+
+#### File Structure
+*   **Colocation**: Keep related files together (e.g., component, test, and styles if utilizing modules).
+*   **Barrels**: Use index/barrel files sparingly to export the public API of a module.
+
+## 3. Version Control & Collaboration
+
+### Git Practices
+*   **Commits**: Conventional Commits style (e.g., `feat: add login page`, `fix: resolve auth timeout`).
+*   **Branches**: `feat/feature-name`, `fix/issue-description`, `chore/maintenance`.
+
+### Code Review Standards
+
+To be defined.
+
+## 4. Documentation Requirements
+
+*   **Self-Documenting Code**: Prioritize clear naming over comments.
+*   **Comments**: Use comments *only* to explain "Why", not "What".
+    *   *Bad*: `// increment i by 1`
+    *   *Good*: `// Retry logic required due to potential API race condition`
+*   **API Documentation**: Use the language's standard doc comment format for public utility functions and complex interfaces to provide IDE hints.
+*   **Deployment Guide**: A `DEPLOYMENT.md` file MUST exist at the project root with step-by-step instructions covering:
+    *   **SaaS Product Configuration**: Account setup and configuration for every third-party service the project depends on. Include required environment variables, API keys, webhook URLs, and any dashboard settings that must be configured.
+    *   **Infrastructure Setup**: Instructions for provisioning hosting, databases, DNS, CDN, and any other infrastructure components.
+    *   **Environment Variables**: A complete list of all required environment variables with descriptions, expected formats, and where to obtain each value.
+    *   **Build & Deploy Steps**: Commands and procedures to build and deploy the application to production, including any CI/CD pipeline configuration.
+    *   **Post-Deploy Verification**: Checklist of smoke tests and health checks to confirm a successful deployment.
+    *   **Rollback Procedure**: Steps to revert to the previous version if a deployment fails.
+    *   Keep `DEPLOYMENT.md` updated whenever a new SaaS dependency is added or deployment steps change.
+
+## 5. Error Handling & Logging
+
+*   **Pattern**: Use error boundaries or equivalent mechanisms to catch and handle UI errors gracefully.
+*   **Backend**: Use structured error objects. Avoid throwing raw strings or untyped errors.
+*   **Logging**: Log significant state changes and errors. Do not leave debugging log statements in production code.
+
+## 6. Performance & Optimization
+
+*   **Rendering**: Memoize or cache expensive computations only when profiling shows a measurable benefit. Virtualize long lists to avoid rendering off-screen items.
+*   **Images**: Always use optimized image components or pipelines provided by the framework.
+
+### SEO & Discoverability
+
+> [!IMPORTANT]
+> **SEO is a core product requirement, not an afterthought.**
+> Every page should be optimized for search engines and social sharing.
+
+#### Metadata Standards
+*   Every page must export metadata including title, description, and Open Graph tags.
+*   **Title Format**: `[Page Name] - [Site Name]` (max 60 characters)
+*   **Description**: 120-160 characters, include primary keyword naturally
+*   **Open Graph**: Always include `title`, `description`, and `images` for social sharing
+
+#### Technical SEO
+*   **Semantic HTML**: Use proper heading hierarchy (`h1` → `h2` → `h3`). One `h1` per page.
+*   **Image Alt Text**: All images MUST have descriptive `alt` attributes.
+    *   *Bad*: `alt="image"`
+    *   *Good*: `alt="Professional reviewing code on laptop screen"`
+*   **Structured Data**: Add JSON-LD schema markup where applicable.
+*   **Sitemap**: Keep `sitemap.xml` updated via dynamic sitemap generation.
+*   **Robots.txt**: Configure properly to allow indexing of public pages, block admin/auth routes.
+
+#### Performance for SEO
+*   **Core Web Vitals**: Monitor and optimize for LCP, FID, CLS.
+    *   Use optimized image components with priority for above-fold images
+    *   Lazy load below-fold content
+*   **Mobile-First**: All pages must be responsive and mobile-friendly (Google mobile-first indexing).
+*   **Page Speed**: Target < 3s initial load on 3G connections.
+
+#### Content Guidelines
+*   **URLs**: Use descriptive, keyword-rich slugs
+    *   *Good*: `/services/web-development`
+    *   *Bad*: `/s/123`
+*   **Internal Linking**: Link related content naturally using descriptive anchor text.
+*   **Heading Structure**: Front-load important keywords in headings without keyword stuffing.
+
+## 7. Security Practices
+
+*   **Input Validation**: Validate all external inputs (API params, form data) using a schema validation library.
+*   **Authentication**: Never implement custom crypto. Use an established auth provider.
+*   **Authorization**: Verify user permissions on *every* server action/API route.
+
+## 8. Refactoring Guidelines
+
+*   **Boy Scout Rule**: Always leave the code cleaner than you found it.
+*   **Refactor Step**: In TDD, the refactor step is not optional. It is the moment to apply DRY and clean up nesting.
+
+## 9. Definition of Done
+
+1.  [ ] Tests written (red -> green).
+2.  [ ] Code follows style guide (linted & formatted).
+3.  [ ] No new Type errors.
+4.  [ ] Logic extracted and readable.
+