mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
docs: add spec_v1.md (v1 completion record) and move all specs to docs/design/
This commit is contained in:
1 parent
59951a7224
commit
e922ce64b8
18 files changed
+628
No files matched your search
@@ -88,6 +88,19 @@ src/
|
|||||||
4. **Theme from system:** When stored theme is `'system'`, `cycleTheme` must skip to opposite theme on first click (not go to `'dark'` which resolves to same visual)
|
4. **Theme from system:** When stored theme is `'system'`, `cycleTheme` must skip to opposite theme on first click (not go to `'dark'` which resolves to same visual)
|
||||||
5. **Footer/Nav links:** Must use `<Link to>`, not `<a href>` for client-side navigation
|
5. **Footer/Nav links:** Must use `<Link to>`, not `<a href>` for client-side navigation
|
||||||
|
|
||||||
|
## Design Specs
|
||||||
|
|
||||||
|
All specification documents are in `docs/design/`:
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `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.) |
|
||||||
|
|
||||||
|
Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
|
||||||
|
|
||||||
## Code Style & Linting
|
## Code Style & Linting
|
||||||
|
|
||||||
- TypeScript: `verbatimModuleSyntax`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`
|
- TypeScript: `verbatimModuleSyntax`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`
|
||||||
|
|||||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,441 @@
|
|||||||
|
# Specification — v2 Features
|
||||||
|
|
||||||
|
> **Document:** `spec-v2.md`
|
||||||
|
> **Version:** 0.1.0
|
||||||
|
> **Status:** Draft — awaiting review
|
||||||
|
> **Branch:** `dev_v2`
|
||||||
|
> **Parent branch:** `dev` (v0.0.1)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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 && (
|
||||||
|
<Link to="/resume" className="nav-link">Resume</Link>
|
||||||
|
)}
|
||||||
|
|
||||||
|
// OR ContactPage.tsx
|
||||||
|
<a href="/resume.pdf" download className="btn-primary">Download Resume</a>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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
|
||||||
|
<Helmet>
|
||||||
|
<title>{profile.name} — Senior Software Engineer</title>
|
||||||
|
<meta name="description" content={profile.bio} />
|
||||||
|
<link rel="canonical" href={siteUrl} />
|
||||||
|
</Helmet>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3.2. Open Graph
|
||||||
|
|
||||||
|
Mỗi page có OG tags:
|
||||||
|
|
||||||
|
```html
|
||||||
|
<meta property="og:title" content="..." />
|
||||||
|
<meta property="og:description" content="..." />
|
||||||
|
<meta property="og:image" content="/og-image.png" />
|
||||||
|
<meta property="og:url" content="..." />
|
||||||
|
<meta property="og:type" content="website" />
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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ó `<title>` và `<meta description>` 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
|
||||||
|
<script
|
||||||
|
defer
|
||||||
|
data-domain="yourdomain.com"
|
||||||
|
src="https://plausible.io/js/script.outbound-links.js"
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
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(<Navigation />)
|
||||||
|
navItems.forEach(item => {
|
||||||
|
expect(screen.getByText(item.label)).toBeInTheDocument()
|
||||||
|
})
|
||||||
|
})
|
||||||
|
|
||||||
|
test('NavLink highlights active route', () => {
|
||||||
|
render(<MemoryRouter initialEntries={['/about']}> <Navigation /> </MemoryRouter>)
|
||||||
|
expect(screen.getByText('About')).toHaveClass('active')
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
#### HomePage
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
test('renders hero section', () => {
|
||||||
|
render(<HomePage />)
|
||||||
|
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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Out of Scope (v2)
|
||||||
|
|
||||||
|
- CMS integration (Phase 5+)
|
||||||
|
- Multi-language / i18n (Phase 5+)
|
||||||
|
- Interactive diagrams / simulations (Phase 5+)
|
||||||
|
- Search functionality (Phase 5+)
|
||||||
|
- Contact form with backend (Phase 5+)
|
||||||
|
- Resume PDF generation (user uploads manually)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Approval
|
||||||
|
|
||||||
|
- [ ] All requirements reviewed and confirmed
|
||||||
|
- [ ] Implementation order agreed
|
||||||
|
- [ ] Ready to start coding
|
||||||
File renamed without changes.
@@ -0,0 +1,174 @@
|
|||||||
|
# Specification — v1 (Foundation + Core Portfolio)
|
||||||
|
|
||||||
|
> **Document:** `spec_v1.md`
|
||||||
|
> **Version:** 1.0.0
|
||||||
|
> **Status:** Completed
|
||||||
|
> **Branch:** `dev` (merged from `dev_v1`)
|
||||||
|
> **Tag:** `v0.0.1`
|
||||||
|
> **Commit:** `7e42bd8` (feat) + `59951a7` (docs)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
v1 implements **Phase 1 (Foundation)** and **Phase 2 (Core Portfolio)** from `spec.md`. All pages, components, theming, and responsive layout are complete.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Completed Features
|
||||||
|
|
||||||
|
### 1. Foundation
|
||||||
|
|
||||||
|
| Feature | Status | Details |
|
||||||
|
|---------|--------|---------|
|
||||||
|
| Vite 8 + React 19 + TypeScript 6 | Done | Bundler mode, strict linting |
|
||||||
|
| Oxlint 1 | Done | `react/rules-of-hooks` error, `react/only-export-components` warn |
|
||||||
|
| React Router v6 | Done | Pin `6.30.6`, 7 routes defined |
|
||||||
|
| CSS Variables + Theming | Done | `data-theme` attribute, dark/light/system |
|
||||||
|
| Responsive Design | Done | Mobile menu, fluid containers, touch-friendly |
|
||||||
|
|
||||||
|
### 2. Routing & Pages
|
||||||
|
|
||||||
|
| Route | Page | Component | Status |
|
||||||
|
|-------|------|-----------|--------|
|
||||||
|
| `/` | Home | `HomePage` | Done |
|
||||||
|
| `/about` | About | `AboutPage` | Done |
|
||||||
|
| `/experience` | Experience | `ExperiencePage` | Done |
|
||||||
|
| `/projects` | Projects List | `ProjectsListPage` | Done |
|
||||||
|
| `/projects/:id` | Project Detail | `ProjectDetailPage` | Done |
|
||||||
|
| `/engineering` | Engineering | `EngineeringPage` | Done (placeholder content) |
|
||||||
|
| `/contact` | Contact | `ContactPage` | Done |
|
||||||
|
|
||||||
|
### 3. Layout Components
|
||||||
|
|
||||||
|
| Component | File | Status |
|
||||||
|
|-----------|------|--------|
|
||||||
|
| `Layout` | `src/components/layout/Layout.tsx` | Done — wraps Navigation + main + Footer |
|
||||||
|
| `Navigation` | `src/components/layout/Navigation.tsx` | Done — desktop menu, mobile drawer, theme toggle |
|
||||||
|
| `Footer` | `src/components/layout/Footer.tsx` | Done — copyright, nav links, social links |
|
||||||
|
|
||||||
|
### 4. Page Sections (HomePage)
|
||||||
|
|
||||||
|
| Section | Component | Status |
|
||||||
|
|---------|-----------|--------|
|
||||||
|
| Hero | `src/components/sections/Hero.tsx` | Done — name, title, tagline, CTA, social links |
|
||||||
|
| About | `src/components/sections/About.tsx` | Done — bio, engineering philosophy, current interests |
|
||||||
|
| Expertise | `src/components/sections/Expertise.tsx` | Done — skill groups grid |
|
||||||
|
| Experience | `src/components/sections/Experience.tsx` | Done — timeline with responsibilities |
|
||||||
|
| Projects | `src/components/sections/Projects.tsx` | Done — featured projects grid |
|
||||||
|
| Contact | `src/components/sections/Contact.tsx` | Done — email, GitHub, LinkedIn links |
|
||||||
|
|
||||||
|
### 5. UI Components
|
||||||
|
|
||||||
|
| Component | File | Props/Features | Status |
|
||||||
|
|-----------|------|----------------|--------|
|
||||||
|
| `Button` | `src/components/ui/Button.tsx` | `variant`, `size`, `disabled` | Done |
|
||||||
|
| `Badge` | `src/components/ui/Badge.tsx` | `variant: accent | outline | muted` | Done |
|
||||||
|
| `Tag` | `src/components/ui/Tag.tsx` | `accent` | Done |
|
||||||
|
| `Card` | `src/components/ui/Card.tsx` | `as`, children | Done |
|
||||||
|
| `SectionHeading` | `src/components/ui/SectionHeading.tsx` | `title`, `subtitle` | Done |
|
||||||
|
| `SocialLinks` | `src/components/ui/SocialLinks.tsx` | `links`, `variant` | Done |
|
||||||
|
|
||||||
|
### 6. Theming
|
||||||
|
|
||||||
|
| Feature | Status | Details |
|
||||||
|
|---------|--------|---------|
|
||||||
|
| `ThemeProvider` | Done | Context provider, `data-theme` on `<html>` |
|
||||||
|
| `useTheme()` hook | Done | Returns `{ theme, resolvedTheme, setTheme, cycleTheme }` |
|
||||||
|
| Theme cycle | Done | `dark` ↔ `light` ↔ `system` (system skips to opposite) |
|
||||||
|
| localStorage persistence | Done | Key: `portfolio-theme` |
|
||||||
|
| System preference detection | Done | `prefers-color-scheme: dark` |
|
||||||
|
| CSS variables for both themes | Done | `src/index.css` root + `[data-theme="dark"]` |
|
||||||
|
|
||||||
|
### 7. Data Layer
|
||||||
|
|
||||||
|
| Module | File | Content | Status |
|
||||||
|
|--------|------|---------|--------|
|
||||||
|
| Profile | `src/data/profile.ts` | Name, title, tagline, bio, links, interests, philosophy | Done |
|
||||||
|
| Skills | `src/data/skills.ts` | 6 skill groups × 5-6 skills each | Done |
|
||||||
|
| Experience | `src/data/experience.ts` | 1 entry with 3 featured achievements | Done |
|
||||||
|
| Projects | `src/data/projects.ts` | 4 projects with sections, metrics, tech stacks | Done |
|
||||||
|
|
||||||
|
### 8. Types
|
||||||
|
|
||||||
|
| Interface | File | Fields | Status |
|
||||||
|
|-----------|------|--------|--------|
|
||||||
|
| `Profile` | `src/types/index.ts` | name, title, tagline, bio, email, links, interests, philosophy | Done |
|
||||||
|
| `SkillGroup` | `src/types/index.ts` | title, skills[] | Done |
|
||||||
|
| `ExperienceEntry` | `src/types/index.ts` | id, title, company, duration, location, responsibilities, achievements | Done |
|
||||||
|
| `FeaturedAchievement` | `src/types/index.ts` | id, title, context, technicalWork, impact, metrics, technologies, featured | Done |
|
||||||
|
| `Project` | `src/types/index.ts` | id, title, summary, category, role, technologies, metrics, featured, urls | Done |
|
||||||
|
| `ProjectDetail` | `src/types/index.ts` | extends Project + sections[] | Done |
|
||||||
|
| `ProjectSection` | `src/types/index.ts` | id, number, title, content, type | Done |
|
||||||
|
| `PhilosophyPoint` | `src/types/index.ts` | title, description, keywords[] | Done |
|
||||||
|
| `ProjectCategory` | `src/types/index.ts` | 6 union types | Done |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
App.tsx
|
||||||
|
└── ThemeProvider
|
||||||
|
└── BrowserRouter
|
||||||
|
└── Layout
|
||||||
|
├── Navigation (top bar + mobile drawer)
|
||||||
|
├── <Routes>
|
||||||
|
│ ├── HomePage (Hero + About + Expertise + Experience + Projects + Contact)
|
||||||
|
│ ├── AboutPage
|
||||||
|
│ ├── ExperiencePage
|
||||||
|
│ ├── ProjectsListPage
|
||||||
|
│ ├── ProjectDetailPage
|
||||||
|
│ ├── EngineeringPage
|
||||||
|
│ └── ContactPage
|
||||||
|
└── Footer
|
||||||
|
```
|
||||||
|
|
||||||
|
**Data flow:** All content comes from `src/data/*.ts` modules. Components are presentational — no hardcoded text except labels/CTAs.
|
||||||
|
|
||||||
|
**CSS:** Global variables in `src/index.css`, component styles in `src/App.css`. No CSS library.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Known Limitations
|
||||||
|
|
||||||
|
| # | Limitation | Impact | v2 Plan |
|
||||||
|
|---|------------|--------|---------|
|
||||||
|
| 1 | No Blog system | Cannot publish articles | Phase 4: MDX-based blog |
|
||||||
|
| 2 | No SEO metadata | No `<title>`, `<meta>`, OG tags per page | Phase 5: react-helmet-async |
|
||||||
|
| 3 | No Analytics | No page view tracking | Phase 5: Plausible |
|
||||||
|
| 4 | No Testing | No unit/E2E tests | Phase 5: Vitest + Playwright |
|
||||||
|
| 5 | No CI/CD | Manual builds only | Phase 5: GitHub Actions |
|
||||||
|
| 6 | No Resume download | No PDF resume | v2: Add link/button |
|
||||||
|
| 7 | Engineering page placeholder | "Coming soon" text | v2: Populate with real content |
|
||||||
|
| 8 | Projects use `<a href>` not `<Link>` | Client-side nav broken on projects page | v2: Fix to `<Link>` |
|
||||||
|
| 9 | No i18n | Vietnamese-only | Future: English support |
|
||||||
|
| 10 | No CMS | Content in TS files | Future: headless CMS or MDX |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Files Summary
|
||||||
|
|
||||||
|
| Category | Count | Path |
|
||||||
|
|----------|-------|------|
|
||||||
|
| Pages | 7 | `src/pages/*.tsx` |
|
||||||
|
| Layout components | 3 | `src/components/layout/*.tsx` |
|
||||||
|
| Section components | 6 | `src/components/sections/*.tsx` |
|
||||||
|
| UI components | 6 | `src/components/ui/*.tsx` |
|
||||||
|
| Data modules | 4 | `src/data/*.ts` |
|
||||||
|
| Hooks | 1 | `src/hooks/useTheme.tsx` |
|
||||||
|
| Types | 1 | `src/types/index.ts` |
|
||||||
|
| CSS | 2 | `src/index.css`, `src/App.css` |
|
||||||
|
| **Total source files** | **30** | |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Approval
|
||||||
|
|
||||||
|
- [x] All Phase 1 + Phase 2 requirements implemented
|
||||||
|
- [x] TypeScript compiles without errors
|
||||||
|
- [x] Oxlint passes
|
||||||
|
- [x] Build succeeds
|
||||||
|
- [x] Responsive on mobile/desktop
|
||||||
|
- [x] Tagged `v0.0.1` on branch `dev`
|
||||||
|
- [x] AGENTS.md updated with project context
|
||||||
Reference in new issue
Block a user