mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-23 00:20:40 +07:00
docs: update AGENTS.md to reflect current project state
- Add motion, playwright, tsx to Tech Stack - Add build:resume/build:resume-all commands - Update theming: remove system variant, document resolvedTheme - Add resume.ts to Data Layer - Add new components (HeroParticles, DownloadResume, Typewriter, AnimatedSection, InView, RollingTextLink, BackToTop) - Add useClickOutside hook - Add Motion & Animation section - Add External Assets section - Add Scripts section - Add nginx.conf and docker-compose.yaml to Deployment - Remove obsolete system theme gotchas - Add motion/react import gotcha - Add v3 specs to Design Specs
This commit is contained in:
1 parent
b58e3ce306
commit
ca8ff2f983
1 file changed
+50
-21
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
## Project
|
## Project
|
||||||
|
|
||||||
Personal engineering portfolio — multi-page SPA built with React + TypeScript + Vite. Data-driven content from `src/data/`, styled with CSS variables supporting dark/light/system themes.
|
Personal engineering portfolio — multi-page SPA built with React + TypeScript + Vite. Data-driven content from `src/data/`, styled with CSS variables supporting dark/light themes. Motion animations via `motion/react`. Bilingual resume generation (EN/VI).
|
||||||
|
|
||||||
## Tech Stack
|
## Tech Stack
|
||||||
|
|
||||||
@@ -12,7 +12,9 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
|||||||
| Language | TypeScript 6 (bundler mode, `verbatimModuleSyntax`, `noEmit`) |
|
| Language | TypeScript 6 (bundler mode, `verbatimModuleSyntax`, `noEmit`) |
|
||||||
| Bundler | Vite 8 |
|
| Bundler | Vite 8 |
|
||||||
| Router | React Router v8 (`react-router` package, pinned `8.4.0`) |
|
| Router | React Router v8 (`react-router` package, pinned `8.4.0`) |
|
||||||
|
| Animation | motion ^14.0.0 (`motion/react` ESM entrypoint) |
|
||||||
| Linter | Oxlint 1 (`plugins: react, typescript, oxc`) |
|
| Linter | Oxlint 1 (`plugins: react, typescript, oxc`) |
|
||||||
|
| Resume generation | playwright ^1.64.0, tsx ^4.23.15 |
|
||||||
| Package manager | pnpm |
|
| Package manager | pnpm |
|
||||||
|
|
||||||
## Commands
|
## Commands
|
||||||
@@ -21,6 +23,8 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
|||||||
|---------|-------------|
|
|---------|-------------|
|
||||||
| `pnpm dev` | Start dev server with HMR |
|
| `pnpm dev` | Start dev server with HMR |
|
||||||
| `pnpm build` | Type-check (`tsc -b`) then build for production |
|
| `pnpm build` | Type-check (`tsc -b`) then build for production |
|
||||||
|
| `pnpm build:resume` | Generate resume PDF (default EN) via Playwright |
|
||||||
|
| `pnpm build:resume-all` | Generate bilingual resume PDFs (EN + VI) |
|
||||||
| `pnpm lint` | Run Oxlint |
|
| `pnpm lint` | Run Oxlint |
|
||||||
| `pnpm preview` | Preview production build locally |
|
| `pnpm preview` | Preview production build locally |
|
||||||
|
|
||||||
@@ -46,9 +50,9 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
|||||||
## Theming
|
## Theming
|
||||||
|
|
||||||
- `src/hooks/useTheme.tsx` — `ThemeProvider` + `useTheme` hook
|
- `src/hooks/useTheme.tsx` — `ThemeProvider` + `useTheme` hook
|
||||||
- State machine: `dark` ↔ `light` ↔ `system`
|
- Simple toggle: `'dark'` ↔ `'light'` (no `system` variant)
|
||||||
- **Critical:** `cycleTheme` skips `system` when prev is `system` (goes to opposite theme instead)
|
- `resolvedTheme` — runtime resolved value (always `'dark'` or `'light'`)
|
||||||
- `data-theme` attribute on `<html>` set by `useEffect`
|
- `data-theme` attribute set on `<html>` during render (before paint)
|
||||||
- Stored in `localStorage` key `portfolio-theme`
|
- Stored in `localStorage` key `portfolio-theme`
|
||||||
|
|
||||||
## Data Layer
|
## Data Layer
|
||||||
@@ -57,6 +61,7 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
|||||||
- `src/data/skills.ts` — skill groups → skills
|
- `src/data/skills.ts` — skill groups → skills
|
||||||
- `src/data/experience.ts` — work history entries
|
- `src/data/experience.ts` — work history entries
|
||||||
- `src/data/projects.ts` — project cards with categories
|
- `src/data/projects.ts` — project cards with categories
|
||||||
|
- `src/data/resume.ts` — resume availability, supported languages, URL generation
|
||||||
|
|
||||||
## Component Structure
|
## Component Structure
|
||||||
|
|
||||||
@@ -64,15 +69,49 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
|||||||
src/
|
src/
|
||||||
components/
|
components/
|
||||||
layout/ — Layout.tsx, Navigation.tsx, Footer.tsx
|
layout/ — Layout.tsx, Navigation.tsx, Footer.tsx
|
||||||
sections/ — Hero, About, Expertise, Experience, Projects, Contact (used in HomePage)
|
sections/ — Hero, About, Expertise, Experience, Projects, Contact, HeroParticles, DownloadResume
|
||||||
ui/ — Badge, Button, Card, SectionHeading, SocialLinks, Tag
|
ui/ — Badge, Button, Card, SectionHeading, SocialLinks, Tag, Typewriter, AnimatedSection, InView, RollingTextLink, BackToTop
|
||||||
index.ts — barrel export
|
index.ts — barrel export
|
||||||
data/ — profile, skills, experience, projects (TS modules)
|
data/ — profile, skills, experience, projects, resume (TS modules)
|
||||||
hooks/ — useTheme.tsx
|
hooks/ — useTheme.tsx, useClickOutside.ts
|
||||||
pages/ — HomePage, AboutPage, ExperiencePage, ProjectsListPage, ProjectDetailPage, EngineeringPage, ContactPage, index.ts
|
pages/ — HomePage, AboutPage, ExperiencePage, ProjectsListPage, ProjectDetailPage, EngineeringPage, ContactPage, index.ts
|
||||||
types/ — shared TypeScript interfaces
|
types/ — shared TypeScript interfaces
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Motion & Animation
|
||||||
|
|
||||||
|
- `motion/react` v14 — ESM-first entrypoint (NOT `framer-motion`)
|
||||||
|
- `AnimatedSection.tsx` — scroll-triggered motion animation wrapper
|
||||||
|
- `InView.tsx` — viewport intersection observer motion component
|
||||||
|
- `RollingTextLink.tsx` — animated text-scrolling navigation link
|
||||||
|
- `BackToTop.tsx` — scroll-to-top floating button with AnimatePresence
|
||||||
|
- `HeroParticles.tsx` — decorative particle background (uses AnimatePresence)
|
||||||
|
|
||||||
|
## External Assets
|
||||||
|
|
||||||
|
- `public/fonts/` — Inter font (Regular, Medium, SemiBold, Bold) in woff2
|
||||||
|
- `public/icons.svg` — SVG sprite for icons
|
||||||
|
- `public/resume-template.html` — HTML template for resume PDF generation
|
||||||
|
- `public/profile-photo.webp` — profile photo
|
||||||
|
|
||||||
|
## Scripts
|
||||||
|
|
||||||
|
- `scripts/generate-resume.ts` — Playwright-based PDF resume generator (bilingual en/vi)
|
||||||
|
|
||||||
|
## Deployment
|
||||||
|
|
||||||
|
- Deployment is triggered automatically by gitea workflow `.gitea/workflows/deploy.yml`
|
||||||
|
- `nginx.conf` — production Nginx SPA routing + caching config
|
||||||
|
- `docker-compose.yaml` — Docker service for local nginx deployment
|
||||||
|
|
||||||
|
```
|
||||||
|
.gitea/
|
||||||
|
└── workflows/
|
||||||
|
└── deploy.yml
|
||||||
|
nginx.conf
|
||||||
|
docker-compose.yaml
|
||||||
|
```
|
||||||
|
|
||||||
## CSS Architecture
|
## CSS Architecture
|
||||||
|
|
||||||
- `src/index.css` — CSS variables (root + `[data-theme="dark"]`), global resets
|
- `src/index.css` — CSS variables (root + `[data-theme="dark"]`), global resets
|
||||||
@@ -80,23 +119,12 @@ src/
|
|||||||
- No CSS library — plain CSS with variables for theming
|
- No CSS library — plain CSS with variables for theming
|
||||||
- `#main-content` in Layout has `style={{ flex: 1 }}` (parent `#root` is `display: flex; flex-direction: column`)
|
- `#main-content` in Layout has `style={{ flex: 1 }}` (parent `#root` is `display: flex; flex-direction: column`)
|
||||||
|
|
||||||
## Deployment
|
|
||||||
|
|
||||||
- Deployment is triggered automatically by gitea workflow `.gitea/workflows/deploy.yml`setup in the repository.
|
|
||||||
|
|
||||||
```
|
|
||||||
.gitea/
|
|
||||||
└── workflows/
|
|
||||||
└── deploy.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
## Known Issues & Gotchas
|
## Known Issues & Gotchas
|
||||||
|
|
||||||
1. **React Router v8 routing:** Use `<Layout><Routes>...</Routes></Layout>`, NOT `<Route element={<Layout />}>` with nested routes — the latter doesn't pass `children` correctly
|
1. **React Router v8 routing:** Use `<Layout><Routes>...</Routes></Layout>`, NOT `<Route element={<Layout />}>` with nested routes — the latter doesn't pass `children` correctly
|
||||||
2. **Import path:** All router imports use `react-router` (not `react-router-dom`) — e.g., `import { Link, useLocation } from 'react-router'`
|
2. **Import path:** All router imports use `react-router` (not `react-router-dom`) — e.g., `import { Link, useLocation } from 'react-router'`
|
||||||
3. **Theme cycle:** `cycleTheme` dependency array must be `[]` (empty), NOT `[setTheme]` — `setTheme` is not used inside `cycleTheme`
|
3. **Animation imports:** Use `motion/react` (v14 ESM), NOT `framer-motion` — e.g., `import { motion, AnimatePresence } from 'motion/react'`
|
||||||
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. **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
|
## Design Specs
|
||||||
|
|
||||||
@@ -109,6 +137,7 @@ All specification documents are in `docs/design/`:
|
|||||||
| `spec-v2.md` | v2 index — overview, implementation order, feature list |
|
| `spec-v2.md` | v2 index — overview, implementation order, feature list |
|
||||||
| `specs/ui/spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) |
|
| `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/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) |
|
||||||
|
|
||||||
Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
|
Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user