Second axis on <html>: data-palette (Portfolio type Palette = 'red' | 'blue', localStorage key portfolio-palette, default red so existing visitors see no change). Both attributes are written before paint by the index.html init script and re-written during render in useTheme. - src/types/index.ts, src/data/palettes.ts: Palette + paletteIds/paletteMeta (Record<Language, string>, indexed inline - no lookup helper) - src/hooks/useTheme.tsx: palette state, data-palette write during render, persistence, setPalette; no cyclePalette - src/components/layout/ThemePaletteMenu.tsx: disclosure semantics (aria-expanded/aria-controls, aria-current), variant nav|sheet, panel ids derived from variant, Escape closes and refocuses the trigger - src/components/layout/Navigation.tsx: nav instance in .nav-actions, sheet instance after the mobile link list, remounted closed via key - src/index.css: blue dark/light blocks (0,3,0 selectors) + preview tokens; red --accent-soft/--accent-glow re-derived from the accent in force - src/App.css: .nav-palette* block (token-only), nav hidden at 1024px, sheet options inline - specs: palette-switch spec v0.3.0 with the implementation record; corrected the false AA claim in spec-v3-theme-colors.md (3.90:1, not ~4.8), the composite values in spec-v3-theme-palette-gasatrya.md, the Footer consumer claim in spec-v3-theme-switch.md; AGENTS.md Theming section documents the palette axis Verified: tsc exit 0; vite build green (CSS 31.80 kB); oxlint unchanged at 11 errors / 9 warnings; hex gate over src/App.css 0 matches; inline type styles 0; contrast minima 4.96 / 4.63 / 4.81 / 4.64 with zero AA failures.
9.5 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 the Theme type. Consumers, verified with grep -rn "useTheme" src on 2026-10-17:
src/App.tsx:3— importsThemeProvideronly; calls no hook methodsrc/components/layout/Navigation.tsx:10—const { cycleTheme, resolvedTheme } = useTheme()src/components/layout/ThemePaletteMenu.tsx:13—const { palette, setPalette } = useTheme(), added later byspec-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
- 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.