mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
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.
332 lines
9.5 KiB
Markdown
332 lines
9.5 KiB
Markdown
# 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.
|