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,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.*