mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
Timeline structure
- Spine drawn per node (.timeline-entry::before) instead of one line on .timeline, so it ends at
the TLDR diamond; marker and spine centres coincide at x=6 (gutter 36 desktop / 28 mobile)
- TLDR terminal node: markup in ExperiencePage + Experience section, copy in i18n/strings.ts
(experience.tldr / experience.tldrText), CSS .timeline-tldr* (stub, accent link, hollow
diamond, chip, text)
- ExperienceEntry gains variant?: 'current' | 'gap'; the class is composed in JSX rather than
hard-coding entry ids
Node decoration
- current node: TLDR-family panel (--bg-surface, 1px --border, radius-lg, whisper shadow) with a
2px accent left edge, real entry padding (16/18/20, mobile 14/16/18) and a pulsing marker;
mobile pulse capped at 6px spread so the ring never touches the panel border
- gap node: dashed spine (repeating-linear-gradient), 10px muted marker, no divider,
italic-muted title and company
Data
- New relax-gap entry (Aug 2026 – Oct 2026) between open-to-work and lazada-senior-swe; unique
entry ids; Nexts and SAP bullets aligned across VI/EN
Typography
- Add --measure-page (680px); .prose-wide / .lede-wide; .page-body 700 -> 680; philosophy grid
3 columns, 2 at <=1024px
Cleanup
- Achievements dropped from the SPA timeline and their dead .achievement* rules deleted
(.achievement-metric kept: projects pages still use it)
Resume generator
- "${exp.achievements?.map(...).join('')}" short-circuited the whole chain and printed the
literal "undefined" in every PDF once an entry had no achievements; now (exp.achievements ?? [])
Docs: spec-ui-experience.md, spec-v3-typography.md, AGENTS.md
Verified: tsc -b clean; vite build green; oxlint 11 errors / 9 warnings (HEAD baseline was 15/9 —
the four that disappeared were the achievements markup findings); pnpm build:resume-all renders
both PDFs with the new ordering and no "undefined".
8.5 KiB
8.5 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/— Source Sans 3 woff2 (Regular, Medium, Semibold, Bold); used by the resume generator only — the SPA renderssystem-uipublic/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 (:rootdark default,[data-theme="light"], plus aprefers-color-scheme: lightbridge), global resets, typography scalesrc/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)
Typography
- Scale tokens in
src/index.css:--text-body: 18px,--text-lede: 20px,--text-meta: 15px,--leading-body: 1.65,--measure-prose: 600px,--measure-page: 680px - Global:
p=--text-body/--leading-body;h321px,h418px,h516px,h615px - Two measures:
.prose(600px) for long-form narrative,.prose-wide(680px, body steps up to--text-lede) for page-length prose. A lead paragraph uses.prose-lede(600px), or.prose-lede lede-wide(680px) when it sits next to a full-width grid. Non-prose columns use.page-body(--measure-page); titles inside a column use.subheading - Cards and grids take the full container width; text columns do not.
/aboutand the homepage About section usecontainer-widewith.philosophy-gridat 3 columns (2 at ≤1024px, 1 at ≤768px), the same model as.expertise-grid - Body copy sizes come from the tokens; 12-14px literals are reserved for chrome (tags, badges, pills, footer, duration labels)
- Components MUST NOT set
fontSize/lineHeightinline — use the classes above - Font stack is
system-ui: no webfont is loaded by the SPA. The Source Sans 3 woff2 files inpublic/fonts/are consumed only byscripts/generate-resume.ts - Spec:
docs/design/specs/v3/spec-v3-typography.md
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.
Specification Rules
When proposing or implementing changes, always include these 3 sections:
1. Implementation Details
- Describe every code step: what to write, edit, or delete
- List new imports, functions, props, state, CSS classes
- Identify edge cases and error handling
2. Affected Files
- File + line range to edit:
src/foo.ts:42-57 - New file to create:
src/bar.ts - File to delete:
src/dead.ts
3. Progress Tracking
- Update relevant spec with status:
TODO/IN_PROGRESS/DONE - Record which acceptance criteria were verified
- Format: checklist in spec or inline code comments
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