Files
cv/docs/design/specs/v3/spec-v3-theme-switch.md
T
dong.nguyen f2c920d6ad feat(theme): red/blue palette switch with a nav + mobile-sheet color menu
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.
2026-10-17 00:32:49 +07:00

9.5 KiB

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

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 (dark or light)
  • 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 — 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.