mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
6.4 KiB
6.4 KiB
Agent Guidelines — portfolio
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 themes. Motion animations via motion/react. Bilingual resume generation (EN/VI).
Tech Stack
| Layer | Tool |
|---|---|
| Framework | React 19 |
| Language | TypeScript 6 (bundler mode, verbatimModuleSyntax, noEmit) |
| Bundler | Vite 8 |
| 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) |
| Resume generation | playwright ^1.64.0, tsx ^4.23.15 |
| Package manager | pnpm |
Commands
| Command | Description |
|---|---|
pnpm dev |
Start dev server with HMR |
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 preview |
Preview production build locally |
Routing
App.tsxwraps<BrowserRouter>→<Layout>→<Routes>(NOT nested<Route element>— causeschildrennot to pass)- Layout:
<Navigation>(top) →<main id="main-content">→<Footer>(bottom) - All internal navigation MUST use
<Link>/<NavLink>, never<a href>(causes full page reload) - Footer internal links also use
<Link>; external links (GitHub, LinkedIn, email) keep<a>withtarget="_blank"
Pages
| Route | Component | Section |
|---|---|---|
/ |
HomePage |
Hero + About + Expertise + Experience + Projects + Contact |
/about |
AboutPage |
Full about section |
/experience |
ExperiencePage |
Timeline |
/projects |
ProjectsListPage |
All projects grid |
/projects/:id |
ProjectDetailPage |
Single project |
/philosophy |
PhilosophyPage |
Engineering philosophy |
/contact |
ContactPage |
Contact info |
Theming
src/hooks/useTheme.tsx—ThemeProvider+useThemehook- Simple toggle:
'dark'↔'light'(nosystemvariant) resolvedTheme— runtime resolved value (always'dark'or'light')data-themeattribute set on<html>during render (before paint)- Stored in
localStoragekeyportfolio-theme
Data Layer
src/data/profile.ts— name, title, bio, linkssrc/data/skills.ts— skill groups → skillssrc/data/experience.ts— work history entriessrc/data/projects.ts— project cards with categoriessrc/data/resume.ts— resume availability, supported languages, URL generation
Component Structure
src/
components/
layout/ — Layout.tsx, Navigation.tsx, Footer.tsx
sections/ — Hero, About, Expertise, Experience, Projects, Contact, HeroParticles, DownloadResume
ui/ — Badge, Button, Card, SectionHeading, SocialLinks, Tag, Typewriter, AnimatedSection, InView, RollingTextLink, BackToTop
index.ts — barrel export
data/ — profile, skills, experience, projects, resume (TS modules)
hooks/ — useTheme.tsx, useClickOutside.ts
pages/ — HomePage, AboutPage, ExperiencePage, ProjectsListPage, ProjectDetailPage, PhilosophyPage, ContactPage, index.ts
types/ — shared TypeScript interfaces
Motion & Animation
motion/reactv14 — ESM-first entrypoint (NOTframer-motion)AnimatedSection.tsx— scroll-triggered motion animation wrapperInView.tsx— viewport intersection observer motion componentRollingTextLink.tsx— animated text-scrolling navigation linkBackToTop.tsx— scroll-to-top floating button with AnimatePresenceHeroParticles.tsx— decorative particle background (uses AnimatePresence)
External Assets
public/fonts/— Inter font (Regular, Medium, SemiBold, Bold) in woff2public/icons.svg— SVG sprite for iconspublic/resume-template.html— HTML template for resume PDF generationpublic/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 configdocker-compose.yaml— Docker service for local nginx deployment
.gitea/
└── workflows/
└── deploy.yml
nginx.conf
docker-compose.yaml
CSS Architecture
src/index.css— CSS variables (root +[data-theme="dark"]), global resetssrc/App.css— component-level styles (Navigation, Footer, page sections)- No CSS library — plain CSS with variables for theming
#main-contentin Layout hasstyle={{ flex: 1 }}(parent#rootisdisplay: flex; flex-direction: column)
Known Issues & Gotchas
- React Router v8 routing: Use
<Layout><Routes>...</Routes></Layout>, NOT<Route element={<Layout />}>with nested routes — the latter doesn't passchildrencorrectly - Import path: All router imports use
react-router(notreact-router-dom) — e.g.,import { Link, useLocation } from 'react-router' - Animation imports: Use
motion/react(v14 ESM), NOTframer-motion— e.g.,import { motion, AnimatePresence } from 'motion/react' - 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 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) |
Read spec.md first for product context. Read spec-v2.md for current feature scope.
Code Style & Linting
- TypeScript:
verbatimModuleSyntax,noUnusedLocals,noUnusedParameters,noFallthroughCasesInSwitch - Oxlint:
react/rules-of-hooks= error,react/only-export-components= warn - No framework-specific CSS library — plain CSS with CSS variables
- Data-driven: all content from TS modules, not hardcoded in JSX