mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
Preview chips now mirror the bar swatch: --preview-*-accent is declared per theme (dark #f87171/#60a5fa, light #b04138/#2563eb, repeated in the prefers-color-scheme bridge) and the two [data-palette=blue] blocks declare nothing, since a chip names its own palette through data-preview. --preview-*-bg is deleted; chips take the shared --border-strong hairline. Dark-mode dots move from 2.53/3.13 to 5.24/6.36 against their panel. The hamburger leads the bar in a new .nav-brand group (trigger then brand), and the wordmark becomes a 24px stroke home icon in a 44px target with a :focus-visible ring, still a <Link to="/">. .logo-bracket/.logo-text are removed and the <=420px guard drops its brand-gap override: the row measures 252px inside 288px. Docs: new specs/v3/spec-v3-nav-swatch-and-hamburger.md plus supersession notes in spec-v3-mobile-navigation, spec-v3-theme-palette-switch and spec-v3-ui-enhancements; AGENTS.md, spec-ui-layout and spec-ui-navigation updated. Gates: tsc+vite build exit 0, oxlint 15 findings (11 rules-of-hooks, unchanged baseline), zero hex in App.css, 12/12 SSR bar-order assertions.
192 lines
14 KiB
Markdown
192 lines
14 KiB
Markdown
# 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.tsx` wraps `<BrowserRouter>` → `<Layout>` → `<Routes>` (NOT nested `<Route element>` — causes `children` not 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>` with `target="_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 |
|
||
| `/contact` | `ContactPage` | Contact info |
|
||
| `/philosophy` | `PhilosophyPage` | Engineering philosophy |
|
||
|
||
## Theming
|
||
|
||
- Two independent axes on `<html>`: lightness (`Theme`) and color (`Palette`), both written during render before paint
|
||
- `src/hooks/useTheme.tsx` — `ThemeProvider` + `useTheme` hook, carries both axes
|
||
- Simple toggle: `'dark'` ↔ `'light'` (no `system` variant); `resolvedTheme` — runtime resolved value (always `'dark'` or `'light'`)
|
||
- `data-theme` attribute + `localStorage` key `portfolio-theme`
|
||
- `type Palette = 'red' | 'blue'` (`src/types/index.ts`), labels/hints in `src/data/palettes.ts` (`paletteIds`, `paletteMeta`); default `red`
|
||
- `data-palette` attribute + `localStorage` key `portfolio-palette`; `index.html`'s init script writes both attributes before paint
|
||
- Palette overrides in `src/index.css` are `:root[data-theme='dark'][data-palette='blue']` / `:root[data-theme='light'][data-palette='blue']` (specificity 0,3,0 — they beat the base blocks regardless of order); no blue variant exists in the `prefers-color-scheme` bridge, because the init script always writes `data-palette`
|
||
- Accent has two tiers: `--accent` / `--accent-hover` / `--accent-active` are the bright signal colours (links, underlines, borders, glows) and the fill of the pale accent surfaces (palette-option hover, `.tag-accent`, `.back-to-top`, resume summary bar); `--accent-solid` / `-hover` / `-active` plus `--text-on-accent-solid` are the deeper fill and light text used by `.btn-primary` and `.badge-accent`, which is what lets a dark-mode button carry light text. The solid family is declared in all five blocks of `src/index.css` (dark red, light red, dark blue, light blue, the `prefers-color-scheme` bridge); the two light blocks duplicate the plain accent values verbatim, so light mode does not move. Spec: `docs/design/specs/v3/spec-v3-nav-cta-enhancements.md`
|
||
- Picker, two renderings, both present at every width: the bar uses `src/components/layout/ThemePaletteMenu.tsx` — icon-only trigger (`nav-control nav-palette-trigger`, a 20px half-circle swatch: active palette's accent on the left, `--swatch-empty` on the right; no text, no chevron; the name lives in `aria-label`, the hint in `title`) opening the `#palette-menu` panel. The sheet renders its own Theme color row inside `MobileMenu.tsx` from `paletteIds` + `paletteMeta` as `.mobile-menu-swatch-option` buttons — the same segmented shape as the Mode/Language rows, options drawn as colour icons via `.nav-palette-preview`. `ThemePaletteMenu` has no `variant` prop and is never mounted in the sheet
|
||
- Preview chips are theme-aware: `--preview-red-accent` / `--preview-blue-accent` are declared per theme — `:root` dark pair, `:root[data-theme='light']` light pair, repeated in the `prefers-color-scheme` bridge — and mirror that block's `--accent`, so a submenu dot and the bar swatch's accent half are the same colour in the same theme. Each chip names its own palette through `data-preview`, so the two `[data-palette='blue']` blocks declare no preview token; `--swatch-empty` stays one constant. Spec: `docs/design/specs/v3/spec-v3-nav-swatch-and-hamburger.md`
|
||
- Bar controls share one chrome: `.nav-control` covers the language toggle, the mode toggle and the palette trigger (44px bordered box, accent border + text on hover/open, one `:focus-visible`). The hamburger leads the bar at every width it appears: `.nav-brand` (`display: flex; gap: 12px`) holds it first and the brand home icon right after, at the bar's left edge — `.nav-logo` is a 24px stroke house in a 44px target, a `<Link to="/">` named by the translated `strings.nav.home` label with the svg `aria-hidden`, so it carries its own `:focus-visible` ring. `.nav-actions` then carries the three appearance controls in that order (language, mode, theme color) at the right end. The sheet's Appearance group follows the same order (Language row, Mode row, Theme color row). `@media (max-width: 420px)` tightens the container padding and the action gap so the row fits a 320px viewport (40 + 12 + 44 + 44×3 + 12×2 = 252px inside 288px)
|
||
|
||
## Data Layer
|
||
|
||
- `src/data/profile.ts` — name, title, bio, links
|
||
- `src/data/skills.ts` — skill groups → skills
|
||
- `src/data/experience.ts` — work history entries; optional `variant: 'current' | 'gap'` selects the timeline decoration (live node / career break)
|
||
- `src/data/projects.ts` — project cards with categories
|
||
- `src/data/resume.ts` — resume availability, supported languages, URL generation
|
||
- `src/data/navigation.ts` — `navPaths` (bar + sheet order: Home, About, Experience, Projects, Contact, Philosophy), `footerPaths`
|
||
- `src/data/social.ts` — social tiles as `{id, href, external}`; `email` is a `mailto:` link with `external: false`, so it renders no `target`/`rel`
|
||
- `src/i18n/strings.ts` — every chrome string as `{en, vi}`; the sheet's group labels, Mode/Language options and the social `aria-label`s live in `strings.nav` / `strings.social`
|
||
|
||
## Component Structure
|
||
|
||
```
|
||
src/
|
||
components/
|
||
layout/ — Layout.tsx, Navigation.tsx, MobileMenu.tsx, Footer.tsx, ThemePaletteMenu.tsx
|
||
sections/ — Hero, About, Expertise, Experience, Projects, Contact, HeroParticles, DownloadResume
|
||
ui/ — Badge, Button, SectionHeading, SocialLinks, Tag, Typewriter, InView, RollingTextLink, BackToTop
|
||
index.ts — barrel export
|
||
data/ — profile, skills, experience, projects, resume, palettes, navigation, social (TS modules)
|
||
hooks/ — useTheme.tsx, useLanguage.tsx, useClickOutside.ts
|
||
pages/ — HomePage, AboutPage, ExperiencePage, ProjectsListPage, ProjectDetailPage, PhilosophyPage, ContactPage, index.ts
|
||
types/ — shared TypeScript interfaces
|
||
```
|
||
|
||
## Motion & Animation
|
||
|
||
- `motion/react` v14 — ESM-first entrypoint (NOT `framer-motion`)
|
||
- Section entrance recipe — every section (`Hero`, `About`, `Expertise`, `Experience`, `Projects`, `Contact`) and every standalone page: `InView` wrapping a `motion.section` with `initial="hidden" whileInView="visible"`, `viewport={{ once: true, amount: 0.1 }}` and `variants` `hidden: { opacity: 0 }` / `visible: { opacity: 1, transition: { duration: 0.5 } }`
|
||
- Item recipe (timeline entries, philosophy/expertise/project cards, hero content blocks, contact links, project-detail blocks): `motion.*` with `initial={{ opacity: 0, y: 24 }}`, `whileInView={{ opacity: 1, y: 0 }}`, `viewport={{ once: true, amount: 0.2 }}`, `transition={{ duration: 0.45, ease: 'easeOut', delay: i * 0.08 }}`
|
||
- Hover/press recipe — motion owns the transform, CSS `:hover` only colour/border/shadow: cards and links (`.project-card`, `.expertise-card`, `.philosophy-card`, `.contact-link`) use `whileHover={{ scale: 1.02, y: -4 }}` + `whileTap={{ scale: 0.98 }}`; `Button` uses `whileHover={{ y: -2 }}` + `whileTap={{ scale: 0.95 }}`; `.social-link` tiles use `scale: 1.1` / `0.9`. A motion-animated element never carries a CSS `transform` or `transition: all`
|
||
- `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)
|
||
- Palette swatch rotation — `ThemePaletteMenu.tsx` renders the swatch as a `motion.span` whose `rotate` target is 90° while the `#palette-menu` submenu is open and 0° otherwise; reduced motion comes from the global `motion.config.reducedMotion = 'user'` in `main.tsx`, so no per-component branch
|
||
|
||
## External Assets
|
||
|
||
- `public/fonts/` — Source Sans 3 woff2 (Regular, Medium, Semibold, Bold); used by the resume generator only — the SPA renders `system-ui`
|
||
- `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
|
||
|
||
- `src/index.css` — CSS variables (`:root` dark default, `[data-theme="light"]`, plus a `prefers-color-scheme: light` bridge), global resets, typography scale
|
||
- `src/App.css` — component-level styles (Navigation, Footer, page sections)
|
||
- 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`)
|
||
|
||
## 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`; `h3` 21px, `h4` 18px, `h5` 16px, `h6` 15px
|
||
- 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. `/about` and the homepage About section use `container-wide` with `.philosophy-grid` at 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` / `lineHeight` inline — use the classes above
|
||
- Font stack is `system-ui`: no webfont is loaded by the SPA. The Source Sans 3 woff2 files in `public/fonts/` are consumed only by `scripts/generate-resume.ts`
|
||
- Spec: `docs/design/specs/v3/spec-v3-typography.md`
|
||
|
||
## 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
|
||
2. **Import path:** All router imports use `react-router` (not `react-router-dom`) — e.g., `import { Link, useLocation } from 'react-router'`
|
||
3. **Animation imports:** Use `motion/react` (v14 ESM), NOT `framer-motion` — e.g., `import { motion, AnimatePresence } from 'motion/react'`
|
||
4. **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, theme palette switch, UI enhancements, mobile navigation, nav & CTA 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
|