diff --git a/AGENTS.md b/AGENTS.md
index 60e0ad3..c2c2a0a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -96,8 +96,9 @@ All specification documents are in `docs/design/`:
|------|---------|
| `spec.md` | Main PRD — product vision, positioning, narrative, IA, acceptance criteria |
| `spec-v1.md` | v1 completion record — features implemented, known limitations, files summary |
-| `spec-v2.md` | v2 features — Resume, Blog, SEO, Analytics, Testing, CI/CD |
-| `spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) |
+| `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) |
Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
diff --git a/docs/design/spec-v2.md b/docs/design/spec-v2.md
index 09ddf08..f352deb 100644
--- a/docs/design/spec-v2.md
+++ b/docs/design/spec-v2.md
@@ -8,418 +8,27 @@
---
+
+## Prerequisites (Completed)
+
+| File | Feature | Status |
+|------|---------|--------|
+| `specs/v2/spec-v2-router.md` | React Router v6 → v7 | ✅ Done |
+| `specs/v2/spec-v2-router-v8.md` | React Router v7 → v8 | ✅ Done |
## Overview
-Phase 1 (Foundation) + Phase 2 (Core Portfolio) đã hoàn thành trong v0.0.1. v2 tập trung vào:
-
-1. **Resume download** (P1)
-2. **Blog system** — MDX-based articles (P1)
-3. **SEO** — metadata, Open Graph, sitemap (P1)
-4. **Analytics** — privacy-friendly page view tracking (P2)
-5. **Testing** — Vitest + Testing Library (P5)
-6. **CI/CD pipeline** (P5)
-
----
-
-## 1. Resume Download
-
-### Requirement
-
-- Nút "Download Resume" trong nav hoặc Contact page
-- Link đến file PDF (placeholder ban đầu)
-- Khi chưa có PDF → ẩn nút, hoặc hiển thị "Coming soon"
-- PDF sẽ upload vào `public/resume.pdf`
-
-### Implementation
-
-```tsx
-// Navigation.tsx
-{resumeAvailable && (
- Resume
-)}
-
-// OR ContactPage.tsx
-Download Resume
-```
-
-### Data
-
-- `public/resume.pdf` — PDF file (user tự upload)
-- Không cần data module
-
-### Acceptance
-
-- [ ] Nút Resume hiển thị trong nav
-- [ ] Click → download PDF
-- [ ] Khi chưa có PDF → nút ẩn hoặc disabled
-- [ ] Responsive trên mobile
-
----
-
-## 2. Blog System
-
-### Requirement
-
-Blog cho phép viết technical articles bằng Markdown/MDX, render trên client.
-
-### Architecture
-
-```
-src/
- content/
- blog/
- post-1.mdx
- post-2.mdx
- components/
- blog/
- BlogListPage.tsx
- BlogPostPage.tsx
- ArticleCard.tsx
- CodeBlock.tsx
-```
-
-### Features
-
-#### 2.1. Frontmatter
-
-Mỗi article có frontmatter:
-
-```yaml
----
-title: "Building High-Performance Event Simulation with Go"
-date: "2024-06-15"
-tags: ["engineering", "golang", "simulation"]
-summary: "Discrete event simulation for logistics facilities"
----
-```
-
-#### 2.2. Blog List Page (`/blog`)
-
-- Hiển thị danh sách articles
-- Sort theo date (newest first)
-- Filter theo tags (pill buttons)
-- Mỗi article card: title, date, tags, summary
-
-#### 2.3. Article Page (`/blog/:slug`)
-
-- Render MDX content
-- Code blocks với syntax highlighting
-- TOC (table of contents) sidebar (desktop)
-- Reading time estimate
-- Breadcrumb navigation
-
-#### 2.4. Code Highlighting
-
-- Dùng `rehype-prism-plus` hoặc `rehype-raw` + `prismjs`
-- Không dùng library nặng như `react-syntax-highlighter`
-- Theme: dark/light compatible với CSS variables
-
-#### 2.5. MDX Processing
-
-- Dùng `@mdx-js/react` + `@mdx-js/rollup` (Vite plugin)
-- Build-time compilation (không runtime)
-- Frontmatter extracted tại build time
-
-### Vite Config Changes
-
-```ts
-// vite.config.ts
-import mdx from '@mdx-js/rollup'
-
-export default defineConfig({
- plugins: [
- react(),
- mdx({
- providerImportSource: '@mdx-js/react',
- }),
- ],
-})
-```
-
-### Acceptance
-
-- [ ] `/blog` hiển thị danh sách articles
-- [ ] Article card có title, date, tags, summary
-- [ ] Click article → navigate đến `/blog/:slug`
-- [ ] MDX content render đúng
-- [ ] Code blocks có syntax highlighting
-- [ ] Tags filter hoạt động
-- [ ] TOC sidebar (desktop only)
-- [ ] Reading time hiển thị
-- [ ] Responsive
-- [ ] Không crash khi missing article
-
----
-
-## 3. SEO
-
-### Requirement
-
-Mỗi page có metadata riêng cho SEO và social sharing.
-
-### Implementation
-
-#### 3.1. Dynamic Metadata
-
-Dùng `react-helmet-async` (hoặc `@remix-run/react` helmet nếu cần SSR sau này).
-
-```tsx
-import { Helmet } from 'react-helmet-async'
-
-// HomePage.tsx
-
- {profile.name} — Senior Software Engineer
-
-
-
-```
-
-#### 3.2. Open Graph
-
-Mỗi page có OG tags:
-
-```html
-
-
-
-
-
-```
-
-#### 3.3. Sitemap
-
-- Generate `sitemap.xml` tại build time
-- Dùng `vite-plugin-sitemap` hoặc tự viết script
-- Include tất cả public pages
-
-#### 3.4. Robots.txt
-
-- `public/robots.txt`
-- Allow all (trừ `/admin` nếu có sau này)
-
-#### 3.5. Structured Data (JSON-LD)
-
-- `Person` schema cho homepage
-- `Article` schema cho blog posts
-- `BreadcrumbList` cho nested pages
-
-### Acceptance
-
-- [ ] Mỗi page có `
` và `` riêng
-- [ ] OG tags đúng trên mỗi page
-- [ ] `sitemap.xml` generated tại build
-- [ ] `robots.txt` có trong `public/`
-- [ ] JSON-LD structured data
-- [ ] Canonical URL đúng
-
----
-
-## 4. Analytics
-
-### Requirement
-
-Privacy-friendly analytics — không dùng Google Analytics.
-
-### Options
-
-**Option A: Plausible Analytics** (recommended)
-- Lightweight, privacy-first
-- No cookie banner needed
-- Simple script integration
-
-**Option B: Umami**
-- Self-hosted option
-- Open source
-- Similar to Plausible
-
-**Option C: Custom minimal tracking**
-- Track page views only
-- Store in localStorage
-- Batch send to endpoint (optional)
-
-### Implementation (Plausible)
-
-```tsx
-// main.tsx
-
-```
-
-Hoặc dùng `react-use-plausible`:
-
-```tsx
-import { usePlausible } from 'react-use-plausible'
-
-const plausible = usePlausible()
-// Auto pageview tracking
-```
-
-### Acceptance
-
-- [ ] Page view tracking hoạt động
-- [ ] Không cookie banner
-- [ ] Không ảnh hưởng performance
-- [ ] Configurable via env var (ENABLE_ANALYTICS)
-
----
-
-## 5. Testing
-
-### Requirement
-
-Unit tests cho components và hooks. E2E tests cho critical paths.
-
-### Stack
-
-- **Vitest** — unit/integration tests
-- **@testing-library/react** — component tests
-- **@testing-library/jest-dom** — assertions
-- **Playwright** — E2E tests
-
-### Test Structure
-
-```
-src/
- __tests__/
- hooks/
- useTheme.test.tsx
- components/
- Navigation.test.tsx
- Footer.test.tsx
- Badge.test.tsx
- pages/
- HomePage.test.tsx
- e2e/
- navigation.spec.ts
- theme.spec.ts
- responsive.spec.ts
-```
-
-### Critical Tests
-
-#### useTheme
-
-```tsx
-test('cycles through themes correctly', () => {
- const { result } = renderHook(() => useTheme())
- act(() => { result.current.cycleTheme() })
- expect(result.current.theme).toBe('light') // or 'dark'
-})
-
-test('persists theme to localStorage', () => {
- renderHook(() => useTheme())
- expect(localStorage.getItem('portfolio-theme')).toBe('dark')
-})
-```
-
-#### Navigation
-
-```tsx
-test('renders all nav items', () => {
- render()
- navItems.forEach(item => {
- expect(screen.getByText(item.label)).toBeInTheDocument()
- })
-})
-
-test('NavLink highlights active route', () => {
- render( )
- expect(screen.getByText('About')).toHaveClass('active')
-})
-```
-
-#### HomePage
-
-```tsx
-test('renders hero section', () => {
- render()
- expect(screen.getByRole('heading', { name: profile.name })).toBeInTheDocument()
-})
-```
-
-### Acceptance
-
-- [ ] useTheme tests pass
-- [ ] Navigation tests pass
-- [ ] HomePage tests pass
-- [ ] E2E: navigation works
-- [ ] E2E: theme toggle works
-- [ ] E2E: responsive layout correct
-- [ ] Test coverage > 70%
-
----
-
-## 6. CI/CD Pipeline
-
-### Requirement
-
-GitHub Actions pipeline:
-
-1. **Lint** — oxlint
-2. **Type check** — tsc -b
-3. **Test** — vitest
-4. **Build** — vite build
-5. **Deploy** — to Vercel (on main branch push)
-
-### GitHub Actions
-
-```yaml
-# .github/workflows/ci.yml
-name: CI
-
-on:
- push:
- branches: [dev, main]
- pull_request:
- branches: [dev]
-
-jobs:
- ci:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
- - uses: pnpm/action-setup@v4
- - uses: actions/setup-node@v4
- with:
- node-version: 20
- cache: pnpm
- - run: pnpm install --frozen-lockfile
- - run: pnpm lint
- - run: pnpm build
- - run: pnpm test
-```
-
-### Vercel Integration
-
-- Connect GitHub repo
-- Auto deploy on `dev` → preview
-- Auto deploy on `main` → production
-- Environment variables: `SITE_URL`, `PLAUSIBLE_DOMAIN` (optional)
-
-### Acceptance
-
-- [ ] CI pass trên push vào dev
-- [ ] Lint pass
-- [ ] Build pass
-- [ ] Tests pass
-- [ ] Preview deploy trên Vercel
-- [ ] Production deploy khi merge vào main
-
----
-
-## Implementation Order
-
-Ưu tiên thực hiện:
-
-1. **Resume download** (5 phút, trivial)
-2. **SEO** (metadata, OG, sitemap) — cần làm trước khi deploy
-3. **Blog system** (MDX + articles) — P1, substantial work
-4. **Analytics** (Plausible) — quick win
-5. **Testing** (Vitest + E2E) — P5, important but can iterate
-6. **CI/CD** (GitHub Actions) — P5, automate after features done
+v2 bao gồm 6 tính năng, mỗi tính năng có spec riêng trong `specs/`:
+
+| File | Feature | Priority | Est. | Status |
+|------|---------|----------|------|--------|
+| `specs/v2/spec-v2-resume.md` | Resume download | P1 | ~15 min | ✅ Done |
+| `specs/v2/spec-v2-seo.md` | SEO (metadata, OG, sitemap) | P1 | ~1 hour | |
+| `specs/v2/spec-v2-blog.md` | Blog (MDX, articles, syntax highlight) | P1 | ~4 hours | |
+| `specs/v2/spec-v2-analytics.md` | Analytics (Plausible) | P2 | ~30 min | |
+| `specs/v2/spec-v2-testing.md` | Testing (Vitest + E2E) | P5 | ~3 hours | |
+| `specs/v2/spec-v2-cicd.md` | CI/CD (GitHub Actions) | P5 | ~1 hour | |
+
+**Implementation order:** ~~Resume~~ → SEO → Blog → Analytics → Testing → CI/CD
---
diff --git a/docs/design/spec-ui-about.md b/docs/design/specs/ui/spec-ui-about.md
similarity index 100%
rename from docs/design/spec-ui-about.md
rename to docs/design/specs/ui/spec-ui-about.md
diff --git a/docs/design/spec-ui-blog.md b/docs/design/specs/ui/spec-ui-blog.md
similarity index 100%
rename from docs/design/spec-ui-blog.md
rename to docs/design/specs/ui/spec-ui-blog.md
diff --git a/docs/design/spec-ui-components.md b/docs/design/specs/ui/spec-ui-components.md
similarity index 100%
rename from docs/design/spec-ui-components.md
rename to docs/design/specs/ui/spec-ui-components.md
diff --git a/docs/design/spec-ui-contact.md b/docs/design/specs/ui/spec-ui-contact.md
similarity index 100%
rename from docs/design/spec-ui-contact.md
rename to docs/design/specs/ui/spec-ui-contact.md
diff --git a/docs/design/spec-ui-engineering.md b/docs/design/specs/ui/spec-ui-engineering.md
similarity index 100%
rename from docs/design/spec-ui-engineering.md
rename to docs/design/specs/ui/spec-ui-engineering.md
diff --git a/docs/design/spec-ui-experience.md b/docs/design/specs/ui/spec-ui-experience.md
similarity index 100%
rename from docs/design/spec-ui-experience.md
rename to docs/design/specs/ui/spec-ui-experience.md
diff --git a/docs/design/spec-ui-expertise.md b/docs/design/specs/ui/spec-ui-expertise.md
similarity index 100%
rename from docs/design/spec-ui-expertise.md
rename to docs/design/specs/ui/spec-ui-expertise.md
diff --git a/docs/design/spec-ui-footer.md b/docs/design/specs/ui/spec-ui-footer.md
similarity index 100%
rename from docs/design/spec-ui-footer.md
rename to docs/design/specs/ui/spec-ui-footer.md
diff --git a/docs/design/spec-ui-hero.md b/docs/design/specs/ui/spec-ui-hero.md
similarity index 100%
rename from docs/design/spec-ui-hero.md
rename to docs/design/specs/ui/spec-ui-hero.md
diff --git a/docs/design/spec-ui-layout.md b/docs/design/specs/ui/spec-ui-layout.md
similarity index 100%
rename from docs/design/spec-ui-layout.md
rename to docs/design/specs/ui/spec-ui-layout.md
diff --git a/docs/design/spec-ui-navigation.md b/docs/design/specs/ui/spec-ui-navigation.md
similarity index 100%
rename from docs/design/spec-ui-navigation.md
rename to docs/design/specs/ui/spec-ui-navigation.md
diff --git a/docs/design/spec-ui-project-detail.md b/docs/design/specs/ui/spec-ui-project-detail.md
similarity index 100%
rename from docs/design/spec-ui-project-detail.md
rename to docs/design/specs/ui/spec-ui-project-detail.md
diff --git a/docs/design/spec-ui-projects-list.md b/docs/design/specs/ui/spec-ui-projects-list.md
similarity index 100%
rename from docs/design/spec-ui-projects-list.md
rename to docs/design/specs/ui/spec-ui-projects-list.md
diff --git a/docs/design/spec-ui-projects.md b/docs/design/specs/ui/spec-ui-projects.md
similarity index 100%
rename from docs/design/spec-ui-projects.md
rename to docs/design/specs/ui/spec-ui-projects.md
diff --git a/docs/design/specs/v2/spec-v2-analytics.md b/docs/design/specs/v2/spec-v2-analytics.md
new file mode 100644
index 0000000..d6a1b47
--- /dev/null
+++ b/docs/design/specs/v2/spec-v2-analytics.md
@@ -0,0 +1,65 @@
+# Specification — v2 Analytics
+
+> **Document:** `spec-v2-analytics.md`
+> **Version:** 0.1.0
+> **Parent:** `spec-v2.md`
+> **Priority:** P2
+> **Estimate:** ~30 minutes
+
+---
+
+## Requirement
+
+Privacy-friendly analytics — không dùng Google Analytics.
+
+---
+
+## Options
+
+**Option A: Plausible Analytics** (recommended)
+- Lightweight, privacy-first
+- No cookie banner needed
+- Simple script integration
+
+**Option B: Umami**
+- Self-hosted option
+- Open source
+- Similar to Plausible
+
+**Option C: Custom minimal tracking**
+- Track page views only
+- Store in localStorage
+- Batch send to endpoint (optional)
+
+---
+
+## Implementation (Plausible)
+
+```tsx
+// main.tsx — add script tag
+
+```
+
+Hoặc dùng `react-use-plausible`:
+
+```tsx
+import { usePlausible } from 'react-use-plausible'
+
+const plausible = usePlausible()
+// Auto pageview tracking
+```
+
+Configurable via env var: `ENABLE_ANALYTICS`
+
+---
+
+## Acceptance
+
+- [ ] Page view tracking hoạt động
+- [ ] Không cookie banner
+- [ ] Không ảnh hưởng performance
+- [ ] Configurable via env var (ENABLE_ANALYTICS)
diff --git a/docs/design/specs/v2/spec-v2-blog.md b/docs/design/specs/v2/spec-v2-blog.md
new file mode 100644
index 0000000..4951976
--- /dev/null
+++ b/docs/design/specs/v2/spec-v2-blog.md
@@ -0,0 +1,105 @@
+# Specification — v2 Blog System
+
+> **Document:** `spec-v2-blog.md`
+> **Version:** 0.1.0
+> **Parent:** `spec-v2.md`
+> **Priority:** P1
+> **Estimate:** ~4 hours
+
+---
+
+## Requirement
+
+Blog cho phép viết technical articles bằng Markdown/MDX, render trên client.
+
+---
+
+## Architecture
+
+```
+src/
+ content/
+ blog/
+ post-1.mdx
+ post-2.mdx
+ components/
+ blog/
+ BlogListPage.tsx
+ BlogPostPage.tsx
+ ArticleCard.tsx
+ CodeBlock.tsx
+```
+
+---
+
+## Features
+
+### Frontmatter
+
+Mỗi article có frontmatter:
+
+```yaml
+---
+title: "Building High-Performance Event Simulation with Go"
+date: "2024-06-15"
+tags: ["engineering", "golang", "simulation"]
+summary: "Discrete event simulation for logistics facilities"
+---
+```
+
+### Blog List Page (`/blog`)
+
+- Hiển thị danh sách articles
+- Sort theo date (newest first)
+- Filter theo tags (pill buttons)
+- Mỗi article card: title, date, tags, summary
+
+### Article Page (`/blog/:slug`)
+
+- Render MDX content
+- Code blocks với syntax highlighting
+- TOC (table of contents) sidebar (desktop)
+- Reading time estimate
+- Breadcrumb navigation
+
+### Code Highlighting
+
+- Dùng `rehype-prism-plus` hoặc `rehype-raw` + `prismjs`
+- Không dùng library nặng như `react-syntax-highlighter`
+- Theme: dark/light compatible với CSS variables
+
+### MDX Processing
+
+- Dùng `@mdx-js/react` + `@mdx-js/rollup` (Vite plugin)
+- Build-time compilation (không runtime)
+- Frontmatter extracted tại build time
+
+### Vite Config Changes
+
+```ts
+import mdx from '@mdx-js/rollup'
+
+export default defineConfig({
+ plugins: [
+ react(),
+ mdx({
+ providerImportSource: '@mdx-js/react',
+ }),
+ ],
+})
+```
+
+---
+
+## Acceptance
+
+- [ ] `/blog` hiển thị danh sách articles
+- [ ] Article card có title, date, tags, summary
+- [ ] Click article → navigate đến `/blog/:slug`
+- [ ] MDX content render đúng
+- [ ] Code blocks có syntax highlighting
+- [ ] Tags filter hoạt động
+- [ ] TOC sidebar (desktop only)
+- [ ] Reading time hiển thị
+- [ ] Responsive
+- [ ] Không crash khi missing article
diff --git a/docs/design/specs/v2/spec-v2-cicd.md b/docs/design/specs/v2/spec-v2-cicd.md
new file mode 100644
index 0000000..33eba73
--- /dev/null
+++ b/docs/design/specs/v2/spec-v2-cicd.md
@@ -0,0 +1,61 @@
+# Specification — v2 CI/CD Pipeline
+
+> **Document:** `spec-v2-cicd.md`
+> **Version:** 0.1.0
+> **Parent:** `spec-v2.md`
+> **Priority:** P5
+> **Estimate:** ~1 hour
+
+---
+
+## Requirement
+
+GitHub Actions pipeline cho automated build, lint, test. Vercel cho deployment.
+
+---
+
+## GitHub Actions
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+ push:
+ branches: [dev, main]
+ pull_request:
+ branches: [dev]
+
+jobs:
+ ci:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 20
+ cache: pnpm
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm lint
+ - run: pnpm build
+ - run: pnpm test
+```
+
+## Vercel Integration
+
+- Connect GitHub repo
+- Auto deploy on `dev` → preview
+- Auto deploy on `main` → production
+- Environment variables: `SITE_URL`, `PLAUSIBLE_DOMAIN` (optional)
+
+---
+
+## Acceptance
+
+- [ ] CI pass trên push vào dev
+- [ ] Lint pass
+- [ ] Build pass
+- [ ] Tests pass
+- [ ] Preview deploy trên Vercel
+- [ ] Production deploy khi merge vào main
diff --git a/docs/design/specs/v2/spec-v2-resume.md b/docs/design/specs/v2/spec-v2-resume.md
new file mode 100644
index 0000000..07cfa1f
--- /dev/null
+++ b/docs/design/specs/v2/spec-v2-resume.md
@@ -0,0 +1,104 @@
+# Specification — v2 Resume Download
+
+> **Document:** `spec-v2-resume.md`
+> **Version:** 0.3.0
+> **Parent:** `spec-v2.md`
+> **Priority:** P1
+> **Estimate:** ~15 minutes
+
+---
+
+## Requirement
+
+- Nút **"Download Resume"** hiển thị ở **2 vị trí**:
+ 1. **Hero section** — CTA row (bên cạnh "View Projects" / "Contact Me")
+ 2. **Contact section** — trong `contact-links` grid
+- Link trực tiếp đến file PDF (`/resume.pdf`) với attribute `download`
+- Khi chưa có PDF → ẩn hoàn toàn ở cả 2 vị trí
+- PDF upload vào `public/resume.pdf`
+- (Optional) Nav link `/resume` để xem resume dạng HTML (Phase 2+)
+
+---
+
+## Implementation
+
+### Hero Section (primary CTA)
+
+```tsx
+// Hero.tsx
+import { resumeAvailable } from '@/data/resume'
+
+export function Hero() {
+ return (
+
+
+ {/* ... heading, title, tagline ... */}
+
+
+ {resumeAvailable && (
+
+ )}
+
+
+
+
+ {/* ... hero-visual ... */}
+
+ )
+}
+```
+
+### Contact Section (secondary)
+
+```tsx
+// Contact.tsx
+import { resumeAvailable } from '@/data/resume'
+
+export function Contact() {
+ return (
+
+ )
+}
+```
+
+### Data Detection
+
+```ts
+// src/data/resume.ts
+export const resumeAvailable = true // set false khi chưa có PDF
+```
+
+### Nav (optional — Phase 2)
+
+Nút Resume trong nav chỉ hiện khi có `/resume` route (HTML resume page).
+
+---
+
+## Acceptance
+- [x] Nút "Download Resume" hiển thị trong Hero CTA row
+- [x] Nút "Download Resume" hiển thị trong Contact section
+- [x] Click → download PDF từ `/resume.pdf`
+- [x] Khi chưa có PDF → ẩn hoàn toàn ở cả 2 vị trí
+- [x] Responsive trên mobile
+- [x] Nav không có nút Resume (Phase 2)
+
diff --git a/docs/design/specs/v2/spec-v2-router-v8.md b/docs/design/specs/v2/spec-v2-router-v8.md
new file mode 100644
index 0000000..94cc191
--- /dev/null
+++ b/docs/design/specs/v2/spec-v2-router-v8.md
@@ -0,0 +1,94 @@
+# Specification — v2 React Router v7 → v8 Migration
+
+> **Document:** `spec-v2-router-v8.md`
+> **Version:** 0.1.0
+> **Parent:** `spec-v2.md`
+> **Priority:** P0 (prerequisite for v2)
+> **Estimate:** ~15 minutes
+
+---
+
+## Background
+
+React Router v8 consolidates DOM APIs into `react-router/dom` and removes the `react-router-dom` re-export package. This app uses only the declarative mode (`` + `` + ``) — no data router, no loaders, no actions, no meta functions, no splat routes.
+
+**Current state:**
+- `react-router` pinned at `7.18.4`
+- 4 files import from `react-router`
+- No `react-router-dom` (already removed in v7 migration)
+- No `meta` functions, no `useMatches().data`, no data router APIs
+- React `^19.2.8` (≥ 19.2.7 ✅)
+- Vite `^8.3.0` (≥ 7 ✅)
+
+---
+
+## Analysis
+
+### Future flags
+
+All 5 future flags are framework/data mode only. **Not applicable** to this app:
+
+| Flag | Applicable? | Notes |
+|------|-------------|-------|
+| `v8_middleware` | No | No data router / framework mode |
+| `v8_splitRouteModules` | No | No `` / data router |
+| `v8_viteEnvironmentApi` | No | No SSR / custom server config |
+| `v8_passThroughRequests` | No | No loaders/actions |
+| `v8_trailingSlashAwareDataRequests` | No | No `.data` request handling |
+
+### Breaking changes
+
+| Change | Applicable? | Notes |
+|--------|-------------|-------|
+| `meta`/`matches` `.data` → `loaderData` | No | No meta functions |
+| `react-router-dom` removal | No | Already removed in v7 migration |
+| Cloudflare plugin | No | Not using Cloudflare |
+| `@react-router/architect` | No | Not using adapters |
+
+### Minimum versions
+
+| Requirement | Current | Required | Status |
+|-------------|---------|----------|--------|
+| `react` | `^19.2.8` | `≥19.2.7` | ✅ |
+| `react-dom` | `^19.2.8` | `≥19.2.7` | ✅ |
+| `vite` | `^8.3.0` | `≥7` | ✅ |
+
+---
+
+## Implementation Steps
+
+### Step 1: Update package.json
+
+```diff
+- "react-router": "7.18.4"
++ "react-router": "8.4.0"
+```
+
+### Step 2: Install and verify
+
+```sh
+pnpm install
+pnpm build
+pnpm lint
+```
+
+---
+
+## Acceptance
+
+- [x] `package.json` has `react-router@8.4.0`
+- [x] `pnpm build` succeeds without errors
+- [x] Dev server runs without console warnings
+- [x] All routes work correctly (/ → /about → /projects → /projects/:id → /engineering → /contact)
+- [x] Navigation highlighting works (NavLink active state)
+- [x] Mobile menu still works
+- [x] Project detail page works (useParams + Link)
+
+---
+
+## Notes
+
+- v8 upgrade is non-breaking for this app (pure declarative `` pattern)
+- No code changes needed — only package version bump
+- `react-router-dom` already removed in v7 migration
+- All future flags are framework/data mode only, not applicable to this app
diff --git a/docs/design/specs/v2/spec-v2-router.md b/docs/design/specs/v2/spec-v2-router.md
new file mode 100644
index 0000000..9cdc34f
--- /dev/null
+++ b/docs/design/specs/v2/spec-v2-router.md
@@ -0,0 +1,98 @@
+# Specification — v2 React Router v6 → v7 Migration
+
+> **Document:** `spec-v2-router.md`
+> **Version:** 0.1.0
+> **Parent:** `spec-v2.md`
+> **Priority:** P0 (prerequisite for v2)
+> **Estimate:** ~30 minutes
+
+---
+
+## Background
+
+React Router v7 consolidates `react-router-dom` into `react-router`. The upgrade is non-breaking if future flags are enabled. This app uses the simple `` + `` pattern (no data router, no forms, no splat routes).
+
+**Current state:**
+- `react-router-dom` pinned at `6.30.6` (exact, no `^`)
+- 4 files import from `react-router-dom`
+- No splat routes, no forms, no data router APIs
+
+---
+
+## Analysis
+
+### Applicable flags
+
+| Flag | Applicable? | Notes |
+|------|-------------|-------|
+| `v7_relativeSplatPath` | No | No splat routes (`*`) in app |
+| `v7_startTransition` | **Yes** | Must enable on `` |
+| `v7_fetcherPersist` | No | No `` / data router |
+| `v7_normalizeFormMethod` | No | No forms in app |
+| `v7_partialHydration` | No | No `` / data router |
+| `v7_skipActionErrorRevalidation` | No | No data router |
+
+### Files affected
+
+| File | Current import | Change needed |
+|------|---------------|---------------|
+| `src/App.tsx` | `react-router-dom` | → `react-router` + enable flag |
+| `src/components/layout/Navigation.tsx` | `react-router-dom` | → `react-router` |
+| `src/components/layout/Footer.tsx` | `react-router-dom` | → `react-router` |
+| `src/pages/ProjectDetailPage.tsx` | `react-router-dom` | → `react-router` |
+
+---
+
+## Implementation Steps
+
+### Step 1: Verify no future flags needed
+
+In v7, `v7_startTransition` and other future flags are enabled by default. No `future` prop needed on ``.
+
+### Step 2: Update package.json
+
+
+```diff
+- "react-router-dom": "6.30.6"
++ "react-router": "7.18.4"
+```
+
+Also remove `@types/react-router-dom` if present (v7 types are bundled).
+
+### Step 3: Update imports
+
+All files: replace `from 'react-router-dom'` → `from 'react-router'`
+
+```
+src/App.tsx
+src/components/layout/Navigation.tsx
+src/components/layout/Footer.tsx
+src/pages/ProjectDetailPage.tsx
+```
+
+### Step 4: Install and verify
+
+```bash
+pnpm install
+pnpm build
+```
+
+---
+
+## Acceptance
+
+- [x] `package.json` has `react-router` (not `react-router-dom`)
+- [x] All 4 files import from `react-router`
+- [x] `pnpm build` succeeds without errors
+- [x] Dev server runs without console warnings
+- [x] All routes work correctly (/ → /about → /projects → /projects/:id → /engineering → /contact)
+- [x] Navigation highlighting works (NavLink active state)
+- [x] Mobile menu still works
+
+---
+
+## Notes
+
+- v7 upgrade is non-breaking for this app (simple `` pattern)
+- No code logic changes needed — only imports + package name
+- v7 enables all future flags by default; no `future` prop needed
diff --git a/docs/design/specs/v2/spec-v2-seo.md b/docs/design/specs/v2/spec-v2-seo.md
new file mode 100644
index 0000000..b442ccf
--- /dev/null
+++ b/docs/design/specs/v2/spec-v2-seo.md
@@ -0,0 +1,72 @@
+# Specification — v2 SEO
+
+> **Document:** `spec-v2-seo.md`
+> **Version:** 0.1.0
+> **Parent:** `spec-v2.md`
+> **Priority:** P1
+> **Estimate:** ~1 hour
+
+---
+
+## Requirement
+
+Mỗi page có metadata riêng cho SEO và social sharing.
+
+---
+
+## Implementation
+
+### Dynamic Metadata
+
+Dùng `react-helmet-async`.
+
+```tsx
+import { Helmet } from 'react-helmet-async'
+
+// HomePage.tsx
+
+ {profile.name} — Senior Software Engineer
+
+
+
+```
+
+### Open Graph
+
+Mỗi page có OG tags:
+
+```html
+
+
+
+
+
+```
+
+### Sitemap
+
+- Generate `sitemap.xml` tại build time
+- Dùng `vite-plugin-sitemap` hoặc tự viết script
+- Include tất cả public pages
+
+### Robots.txt
+
+- `public/robots.txt`
+- Allow all
+
+### Structured Data (JSON-LD)
+
+- `Person` schema cho homepage
+- `Article` schema cho blog posts (sau này)
+- `BreadcrumbList` cho nested pages
+
+---
+
+## Acceptance
+
+- [ ] Mỗi page có `` và `` riêng
+- [ ] OG tags đúng trên mỗi page
+- [ ] `sitemap.xml` generated tại build
+- [ ] `robots.txt` có trong `public/`
+- [ ] JSON-LD structured data
+- [ ] Canonical URL đúng
diff --git a/docs/design/specs/v2/spec-v2-testing.md b/docs/design/specs/v2/spec-v2-testing.md
new file mode 100644
index 0000000..da61e1d
--- /dev/null
+++ b/docs/design/specs/v2/spec-v2-testing.md
@@ -0,0 +1,99 @@
+# Specification — v2 Testing
+
+> **Document:** `spec-v2-testing.md`
+> **Version:** 0.1.0
+> **Parent:** `spec-v2.md`
+> **Priority:** P5
+> **Estimate:** ~3 hours
+
+---
+
+## Requirement
+
+Unit tests cho components và hooks. E2E tests cho critical paths.
+
+---
+
+## Stack
+
+- **Vitest** — unit/integration tests
+- **@testing-library/react** — component tests
+- **@testing-library/jest-dom** — assertions
+- **Playwright** — E2E tests
+
+---
+
+## Test Structure
+
+```
+src/
+ __tests__/
+ hooks/
+ useTheme.test.tsx
+ components/
+ Navigation.test.tsx
+ Footer.test.tsx
+ Badge.test.tsx
+ pages/
+ HomePage.test.tsx
+ e2e/
+ navigation.spec.ts
+ theme.spec.ts
+ responsive.spec.ts
+```
+
+---
+
+## Critical Tests
+
+### useTheme
+
+```tsx
+test('cycles through themes correctly', () => {
+ const { result } = renderHook(() => useTheme())
+ act(() => { result.current.cycleTheme() })
+ expect(result.current.theme).toBe('light')
+})
+
+test('persists theme to localStorage', () => {
+ renderHook(() => useTheme())
+ expect(localStorage.getItem('portfolio-theme')).toBe('dark')
+})
+```
+
+### Navigation
+
+```tsx
+test('renders all nav items', () => {
+ render()
+ navItems.forEach(item => {
+ expect(screen.getByText(item.label)).toBeInTheDocument()
+ })
+})
+
+test('NavLink highlights active route', () => {
+ render( )
+ expect(screen.getByText('About')).toHaveClass('active')
+})
+```
+
+### HomePage
+
+```tsx
+test('renders hero section', () => {
+ render()
+ expect(screen.getByRole('heading', { name: profile.name })).toBeInTheDocument()
+})
+```
+
+---
+
+## Acceptance
+
+- [ ] useTheme tests pass
+- [ ] Navigation tests pass
+- [ ] HomePage tests pass
+- [ ] E2E: navigation works
+- [ ] E2E: theme toggle works
+- [ ] E2E: responsive layout correct
+- [ ] Test coverage > 70%
diff --git a/package.json b/package.json
index 6d0b62e..e798262 100644
--- a/package.json
+++ b/package.json
@@ -12,7 +12,7 @@
"dependencies": {
"react": "^19.2.8",
"react-dom": "^19.2.8",
- "react-router-dom": "6.30.6"
+ "react-router": "8.4.0"
},
"devDependencies": {
"@types/node": "^24.13.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9d5c6c5..8f6af07 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -14,9 +14,9 @@ importers:
react-dom:
specifier: ^19.2.8
version: 19.3.0(react@19.3.0)
- react-router-dom:
- specifier: 6.30.6
- version: 6.30.6(react-dom@19.3.0(react@19.3.0))(react@19.3.0)
+ react-router:
+ specifier: 8.4.0
+ version: 8.4.0(react-dom@19.3.0(react@19.3.0))(react@19.3.0)
devDependencies:
'@types/node':
specifier: ^24.13.3
@@ -167,9 +167,8 @@ packages:
cpu: [x64]
os: [win32]
- '@remix-run/router@1.23.4':
- resolution: {integrity: sha512-q7j5geK7xs3UJSdm9/iytUNclBnLmYx1EnSeCFXHPeutdqgIMeFeHtUZgS3EhlKxdBEAu8OwtJCwmLrEzpSs7Q==}
- engines: {node: '>=14.0.0'}
+ '@remix-run/route-pattern@0.22.1':
+ resolution: {integrity: sha512-czdGJWh09Lapvcqt7Vb09KlrU2PhRJ8xQaI+AItTuD9aDJ5MAgxnS38lnys6Ll+6RJEqPiaUqTwIQhVLwFvv+w==}
'@rolldown/binding-android-arm-eabi@1.2.12':
resolution: {integrity: sha512-dB/a1214qKfHMXCpgqR4OZT+jS4kTyEXbQGJPqzobt5EwH5rX080pxE37alt3RzvR1bf1Yz/yGqRfrYAxuPw0A==}
@@ -297,6 +296,9 @@ packages:
oxc-transform-react:
optional: true
+ cookie-es@3.1.1:
+ resolution: {integrity: sha512-UaXxwISYJPTr9hwQxMFYZ7kNhSXboMXP+Z3TRX6f1/NyaGPfuNUZOWP1pUEb75B2HjfklIYLVRfWiFZJyC6Npg==}
+
csstype@3.2.3:
resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
@@ -426,18 +428,15 @@ packages:
peerDependencies:
react: ^19.3.0
- react-router-dom@6.30.6:
- resolution: {integrity: sha512-0RHKZz7wwffvkU+2MFVT2NnjK44ssLEV+m0CAJaS2Ksmorrwj7WxH00jO0SOCW26/tINUnJHToXblDs33I38YQ==}
- engines: {node: '>=14.0.0'}
+ react-router@8.4.0:
+ resolution: {integrity: sha512-JtydAkBvU9UTEe5qNC+POhu+ZBNM7rlKY2IegwXc7Idj7xfRG16x5RZrw3mju+XlqBxfvb2ky9P3jUp9WyWC1g==}
+ engines: {node: '>=22.22.0'}
peerDependencies:
- react: '>=16.8'
- react-dom: '>=16.8'
-
- react-router@6.30.6:
- resolution: {integrity: sha512-5HfK7k5im7LTOB0EqCQmfvy4C13G92Ssj1VTmouTK3AJvyjKTnFuCV0vcMAD/JS+JC4DvDIBRrlAeJIFjh5VWg==}
- engines: {node: '>=14.0.0'}
- peerDependencies:
- react: '>=16.8'
+ react: '>=19.2.7'
+ react-dom: '>=19.2.7'
+ peerDependenciesMeta:
+ react-dom:
+ optional: true
react@19.3.0:
resolution: {integrity: sha512-E8LUcbtBWt20bbl2YoHfx4ZDBdxVTfOKtCZn9cDSJ4l6/nuoApcpIBcj47t2wZoVX8g2ZHuMHbiShgCR1T5Sog==}
@@ -571,7 +570,7 @@ snapshots:
'@oxlint/binding-win32-x64-msvc@1.86.0':
optional: true
- '@remix-run/router@1.23.4': {}
+ '@remix-run/route-pattern@0.22.1': {}
'@rolldown/binding-android-arm-eabi@1.2.12':
optional: true
@@ -637,6 +636,8 @@ snapshots:
'@rolldown/pluginutils': 1.0.1
vite: 8.3.2(@types/node@24.19.1)
+ cookie-es@3.1.1: {}
+
csstype@3.2.3: {}
detect-libc@2.1.2: {}
@@ -736,17 +737,13 @@ snapshots:
react: 19.3.0
scheduler: 0.28.0
- react-router-dom@6.30.6(react-dom@19.3.0(react@19.3.0))(react@19.3.0):
+ react-router@8.4.0(react-dom@19.3.0(react@19.3.0))(react@19.3.0):
dependencies:
- '@remix-run/router': 1.23.4
+ '@remix-run/route-pattern': 0.22.1
+ cookie-es: 3.1.1
react: 19.3.0
+ optionalDependencies:
react-dom: 19.3.0(react@19.3.0)
- react-router: 6.30.6(react@19.3.0)
-
- react-router@6.30.6(react@19.3.0):
- dependencies:
- '@remix-run/router': 1.23.4
- react: 19.3.0
react@19.3.0: {}
diff --git a/public/profile-photo.jpg b/public/profile-photo.jpg
new file mode 100644
index 0000000..3d8c0ec
Binary files /dev/null and b/public/profile-photo.jpg differ
diff --git a/public/profile-photo.webp b/public/profile-photo.webp
new file mode 100644
index 0000000..4670338
Binary files /dev/null and b/public/profile-photo.webp differ
diff --git a/public/profile-photo.webp~ b/public/profile-photo.webp~
new file mode 100644
index 0000000..af79baf
Binary files /dev/null and b/public/profile-photo.webp~ differ
diff --git a/src/App.tsx b/src/App.tsx
index b22964b..70f639d 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -1,5 +1,5 @@
import './App.css'
-import { BrowserRouter, Routes, Route } from 'react-router-dom'
+import { BrowserRouter, Routes, Route } from 'react-router'
import { ThemeProvider } from '@/hooks/useTheme'
import { Layout } from '@/components/layout/Layout'
import {
diff --git a/src/components/layout/Footer.tsx b/src/components/layout/Footer.tsx
index 68dcb21..c7f8e15 100644
--- a/src/components/layout/Footer.tsx
+++ b/src/components/layout/Footer.tsx
@@ -1,4 +1,4 @@
-import { Link } from 'react-router-dom'
+import { Link } from 'react-router'
import { profile } from '@/data/profile'
const footerLinks = [
diff --git a/src/components/layout/Navigation.tsx b/src/components/layout/Navigation.tsx
index cc0246f..7d806aa 100644
--- a/src/components/layout/Navigation.tsx
+++ b/src/components/layout/Navigation.tsx
@@ -1,5 +1,5 @@
import { useState, useEffect } from 'react'
-import { Link, NavLink, useLocation } from 'react-router-dom'
+import { Link, NavLink, useLocation } from 'react-router'
import { useTheme } from '@/hooks/useTheme'
const navItems = [
diff --git a/src/components/sections/Contact.tsx b/src/components/sections/Contact.tsx
index 91f7bbb..f9789b1 100644
--- a/src/components/sections/Contact.tsx
+++ b/src/components/sections/Contact.tsx
@@ -1,3 +1,4 @@
+import { resumeAvailable } from '@/data/resume'
import { SectionHeading } from '@/components/ui/SectionHeading'
import { profile } from '@/data/profile'
@@ -34,6 +35,19 @@ export function Contact() {
Your Name
+ {resumeAvailable && (
+
+
+
+
Download Resume
+
PDF
+
+
+ )}
)
diff --git a/src/components/sections/Hero.tsx b/src/components/sections/Hero.tsx
index 1c48da1..7415117 100644
--- a/src/components/sections/Hero.tsx
+++ b/src/components/sections/Hero.tsx
@@ -1,3 +1,4 @@
+import { resumeAvailable } from '@/data/resume'
import { Button } from '@/components/ui/Button'
import { SocialLinks } from '@/components/ui/SocialLinks'
import { profile } from '@/data/profile'
@@ -49,6 +50,11 @@ export function Hero() {
+ {resumeAvailable && (
+
+ )}
diff --git a/src/components/ui/Button.tsx b/src/components/ui/Button.tsx
index 8dc78d5..ca0da91 100644
--- a/src/components/ui/Button.tsx
+++ b/src/components/ui/Button.tsx
@@ -8,6 +8,7 @@ interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
variant?: ButtonVariant
size?: ButtonSize
href?: string
+ download?: boolean
children: React.ReactNode
}
diff --git a/src/data/resume.ts b/src/data/resume.ts
new file mode 100644
index 0000000..3fde682
--- /dev/null
+++ b/src/data/resume.ts
@@ -0,0 +1 @@
+export const resumeAvailable = true
diff --git a/src/pages/ProjectDetailPage.tsx b/src/pages/ProjectDetailPage.tsx
index d275658..338ef87 100644
--- a/src/pages/ProjectDetailPage.tsx
+++ b/src/pages/ProjectDetailPage.tsx
@@ -1,4 +1,4 @@
-import { useParams, Link } from 'react-router-dom'
+import { useParams, Link } from 'react-router'
import { Badge } from '@/components/ui/Badge'
import { Tag } from '@/components/ui/Tag'
import { projects } from '@/data/projects'