CompanySite/.agents/frontend-specialist/THEME_VISUAL_GUIDE.md

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

---

Table of Contents

1. Overview
2. Color Comparison: Light vs Dark
3. Page-by-Page Visual Reference
   • Home Page
   • About Page
   • Services Page
   • Portfolio Page
   • Contact Page
4. Component Showcase
5. Screenshot Generation
6. Image Optimization Guide
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

# 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

# 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

# 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:

<!-- Prefer WebP with PNG fallback -->
<picture>
  <source srcset="screenshots/dark/home-desktop.webp" type="image/webp">
  <img src="screenshots/dark/home-desktop.png"
       alt="Home page in dark mode"
       loading="lazy"
       width="1440" height="900">
</picture>

---

7. Usage in Documentation

Embedding in README or Docs

## Theme Preview

### Light Mode
![Home Page Light](./screenshots/light/home-desktop.png)

### Dark Mode
![Home Page Dark](./screenshots/dark/home-desktop.png)

> Toggle theme using the sun/moon button in the header (desktop)
> or at the bottom of the mobile menu.

Side-by-Side Comparison (HTML)

<table>
  <tr>
    <th>Light Mode</th>
    <th>Dark Mode</th>
  </tr>
  <tr>
    <td><img src=".agents/frontend-specialist/screenshots/light/home-desktop.png"
             alt="Home - Light" width="640"></td>
    <td><img src=".agents/frontend-specialist/screenshots/dark/home-desktop.png"
             alt="Home - Dark" width="640"></td>
  </tr>
</table>

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 Documentation: .agents/documentation-writer/THEME_SYSTEM_GUIDE.md