mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
- Remove 'system' from Theme type (now 'dark' | 'light') - Fix cycle to predictable dark -> light -> dark -> light - Replace getStoredTheme with getInitialTheme - Initial load: check localStorage, detect system theme, fallback dark - Simplify resolveTheme (no longer needs system branch) - Remove unused getSystemTheme function - Add spec-v3-theme-switch.md
9.2 KiB
9.2 KiB
Specification — v3 Theme Switch Fix
Document:
spec-v3-theme-switch.mdVersion: 0.1.0 Parent:spec-v2.mdPriority: 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 expectsdark)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
lightgoes tosysteminstead of back todark
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:
- Check for stored theme in localStorage
- If stored theme exists → use it
- If no stored theme → detect system theme (
prefers-color-scheme) - If system theme detection available → use it
- If system theme detection unavailable (older browser) → fallback to
dark - Store the resolved theme (
darkorlight) 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/lightchoices are clearer and more predictable - Reduces cognitive load: 2 states instead of 3
Goal
- Fix cycle to simple
dark → light → dark(removesystemstate) - Improve initial load: detect system theme, fallback to dark
- Store resolved theme (not
'system') on first visit
Current Implementation
File: src/hooks/useTheme.tsx
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:
type Theme = 'dark' | 'light' | 'system'
After:
type Theme = 'dark' | 'light'
Step 2: Replace getStoredTheme with getInitialTheme
Before:
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:
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 (
darkorlight) - If system detection unavailable → fallback to
'dark'
Step 3: Remove getSystemTheme and simplify resolveTheme
Before:
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:
// getSystemTheme removed — no longer needed
function resolveTheme(theme: Theme): 'dark' | 'light' {
return theme
}
Step 4: Update ThemeProvider
Before:
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:
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 Theme type. Current consumers:
src/App.tsx— usesuseTheme().theme,useTheme().resolvedTheme,useTheme().cycleTheme,useTheme().setThemesrc/components/layout/Navigation.tsx— usesuseTheme().theme,useTheme().cycleThemesrc/components/layout/Footer.tsx— usesuseTheme().theme,useTheme().cycleTheme
All consumers only read theme and resolvedTheme values ('dark' | 'light'), no pattern matching on 'system'. No changes needed.
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
- 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.
- System sync: If we remove
systemstate, 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.