diff --git a/AGENTS.md b/AGENTS.md index f922dc4..5353ceb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,11 +49,14 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript ## Theming -- `src/hooks/useTheme.tsx` — `ThemeProvider` + `useTheme` hook -- Simple toggle: `'dark'` ↔ `'light'` (no `system` variant) -- `resolvedTheme` — runtime resolved value (always `'dark'` or `'light'`) -- `data-theme` attribute set on `` during render (before paint) -- Stored in `localStorage` key `portfolio-theme` +- Two independent axes on ``: lightness (`Theme`) and color (`Palette`), both written during render before paint +- `src/hooks/useTheme.tsx` — `ThemeProvider` + `useTheme` hook, carries both axes +- Simple toggle: `'dark'` ↔ `'light'` (no `system` variant); `resolvedTheme` — runtime resolved value (always `'dark'` or `'light'`) +- `data-theme` attribute + `localStorage` key `portfolio-theme` +- `type Palette = 'red' | 'blue'` (`src/types/index.ts`), labels/hints in `src/data/palettes.ts` (`paletteIds`, `paletteMeta`); default `red` +- `data-palette` attribute + `localStorage` key `portfolio-palette`; `index.html`'s init script writes both attributes before paint +- Palette overrides in `src/index.css` are `:root[data-theme='dark'][data-palette='blue']` / `:root[data-theme='light'][data-palette='blue']` (specificity 0,3,0 — they beat the base blocks regardless of order); no blue variant exists in the `prefers-color-scheme` bridge, because the init script always writes `data-palette` +- Picker: `src/components/layout/ThemePaletteMenu.tsx`, mounted twice in `Navigation.tsx` — `variant="nav"` in `.nav-actions` (>1024px) and `variant="sheet"` inside `.mobile-menu` (≤1024px, remounted closed via `key={location.pathname}`) ## Data Layer @@ -68,11 +71,11 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript ``` src/ components/ - layout/ — Layout.tsx, Navigation.tsx, Footer.tsx + layout/ — Layout.tsx, Navigation.tsx, Footer.tsx, ThemePaletteMenu.tsx sections/ — Hero, About, Expertise, Experience, Projects, Contact, HeroParticles, DownloadResume ui/ — Badge, Button, SectionHeading, SocialLinks, Tag, Typewriter, AnimatedSection, InView, RollingTextLink, BackToTop index.ts — barrel export - data/ — profile, skills, experience, projects, resume (TS modules) + data/ — profile, skills, experience, projects, resume, palettes (TS modules) hooks/ — useTheme.tsx, useClickOutside.ts pages/ — HomePage, AboutPage, ExperiencePage, ProjectsListPage, ProjectDetailPage, PhilosophyPage, ContactPage, index.ts types/ — shared TypeScript interfaces @@ -148,7 +151,7 @@ All specification documents are in `docs/design/`: | `spec-v2.md` | v2 index — overview, implementation order, feature list | | `specs/ui/spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) | | `specs/v2/spec-v2-*.md` | v2 feature specs (resume, seo, blog, analytics, testing, cicd) | -| `specs/v3/spec-v3-*.md` | v3 feature specs (theme colors, theme switch, UI enhancements) | +| `specs/v3/spec-v3-*.md` | v3 feature specs (theme colors, theme switch, theme palette switch, UI enhancements) | Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope. diff --git a/docs/design/specs/v3/spec-v3-theme-colors.md b/docs/design/specs/v3/spec-v3-theme-colors.md index 3b08989..8a7d5ac 100644 --- a/docs/design/specs/v3/spec-v3-theme-colors.md +++ b/docs/design/specs/v3/spec-v3-theme-colors.md @@ -5,7 +5,7 @@ > **Parent:** `spec-v2.md` > **Priority:** P2 > **Estimate:** ~2 hours -> **⚠ SUPERSEDED (palette section).** The color palette, the `--bg-gradient-*` tokens, the body gradient and the `.hero::before` radial glow described in §1 and §2 of this document were **never implemented** and are now replaced by `specs/v3/spec-v3-theme-palette-gasatrya.md` (v0.3.0), which defines the shipped token set: 26 dark + 24 light tokens, `color-scheme`, `--text-on-accent`, `--accent-soft`, `--accent-glow`, `--border-strong`, `--inset-highlight`, `--success-glow`, `--warning`. The depth effect in this site comes from `.section::before` (`src/App.css`), not from a body gradient. Read that file before touching any color value. +> **⚠ SUPERSEDED (palette section).** The color palette, the `--bg-gradient-*` tokens, the body gradient and the `.hero::before` radial glow described in §1 and §2 of this document were **never implemented** and are now replaced by `specs/v3/spec-v3-theme-palette-gasatrya.md` (v0.3.0), which defines the shipped token set: 26 dark + 24 light tokens, `color-scheme`, `--text-on-accent`, `--accent-soft`, `--accent-glow`, `--border-strong`, `--inset-highlight`, `--success-glow`, `--warning`. The depth effect in this site comes from `.section::before` (`src/App.css`), not from a body gradient. Read that file before touching any color value. The blue values sketched below were never measured and two of them fail WCAG AA — the implemented, measured blue palette is `specs/v3/spec-v3-theme-palette-switch.md` §5 (shipped as `data-palette="blue"`, selectable from the navigation). --- @@ -68,7 +68,7 @@ Replace with a deep gray palette with slight warmth: **Contrast check:** - `#e8eaed` on `#0f1117` -> ~13.5:1 (AAA pass) - `#9aa0a6` on `#0f1117` -> ~6.8:1 (AA pass) -- `#6b7280` on `#0f1117` -> ~4.8:1 (AA pass) +- `#6b7280` on `#0f1117` -> **3.90:1 (AA FAIL)** — the claim in earlier revisions of this document ("~4.8:1, AA pass") was never measured. Measured with WCAG relative luminance on 2026-10-17. The measured replacement is `#828d9e` on `#0f1117` = 5.62:1, shipped in the blue-dark block of `spec-v3-theme-palette-switch.md` §5 ### 2. Gradient Background @@ -180,7 +180,7 @@ Light theme gradient variables set to `#ffffff` (no visible gradient). Only dark - [X] `body` has 180deg gradient (top to bottom) - [X] Hero has radial glow overlay above - [X] `.hero` has `position: relative` for stacking context -- [X] WCAG AA contrast ratio >= 4.5:1 for all text on backgrounds +- [X] WCAG AA contrast ratio >= 4.5:1 for all text on backgrounds — **not true of the values in this document**: `#6b7280` on `#0f1117` measures 3.90:1. It is true of the shipped token set (`spec-v3-theme-palette-gasatrya.md`) and of both palettes in `spec-v3-theme-palette-switch.md` §5 - [X] No layout shift or overflow - [X] System dark mode (`prefers-color-scheme: dark`) is in sync - [X] Linter (`pnpm lint`) passes diff --git a/docs/design/specs/v3/spec-v3-theme-palette-gasatrya.md b/docs/design/specs/v3/spec-v3-theme-palette-gasatrya.md index e33451d..6b6bf0b 100644 --- a/docs/design/specs/v3/spec-v3-theme-palette-gasatrya.md +++ b/docs/design/specs/v3/spec-v3-theme-palette-gasatrya.md @@ -124,6 +124,8 @@ Every item below is reproduced from source text, not inferred. B1 and B2 are the | `amber-700 / amber-400` | `--warning` **(new)** | | | `on-surface/5` | `--grid-color` | Architectural hairline grid | +> **Correction 2026-10-17.** `--accent-soft` and `--accent-glow` no longer take their hue from the third red `#ef4444`. The site now has two palettes, so both are derived from **the accent in force**: red-dark `rgba(248,113,113,0.12)` / `rgba(248,113,113,0.30)`, red-light `rgba(176,65,56,0.10)` / `rgba(176,65,56,0.22)`, blue-dark `rgba(96,165,250,0.12)` / `rgba(96,165,250,0.30)`, blue-light `rgba(37,99,235,0.1)` / `rgba(37,99,235,0.22)`. The **alpha** values in the tables below are unchanged — only the hue source moved. Record: `spec-v3-theme-palette-switch.md` §5 "Red, re-derived" and its §10 decision 1. + ### 3.2 Light theme | Token | Value | Contrast on `--bg-primary` / `--bg-surface` | @@ -138,9 +140,9 @@ Every item below is reproduced from source text, not inferred. B1 and B2 are the | `--accent-hover` | `#a8382f` | 5.89 / 6.15 / 6.42 | | `--accent-active` | `#9b3229` | 6.68 / 6.99 / 7.29 | | `--text-on-accent` | `#ffffff` | 5.74 on `--accent`, 6.42 on `--accent-hover`, 7.29 on `--accent-active` (AA) | -| `--accent-soft` | `rgba(239,68,68,0.10)` | translucent fills only (`.btn-secondary:hover`, focus ring) | +| `--accent-soft` | `rgba(176,65,56,0.10)` | translucent fills only (`.btn-secondary:hover`, focus ring). Hue re-derived 2026-10-16 from `--accent`, was `rgba(239,68,68,0.10)` | | `--accent-tint` | `#f5e3e1` | **opaque** panel = `--accent-soft` composited over `--bg-primary`; masks the conic lazer under `.download-resume-lazer-inner`. Accent text on it 4.63 | -| `--accent-glow` | `rgba(239,68,68,0.22)` | colored shadows/glows | +| `--accent-glow` | `rgba(176,65,56,0.22)` | colored shadows/glows. Hue re-derived 2026-10-16 from `--accent`, was `rgba(239,68,68,0.22)` | | `--border` | `#e3e1dc` | ≈ `on-surface` at 8 % over `#f6f5f2` | | `--border-strong` | `#d9d6d0` | ≈ 15 % alpha | | `--shadow` | `rgba(21,25,20,0.10)` | warm shadow, not pure black | @@ -171,9 +173,9 @@ Inversion rule: `on-surface` becomes the canvas, `neutral` becomes the text; sur | `--accent-hover` | `#fca5a5` | 9.37 / 8.27 | | `--accent-active` | `#f06060` | 5.54 / 4.89 / 4.52 on bg / surface / elevated (press state). Was `#ef4444`: 4.17 / 3.85 → below AA | | `--text-on-accent` | `#151914` | 6.43 on `--accent` (AA) — dark ink on light red | -| `--accent-soft` | `rgba(239,68,68,0.12)` | translucent fills only (`.btn-secondary:hover`, focus ring); lowered from 0.16 | +| `--accent-soft` | `rgba(248,113,113,0.12)` | translucent fills only (`.btn-secondary:hover`, focus ring); alpha lowered from 0.16, hue re-derived 2026-10-16 from `--accent`, was `rgba(239,68,68,0.12)` | | `--accent-tint` | `#2f1e1a` | **opaque** panel = `--accent-soft` composited over `--bg-primary`; needed because a translucent panel cannot mask the conic lazer under `.download-resume-lazer-inner`. Accent text on it 5.74 | -| `--accent-glow` | `rgba(239,68,68,0.30)` | | +| `--accent-glow` | `rgba(248,113,113,0.30)` | colored shadows/glows. Hue re-derived 2026-10-16 from `--accent`, was `rgba(239,68,68,0.30)` | | `--border` | `#2a3028` | 1.31 vs `--bg-primary` | | `--border-strong` | `#3a403a` | 1.67 | | `--shadow` | `rgba(0,0,0,0.45)` | | @@ -216,9 +218,9 @@ New structure: **one dark block + one light block + one media bridge** (removes --accent-hover: #fca5a5; --accent-active: #f06060; --text-on-accent: #151914; - --accent-soft: rgba(239, 68, 68, 0.12); + --accent-soft: rgba(248, 113, 113, 0.12); --accent-tint: #2f1e1a; - --accent-glow: rgba(239, 68, 68, 0.30); + --accent-glow: rgba(248, 113, 113, 0.30); --border: #2a3028; --border-strong: #3a403a; --shadow: rgba(0, 0, 0, 0.45); @@ -268,9 +270,9 @@ New structure: **one dark block + one light block + one media bridge** (removes --accent-hover: #a8382f; --accent-active: #9b3229; --text-on-accent: #ffffff; - --accent-soft: rgba(239, 68, 68, 0.10); + --accent-soft: rgba(176, 65, 56, 0.10); --accent-tint: #f5e3e1; - --accent-glow: rgba(239, 68, 68, 0.22); + --accent-glow: rgba(176, 65, 56, 0.22); --border: #e3e1dc; --border-strong: #d9d6d0; --shadow: rgba(21, 25, 20, 0.10); @@ -297,9 +299,9 @@ New structure: **one dark block + one light block + one media bridge** (removes --accent-hover: #a8382f; --accent-active: #9b3229; --text-on-accent: #ffffff; - --accent-soft: rgba(239, 68, 68, 0.10); + --accent-soft: rgba(176, 65, 56, 0.10); --accent-tint: #f5e3e1; - --accent-glow: rgba(239, 68, 68, 0.22); + --accent-glow: rgba(176, 65, 56, 0.22); --border: #e3e1dc; --border-strong: #d9d6d0; --shadow: rgba(21, 25, 20, 0.10); @@ -449,6 +451,7 @@ New structure: **one dark block + one light block + one media bridge** (removes 1. ~~Light `--accent`: `#b91c1c` or brand flag red `#CE1126`?~~ **DECIDED: `#b91c1c`** (Tailwind red-700) at the time of writing — **now superseded by decision 9**, which moved the light ramp to `#b04138 / #a8382f / #9b3229` after the user found the original too heavy. `#CE1126` stays available as a brand-only value for `public/favicon.svg` / og images (§4.4). 2. ~~Keep the vivid `#ef4444` visible anywhere in the UI?~~ **DECIDED: no literal `#ef4444` in text or fills.** It survives only as `rgba(239,68,68,…)` inside `--accent-soft` / `--accent-glow`. Correction made during implementation: the dark press token shipped as **`#f06060`**, not `#ef4444` — measured `#ef4444` was 4.17 on `--bg-surface` and 3.85 on `--bg-elevated` (below AA); `#f06060` measures 5.54 / 4.89 / 4.52 and still reads as a pressed, more saturated red against the `#f87171` base. + - **Correction 2026-10-17:** the `rgba(239,68,68,…)` composites no longer survive either. Both were re-derived onto the accent in force — `rgba(248,113,113,…)` dark, `rgba(176,65,56,…)` light — so no `#ef4444` remains in any form (`spec-v3-theme-palette-switch.md` §5, decision 1 in its §10). 3. ~~Adopt gasatrya's architectural hairline grid?~~ **DEFERRED** to a separate v3 layout spec. Keep the current 60 px `.hero-bg-grid`; only its `--grid-color` value changes. 4. ~~Identity shift blue → red?~~ **DECIDED: full red adoption.** All 63 `--accent` consumers move onto the red ramp and every blue value is removed from `src/` (CTA gradient, `.name-highlight` gradient, blue `--grid-color`, blue glow shadows). 5. ~~CSS default theme?~~ **DECIDED: keep dark as the `:root` default.** `useTheme.getInitialTheme()` and the §4.2 init script both resolve the OS preference, so the CSS default only governs the no-JS baseline. Zero structural churn. @@ -488,8 +491,10 @@ New structure: **one dark block + one light block + one media bridge** (removes - `pnpm exec tsc -b` → exit 0. - `pnpm exec vite build --outDir dist-verify` → 538 modules, `index.css` 26.11 kB (gzip 5.46 kB), built in 137 ms, no errors; temp out dir deleted after every run. `pnpm build` itself is still blocked by the `dist/` mount in `docker-compose.yaml:7`. - Built-CSS hex census: `#b04138`, `#a8382f`, `#9b3229`, `#f5e3e1`, `#e3e1dc`, `#d9d6d0`, `#f6f5f2`, `#fbfaf8`, `#efece6`, `#991b1b`, `#b45309`, `#15803d`, `#ffffff` all ×2 (light block + bridge); `#2f1e1a`, `#f87171`, `#fca5a5`, `#f06060`, `#b7aea0`, `#8f9a8e`, `#4ade80`, `#fbbf24`, `#3a403a`, `#2a3028`, `#272a28`, `#202423`, `#1a1e1b`, `#151914` (×4: dark ink + dark `--text-on-accent` + shadow composites) once per dark block. Alpha composites appear as 8-digit hex (`#ef44441f` = `--accent-soft` dark, `#ef444438` = `--accent-glow`, `#15191412` = light `--shadow`, `#00000073` = dark `--shadow`, `#ffffffe6` = light `--inset-highlight`). No `#b91c1c`, no `#7f1d1d`, no `#96 165 250`-family blue. The only remaining literal `#fff` / `#000` pairs belong to `src/assets/vite.svg`'s own `