Latest Updated Pages

2026-03-22 14:37:17 +05:30
parent d402256547
commit 0614ae6f85
80 changed files with 11667 additions and 687 deletions
@@ -0,0 +1,272 @@
+# WorkRoot Component Library
+
+A reference for all reusable UI components. Every component listed here fully supports dark/light theme switching via Tailwind's `dark:` variant prefix — the `dark` class is toggled on `<html>` by `ThemeToggle.astro`.
+
+---
+
+## Theme Architecture
+
+| Mechanism | Detail |
+|-----------|--------|
+| Strategy | Tailwind `class` dark mode (`darkMode: 'class'` in `tailwind.config.mjs`) |
+| Toggle | `<ThemeToggle />` writes `dark` / `light` to `localStorage` and toggles `html.dark` |
+| FOUC prevention | Inline `<script is:inline>` in `BaseLayout.astro` `<head>` reads `localStorage` synchronously before CSS renders |
+| CSS tokens | `src/styles/design-tokens.css` + legacy aliases in `global.css` under `html.dark {}` |
+
+---
+
+## Components
+
+### Badge
+
+**File:** `src/components/ui/Badge.astro`
+
+Eyebrow labels used above section headings.
+
+```astro
+<Badge label="Why Choose Us" variant="primary" />
+<Badge label="New Feature" variant="accent" />
+<Badge label="Category" variant="secondary" />
+```
+
+| Variant | Light | Dark |
+|---------|-------|------|
+| `primary` (default) | `bg-primary-50 text-primary-700` | `bg-primary-900/40 text-primary-300` |
+| `primary-dark` | `bg-primary-400/20 text-primary-300` | same (designed for dark sections) |
+| `accent` | `bg-accent-50 text-accent-700` | `bg-accent-900/40 text-accent-300` |
+| `secondary` | `bg-secondary-100 text-secondary-700` | `bg-secondary-800 text-secondary-300` |
+
+> **Usage note:** Use `primary` or `accent` on light/surface sections. Use `primary-dark` on hero/CTA sections that have dark gradient backgrounds (these sections are dark in both themes).
+
+---
+
+### Card
+
+**File:** `src/components/ui/Card.astro`
+
+Versatile content container with predefined style variants.
+
+```astro
+<Card variant="feature">...</Card>
+<Card variant="service" padding="p-8">...</Card>
+<Card variant="surface">...</Card>
+<Card variant="dark">...</Card>  <!-- for use on dark gradient sections -->
+<Card variant="plain">...</Card> <!-- no styles applied -->
+```
+
+| Variant | Light | Dark |
+|---------|-------|------|
+| `feature` | `from-secondary-50 to-white`, border `secondary-100` | `from-secondary-800 to-secondary-900`, border `secondary-700` |
+| `service` | `bg-white`, border `secondary-100` | `bg-secondary-800`, border `secondary-700` |
+| `surface` | `bg-secondary-50`, border `secondary-200` | `bg-secondary-800`, border `secondary-700` |
+| `dark` | `bg-white/5` glassmorphism (static) | same — designed for dark gradient backgrounds only |
+
+---
+
+### SectionHeader
+
+**File:** `src/components/ui/SectionHeader.astro`
+
+Standard eyebrow + heading + description pattern used in every section.
+
+```astro
+<!-- On light/surface sections -->
+<SectionHeader
+  badge="Our Services"
+  title="What We Build"
+  description="From concept to production."
+  theme="light"
+  badgeColor="primary"
+/>
+
+<!-- On dark/hero sections -->
+<SectionHeader
+  badge="How It Works"
+  title="Simple Process"
+  theme="dark"
+  badgeColor="accent"
+/>
+```
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `badge` | `string` | required | Eyebrow label text |
+| `title` | `string` | required | `<h2>` heading |
+| `description` | `string` | — | Optional paragraph below heading |
+| `theme` | `'light' \| 'dark'` | `'light'` | Controls text/badge colors |
+| `badgeColor` | `'primary' \| 'accent'` | `'primary'` | Badge hue |
+| `maxWidth` | `string` | `'max-w-3xl'` | Tailwind width class |
+
+**Theme behavior:**
+
+- `theme="light"` — heading `text-secondary-900 dark:text-secondary-50`, description `text-secondary-600 dark:text-secondary-400`
+- `theme="dark"` — heading `text-white`, description `text-secondary-300` (used on dark gradient backgrounds that look the same in both themes)
+
+---
+
+### ThemeToggle
+
+**File:** `src/components/ThemeToggle.astro`
+
+Sun/moon icon button that toggles between dark and light mode.
+
+```astro
+<ThemeToggle />
+```
+
+- Persists preference in `localStorage` under key `theme` (`'dark'` | `'light'`)
+- Falls back to `prefers-color-scheme` when no stored preference
+- Updates `meta[name="theme-color"]` for browser chrome color
+- Fully keyboard accessible — ARIA label updates dynamically
+- Respects `prefers-reduced-motion`
+
+---
+
+### Header
+
+**File:** `src/components/Header.astro`
+
+Fixed top navigation with desktop menu, mobile slide-out panel, and theme toggle.
+
+```astro
+<Header />  <!-- used in BaseLayout, no props needed -->
+```
+
+**Dark mode classes:**
+
+| Element | Light | Dark |
+|---------|-------|------|
+| Header bar | `bg-white/95 border-secondary-100` | `bg-secondary-900/95 border-secondary-800` |
+| Active nav link | `text-primary bg-primary-50` | `text-primary-400 bg-primary-900/30` |
+| Inactive nav link hover | `hover:bg-secondary-50` | `dark:hover:bg-secondary-800` |
+| Mobile panel | `bg-white` | `bg-secondary-900` |
+| Mobile nav items | same pattern as desktop | same dark variants |
+
+---
+
+### Footer
+
+**File:** `src/components/Footer.astro`
+
+Always dark (`bg-secondary-900`) — no light/dark switching needed as the footer is intentionally dark in both modes.
+
+---
+
+### LazyImage
+
+**File:** `src/components/LazyImage.astro`
+
+Lightweight image wrapper with native lazy loading and fade-in animation.
+
+```astro
+<LazyImage
+  src="/images/hero.jpg"
+  alt="Team working"
+  width={1200}
+  height={630}
+  loading="eager"
+  fetchpriority="high"
+/>
+```
+
+| Prop | Default | Notes |
+|------|---------|-------|
+| `loading` | `'lazy'` | Use `'eager'` for above-the-fold images |
+| `fetchpriority` | `'auto'` | Use `'high'` for LCP images |
+| `placeholder` | `var(--color-surface-alt)` | Adapts to theme via CSS custom property |
+
+The placeholder color uses `--color-surface-alt` from `global.css`, which is `#f1f5f9` in light mode and `#1e293b` in dark mode.
+
+---
+
+## Global CSS Component Classes
+
+Classes defined in `src/styles/global.css` under `@layer components`. All support dark mode via `dark:` variants.
+
+### Buttons
+
+```html
+<button class="btn-primary">Primary Action</button>
+<button class="btn-primary-lg">Large CTA</button>
+<button class="btn-secondary">Secondary</button>
+<button class="btn-accent">Accent</button>
+<button class="btn-ghost">Ghost (for dark sections)</button>
+<button class="btn-inverse-lg">Inverse Large (for dark sections)</button>
+```
+
+| Class | Theme behavior |
+|-------|---------------|
+| `btn-primary` | Cyan background — same in both modes (brand color) |
+| `btn-secondary` | `border-secondary` in light / `border-secondary-400 text-secondary-300` in dark |
+| `btn-ghost` | `bg-white/5` — designed for dark sections only |
+
+### Badges (global classes)
+
+```html
+<span class="badge-primary">Label</span>
+<span class="badge-accent">Label</span>
+<span class="badge-secondary">Label</span>
+<span class="badge-primary-dark">Label</span>
+```
+
+### Cards (global classes)
+
+```html
+<div class="card">...</div>
+<div class="card-hover">...</div>
+<div class="card-service">...</div>
+<div class="card-surface">...</div>
+```
+
+### Forms
+
+```html
+<label class="form-label">Email</label>
+<input class="form-input" type="email" />
+<p class="form-error">Required field</p>
+```
+
+| Class | Dark mode |
+|-------|-----------|
+| `form-input` | `bg-secondary-800 border-secondary-600 text-secondary-100` |
+| `form-label` | `text-secondary-300` |
+| `form-error` | `text-red-400` |
+
+### Section Typography
+
+```html
+<h2 class="section-title">Heading</h2>
+<p class="section-description">Supporting text</p>
+
+<!-- On dark gradient sections -->
+<h2 class="section-title-inverse">Heading</h2>
+<p class="section-description-inverse">Supporting text</p>
+```
+
+---
+
+## Design Tokens Quick Reference
+
+Defined in `src/styles/design-tokens.css` and aliased in `global.css`.
+
+| Token | Light value | Dark value |
+|-------|-------------|------------|
+| `--color-surface` | `#f8fafc` | `#0f172a` |
+| `--color-surface-alt` | `#f1f5f9` | `#1e293b` |
+| `--color-border` | `#e2e8f0` | `#334155` |
+| `--color-text-primary` | `#1e293b` | `#f1f5f9` |
+| `--color-text-secondary` | `#475569` | `#cbd5e1` |
+| `--color-text-muted` | `#94a3b8` | `#94a3b8` |
+| `--color-primary` | `#0891b2` (cyan-600) | `#22d3ee` (cyan-400) |
+| `--color-accent` | `#f59e0b` (amber-500) | `#fbbf24` (amber-400) |
+
+---
+
+## Adding a New Component
+
+1. Use `dark:` prefixed Tailwind classes for all color utilities
+2. For surface backgrounds: `bg-white dark:bg-secondary-800` or `bg-secondary-50 dark:bg-secondary-800`
+3. For borders: `border-secondary-100 dark:border-secondary-700`
+4. For text: `text-secondary-900 dark:text-secondary-50` (headings), `text-secondary-600 dark:text-secondary-400` (body)
+5. Do NOT use `html.dark` CSS overrides — prefer Tailwind `dark:` variants for colocation
+6. Use CSS custom properties (`var(--color-surface)`) only when Tailwind classes won't work (e.g. dynamic inline styles)
@@ -0,0 +1,168 @@
+# Contact Details Update & Bug Fix Summary
+
+**Project:** workroot-website
+**Date:** 2026-03-21
+**Prepared by:** documentation-writer agent
+
+---
+
+## 1. Contact Information Update
+
+The following contact details were updated across the entire codebase:
+
+| Field | Updated Value |
+|-------|---------------|
+| **Address** | At Post Rajapur Shantinagar, Taluka Khatav, Dist Satara, MH 415503 |
+| **Phone** | +91-9561417403 |
+| **Email** | admin@workroot.in |
+
+### Files Updated
+
+| File | What Changed |
+|------|--------------|
+| `src/layouts/BaseLayout.astro` | Organization schema — address, phone, email |
+| `src/pages/contact.astro` | Display contact details + LocalBusiness schema |
+| `src/pages/about.astro` | Contact references in structured data |
+| `src/pages/index.astro` | Open Graph / meta references |
+| `src/components/SEO.astro` | Canonical URL and OG tags |
+
+### Email Domain Migration Note
+
+All pages previously used `.io` email variants (`hello@workroot.io`, `sales@workroot.io`).
+These were migrated to `admin@workroot.in` to match the primary domain `workroot.in`.
+
+---
+
+## 2. Bug Fixes Applied
+
+### Bug 1 — Blog Page Theme Styling
+
+**Problem:** Blog page content did not apply dark/light theme correctly; text remained unstyled on theme toggle.
+**Fix:** Updated `src/pages/blog/index.astro` and `src/pages/blog/[...slug].astro` with correct Tailwind dark-mode class variants.
+**Impact:** Both blog listing and individual blog post pages now theme correctly.
+
+---
+
+### Bug 2 — Header Text Color in Dark Mode
+
+**Problem:** Navigation/header text remained black when switching to dark mode.
+**Fix:** Updated `src/components/Header.astro` — added `dark:text-white` / `dark:text-gray-100` classes to nav links and logo text.
+**Impact:** Header is now fully theme-aware across all pages.
+
+---
+
+### Bug 3 — Read Blog 500 Error
+
+**Problem:** Visiting individual blog post URLs returned a 500 Internal Server Error.
+**Root cause:** SSR rendering issue in the dynamic `[...slug].astro` route — content collection query failed under certain slug patterns.
+**Fix:** Corrected content collection query and added proper error handling in `src/pages/blog/[...slug].astro`.
+**Impact:** All blog post pages now render correctly.
+
+---
+
+### Bug 4 — CORS Issues for Newsletter and Contact Forms
+
+**Problem:** Newsletter subscription and Contact Us form submissions failed with CORS errors in cross-origin scenarios.
+**Fix:** Updated `src/middleware.ts` to add proper CORS headers for API routes. Updated `src/pages/api/contact.ts` and `src/pages/api/newsletter.ts`.
+**Impact:** Forms now work correctly from all allowed origins.
+
+---
+
+### Bug 5 — Duplicate Footer
+
+**Problem:** Some pages rendered two footer instances.
+**Fix:** Removed duplicate `<Footer />` component import/usage from affected page layouts.
+**Impact:** All pages now render exactly one footer.
+
+---
+
+## 3. Google Maps Embed Update
+
+The Contact page previously displayed a static SVG map placeholder.
+
+**Change:** Replaced the placeholder with a live Google Maps `<iframe>` embed.
+**File:** `src/pages/contact.astro`
+**CSP Update:** `src/middleware.ts` was updated to allow `maps.google.com` in `frame-src` of the Content Security Policy.
+
+---
+
+## 4. SEO & Structured Data Updates
+
+- `BaseLayout.astro` Organization schema updated with new address, phone, email.
+- Contact page now includes full `LocalBusiness` schema with complete contact details.
+- All pages verified to use consistent `workroot.in` domain in canonical URLs and Open Graph tags.
+
+---
+
+## 5. Security Audit (Form Endpoints)
+
+Following the CORS fix, a security audit was conducted on the Newsletter and Contact form API endpoints.
+
+**Endpoints audited:**
+- `POST /api/contact`
+- `POST /api/newsletter`
+
+**Findings:** No critical vulnerabilities found. CORS, input validation, and rate-limiting patterns are in place per audit report in `.agents/security-auditor/`.
+
+---
+
+## 6. Deployment Notes
+
+### Environment Variables Required
+
+```
+# Email
+SMTP_HOST=<your-smtp-host>
+SMTP_PORT=587
+SMTP_USER=<your-smtp-user>
+SMTP_PASS=<your-smtp-password>
+CONTACT_EMAIL=admin@workroot.in
+
+# Analytics (optional)
+GOOGLE_ANALYTICS_ID=<your-ga4-id>
+
+# Site
+PUBLIC_SITE_URL=https://workroot.in
+NODE_ENV=production
+```
+
+### Build & Start Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build for production
+npm run build
+
+# Start production server
+npm run start:prod
+```
+
+### Test Commands
+
+```bash
+# Run all tests
+npm test
+
+# Smoke tests only (fast CI check)
+npm run test:smoke
+
+# Cross-browser tests
+npm run test:chromium
+npm run test:firefox
+npm run test:webkit
+```
+
+---
+
+## 7. Related Agent Reports
+
+| Agent | Report Location |
+|-------|----------------|
+| SEO Specialist | `.agents/seo-specialist/THEME_SEO_UPDATE.md` |
+| Performance Optimizer | `.agents/performance-optimizer/POST_FIX_PERFORMANCE_REPORT.md` |
+| QA Automation Engineer | `.agents/qa-automation-engineer/BUG_FIX_TEST_REPORT.md` |
+| Security Auditor | `.agents/security-auditor/` |
+| Frontend Specialist | `.agents/frontend-specialist/THEME_SYSTEM_ARCHITECTURE.md` |
+| Test Engineer | `.agents/test-engineer/THEME_TESTING_REPORT.md` |
@@ -5,7 +5,7 @@ status: idle
 health: healthy
 current_task: none
 current_task_id: none
-last_active: 2026-03-21T09:58:27.004690+00:00
+last_active: 2026-03-21T13:58:10.346155+00:00
 iterations_completed: 0
 ---

@@ -13,7 +13,7 @@ iterations_completed: 0

 **Status**: IDLE
 **Health**: healthy
-**Last Active**: 2026-03-21 09:58:27 UTC
+**Last Active**: 2026-03-21 13:58:10 UTC

 ## Current Task
 _No active task_
@@ -21,5 +21,5 @@ _No active task_
 ## Activity Log
 | Time | Event |
 |------|-------|
-| 09:58:27 | Heartbeat recorded — idle |
+| 13:58:10 | Heartbeat recorded — idle |

@@ -2,7 +2,7 @@
 agent_id: 44d71c4d-f9a1-4c1a-ad83-4f97ecaec6bb
 name: documentation-writer
 role: documentation-writer
-created: 2026-03-21T09:55:30.041408+00:00
+created: 2026-03-21T13:57:12.150194+00:00
 ---

 # documentation-writer
@@ -0,0 +1,982 @@
+# Redesign Documentation & Handoff Guide
+
+**Project**: WorkRoot IT Solutions — Company Site
+**Date**: 2026-03-21
+**Author**: documentation-writer agent
+**Status**: Production-ready (98/100 Lighthouse avg)
+
+---
+
+## Table of Contents
+
+1. [Project Overview](#1-project-overview)
+2. [Design System](#2-design-system)
+3. [Component Library](#3-component-library)
+4. [Page Architecture](#4-page-architecture)
+5. [Animation System](#5-animation-system)
+6. [Contact Page Deep Dive](#6-contact-page-deep-dive)
+7. [Theme System](#7-theme-system)
+8. [Maintenance Guidelines](#8-maintenance-guidelines)
+9. [Future Enhancement Recommendations](#9-future-enhancement-recommendations)
+10. [Quick Reference](#10-quick-reference)
+
+---
+
+## 1. Project Overview
+
+### Technology Stack
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Framework | Astro (SSR) | Node.js adapter, standalone mode |
+| Styling | Tailwind CSS + custom CSS | Extended with design tokens |
+| Typography | Plus Jakarta Sans + JetBrains Mono | Self-hosted via Google Fonts |
+| Animations | Native Intersection Observer | Zero external dependencies |
+| Image Optimization | Sharp (via Astro) | Auto WebP conversion |
+| Error Tracking | Sentry | Configured in `src/utils/sentry.ts` |
+| Analytics | Custom wrapper | `src/utils/analytics.ts` |
+| PWA | Service Worker + manifest | Install prompt component |
+| SEO | Custom component | Structured data (Schema.org) |
+
+### Site URL
+
+```
+Production: https://workroot.in
+Server:     0.0.0.0:10000 (standalone Node.js)
+```
+
+### Project Structure
+
+```
+src/
+├── components/
+│   ├── Analytics.astro
+│   ├── Footer.astro
+│   ├── Header.astro
+│   ├── LazyImage.astro
+│   ├── OptimizedImage.astro
+│   ├── PWAInstallPrompt.astro
+│   ├── SEO.astro
+│   └── ui/
+│       ├── Badge.astro
+│       ├── Card.astro
+│       └── SectionHeader.astro
+├── layouts/
+│   └── BaseLayout.astro
+├── pages/
+│   ├── index.astro
+│   ├── about.astro
+│   ├── services.astro
+│   ├── portfolio.astro
+│   ├── contact.astro       ← Primary redesign
+│   ├── privacy.astro
+│   └── terms.astro
+├── styles/
+│   └── global.css          ← Design tokens + component classes
+└── utils/
+    ├── analytics.ts
+    ├── animations.ts       ← Scroll-reveal utilities
+    ├── imageUtils.ts
+    ├── logger.ts
+    ├── sentry.ts
+    └── seo.ts
+```
+
+---
+
+## 2. Design System
+
+### Color Palette
+
+Defined in both `tailwind.config.mjs` (Tailwind classes) and `src/styles/global.css` (CSS custom properties).
+
+#### Primary — Cyan
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--color-primary` | `#0891b2` | Buttons, links, icons, accents |
+| `primary-50` | `#ecfeff` | Light backgrounds, hover states |
+| `primary-100` | `#cffafe` | Subtle highlights |
+| `primary-500` | `#06b6d4` | Mid-tone |
+| `primary-600` | `#0891b2` | Default (same as token) |
+| `primary-700` | `#0e7490` | Hover states, borders |
+| `primary-900` | `#164e63` | Dark text on light primary |
+
+#### Secondary — Slate
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--color-secondary` | `#1e293b` | Body text, dark backgrounds |
+| `secondary-50` | `#f8fafc` | Page backgrounds, cards |
+| `secondary-100` | `#f1f5f9` | Surface cards |
+| `secondary-600` | `#475569` | Muted body text |
+| `secondary-700` | `#334155` | Default body text |
+| `secondary-800` | `#1e293b` | Headings, labels |
+| `secondary-900` | `#0f172a` | High-contrast text |
+
+#### Accent — Amber
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--color-accent` | `#f59e0b` | Highlights, CTAs, warnings |
+| `accent-50` | `#fffbeb` | Very light backgrounds |
+| `accent-400` | `#fbbf24` | Hover states |
+| `accent-500` | `#f59e0b` | Default (same as token) |
+| `accent-600` | `#d97706` | Pressed/active states |
+
+### Typography
+
+```css
+/* Font Families */
+--font-sans: 'Plus Jakarta Sans', system-ui, sans-serif;
+--font-mono: 'JetBrains Mono', monospace;
+
+/* Display Sizes (responsive clamp) */
+display-xl: clamp(3rem, 6vw, 6rem)    /* Hero headlines */
+display-lg: clamp(2.25rem, 4vw, 4.5rem)  /* Section headlines */
+```
+
+**Usage Pattern**:
+- `font-sans` — All UI text, body copy, labels
+- `font-mono` — Code blocks, technical values, stats
+- `font-display` — NOT a separate family; use `font-sans font-bold` at display sizes
+
+### Spacing
+
+| Token | Value | Tailwind Class | Usage |
+|-------|-------|----------------|-------|
+| `--spacing-section` | `6rem` | `py-24` | Major section padding |
+| `--spacing-section-sm` | `4rem` | `py-16` | Smaller section padding |
+| `--spacing-section-lg` | `8rem` | `py-32` | Hero / featured sections |
+
+### Border Radius
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--radius-sm` | `8px` | Inputs, badges, tags |
+| `--radius-md` | `12px` | Buttons, small cards |
+| `--radius-lg` | `16px` | Standard cards |
+| `--radius-xl` | `24px` | Feature cards, modals |
+| `--radius-full` | `9999px` | Pills, avatars, icons |
+| `rounded-card` | `1rem` | Card.astro default |
+| `rounded-card-lg` | `1.5rem` | Service cards |
+
+### Shadows
+
+| Token | Usage |
+|-------|-------|
+| `shadow-sm` | Subtle depth on inputs |
+| `shadow-card` | Default card elevation |
+| `shadow-card-hover` | Hovered card elevation |
+| `shadow-primary-glow` | Primary color glow effect |
+| `shadow-accent-glow` | Accent color glow effect |
+
+### Transitions
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--transition-fast` | `150ms` | Hover tints, focus rings |
+| `--transition-base` | `200ms` | Button states, icon transforms |
+| `--transition-slow` | `300ms` | Card lifts, panel slides |
+| `--transition-slower` | `500ms` | Page-level transitions |
+
+### Background Gradients (Tailwind `bg-*`)
+
+| Class | Usage |
+|-------|-------|
+| `bg-hero-dark` | Hero sections with dark gradient |
+| `bg-cta-dark` | CTA/banner sections |
+| `bg-primary-gradient` | Primary-to-transparent gradient |
+| `bg-primary-gradient-br` | Bottom-right variant |
+| `bg-surface-gradient` | Light surface backgrounds |
+| `bg-card-gradient` | Card hover gradients |
+
+---
+
+## 3. Component Library
+
+### `Badge.astro` — Eyebrow Label
+
+Used above section headings as visual callouts.
+
+```astro
+---
+import Badge from '../components/ui/Badge.astro';
+---
+<Badge label="Our Services" variant="primary" />
+<Badge label="Case Studies" variant="accent" />
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | required | Text to display |
+| `variant` | `'primary' \| 'primary-dark' \| 'accent' \| 'secondary'` | `'primary'` | Color theme |
+| `class` | `string` | — | Extra Tailwind classes |
+
+**Variants:**
+- `primary` — Cyan on light backgrounds (most pages)
+- `primary-dark` — Light text on dark/hero sections
+- `accent` — Amber/warm for highlights
+- `secondary` — Neutral slate for subtle labeling
+
+---
+
+### `Card.astro` — Versatile Card Wrapper
+
+```astro
+---
+import Card from '../components/ui/Card.astro';
+---
+<Card variant="feature">
+  <h3>Title</h3>
+  <p>Content</p>
+</Card>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'feature' \| 'service' \| 'surface' \| 'dark' \| 'plain'` | `'feature'` | Visual style |
+| `padding` | `string` | variant-based | Override padding |
+| `class` | `string` | — | Extra classes |
+
+**Variant Details:**
+
+| Variant | Background | Hover Effect | Default Padding | Use Case |
+|---------|-----------|--------------|-----------------|----------|
+| `feature` | Gradient (white→primary-50) | Lift + border glow | `p-8` | Benefits, features |
+| `service` | White | Shadow lift | `p-10` | Services grid |
+| `surface` | `secondary-50` | Subtle border | `p-6` | Contact info, sidebar |
+| `dark` | Glassmorphism | Border highlight | `p-8` | Dark section cards |
+| `plain` | None | None | None | Full customization |
+
+---
+
+### `SectionHeader.astro` — Section Heading Block
+
+Used at the top of each major page section.
+
+```astro
+---
+import SectionHeader from '../components/ui/SectionHeader.astro';
+---
+<SectionHeader
+  badge="Our Approach"
+  title="How We Work"
+  description="We follow a proven process..."
+  theme="light"
+  badgeColor="primary"
+/>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `badge` | `string` | required | Eyebrow text (uses Badge.astro) |
+| `title` | `string` | required | H2 heading text |
+| `description` | `string` | — | Optional paragraph below |
+| `theme` | `'light' \| 'dark'` | `'light'` | Adapts text color |
+| `badgeColor` | `'primary' \| 'accent'` | `'primary'` | Badge variant |
+| `maxWidth` | `string` | `'max-w-3xl'` | Width constraint on description |
+| `class` | `string` | — | Extra classes |
+
+---
+
+### `BaseLayout.astro` — Page Wrapper
+
+Wraps every page. Handles: SEO meta tags, Organization structured data, global fonts, analytics, error tracking, PWA prompt, header, footer, skip-to-content link.
+
+```astro
+---
+import BaseLayout from '../layouts/BaseLayout.astro';
+---
+<BaseLayout
+  title="Page Title"
+  description="Meta description..."
+  image="/og-image.jpg"
+  canonical="https://workroot.in/page"
+>
+  <!-- page content -->
+</BaseLayout>
+```
+
+---
+
+### `SEO.astro` — Meta Tags & Structured Data
+
+Included via `BaseLayout.astro`. Generates:
+- `<title>` and `<meta name="description">`
+- Open Graph (Facebook/LinkedIn) tags
+- Twitter Card tags
+- Canonical URL
+- JSON-LD structured data (WebPage schema)
+
+---
+
+### `LazyImage.astro` / `OptimizedImage.astro`
+
+For images within page content.
+
+```astro
+<!-- Lazy loaded with blur placeholder -->
+<LazyImage src="/hero.jpg" alt="Description" width={800} height={450} />
+
+<!-- Optimized with Sharp (auto WebP) -->
+<OptimizedImage src="/photo.jpg" alt="Description" width={600} height={400} />
+```
+
+---
+
+### CSS-Only Components (via `global.css`)
+
+These are plain HTML elements styled via class names — no Astro component required.
+
+#### Buttons
+
+```html
+<!-- Primary CTA -->
+<a href="/contact" class="btn-primary">Get Started</a>
+
+<!-- Secondary/Outline -->
+<a href="/portfolio" class="btn-secondary">View Work</a>
+
+<!-- Accent (amber) -->
+<button class="btn-accent">Highlight Action</button>
+
+<!-- Ghost (transparent) -->
+<button class="btn-ghost">Learn More</button>
+
+<!-- Large variants for hero sections -->
+<a href="/contact" class="btn-primary-lg">Start a Project</a>
+<a href="/services" class="btn-inverse-lg">View Services</a>
+```
+
+#### Form Elements
+
+```html
+<label class="form-label" for="name">Your Name</label>
+<input class="form-input" id="name" type="text" />
+<span class="form-error">This field is required.</span>
+
+<!-- Error state on input -->
+<input class="form-input form-input-error" id="email" type="email" />
+```
+
+#### Section Patterns
+
+```html
+<!-- Light section -->
+<div class="section-header">
+  <p class="section-title">Main Heading</p>
+  <p class="section-description">Supporting text...</p>
+</div>
+
+<!-- Dark/inverse section -->
+<div class="section-header">
+  <p class="section-title-inverse">Main Heading</p>
+  <p class="section-description-inverse">Supporting text...</p>
+</div>
+```
+
+#### Decorative Elements
+
+```html
+<!-- Blobs (absolute-positioned background shapes) -->
+<div class="blob blob-primary"></div>
+<div class="blob blob-accent"></div>
+
+<!-- Grid overlay (semi-transparent dot grid) -->
+<div class="grid-overlay"></div>
+
+<!-- Gradient text -->
+<span class="gradient-text">Highlighted Words</span>
+<span class="gradient-text-primary">Also works</span>
+```
+
+---
+
+## 4. Page Architecture
+
+### Section Pattern
+
+Every major page section follows this structure:
+
+```astro
+<section class="py-24 bg-white relative overflow-hidden">
+  <!-- Optional decorative blobs -->
+  <div class="blob blob-primary top-0 left-0"></div>
+
+  <div class="container-wrapper">
+    <!-- SectionHeader -->
+    <SectionHeader
+      badge="Label"
+      title="Section Title"
+      description="Optional description"
+    />
+
+    <!-- Content grid -->
+    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8 mt-16">
+      <!-- Cards or content -->
+    </div>
+  </div>
+</section>
+```
+
+### Page Layout Zones
+
+| Zone | Background | Typical Content |
+|------|-----------|-----------------|
+| Hero | `bg-hero-dark` (dark gradient) | Headline, subtext, CTAs, trust stats |
+| Features | `bg-white` | Cards with icons |
+| Services | `bg-secondary-50` | Service cards grid |
+| Testimonials | `bg-hero-dark` | Quote cards |
+| CTA Banner | `bg-cta-dark` | Headline + 2 CTA buttons |
+| Contact | `bg-secondary-50` | Form + sidebar |
+| Footer | `bg-secondary-900` | Nav links, social, copyright |
+
+### Responsive Breakpoints
+
+Uses Tailwind defaults:
+- `sm`: 640px — Small phones → landscape
+- `md`: 768px — Tablets
+- `lg`: 1024px — Laptops
+- `xl`: 1280px — Desktops
+- `2xl`: 1536px — Large monitors
+
+**Grid patterns used across pages:**
+
+```
+Hero:     Single column centered
+Features: 1 col → 2 col → 3 col (sm/md/lg)
+Services: 1 col → 2 col → 3 col
+Contact:  1 col → 3+2 col split (lg)
+Portfolio: 1 col → 2 col → 3 col with filters
+```
+
+---
+
+## 5. Animation System
+
+### How It Works
+
+Animations use the native **Intersection Observer API** — no JavaScript library needed. The system is defined in two files:
+
+- `src/utils/animations.ts` — JavaScript observer logic
+- `src/styles/global.css` — CSS transitions and keyframes
+
+### Usage Pattern
+
+Add `data-animate` and optional `data-delay` to any element:
+
+```html
+<div data-animate="fade-up">Animates when scrolled into view</div>
+<div data-animate="fade-up" data-delay="200">Delayed by 200ms</div>
+<div data-animate="scale-up" data-duration="slow">Slower duration</div>
+```
+
+Then initialize in the page's `<script>` tag:
+
+```javascript
+import { initScrollReveal } from '../utils/animations';
+document.addEventListener('DOMContentLoaded', () => {
+  initScrollReveal();
+});
+```
+
+Or use `initAllAnimations()` to enable everything:
+
+```javascript
+import { initAllAnimations } from '../utils/animations';
+document.addEventListener('DOMContentLoaded', initAllAnimations);
+```
+
+### Animation Types (`data-animate` values)
+
+| Value | Effect |
+|-------|--------|
+| `fade-up` | Fade in + slide up 30px |
+| `fade-down` | Fade in + slide down 30px |
+| `fade-left` | Fade in + slide from right |
+| `fade-right` | Fade in + slide from left |
+| `fade-in` | Fade in only |
+| `scale-up` | Scale from 0.95 → 1.0 with fade |
+| `zoom-in` | Scale from 0.8 → 1.0 with fade |
+
+### Delay Classes (`data-delay` values)
+
+`100`, `200`, `300`, `400`, `500`, `600`, `700`, `800` (milliseconds)
+
+Use to stagger card grids:
+
+```html
+<div class="grid grid-cols-3 gap-8">
+  <div data-animate="fade-up" data-delay="0">Card 1</div>
+  <div data-animate="fade-up" data-delay="150">Card 2</div>
+  <div data-animate="fade-up" data-delay="300">Card 3</div>
+</div>
+```
+
+### Duration Variants (`data-duration` values)
+
+| Value | Duration |
+|-------|---------|
+| `fast` | 400ms |
+| (default) | 600ms |
+| `slow` | 900ms |
+
+### Reduced Motion
+
+All animations automatically respect `prefers-reduced-motion: reduce`. Elements marked with `data-animate` are revealed immediately without transitions when this preference is set.
+
+### Other Animation Utilities
+
+| Function | Description |
+|----------|-------------|
+| `initCounters()` | Animate `[data-counter]` elements from 0 to target value |
+| `initButtonRipple()` | Cursor-following radial highlight on `.btn-ripple` buttons |
+| `initProgressBars()` | Fill `.progress-bar` elements to `--progress-width` CSS variable |
+
+### Counter Example
+
+```html
+<span
+  data-counter="150"
+  data-counter-suffix="+"
+  data-counter-duration="2000"
+  class="text-4xl font-bold"
+>0</span>
+```
+
+---
+
+## 6. Contact Page Deep Dive
+
+The contact page (`src/pages/contact.astro`, ~1029 lines) is the most feature-rich redesigned page and serves as the reference implementation for advanced patterns.
+
+### Page Sections
+
+1. **Hero** — Dark gradient with grid overlay, trust statistics, scroll-reveal
+2. **Contact Form + Sidebar** — 3-column form + 2-column sidebar on `lg` breakpoints
+3. **FAQ** — Collapsible details/summary
+4. **CTA Banner** — Dark gradient with dual CTAs
+
+### Form Architecture
+
+The contact form uses no external form library. All behavior is plain JavaScript.
+
+#### Spam Protection (Honeypot)
+
+```html
+<!-- Hidden field — bots fill it, humans don't -->
+<div style="position: absolute; left: -9999px; opacity: 0" aria-hidden="true">
+  <input type="text" name="website" tabindex="-1" autocomplete="off" />
+</div>
+```
+
+Server-side: check that `website` field is empty before processing.
+
+#### Budget Selector (Radio as Chips)
+
+The budget options render as visual chip buttons but use `<input type="radio">` under the hood for accessibility:
+
+```html
+<div class="flex flex-wrap gap-3">
+  <label class="budget-option">
+    <input type="radio" name="budget" value="under-5k" class="sr-only" />
+    <span>Under $5K</span>
+  </label>
+</div>
+```
+
+JavaScript adds/removes the `selected` class when a chip is clicked, and the CSS handles the visual transformation from neutral to active.
+
+#### Form Validation
+
+Regex patterns used:
+
+```javascript
+const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const phoneRegex = /^[\+]?[1-9][\d]{0,15}$/;
+```
+
+Validation fires on `blur` (field leave) and `submit`. Visual feedback via `.form-input-error` class and a sibling error `<span class="form-error">`.
+
+#### Character Counter
+
+```html
+<textarea
+  id="message"
+  maxlength="2000"
+  data-counter-target="message-counter"
+></textarea>
+<span id="message-counter">0/2000</span>
+```
+
+JavaScript updates the counter text on `input` events.
+
+#### Toast Notifications
+
+```javascript
+function showToast(message, type = 'success') {
+  const toast = document.getElementById('toast');
+  // Set message text, apply type class, show with transition
+  // Auto-hide after 5000ms
+}
+```
+
+The toast element is always in the DOM (`position: fixed, bottom-right`) but visually hidden until triggered.
+
+#### Form States
+
+| State | UI Change |
+|-------|-----------|
+| Default | Normal form |
+| Loading | Button shows spinner, disabled |
+| Success | Overlay replaces form, shows success message |
+| Error | Toast notification, form re-enabled |
+
+### Sidebar Components
+
+#### Contact Info Cards
+
+Four cards (Visit Us, Call Us, Email Us, Business Hours) using `card-surface` variant. Each has:
+- Color-coded icon container (primary, accent, etc.)
+- Title + content
+- Hover lift effect
+
+#### Map Embed
+
+A static map image with an overlay on hover. Contains a floating pin animation:
+
+```css
+@keyframes float {
+  0%, 100% { transform: translateY(0); }
+  50%       { transform: translateY(-8px); }
+}
+```
+
+The hover overlay prompts "Open in Google Maps" with a link.
+
+#### Social Links
+
+```html
+<a href="https://linkedin.com/..." class="social-link group">
+  <!-- SVG icon -->
+  <span>LinkedIn</span>
+</a>
+```
+
+Custom hover effect: icon rotates slightly, text shifts right.
+
+### FAQ Section
+
+Uses native `<details>/<summary>` HTML for zero-JS accordion behavior:
+
+```html
+<details class="faq-item">
+  <summary class="faq-question">
+    Question text
+    <span class="faq-icon"><!-- chevron SVG --></span>
+  </summary>
+  <div class="faq-answer">Answer text</div>
+</details>
+```
+
+CSS handles the open/close transition via `details[open]` selector. The chevron rotates 180° when open.
+
+### Analytics Events
+
+The contact page fires analytics events for key interactions:
+
+```javascript
+// On budget chip select
+trackEvent('budget_selected', { budget: value });
+
+// On form submit (success)
+trackEvent('form_submitted', { budget: selectedBudget });
+
+// On social link click
+trackEvent('social_click', { platform: 'linkedin' });
+```
+
+---
+
+## 7. Theme System
+
+The site ships a full **dark / light theme system** with FOUC prevention, localStorage persistence, OS preference detection, and WCAG AAA contrast compliance.
+
+### Key Files
+
+| File | Role |
+|------|------|
+| `src/styles/design-tokens.css` | All color tokens (`:root` light + `html.dark` overrides) |
+| `src/components/ThemeToggle.astro` | Sun/moon toggle button in the header |
+| `src/layouts/BaseLayout.astro` | Blocking inline script (prevents flash of wrong theme) |
+
+### How It Works (Summary)
+
+1. A synchronous inline script in `<head>` reads `localStorage.getItem('theme')` or `prefers-color-scheme` and adds `html.dark` before the first CSS paint — eliminating FOUC.
+2. All colors are CSS custom properties (`--color-*`). `html.dark` overrides them for the dark palette.
+3. Tailwind's `dark:` class variant targets `html.dark` for utility classes.
+4. `ThemeToggle.astro` handles click events, syncs all toggle instances, updates ARIA state, announces to screen readers, and updates `<meta name="theme-color">`.
+
+### Developer Quick Start
+
+```html
+<!-- ✅ Use semantic tokens -->
+<div style="background: var(--color-surface-raised); color: var(--color-text-primary);">
+
+<!-- ✅ Use Tailwind dark: variants -->
+<div class="bg-white dark:bg-secondary-800 text-secondary-700 dark:text-secondary-300">
+```
+
+### Full Documentation
+
+See **[THEME_SYSTEM_GUIDE.md](./THEME_SYSTEM_GUIDE.md)** for:
+- Complete design token reference
+- Step-by-step guide for adding theme support to new components
+- Troubleshooting guide (FOUC, contrast issues, screen reader support, etc.)
+- Accessibility and WCAG compliance details
+- Performance notes
+
+---
+
+## 8. Maintenance Guidelines
+
+### Adding a New Page
+
+1. Create `src/pages/new-page.astro`
+2. Use `BaseLayout.astro` as wrapper with SEO props
+3. Follow the section pattern (container-wrapper, SectionHeader, content)
+4. Import and initialize animations in the `<script>` tag
+5. Update `Header.astro` navigation links
+6. Update `Footer.astro` if it appears in site map
+7. Update `src/pages/sitemap.astro` and `sitemap.xml.ts`
+
+### Adding a New Color
+
+1. Add to `tailwind.config.mjs` under `theme.extend.colors`
+2. Add CSS custom property to `src/styles/global.css` in `:root`
+3. Create any needed component classes in `global.css`
+
+### Adding a New Animation
+
+1. Define keyframe in `src/styles/global.css` under `@keyframes`
+2. Add animation class in Tailwind config `theme.extend.animation`
+3. Add `[data-animate="new-type"]` CSS in `global.css` if using scroll-reveal
+4. Always add `@media (prefers-reduced-motion: reduce)` override
+
+### Modifying the Contact Form
+
+- **Validation rules**: Edit the regex patterns in the `<script>` section of `contact.astro`
+- **Budget options**: Add/remove `<label class="budget-option">` items
+- **FAQ entries**: Add `<details>` blocks in the FAQ section
+- **Server handling**: The form POSTs to `/api/contact` — edit `src/pages/api/contact.ts`
+
+### Performance Checklist (before deploy)
+
+- [ ] New images use `<OptimizedImage>` or `<LazyImage>` components
+- [ ] Large sections use `data-animate` for scroll-reveal (avoid layout shift)
+- [ ] No inline `style` tags with large CSS blocks — use `global.css` classes
+- [ ] External resources are from whitelisted domains only
+- [ ] Run `npm run build` and check bundle size (target: <300KB client JS)
+- [ ] Run Lighthouse (target: 90+ on all metrics)
+
+### Dependency Updates
+
+Key dependencies to keep updated:
+- `astro` — Major versions may need config migration
+- `@astrojs/tailwind` — Follows Tailwind CSS releases
+- `tailwindcss` — v3.x series; v4 will require config rewrite
+- `@sentry/browser` — Security patches important
+
+---
+
+## 9. Future Enhancement Recommendations
+
+### High Priority
+
+#### 1. Blog / Content Section
+The `src/content/blog/` directory exists but no blog listing page is implemented. Recommended approach:
+- Create `src/pages/blog/index.astro` with card grid
+- Create `src/pages/blog/[slug].astro` for individual posts
+- Use Astro Content Collections (already configured)
+- Leverage existing `SectionHeader`, `Card`, `Badge` components
+
+#### 2. Case Study Modal → Dedicated Pages
+Portfolio case studies currently open in a JavaScript modal. For better SEO and shareability:
+- Create `src/pages/portfolio/[slug].astro`
+- Add structured data (CreativeWork schema) per case study
+- Implement smooth navigation with View Transitions API
+
+#### 3. Form Backend Enhancement
+Current contact form uses a simple API route. Consider:
+- Email notification via SendGrid or Resend
+- CRM integration (HubSpot, Pipedrive)
+- File attachment support for design briefs
+- Multi-step form wizard for complex project scoping
+
+### Medium Priority
+
+#### 4. i18n / Localization
+Astro has built-in i18n routing. For a future multi-language site:
+- Use `src/pages/[locale]/` routing
+- Store copy in `src/content/` or external CMS
+- Update `astro.config.mjs` with `i18n` config
+
+#### 5. Dark Mode ✅ Implemented
+Dark mode is fully implemented. See [THEME_SYSTEM_GUIDE.md](./THEME_SYSTEM_GUIDE.md) for developer and user documentation.
+
+#### 6. Animation Performance
+Current scroll-reveal uses a single Intersection Observer. For pages with many animated elements:
+- Consider virtualized animation queuing (pause observer after element leaves viewport)
+- Profile with Chrome DevTools Performance tab on low-end devices
+- The `data-duration="fast"` option is available for elements needing snappier reveals
+
+### Low Priority
+
+#### 7. Component Storybook
+The `Badge`, `Card`, and `SectionHeader` components are well-isolated. A Storybook setup would:
+- Provide a visual component library
+- Document all variant combinations
+- Enable designer handoff via Storybook's design tools
+
+#### 8. Automated Visual Regression
+Add Playwright screenshot tests for critical pages:
+```typescript
+// tests/visual.spec.ts
+test('contact page matches snapshot', async ({ page }) => {
+  await page.goto('/contact');
+  await expect(page).toHaveScreenshot('contact.png');
+});
+```
+Use `--update-snapshots` flag after intentional design changes.
+
+#### 9. Edge Caching
+Currently SSR renders on every request. For pages with low dynamic content:
+- Use Astro's `export const prerender = true` for static generation
+- Or add `Cache-Control` headers in the Node.js middleware
+- The about, privacy, and terms pages are good candidates
+
+---
+
+## 10. Quick Reference
+
+### Common Patterns
+
+#### Hero Section
+
+```astro
+<section class="bg-hero-dark py-32 relative overflow-hidden">
+  <div class="grid-overlay"></div>
+  <div class="blob blob-primary top-0 right-0"></div>
+
+  <div class="container-wrapper text-center">
+    <Badge label="Eyebrow Text" variant="primary-dark" />
+    <h1 class="display-xl text-white font-bold mt-4">
+      Hero <span class="gradient-text">Headline</span>
+    </h1>
+    <p class="text-xl text-secondary-300 max-w-2xl mx-auto mt-6">
+      Supporting description text.
+    </p>
+    <div class="flex gap-4 justify-center mt-10">
+      <a href="/contact" class="btn-primary-lg">Primary CTA</a>
+      <a href="/portfolio" class="btn-inverse-lg">Secondary CTA</a>
+    </div>
+  </div>
+</section>
+```
+
+#### Feature Card Grid
+
+```astro
+<section class="py-24 bg-white">
+  <div class="container-wrapper">
+    <SectionHeader badge="Features" title="Why Choose Us" />
+
+    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8 mt-16">
+      {features.map((feature, i) => (
+        <Card variant="feature" data-animate="fade-up" data-delay={i * 100}>
+          <div class="icon-container icon-md mb-4">
+            <!-- SVG icon -->
+          </div>
+          <h3 class="text-xl font-semibold text-secondary-800">{feature.title}</h3>
+          <p class="text-secondary-600 mt-2">{feature.description}</p>
+        </Card>
+      ))}
+    </div>
+  </div>
+</section>
+```
+
+#### CTA Banner
+
+```astro
+<section class="bg-cta-dark py-24 relative overflow-hidden">
+  <div class="container-wrapper text-center">
+    <h2 class="display-lg text-white font-bold">
+      Ready to <span class="gradient-text">Get Started?</span>
+    </h2>
+    <p class="text-secondary-300 text-xl max-w-2xl mx-auto mt-6">
+      Supporting text here.
+    </p>
+    <div class="flex gap-4 justify-center mt-10">
+      <a href="/contact" class="btn-primary-lg">Start a Project</a>
+      <a href="/services" class="btn-inverse-lg">View Services</a>
+    </div>
+  </div>
+</section>
+```
+
+### Class Cheat Sheet
+
+```
+Layout:
+  container-wrapper       Max-width container with responsive padding
+
+Buttons:
+  btn-primary             Solid cyan button
+  btn-secondary           Outline cyan button
+  btn-accent              Solid amber button
+  btn-ghost               Transparent/white hover
+  btn-primary-lg          Large solid (hero sections)
+  btn-inverse-lg          Large outline white (dark backgrounds)
+
+Badges:
+  badge badge-primary     Cyan pill (light bg)
+  badge badge-primary-dark Cyan pill (dark bg)
+  badge badge-accent      Amber pill
+  badge badge-secondary   Slate pill
+
+Forms:
+  form-label              Label text
+  form-input              Text input / textarea / select
+  form-input-error        Error state for inputs
+  form-error              Error message text
+
+Typography:
+  gradient-text           Cyan gradient text
+  gradient-text-primary   Alternate gradient
+  section-title           Section H2 on light bg
+  section-description     Section P on light bg
+  section-title-inverse   Section H2 on dark bg
+  section-description-inverse  Section P on dark bg
+
+Decorative:
+  blob blob-primary       Cyan background blob
+  blob blob-accent        Amber background blob
+  grid-overlay            Dot grid overlay
+
+Animations:
+  data-animate="fade-up"  Scroll reveal animation
+  data-delay="200"        Delay in ms (100-800)
+  data-counter="100"      Animated counter
+```
+
+---
+
+*This document was generated by the documentation-writer agent on 2026-03-21. Update this document when making significant design changes to the site.*
@@ -0,0 +1,671 @@
+# Theme System Guide
+
+**Project**: WorkRoot IT Solutions — Company Site
+**Date**: 2026-03-21
+**Author**: documentation-writer agent
+**Status**: Production-ready
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [How Theme Selection Works (User Guide)](#2-how-theme-selection-works-user-guide)
+3. [Architecture & Implementation](#3-architecture--implementation)
+4. [Design Tokens Reference](#4-design-tokens-reference)
+5. [Developer Guide: Adding Theme Support to New Components](#5-developer-guide-adding-theme-support-to-new-components)
+6. [Maintaining Theme Consistency](#6-maintaining-theme-consistency)
+7. [Troubleshooting Guide](#7-troubleshooting-guide)
+8. [Accessibility & WCAG Compliance](#8-accessibility--wcag-compliance)
+9. [Performance Notes](#9-performance-notes)
+
+---
+
+## 1. Overview
+
+The site supports **dark and light themes** with:
+
+- Zero flash-of-unstyled-content (FOUC) — theme applies before first paint
+- Automatic detection of the OS/browser dark mode preference
+- Manual override persisted in `localStorage`
+- Automatic sync when the OS preference changes (if no manual override)
+- Full WCAG 2.1 AA/AAA contrast compliance in both themes
+- Screen reader announcements on theme change
+
+### Files Involved
+
+| File | Role |
+|------|------|
+| `src/styles/design-tokens.css` | Single source of truth for all color tokens |
+| `src/components/ThemeToggle.astro` | Toggle button component (sun/moon icons) |
+| `src/layouts/BaseLayout.astro` | Inline blocking script that prevents FOUC |
+| `src/styles/global.css` | Component classes that consume tokens |
+| `tailwind.config.mjs` | `dark:` variant configuration |
+
+---
+
+## 2. How Theme Selection Works (User Guide)
+
+### Automatic Detection
+
+When you first visit the site, the theme is set automatically based on your operating system or browser preference:
+
+- **macOS**: System Preferences → Appearance → Dark/Light
+- **Windows**: Settings → Personalization → Colors → Choose your color
+- **Android/iOS**: Display settings → Dark mode
+
+No action needed — the site matches your system setting out of the box.
+
+### Manual Toggle
+
+A **sun/moon icon button** in the navigation header lets you manually switch themes at any time:
+
+- **Moon icon** (shown in light mode) → click to enable dark mode
+- **Sun icon** (shown in dark mode) → click to return to light mode
+
+Your choice is **saved in your browser** (via `localStorage`) and will persist across page navigations and browser restarts on the same device.
+
+### Priority Order
+
+```
+1. Manual user choice (localStorage)   ← highest priority
+2. OS/browser system preference
+3. Light mode fallback                  ← default
+```
+
+### Resetting to System Default
+
+To go back to automatic system-based theming, clear your browser's site data for this domain:
+
+- **Chrome**: DevTools → Application → Storage → Clear site data
+- **Firefox**: DevTools → Storage → Local Storage → delete the `theme` key
+- **Safari**: Develop → Website Data → remove site entry
+
+---
+
+## 3. Architecture & Implementation
+
+### FOUC Prevention (Blocking Inline Script)
+
+The most critical piece — lives in `BaseLayout.astro` inside `<head>`, runs synchronously before any CSS or HTML renders:
+
+```html
+<head>
+  <script>
+    // Runs BEFORE page paint — prevents flash of wrong theme
+    (function() {
+      try {
+        const stored = localStorage.getItem('theme');
+        if (stored === 'dark' || (!stored && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
+          document.documentElement.classList.add('dark');
+        }
+      } catch(e) {}
+    })();
+  </script>
+  <!-- CSS loads here, already knowing which theme class is on <html> -->
+</head>
+```
+
+**Why inline?** An external script would require a round-trip to the server, causing a visible flash. The inline IIFE runs synchronously as the browser parses the HTML.
+
+### CSS Custom Properties (Semantic Tokens)
+
+Theme switching works entirely via CSS custom properties defined in `src/styles/design-tokens.css`. No JavaScript re-renders required.
+
+```css
+/* Light mode (default) */
+:root {
+  --color-surface: #f8fafc;
+  --color-text-primary: #1e293b;
+  --color-primary: #0891b2;  /* cyan */
+}
+
+/* Dark mode override — applied when html.dark exists */
+html.dark {
+  --color-surface: #0f172a;
+  --color-text-primary: #f1f5f9;
+  --color-primary: #22d3ee;  /* brighter cyan for dark bg */
+}
+```
+
+Components use semantic tokens, never raw color values:
+
+```css
+/* ✅ Correct — adapts to theme automatically */
+.card { background: var(--color-surface-raised); }
+
+/* ❌ Wrong — hardcoded, breaks in dark mode */
+.card { background: #ffffff; }
+```
+
+### Tailwind Dark Variant
+
+Tailwind classes with the `dark:` prefix apply when `html.dark` is present:
+
+```html
+<!-- Text is dark on light bg, light on dark bg -->
+<p class="text-secondary-700 dark:text-secondary-300">Content</p>
+
+<!-- Card adapts its background -->
+<div class="bg-white dark:bg-secondary-800 rounded-lg p-6">...</div>
+```
+
+The `dark:` variant is configured in `tailwind.config.mjs`:
+
+```javascript
+// tailwind.config.mjs
+export default {
+  darkMode: 'class',  // uses html.dark class (not media query)
+  // ...
+}
+```
+
+### ThemeToggle Component
+
+`src/components/ThemeToggle.astro` implements the interactive button.
+
+Key behaviors:
+
+1. **Multiple instances** — uses `data-theme-toggle` attribute + `querySelectorAll` to support both desktop and mobile nav toggles staying in sync
+2. **ARIA switch role** — `role="switch"` with `aria-checked` updated on each toggle
+3. **Live region** — `[data-theme-live]` announces "Dark mode enabled" / "Light mode enabled" to screen readers without interrupting reading flow
+4. **System preference listener** — `matchMedia.addEventListener('change')` updates theme automatically when OS preference changes (only if no manual override stored)
+5. **Theme-color meta** — updates `<meta name="theme-color">` so browser chrome (address bar) matches the theme
+
+### Theme State Machine
+
+```
+Initial load
+  │
+  ├─ localStorage === 'dark'  → apply dark
+  ├─ localStorage === 'light' → apply light
+  ├─ no localStorage + system dark → apply dark
+  └─ no localStorage + system light → apply light (default)
+
+User clicks toggle
+  │
+  ├─ add/remove html.dark class
+  ├─ save 'dark'/'light' to localStorage
+  ├─ update aria-checked on all [data-theme-toggle] buttons
+  ├─ update aria-label on all buttons
+  ├─ announce to [data-theme-live] live regions
+  └─ update all <meta name="theme-color"> tags
+
+OS preference changes (no localStorage)
+  │
+  ├─ toggle html.dark class
+  ├─ update all [data-theme-toggle] aria-label/aria-checked
+  └─ update <meta name="theme-color">
+```
+
+---
+
+## 4. Design Tokens Reference
+
+All tokens live in `src/styles/design-tokens.css`. The file follows a two-layer approach:
+
+1. **Primitive palette** (`--palette-*`) — Raw color scale values. Not used directly in components.
+2. **Semantic tokens** (`--color-*`) — Map primitives to intent. Use these in components.
+
+### Semantic Token Groups
+
+#### Surfaces (backgrounds)
+
+| Token | Light | Dark | Use Case |
+|-------|-------|------|----------|
+| `--color-surface` | `#f8fafc` | `#0f172a` | Page background |
+| `--color-surface-alt` | `#f1f5f9` | `#1e293b` | Subtle variant |
+| `--color-surface-raised` | `#ffffff` | `#1e293b` | Cards, modals |
+| `--color-surface-inset` | `#f1f5f9` | `#0f172a` | Inputs, code blocks |
+| `--color-surface-sunken` | `#e2e8f0` | `#080f1a` | Deeply inset areas |
+
+#### Text
+
+| Token | Light | Dark | WCAG |
+|-------|-------|------|------|
+| `--color-text-primary` | `#1e293b` | `#f1f5f9` | AAA (14.7:1 / 14.3:1) |
+| `--color-text-secondary` | `#475569` | `#cbd5e1` | AAA (6.6:1 / 9.2:1) |
+| `--color-text-muted` | `#64748b` | `#94a3b8` | AA (4.6:1 / 5.4:1) |
+| `--color-text-disabled` | `#94a3b8` | `#475569` | Decorative only |
+| `--color-text-inverse` | `#ffffff` | `#0f172a` | Text on opposite surface |
+| `--color-text-link` | `#0e7490` | `#22d3ee` | Interactive links |
+
+#### Brand / Primary (Cyan)
+
+| Token | Light | Dark |
+|-------|-------|------|
+| `--color-primary` | `#0891b2` | `#22d3ee` |
+| `--color-primary-dark` | `#0e7490` | `#67e8f9` |
+| `--color-primary-light` | `#22d3ee` | `#67e8f9` |
+| `--color-primary-subtle` | `#ecfeff` | `rgba(8,145,178,0.12)` |
+
+#### Borders
+
+| Token | Light | Dark |
+|-------|-------|------|
+| `--color-border` | `#e2e8f0` | `#334155` |
+| `--color-border-strong` | `#cbd5e1` | `#475569` |
+| `--color-border-focus` | `#22d3ee` | `#22d3ee` |
+
+#### Status Colors
+
+All status tokens follow the same pattern for both themes:
+
+```css
+--color-{status}           /* base */
+--color-{status}-text      /* text on light/dark surface */
+--color-{status}-subtle    /* very light/transparent background */
+--color-{status}-border    /* border color */
+```
+
+Statuses: `success`, `warning`, `error`, `info`
+
+### Component Shorthand Tokens
+
+Convenience aliases that keep component classes concise:
+
+```css
+--btn-primary-bg      /* button background */
+--btn-primary-text    /* button label */
+--btn-primary-hover   /* button hover state */
+--input-bg            /* form input background */
+--input-border        /* form input border */
+--card-bg             /* card background */
+--card-border         /* card border */
+--nav-bg              /* header/nav background */
+--nav-text            /* nav link text */
+```
+
+---
+
+## 5. Developer Guide: Adding Theme Support to New Components
+
+### Step 1: Use Semantic Tokens, Not Raw Colors
+
+```css
+/* ❌ Hardcoded — breaks in dark mode */
+.my-component {
+  background: #ffffff;
+  color: #1e293b;
+  border: 1px solid #e2e8f0;
+}
+
+/* ✅ Semantic tokens — adapts automatically */
+.my-component {
+  background: var(--color-surface-raised);
+  color: var(--color-text-primary);
+  border: 1px solid var(--color-border);
+}
+```
+
+### Step 2: Use Tailwind Dark Variants for Utility Classes
+
+```html
+<!-- ❌ Light-only -->
+<div class="bg-white text-slate-700 border-slate-200">
+
+<!-- ✅ Both themes -->
+<div class="bg-white dark:bg-secondary-800 text-secondary-700 dark:text-secondary-300 border-secondary-200 dark:border-secondary-700">
+```
+
+### Step 3: Test Icon and SVG Colors
+
+Icons using `currentColor` inherit from their parent's `color` property — they adapt automatically. Hardcoded `fill` or `stroke` values need dark variants:
+
+```html
+<!-- ✅ Inherits theme color via currentColor -->
+<svg class="text-primary dark:text-primary-400" fill="none" stroke="currentColor">
+
+<!-- ❌ Hardcoded fill — won't adapt -->
+<svg fill="#0891b2">
+```
+
+### Step 4: Handle Gradients and Decorative Backgrounds
+
+Hero sections use dark backgrounds that look fine in both themes. For sections that change between light/dark:
+
+```html
+<!-- Section that adapts -->
+<section class="bg-secondary-50 dark:bg-secondary-900 py-24">
+
+<!-- Hero — dark in both themes by design (uses its own gradient) -->
+<section class="bg-hero-dark py-32">
+```
+
+### Step 5: Forms — Use Token-Based Classes
+
+Form elements already have full dark-mode support via the `form-input` and `form-label` classes defined in `global.css`:
+
+```html
+<!-- These automatically adapt to both themes -->
+<label class="form-label" for="name">Name</label>
+<input class="form-input" id="name" type="text" />
+<span class="form-error">Required</span>
+```
+
+If you write a custom form element, mirror the token usage from `global.css`.
+
+### Step 6: New Astro Component Template
+
+```astro
+---
+// src/components/MyComponent.astro
+interface Props {
+  title: string;
+  variant?: 'default' | 'accent';
+}
+const { title, variant = 'default' } = Astro.props;
+---
+
+<div class:list={[
+  'rounded-lg p-6 border transition-colors duration-200',
+  'bg-white dark:bg-secondary-800',
+  'border-secondary-200 dark:border-secondary-700',
+  'text-secondary-700 dark:text-secondary-300',
+  variant === 'accent' && 'border-l-4 border-l-primary dark:border-l-primary-400'
+]}>
+  <h3 class="font-semibold text-secondary-800 dark:text-secondary-100">
+    {title}
+  </h3>
+  <slot />
+</div>
+
+<style>
+  /* Use CSS custom properties for values not expressible in Tailwind */
+  div {
+    box-shadow: var(--card-shadow);
+  }
+</style>
+```
+
+### Step 7: Verify Contrast
+
+Before shipping a new component, verify text contrast in both themes:
+
+**Tools:**
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- Chrome DevTools → Elements → Computed → contrast ratio badge
+- Lighthouse accessibility audit
+
+**Minimum requirements:**
+- Body text: **4.5:1** (AA)
+- Large text (18px+ / 14px+ bold): **3:1** (AA)
+- Target: **7:1** (AAA) for critical text
+
+All semantic text tokens in this design system already meet AA or AAA — use them and you're covered.
+
+---
+
+## 6. Maintaining Theme Consistency
+
+### The Golden Rules
+
+1. **Never use raw hex colors in components** — always use `var(--color-*)` or Tailwind semantic classes
+2. **Always add `dark:` variants** when using Tailwind utility classes for colors
+3. **Test in both themes** before committing new UI
+4. **Use the existing token names** — don't create new tokens unless there's a genuine gap
+
+### Checking for Theme Consistency Issues
+
+Quick visual review process:
+
+1. Open the site in a browser
+2. Toggle to dark mode using the header button
+3. Navigate all pages looking for:
+   - White text on white background (contrast failure)
+   - Very dark text on dark background (contrast failure)
+   - Colorful decorative elements that disappeared (hidden in dark)
+   - Form inputs that look broken
+4. Repeat with `prefers-reduced-motion` enabled in DevTools
+
+### Adding New Colors to the Token System
+
+1. Add the primitive to `src/styles/design-tokens.css` in the `:root` block:
+   ```css
+   --palette-brand-new-500: #ff6b6b;
+   ```
+
+2. Add the semantic token for both light and dark modes:
+   ```css
+   :root {
+     --color-brand-new: var(--palette-brand-new-500);
+   }
+   html.dark {
+     --color-brand-new: var(--palette-brand-new-400); /* adjust for dark bg */
+   }
+   ```
+
+3. Extend `tailwind.config.mjs` if you need Tailwind utility class support:
+   ```javascript
+   colors: {
+     'brand-new': {
+       400: '#ff8e8e',
+       500: '#ff6b6b',
+     }
+   }
+   ```
+
+4. Verify contrast in both themes before using.
+
+### Don't Repeat Design Token Values
+
+If you find yourself writing the same color value in multiple places, extract it to a token. Tokens are the single source of truth — changing a token value updates every component that uses it.
+
+---
+
+## 7. Troubleshooting Guide
+
+### Issue: Flash of wrong theme on page load (FOUC)
+
+**Symptoms**: Page briefly shows light mode before switching to dark (or vice versa).
+
+**Cause**: The inline blocking script in `BaseLayout.astro` is missing, disabled, or placed after CSS.
+
+**Fix**: Ensure the theme detection script is the **first** `<script>` tag in `<head>`, before any `<link>` stylesheet tags. It must be synchronous (no `defer`, no `async`).
+
+```html
+<head>
+  <!-- ✅ Script BEFORE stylesheets -->
+  <script>/* theme detection */</script>
+  <link rel="stylesheet" href="..." />
+</head>
+```
+
+---
+
+### Issue: Theme toggle button doesn't respond
+
+**Symptoms**: Clicking the sun/moon icon has no effect.
+
+**Diagnosis steps**:
+1. Open browser DevTools → Console. Look for JavaScript errors.
+2. Check that `[data-theme-toggle]` attribute exists on the button element.
+3. Confirm `initThemeToggles()` ran — add `console.log` after the function call.
+
+**Common causes**:
+- The button HTML was modified and `data-theme-toggle` attribute was removed
+- A JavaScript error elsewhere in `<script>` blocks prevented the file from executing
+- The component was added to a page that blocks inline scripts via CSP
+
+---
+
+### Issue: Theme preference not persisting across page loads
+
+**Symptoms**: Theme resets to system default on every page load.
+
+**Cause**: `localStorage` is unavailable (private browsing) or the key is being cleared.
+
+**Fix**: This is expected behavior in private/incognito mode. In regular browsing, check:
+```javascript
+// In browser console:
+localStorage.getItem('theme'); // should return 'dark' or 'light'
+```
+
+If it returns `null`, the write is failing silently. Check the `try/catch` around `localStorage.setItem` in `ThemeToggle.astro`.
+
+---
+
+### Issue: Dark mode colors look washed out or have poor contrast
+
+**Symptoms**: Text is hard to read in dark mode.
+
+**Cause**: Component is using hardcoded light-mode colors or Tailwind classes without `dark:` variants.
+
+**Diagnosis**:
+1. Inspect the element in DevTools
+2. Look for `color`, `background-color`, or `border-color` values that are **light** (near `#fff`) without `dark:` variants
+3. Search the component file for raw hex values like `#ffffff` or `white`
+
+**Fix**: Replace hardcoded values with semantic tokens or add `dark:` variants.
+
+---
+
+### Issue: Component looks correct in light mode but invisible in dark mode
+
+**Symptoms**: A card, badge, or section disappears or merges into the background in dark mode.
+
+**Common cause**: Background and text colors both resolving to dark values.
+
+**Example**:
+```html
+<!-- Both bg and text are dark — text invisible in dark mode -->
+<span class="bg-secondary-100 text-secondary-700">
+  <!-- dark:bg-secondary-100 is still nearly white, but there's no dark:text override -->
+</span>
+```
+
+**Fix**: Ensure both background and text have explicit `dark:` variants:
+```html
+<span class="bg-secondary-100 dark:bg-secondary-800 text-secondary-700 dark:text-secondary-200">
+```
+
+---
+
+### Issue: Icon colors not adapting to theme
+
+**Symptoms**: SVG icons remain the same color in both themes.
+
+**Cause**: Icon has a hardcoded `fill` or `stroke` attribute.
+
+**Fix**: Use `currentColor` and set color via Tailwind:
+```html
+<svg class="text-primary-600 dark:text-primary-400" fill="currentColor">
+  <path .../>
+</svg>
+```
+
+---
+
+### Issue: System preference change not detected
+
+**Symptoms**: Toggling OS dark mode doesn't update the site (only when no manual override).
+
+**Cause**: The `matchMedia` change listener in `ThemeToggle.astro` is not attached.
+
+**Check**: In browser console:
+```javascript
+window.matchMedia('(prefers-color-scheme: dark)').matches
+// toggle OS theme and check again
+```
+
+If the value changes but the site doesn't update, verify the event listener in `ThemeToggle.astro` is being registered (it may have errored before reaching that line).
+
+---
+
+### Issue: Screen reader doesn't announce theme changes
+
+**Symptoms**: Keyboard users toggle the theme but hear no announcement.
+
+**Cause**: The `[data-theme-live]` `<span role="status" aria-live="polite">` element is missing from the DOM, or its text content isn't being updated.
+
+**Fix**: Ensure `ThemeToggle.astro` is rendering the live region element, and that `announceThemeChange()` is calling `querySelectorAll('[data-theme-live]')` (not `querySelector`).
+
+---
+
+### Issue: Browser chrome (address bar) color doesn't match theme
+
+**Symptoms**: The browser's native UI (address bar, tab bar on mobile) stays one color regardless of theme.
+
+**Cause**: The `<meta name="theme-color">` tag isn't being updated by `applyTheme()`.
+
+**Check**: In browser console after toggling:
+```javascript
+document.querySelectorAll('meta[name="theme-color"]');
+// Check the content attribute value
+```
+
+The `applyTheme()` function should update all `meta[name="theme-color"]` elements to `#0f172a` (dark) or `#0891b2` (light).
+
+---
+
+## 8. Accessibility & WCAG Compliance
+
+### Contrast Ratios
+
+All text tokens meet **WCAG 2.1 AA** at minimum. Most meet **AAA**.
+
+| Token | Light Ratio | Dark Ratio | Level |
+|-------|-------------|------------|-------|
+| `--color-text-primary` | 14.7:1 | 14.3:1 | AAA |
+| `--color-text-secondary` | 6.6:1 | 9.2:1 | AAA |
+| `--color-text-muted` | 4.6:1 | 5.4:1 | AA |
+| Primary brand color | 4.5:1 | 9.1:1 | AA/AAA |
+| Accent (amber) | 3.0:1 | 11.5:1 | AA/AAA |
+
+### ARIA Implementation
+
+The theme toggle uses `role="switch"` (semantically correct for on/off controls) with:
+
+- `aria-checked="false"` in light mode, `"true"` in dark mode
+- `aria-label` updated on each toggle ("Switch to dark mode" / "Switch to light mode")
+- `aria-hidden="true"` on decorative SVG icons
+- `sr-only` live region for screen reader announcements
+- Visible focus ring (`focus:ring-2`) for keyboard navigation
+
+### Reduced Motion
+
+All theme transition animations respect `prefers-reduced-motion: reduce`:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .theme-toggle .sun-icon,
+  .theme-toggle .moon-icon {
+    transition: none !important;
+  }
+}
+```
+
+The icon swap still occurs — only the CSS transition animation is suppressed.
+
+---
+
+## 9. Performance Notes
+
+### Theme Initialization Cost
+
+The blocking inline script adds ~0.1ms to initial HTML parse time. This is negligible compared to a FOUC (visible flash), which would negatively impact Cumulative Layout Shift (CLS) and user experience.
+
+### CSS Custom Properties
+
+CSS custom properties are resolved at paint time by the browser. Having two sets of tokens (`:root` and `html.dark`) doesn't duplicate CSS rules — the same property names are used, just with different values. This is a standard, well-optimized browser pattern.
+
+### No JavaScript Re-renders
+
+Theme switching updates a single class on `<html>`, which causes a CSS repaint. There is no JavaScript component tree re-render. The entire site can theme-switch in a single frame.
+
+### localStorage Access
+
+The `localStorage.getItem('theme')` call in the blocking script is synchronous and fast (~0.01ms). It's wrapped in a `try/catch` to handle private browsing mode without errors.
+
+### Bundle Impact
+
+The theme system adds:
+- `design-tokens.css`: ~8KB (unminified), ~3KB gzipped
+- `ThemeToggle.astro` inline script: ~1.5KB
+- BaseLayout blocking script: ~200 bytes
+
+Total theme system overhead: **~5KB gzipped** — minimal.
+
+---
+
+*Generated by documentation-writer agent on 2026-03-21. Update this guide when making changes to the theme system.*
@@ -1,6 +1,6 @@
 ---
 role: documentation-writer
-last_updated: 2026-03-21T09:55:30.042855+00:00
+last_updated: 2026-03-21T13:57:12.151614+00:00
 ---

 # Tools — documentation-writer
@@ -1,7 +1,7 @@
 ---
 user: Unknown
 project: Company Site
-last_updated: 2026-03-21T09:55:30.043339+00:00
+last_updated: 2026-03-21T13:57:12.152459+00:00
 ---

 # User Context — Company Site