# Theme Visual Guide — WorkRoot IT Solutions
## Dark / Light Mode Preview & Comparison Reference
**Author:** frontend-specialist
**Date:** 2026-03-21
**Status:** Complete
**Related:** [THEME_SYSTEM_ARCHITECTURE.md](./THEME_SYSTEM_ARCHITECTURE.md)
---
## Table of Contents
1. [Overview](#1-overview)
2. [Color Comparison: Light vs Dark](#2-color-comparison-light-vs-dark)
3. [Page-by-Page Visual Reference](#3-page-by-page-visual-reference)
- [Home Page](#31-home-page)
- [About Page](#32-about-page)
- [Services Page](#33-services-page)
- [Portfolio Page](#34-portfolio-page)
- [Contact Page](#35-contact-page)
4. [Component Showcase](#4-component-showcase)
5. [Screenshot Generation](#5-screenshot-generation)
6. [Image Optimization Guide](#6-image-optimization-guide)
7. [Usage in Documentation](#7-usage-in-documentation)
---
## 1. Overview
The WorkRoot IT Solutions website supports full dark/light theme switching with:
- **Zero flash on load** (FOUC prevention via inline blocking script)
- **System preference detection** (`prefers-color-scheme`)
- **localStorage persistence** across page navigations
- **Smooth 200ms transitions** after first user interaction
- **WCAG 2.1 AAA compliance** in both modes
### Theme Toggle Location
- **Desktop:** Header right side, before "Get Started" button
- **Mobile:** Bottom of mobile menu, labeled "Appearance"
---
## 2. Color Comparison: Light vs Dark
### Surface Hierarchy
```
LIGHT MODE DARK MODE
───────────────────────────────── ─────────────────────────────────
Page Background #f8fafc (slate-50) Page Background #0f172a (slate-950)
Card / Panels #ffffff (white) Card / Panels #1e293b (slate-800)
Hover / Nav #f1f5f9 (slate-100) Hover / Nav #334155 (slate-700)
Inputs #e2e8f0 (slate-200) Inputs #0f172a (slate-950)
Deep Inset #e2e8f0 (slate-200) Deep Inset #080f1a (custom)
```
### Text Hierarchy
```
LIGHT MODE DARK MODE
───────────────────────────────── ─────────────────────────────────
Primary Text #1e293b 14.7:1 ✅ Primary Text #f1f5f9 14.3:1 ✅
Secondary Text #475569 6.6:1 ✅ Secondary Text #cbd5e1 9.2:1 ✅
Muted Text #64748b 4.6:1 ✅ Muted Text #94a3b8 5.4:1 ✅
Disabled Text #94a3b8 2.5:1 ⚠️ Disabled Text #475569 2.1:1 ⚠️
Links #0e7490 Links #22d3ee
Link Hover #155e75 Link Hover #67e8f9
```
> ⚠️ `disabled` text is decorative only — used on inactive form fields.
> All contrast ratios measured against respective page background.
### Brand Colors (Consistent Across Themes)
```
Brand Primary (cyan-500) #0891b2 — same in both modes
Brand on Primary #ffffff (light) / #0f172a (dark)
Brand Accent (amber) #f59e0b (light) / #fbbf24 (dark, +1 shade brighter)
```
### Token Quick Reference
| Role | Light Token | Light Hex | Dark Token | Dark Hex |
|-----------------------|---------------------------|-------------|--------------------------|-------------|
| Page background | `--color-surface` | `#f8fafc` | `--color-surface` | `#0f172a` |
| Card background | `--color-surface-raised` | `#ffffff` | `--color-surface-raised` | `#1e293b` |
| Input background | `--color-surface-inset` | `#f1f5f9` | `--color-surface-inset` | `#0f172a` |
| Border default | `--color-border` | `#e2e8f0` | `--color-border` | `#334155` |
| Heading text | `--color-text-primary` | `#1e293b` | `--color-text-primary` | `#f1f5f9` |
| Body text | `--color-text-secondary` | `#475569` | `--color-text-secondary` | `#cbd5e1` |
| Caption text | `--color-text-muted` | `#64748b` | `--color-text-muted` | `#94a3b8` |
| Brand primary | `--color-brand` | `#0891b2` | `--color-brand` | `#22d3ee` |
| Accent | `--color-accent` | `#f59e0b` | `--color-accent` | `#fbbf24` |
---
## 3. Page-by-Page Visual Reference
> Screenshots are generated by the Playwright script at `scripts/capture-theme-screenshots.js`.
> Run `node scripts/capture-theme-screenshots.js` with the dev server active to regenerate.
> Output directory: `.agents/frontend-specialist/screenshots/`
### 3.1 Home Page
**URL:** `/` (index.astro)
#### Light Mode Layout
```
┌─────────────────────────────────────────────────────────────────────┐
│ HEADER [bg: white/slate-50] Logo | Nav | [☀️/🌙] | Get Started │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ HERO SECTION [bg: slate-900 → slate-800 gradient] │
│ ┌─────────────────────────────────┐ ┌─────────────────────────┐ │
│ │ "Accelerate Your Digital │ │ [Dashboard Preview] │ │
│ │ Transformation" │ │ Card with cyan glow │ │
│ │ │ │ │ │
│ │ Subtext in slate-300 │ │ [Metrics badges] │ │
│ │ │ │ │ │
│ │ [Get Started] [View Portfolio] │ └─────────────────────────┘ │
│ │ bg-cyan-500 border-white/40 │ │
│ └─────────────────────────────────┘ │
│ │
│ BENEFITS [bg: white] ◄── Theme-sensitive section │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 🚀 Rapid │ │ 🛡 Secure│ │ 📈 Scale │ │ 💬 24/7 │ │
│ │ card: │ │ card: │ │ card: │ │ card: │ │
│ │ white │ │ white │ │ white │ │ white │ │
│ │ border: │ │ border: │ │ border: │ │ border: │ │
│ │ slate-200│ │ slate-200│ │ slate-200│ │ slate-200│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ SERVICES [bg: slate-50] ◄── Theme-sensitive section │
│ 4x service cards, same border/bg token pattern │
│ │
│ HOW IT WORKS [bg: slate-900 gradient] ◄── Static dark, both modes │
│ │
│ STATS [bg: cyan-600 → cyan-700] ◄── Static brand, both modes │
│ │
│ TESTIMONIALS [bg: white] ◄── Theme-sensitive section │
│ │
│ CTA [bg: slate-900 gradient] ◄── Static dark, both modes │
├─────────────────────────────────────────────────────────────────────┤
│ FOOTER [bg: slate-900] ◄── Static dark, both modes │
└─────────────────────────────────────────────────────────────────────┘
```
#### Dark Mode Differences (Home)
| Section | Light Mode | Dark Mode |
|----------------|------------------------|------------------------------|
| Header | `bg-white/95` | `bg-slate-950/95` |
| Benefits bg | `bg-white` | `bg-slate-800` (surface-raised) |
| Benefits card | `border-slate-200` | `border-slate-700` |
| Services bg | `bg-slate-50` | `bg-slate-950` (surface) |
| Testimonials | `bg-white` | `bg-slate-800` |
| Hero section | No change (static dark)| No change |
| Footer | No change (static dark)| No change |
---
### 3.2 About Page
**URL:** `/about`
#### Light Mode Layout
```
┌─────────────────────────────────────────────────────────────────────┐
│ HEADER [same as Home] │
├─────────────────────────────────────────────────────────────────────┤
│ HERO [bg: slate-900 → slate-800] ◄── Static dark │
│ "About WorkRoot" + 3 stat badges │
│ │
│ TIMELINE [bg: white] ◄── Theme-sensitive │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ [2019]●────────[2021]●────────[2023]●────────[2025]● │ │
│ │ cyan-500 gradient line │ │
│ │ │ │
│ │ Cards: white bg, slate-100 border, cyan-500 dot │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ MISSION & VISION [bg: slate-50] ◄── Theme-sensitive │
│ ┌────────────────────┐ ┌─────────────────────────────────┐ │
│ │ MISSION │ │ VISION │ │
│ │ gradient: │ │ gradient: │ │
│ │ cyan-500→cyan-700 │ │ slate-800→slate-900 │ │
│ │ (static branded) │ │ (static dark) │ │
│ └────────────────────┘ └─────────────────────────────────┘ │
│ │
│ VALUES [bg: white] ◄── Theme-sensitive │
│ 6x value cards: white bg, slate-100 border, hover → cyan gradient │
│ │
│ TEAM [bg: slate-50] ◄── Theme-sensitive │
│ Team member photo cards with gradient reveal overlay │
│ │
│ CTA [bg: cyan-600 → slate-800] ◄── Static branded │
└─────────────────────────────────────────────────────────────────────┘
```
#### Dark Mode Differences (About)
| Section | Light Mode | Dark Mode |
|----------------|------------------------|------------------------------|
| Timeline bg | `bg-white` | `bg-slate-800` |
| Timeline cards | `border-slate-100` | `border-slate-700` |
| Mission/Vision | `bg-slate-50` | `bg-slate-950` |
| Values bg | `bg-white` | `bg-slate-800` |
| Values cards | `border-slate-100` | `border-slate-700` |
| Team bg | `bg-slate-50` | `bg-slate-950` |
---
### 3.3 Services Page
**URL:** `/services`
#### Light Mode Layout
```
┌─────────────────────────────────────────────────────────────────────┐
│ HEADER [same as Home] │
├─────────────────────────────────────────────────────────────────────┤
│ HERO [static dark gradient] │
│ │
│ SERVICES GRID [bg: white] ◄── Theme-sensitive │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Web Development │ │ Mobile Apps │ │ AI / ML │ │
│ │ white bg │ │ white bg │ │ white bg │ │
│ │ slate-200 border│ │ slate-200 bdr │ │ slate-200 bdr │ │
│ │ ┌─────────────┐ │ │ ... │ │ ... │ │
│ │ │ Feature list│ │ │ │ │ │ │
│ │ │ cyan bullets│ │ │ │ │ │ │
│ │ └─────────────┘ │ │ │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ PROCESS [bg: slate-50] ◄── Theme-sensitive │
│ 4-step numbered cards │
│ │
│ TECHNOLOGIES [bg: white] ◄── Theme-sensitive │
│ Logo grid with tech stack badges │
│ │
│ PRICING [bg: slate-50] ◄── Theme-sensitive │
│ 3-tier pricing cards │
│ │
│ CTA [static dark] │
└─────────────────────────────────────────────────────────────────────┘
```
#### Dark Mode Differences (Services)
| Section | Light Mode | Dark Mode |
|-----------------|--------------------|----------------------|
| Services grid | `bg-white` | `bg-slate-800` |
| Service cards | `border-slate-200` | `border-slate-700` |
| Feature bullets | `text-cyan-700` | `text-cyan-400` |
| Process bg | `bg-slate-50` | `bg-slate-950` |
| Tech logos bg | `bg-white` | `bg-slate-800` |
| Pricing bg | `bg-slate-50` | `bg-slate-950` |
| Pricing cards | `border-slate-200` | `border-slate-700` |
---
### 3.4 Portfolio Page
**URL:** `/portfolio`
#### Light Mode Layout
```
┌─────────────────────────────────────────────────────────────────────┐
│ HEADER [same as Home] │
├─────────────────────────────────────────────────────────────────────┤
│ HERO [static dark gradient] │
│ │
│ FILTER BAR [bg: white] ◄── Theme-sensitive │
│ [All] [Web Dev] [Mobile] [AI/ML] [Cloud] │
│ Inactive: slate-100 bg / Active: cyan-500 bg │
│ │
│ PROJECTS GRID [bg: slate-50] ◄── Theme-sensitive │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ [Screenshot] │ │ [Screenshot] │ │ [Screenshot] │ │ │
│ │ │ Project Name │ │ Project Name │ │ Project Name │ │ │
│ │ │ Tech badges │ │ Tech badges │ │ Tech badges │ │ │
│ │ │ slate-200 bd │ │ slate-200 bd │ │ slate-200 bd │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ CASE STUDY MODAL [overlay: slate-950/80] │
│ Full-bleed modal with project details │
│ │
│ CTA [static dark] │
└─────────────────────────────────────────────────────────────────────┘
```
#### Dark Mode Differences (Portfolio)
| Section | Light Mode | Dark Mode |
|-----------------|--------------------|----------------------------|
| Filter bar bg | `bg-white` | `bg-slate-800` |
| Filter inactive | `bg-slate-100` | `bg-slate-700` |
| Filter active | `bg-cyan-500` | `bg-cyan-500` (unchanged) |
| Projects bg | `bg-slate-50` | `bg-slate-950` |
| Project cards | `border-slate-200` | `border-slate-700` |
| Modal bg | `bg-white` | `bg-slate-800` |
| Tech badges | `bg-cyan-50` | `rgba(8,145,178,0.12)` |
---
### 3.5 Contact Page
**URL:** `/contact`
#### Light Mode Layout
```
┌─────────────────────────────────────────────────────────────────────┐
│ HEADER [same as Home] │
├─────────────────────────────────────────────────────────────────────┤
│ HERO [static dark gradient] │
│ │
│ CONTACT FORM + INFO [bg: white] ◄── Theme-sensitive │
│ ┌───────────────────────────────┐ ┌─────────────────────────┐ │
│ │ CONTACT FORM │ │ CONTACT INFO │ │
│ │ ┌─────────────────────────┐ │ │ │ │
│ │ │ Name [input: white bg] │ │ │ 📍 Address │ │
│ │ │ Email [input: white bg] │ │ │ 📞 Phone │ │
│ │ │ Message [textarea] │ │ │ ✉️ Email │ │
│ │ └─────────────────────────┘ │ │ │ │
│ │ [Send Message: cyan-500] │ │ ┌──────────────────────┐ │ │
│ └───────────────────────────────┘ │ │ Business Hours │ │ │
│ │ │ white card │ │ │
│ │ └──────────────────────┘ │ │
│ └─────────────────────────┘ │
│ │
│ FAQ SECTION [bg: slate-50] ◄── Theme-sensitive │
│ Accordion with slate-200 dividers │
│ │
│ MAP / LOCATION [bg: white] ◄── Theme-sensitive │
└─────────────────────────────────────────────────────────────────────┘
```
#### Dark Mode Differences (Contact)
| Section | Light Mode | Dark Mode |
|-----------------|-------------------------|-----------------------------|
| Form section bg | `bg-white` | `bg-slate-800` |
| Input bg | `bg-white` | `bg-slate-950` (surface-inset) |
| Input border | `border-slate-300` | `border-slate-700` |
| Input text | `text-slate-900` | `text-slate-100` |
| Placeholder | `text-slate-400` | `text-slate-500` |
| FAQ bg | `bg-slate-50` | `bg-slate-950` |
| FAQ dividers | `border-slate-200` | `border-slate-700` |
---
## 4. Component Showcase
### ThemeToggle Button
```
LIGHT MODE DARK MODE
───────────────────────────── ─────────────────────────────
┌───────────────┐ ┌───────────────┐
│ 🌙 (moon) │ │ ☀️ (sun) │
│ w-10 h-10 │ │ w-10 h-10 │
│ rounded-lg │ │ rounded-lg │
│ slate-400 │ │ slate-400 │
└───────────────┘ └───────────────┘
• Click → adds html.dark class
• aria-pressed="false" aria-pressed="true"
• Keyboard: Space/Enter toggle
• Focus: cyan-500 ring (2px)
• Transition: opacity + scale (200ms)
```
### Card Component
```
LIGHT MODE DARK MODE
───────────────────────────── ─────────────────────────────
┌──────────────────────────┐ ┌──────────────────────────┐
│ [icon bg: cyan-50] │ │ [icon bg: cyan/12%] │
│ ┌──┐ │ │ ┌──┐ │
│ │ 🔷 │ │ │ │ 🔷 │ │
│ └──┘ │ │ └──┘ │
│ Title slate-900 │ │ Title slate-100 │
│ Desc slate-600 │ │ Desc slate-400 │
│ bg: white │ │ bg: slate-800 │
│ border: slate-200 │ │ border: slate-700 │
│ shadow: 4px/5% opacity │ │ shadow: ring 1px/8% op │
└──────────────────────────┘ └──────────────────────────┘
Hover: border-cyan-500, shadow-lg
```
### Badge Component
```
LIGHT MODE DARK MODE
───────────────────────────── ─────────────────────────────
┌─────────────────┐ ┌─────────────────┐
│ Primary bg: │ │ Primary bg: │
│ cyan-50 │ │ rgba(8,145,178 │
│ text: cyan-700 │ │ /0.12) │
│ │ │ text: cyan-400 │
└─────────────────┘ └─────────────────┘
┌─────────────────┐ ┌─────────────────┐
│ Success bg: │ │ Success bg: │
│ green-50 │ │ rgba(34,197,94 │
│ text: green-700 │ │ /0.12) │
│ │ │ text: green-300 │
└─────────────────┘ └─────────────────┘
```
### Navigation Header
```
LIGHT MODE DARK MODE
────────────────────────────────────── ──────────────────────────────────────
┌──────────────────────────────────────┐ ┌──────────────────────────────────────┐
│ WORKROOT Home About Serv Port Cont │ │ WORKROOT Home About Serv Port Cont │
│ cyan logo slate-600 nav links 🌙⬛ │ │ cyan logo slate-400 nav links ☀️⬛ │
│ │ │ │
│ bg: white/95 + backdrop-blur-md │ │ bg: slate-950/95 + backdrop-blur-md │
│ border-bottom: slate-200/50 │ │ border-bottom: slate-700/50 │
└──────────────────────────────────────┘ └──────────────────────────────────────┘
```
### Form Input
```
LIGHT MODE DARK MODE
───────────────────────────── ─────────────────────────────
┌─────────────────────────┐ ┌─────────────────────────┐
│ Enter your name... │ │ Enter your name... │
│ (slate-400 placeholder)│ │ (slate-500 placeholder)│
│ │ │ │
│ bg: white │ │ bg: slate-950 │
│ border: slate-300 │ │ border: slate-700 │
└─────────────────────────┘ └─────────────────────────┘
── Focus State ──
┌─────────────────────────┐ ┌─────────────────────────┐
│ Typing... │ │ Typing... │
│ │ │ │
│ border: cyan-400 (ring) │ │ border: cyan-400 (ring) │
│ ring: cyan-400/20 │ │ ring: cyan-400/20 │
└─────────────────────────┘ └─────────────────────────┘
```
---
## 5. Screenshot Generation
A Playwright script is provided to auto-generate screenshots in both themes across all pages and viewports.
### Script Location
```
scripts/capture-theme-screenshots.js
```
### Prerequisites
```bash
# Install Playwright (already in devDependencies)
npm install
# Install browser binaries (first time only)
npx playwright install chromium
# Start dev server in another terminal
npm run dev
```
### Running Screenshots
```bash
# Generate all screenshots (both themes, all pages, 3 viewports)
node scripts/capture-theme-screenshots.js
# Output structure:
# .agents/frontend-specialist/screenshots/
# ├── light/
# │ ├── home-desktop.png (1440x900)
# │ ├── home-tablet.png (768x1024)
# │ ├── home-mobile.png (390x844)
# │ ├── about-desktop.png
# │ ├── about-tablet.png
# │ ├── about-mobile.png
# │ ├── services-desktop.png
# │ ├── services-tablet.png
# │ ├── services-mobile.png
# │ ├── portfolio-desktop.png
# │ ├── portfolio-tablet.png
# │ ├── portfolio-mobile.png
# │ ├── contact-desktop.png
# │ ├── contact-tablet.png
# │ └── contact-mobile.png
# └── dark/
# ├── home-desktop.png
# ├── (same structure as light/)
# └── ...
```
### Viewport Specifications
| Name | Width | Height | Device Context |
|---------|-------|--------|---------------------|
| desktop | 1440 | 900 | MacBook Pro 14" |
| tablet | 768 | 1024 | iPad |
| mobile | 390 | 844 | iPhone 14 |
### Full Page vs Viewport
The script captures **full-page screenshots** (scrolled content) by default. For above-the-fold previews only, set `fullPage: false` in the script options.
---
## 6. Image Optimization Guide
### Recommended Formats for Screenshots
| Use Case | Format | Quality | Notes |
|-----------------------------|--------|---------|-----------------------------------|
| Documentation / guides | PNG | — | Lossless, exact colors |
| Web delivery / social media | WebP | 85% | ~30% smaller than PNG |
| JPEG fallback | JPEG | 80% | For browsers without WebP support |
| Thumbnails (< 200px wide) | WebP | 70% | Acceptable quality at small sizes |
### Optimization Commands
```bash
# Batch convert PNG screenshots to WebP (requires cwebp or sharp)
# Using sharp (Node.js):
npx sharp-cli --input ".agents/frontend-specialist/screenshots/**/*.png" \
--output ".agents/frontend-specialist/screenshots/optimized/" \
--format webp --quality 85
# Using ImageMagick (if available):
find .agents/frontend-specialist/screenshots -name "*.png" \
-exec convert {} -quality 85 {}.webp \;
# Using cwebp (Google WebP tools):
for f in .agents/frontend-specialist/screenshots/light/*.png; do
cwebp -q 85 "$f" -o "${f%.png}.webp"
done
```
### Expected File Sizes
| Screenshot Type | PNG (est.) | WebP (est.) | Reduction |
|----------------------|-------------|-------------|-----------|
| Desktop full-page | 800KB–2MB | 200–500KB | ~70% |
| Tablet full-page | 500KB–1.2MB | 130–300KB | ~70% |
| Mobile full-page | 300KB–700KB | 80–180KB | ~70% |
| Desktop viewport | 300–600KB | 80–160KB | ~70% |
### Lazy Loading for Documentation
When embedding screenshots in Markdown/HTML docs:
```html
```
---
## 7. Usage in Documentation
### Embedding in README or Docs
```markdown
## Theme Preview
### Light Mode
### Dark Mode
> Toggle theme using the sun/moon button in the header (desktop)
> or at the bottom of the mobile menu.
```
### Side-by-Side Comparison (HTML)
```html
| Light Mode |
Dark Mode |
 |
 |
```
### Pages That Changed Most Between Themes
| Page | Visual Change Magnitude | Primary Differences |
|------------|-------------------------|---------------------------------|
| Home | High | Benefits + Testimonials sections |
| About | High | Timeline + Values cards |
| Services | Medium | Service cards + pricing |
| Portfolio | Medium | Filter bar + project grid |
| Contact | High | Form inputs (most noticeable) |
### Sections Unchanged Between Themes
These sections use static dark backgrounds and appear identical in both themes:
- Hero sections on all pages (slate-900 gradient)
- "How It Works" process section (Home)
- Stats banner (Home)
- CTA sections
- Footer
---
## Appendix: Quick Cheatsheet
```
LIGHT → DARK MAPPINGS
─────────────────────────────────────────────────────────────
bg-white → bg-slate-800 (surface-raised)
bg-slate-50 → bg-slate-950 (surface)
border-slate-200 → border-slate-700
border-slate-100 → border-slate-700
text-slate-900 → text-slate-100
text-slate-700 → text-slate-300
text-slate-600 → text-slate-400 (text-secondary)
text-slate-400 → text-slate-500 (text-muted)
text-cyan-600 → text-cyan-400 (links)
bg-cyan-50 → rgba(8,145,178,0.12) (brand-subtle)
text-cyan-700 → text-cyan-400 (brand-primary-text)
UNCHANGED:
bg-secondary-900 → (same — hero/dark sections)
bg-primary-500 → (same — buttons)
text-white → (same — on dark/brand backgrounds)
```
---
*Document generated by frontend-specialist — 2026-03-21*
*Related: [THEME_SYSTEM_ARCHITECTURE.md](./THEME_SYSTEM_ARCHITECTURE.md)*
*Documentation: [.agents/documentation-writer/THEME_SYSTEM_GUIDE.md](..documentation-writer/THEME_SYSTEM_GUIDE.md)*
