Files
cv/docs/design/specs/v3/spec-v3-theme-switch.md
T

331 lines
9.5 KiB
Markdown
Raw Normal View History

# Specification — v3 Theme Switch Fix
> **Document:** `spec-v3-theme-switch.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P1
> **Estimate:** ~1 hour
---
## Problem
### 1. Unintuitive Cycle Order
Current cycle: `dark → light → system → (system opposite) → ...`
When user clicks theme toggle:
- `dark` → `light` (expected)
- `light` → `system` (unexpected — user expects `dark`)
- `system` → opposite of system (e.g., if OS is dark → `light`)
The `system` state is confusing because:
- It doesn't cycle to a fixed next state
- It behaves differently depending on the OS theme
- Users don't understand why clicking once from `light` goes to `system` instead of back to `dark`
**Expected cycle:** `dark → light → dark → light ...`
### 2. Initial Load Behavior
Current: When no stored theme exists, defaults to `'system'` (stored as `'system'` in localStorage).
**Expected:**
1. Check for stored theme in localStorage
2. If stored theme exists → use it
3. If no stored theme → detect system theme (`prefers-color-scheme`)
4. If system theme detection available → use it
5. If system theme detection unavailable (older browser) → fallback to `dark`
6. Store the resolved theme (`dark` or `light`) on first load — do NOT store `'system'`
**Why remove `'system'` from cycle?**
- The portfolio is a personal engineering showcase, not a utility app
- Users who care about system preference can set their OS theme
- Explicit `dark`/`light` choices are clearer and more predictable
- Reduces cognitive load: 2 states instead of 3
---
## Goal
1. Fix cycle to simple `dark → light → dark` (remove `system` state)
2. Improve initial load: detect system theme, fallback to dark
3. Store resolved theme (not `'system'`) on first visit
---
## Current Implementation
**File:** `src/hooks/useTheme.tsx`
```typescript
import { createContext, useContext, useEffect, useState, useCallback } from 'react'
type Theme = 'dark' | 'light' | 'system'
interface ThemeContextValue {
theme: Theme
resolvedTheme: 'dark' | 'light'
setTheme: (theme: Theme) => void
cycleTheme: () => void
}
const ThemeContext = createContext<ThemeContextValue | undefined>(undefined)
const STORAGE_KEY = 'portfolio-theme'
function getSystemTheme(): 'dark' | 'light' {
return window.matchMedia('(prefers-color-scheme: light)').matches ? 'dark' : 'light'
}
function getStoredTheme(): Theme {
try {
const stored = localStorage.getItem(STORAGE_KEY)
if (stored === 'dark' || stored === 'light' || stored === 'system') {
return stored
}
} catch {
// localStorage unavailable
}
return 'system'
}
function resolveTheme(theme: Theme): 'dark' | 'light' {
return theme === 'system' ? getSystemTheme() : theme
}
export function ThemeProvider({ children }: { children: React.ReactNode }) {
const [theme, setThemeState] = useState<Theme>(getStoredTheme)
const resolvedTheme = resolveTheme(theme)
useEffect(() => {
document.documentElement.setAttribute('data-theme', resolvedTheme)
try {
localStorage.setItem(STORAGE_KEY, theme)
} catch {
// localStorage unavailable
}
}, [resolvedTheme, theme])
const setTheme = useCallback((newTheme: Theme) => {
setThemeState(newTheme)
}, [])
const cycleTheme = useCallback(() => {
setThemeState((prev) => {
if (prev === 'system') {
return getSystemTheme() === 'dark' ? 'light' : 'dark'
}
if (prev === 'dark') return 'light'
if (prev === 'light') return 'system'
return 'dark'
})
}, [])
return (
<ThemeContext.Provider value={{ theme, resolvedTheme, setTheme, cycleTheme }}>
{children}
</ThemeContext.Provider>
)
}
export function useTheme() {
const context = useContext(ThemeContext)
if (!context) {
throw new Error('useTheme must be used within ThemeProvider')
}
return context
}
```
---
## Implementation
### Step 1: Change Theme Type
**Before:**
```typescript
type Theme = 'dark' | 'light' | 'system'
```
**After:**
```typescript
type Theme = 'dark' | 'light'
```
### Step 2: Replace getStoredTheme with getInitialTheme
**Before:**
```typescript
function getStoredTheme(): Theme {
try {
const stored = localStorage.getItem(STORAGE_KEY)
if (stored === 'dark' || stored === 'light' || stored === 'system') {
return stored
}
} catch {
// localStorage unavailable
}
return 'system'
}
```
**After:**
```typescript
function getInitialTheme(): 'dark' | 'light' {
try {
const stored = localStorage.getItem(STORAGE_KEY)
if (stored === 'dark' || stored === 'light') {
return stored
}
} catch {
// localStorage unavailable
}
const prefersLight = window.matchMedia('(prefers-color-scheme: light)').matches
return prefersLight ? 'light' : 'dark'
}
```
**Behavior:**
- If localStorage has `'dark'` or `'light'` → use it
- If localStorage has `'system'` (legacy) → treat as no stored value, fall through
- If localStorage unavailable or empty → detect system theme
- If system detection available → use it (`dark` or `light`)
- If system detection unavailable → fallback to `'dark'`
### Step 3: Remove getSystemTheme and simplify resolveTheme
**Before:**
```typescript
function getSystemTheme(): 'dark' | 'light' {
return window.matchMedia('(prefers-color-scheme: light)').matches ? 'dark' : 'light'
}
function resolveTheme(theme: Theme): 'dark' | 'light' {
return theme === 'system' ? getSystemTheme() : theme
}
```
**After:**
```typescript
// getSystemTheme removed — no longer needed
function resolveTheme(theme: Theme): 'dark' | 'light' {
return theme
}
```
### Step 4: Update ThemeProvider
**Before:**
```typescript
export function ThemeProvider({ children }: { children: React.ReactNode }) {
const [theme, setThemeState] = useState<Theme>(getStoredTheme)
const resolvedTheme = resolveTheme(theme)
useEffect(() => {
document.documentElement.setAttribute('data-theme', resolvedTheme)
try {
localStorage.setItem(STORAGE_KEY, theme)
} catch {
// localStorage unavailable
}
}, [resolvedTheme, theme])
const setTheme = useCallback((newTheme: Theme) => {
setThemeState(newTheme)
}, [])
const cycleTheme = useCallback(() => {
setThemeState((prev) => {
if (prev === 'system') {
return getSystemTheme() === 'dark' ? 'light' : 'dark'
}
if (prev === 'dark') return 'light'
if (prev === 'light') return 'system'
return 'dark'
})
}, [])
return (
<ThemeContext.Provider value={{ theme, resolvedTheme, setTheme, cycleTheme }}>
{children}
</ThemeContext.Provider>
)
}
```
**After:**
```typescript
export function ThemeProvider({ children }: { children: React.ReactNode }) {
const [theme, setThemeState] = useState<Theme>(getInitialTheme)
const resolvedTheme = resolveTheme(theme)
useEffect(() => {
document.documentElement.setAttribute('data-theme', resolvedTheme)
try {
localStorage.setItem(STORAGE_KEY, theme)
} catch {
// localStorage unavailable
}
}, [resolvedTheme, theme])
const setTheme = useCallback((newTheme: Theme) => {
setThemeState(newTheme)
}, [])
const cycleTheme = useCallback(() => {
setThemeState((prev) => (prev === 'dark' ? 'light' : 'dark'))
}, [])
return (
<ThemeContext.Provider value={{ theme, resolvedTheme, setTheme, cycleTheme }}>
{children}
</ThemeContext.Provider>
)
}
```
### Step 5: Verify No Other Consumers Need Changes
Check all files that import `useTheme` or reference the `Theme` type. Consumers, verified with `grep -rn "useTheme" src` on 2026-10-17:
- `src/App.tsx:3` — imports `ThemeProvider` only; calls no hook method
- `src/components/layout/Navigation.tsx:10` — `const { cycleTheme, resolvedTheme } = useTheme()`
- `src/components/layout/ThemePaletteMenu.tsx:13` — `const { palette, setPalette } = useTheme()`, added later by `spec-v3-theme-palette-switch.md`
`src/components/layout/Footer.tsx` does **not** import `useTheme` and has no theme control — earlier revisions of this section claimed it did; corrected 2026-10-17.
All consumers read the resolved values directly and nothing pattern-matches on `'system'`, so no consumer needed changes when `system` was removed.
---
## Files Changed
| File | Change |
|------|--------|
| `src/hooks/useTheme.tsx` | Remove `system` from type, replace `getStoredTheme` with `getInitialTheme`, simplify `resolveTheme`, remove `getSystemTheme`, fix `cycleTheme` |
---
## Acceptance
- [ ] Theme type is `'dark' | 'light'` (no `'system'`)
- [ ] Cycle order: `dark → light → dark → light ...`
- [ ] First load with no stored theme → uses system theme (dark or light)
- [ ] First load with no system detection → falls back to `dark`
- [ ] Stored theme is always `'dark'` or `'light'` (never `'system'`)
- [ ] Existing stored `'system'` values handled gracefully (treated as no stored value)
- [ ] Theme toggle UI shows only 2 states
- [ ] No other files need changes (consumers verified)
- [ ] Linter (`pnpm lint`) passes
- [ ] Build (`pnpm build`) passes
---
## Open Questions
1. **Migration:** Should we migrate existing `'system'` stored values to the detected system theme, or just treat them as "no stored value"?
- **Decision:** Treat as "no stored value" (Option A) — user's next toggle will set explicit choice.
2. **System sync:** If we remove `system` state, will users miss the ability to auto-follow OS theme changes?
- **Decision:** No (Option A) — portfolio is a personal showcase, 2-state cycle is sufficient. Users can set OS theme and clear localStorage if they want auto-follow.