diff --git a/docs/design/specs/v3/spec-v3-resume-improvements.md b/docs/design/specs/v3/spec-v3-resume-improvements.md new file mode 100644 index 0000000..440fdd0 --- /dev/null +++ b/docs/design/specs/v3/spec-v3-resume-improvements.md @@ -0,0 +1,364 @@ +# Specification — v3 Resume PDF Improvements + +> **Document:** `spec-v3-resume-improvements.md` +> **Version:** 0.3.0 (adds section reordering: Projects → Skills) +> **Parent:** `spec-v2-resume-playwright.md` +> **Priority:** P2 +> **Estimate:** ~1 hour + +--- + +## Problem + +### 1. Missing Professional Summary in Resume + +The resume PDF lacks a professional summary section. Currently it goes directly from header to experience, which is less informative for recruiters who scan the top of a resume first. + +The `{{BIO}}` placeholder is resolved in `scripts/generate-resume.ts` (line 145) but never rendered in the HTML template — dead code. + +### 2. Inter Font Poor Vietnamese Support + +Current font **Inter** does not render Vietnamese diacritics well in PDF output. Characters like `ơ`, `ư`, `đ`, `ê`, `ô` may appear broken or misaligned. + +**Decision:** Replace Inter with **Source Sans 3** (Adobe open-source) — excellent Vietnamese support, professional style, similar to Inter's clean aesthetic. + +### 3. No HTML Preview Mode for Debugging + +When debugging PDF layout, the only option is to generate the full PDF and open it. This requires: +- Running Playwright (slow) +- Waiting for Chromium to launch +- Generating PDF (2-3s) +- Opening PDF viewer + +Layout iteration takes 5-10 seconds per cycle. Adding a preview mode that opens HTML directly in the browser would reduce iteration to <1 second. + +--- + +## Goal + +1. Add "About me" section with bio content after header, before Experience +2. Add `--preview` flag to open rendered HTML in browser (no PDF generation) +3. Add `build:resume-preview` npm script for convenience +4. Replace Inter font with Source Sans 3 for better Vietnamese support +--- + +## Current Implementation + +### Script: `scripts/generate-resume.ts` + +Bio resolved but not rendered: +```typescript +// Line 145 — resolves bio but template has no {{BIO}} placeholder +.replace('{{BIO}}', resolveField(profile.bioEn, profile.bio)) +``` + +PDF generation (lines 160-178): +```typescript +const browser = await chromium.launch(); +const page = await browser.newPage(); +await page.setContent(html); + +const langSuffix = lang === 'en' ? '' : `-${lang}`; +const outputPath = join(ROOT, `dist/resume${langSuffix}.pdf`); +await page.pdf({ + path: outputPath, + format: 'A4', + printBackground: true, + title: `Resume - ${profile.name} (${lang === 'en' ? 'English' : 'Vietnamese'})`, + author: profile.name, +}); + +await browser.close(); +console.log(`resume${langSuffix}.pdf generated at ${outputPath} [${lang}]`); +``` + +### Template: `public/resume-template.html` + +Structure (lines 259-298): +```html + + +
...
+ + +
...
+ + +
...
+ + +
...
+ + +
...
+ + + + +``` + +No `{{BIO}}` placeholder exists in the template. + +### Package.json Scripts + +```json +{ + "scripts": { + "build:resume": "pnpm tsx scripts/generate-resume.ts", + "build:resume-all": "pnpm tsx scripts/generate-resume.ts --lang=en && pnpm tsx scripts/generate-resume.ts --lang=vi" + } +} +``` + +--- + +## Implementation + +### Font Change: Inter → Source Sans 3 + +**Files affected:** +- `public/fonts/` — replace `Inter-*.woff2` with `SourceSans3-*.woff2` +- `scripts/generate-resume.ts` — update font file names and weight mapping +- `public/resume-template.html` — update `@font-face` font-family name + +**Source Sans 3 weights needed:** +- Regular (400) → `SourceSans3-Regular.ttf.woff2` +- Medium (500) → `SourceSans3-Medium.ttf.woff2` +- Semibold (600) → `SourceSans3-Semibold.ttf.woff2` +- Bold (700) → `SourceSans3-Bold.ttf.woff2` + +**Script changes:** +1. Replace font file names in the validation loop and font loading loop +2. Update `@font-face` CSS to use `font-family: 'Source Sans 3'` +3. Update `body { font-family: 'Inter', ... }` → `font-family: 'Source Sans 3', ...` + +**Note:** Download fonts from [Adobe Fonts / Google Fonts](https://fonts.google.com/specimen/Source+Sans+3). Extract `.woff2` files from the TTF/OTF originals using a converter if needed. + +### Section Reordering: Projects → Skills + +**Current order:** Header → About me → Experience → Skills → Projects +**New order:** Header → About me → Experience → Projects → Skills + +**Rationale:** Skills are more generic/less impactful than Projects. Placing Projects before Skills gives recruiters a clearer view of concrete work experience before technical skills. + +**Change:** Swap the Projects and Skills `
` blocks in `public/resume-template.html` (around lines 280-292). + +### Step 1: Add CSS for About me Section + +**File:** `public/resume-template.html:56-60` + +Add after `.header-info .contact` style block: + +```css + /* About me */ + .about-summary { + font-size: 9.5pt; + color: #4a4a4a; + line-height: 1.6; + margin-bottom: 12px; + page-break-inside: avoid; + } +``` + + +### Step 2: Add About me Section to Template + +**File:** `public/resume-template.html:272-273` + +Insert between header `
` and Experience `
`: + +```html + +
+
{{ABOUT_ME_LABEL}}
+
{{BIO}}
+
+ + +
...
+ + +
...
+ + +
...
+``` + +**Note:** The section uses `.section` class which has `page-break-before: always` for subsequent sections. Since About me comes right after header (first section), it will NOT trigger a page break — it flows naturally after the header on the same page. + + +### Step 3: Reorder Sections (Projects → Skills) + +**File:** `public/resume-template.html:280-292` + +Swap the Projects and Skills `
` blocks: + +```html + +
...
+ + +
...
+ + +
...
+``` +### Step 4: Add --preview Flag to Script + +**File:** `scripts/generate-resume.ts` + +Add preview mode detection after language parsing (around line 15): + +```typescript +// --- CLI args --- +const args = process.argv.slice(2); +const langArg = (args.find(a => a.startsWith('--lang=')) || '').replace('--lang=', '') as Language; +const lang: Language = (langArg === 'en' || langArg === 'vi') ? langArg : 'en'; +const previewMode = args.includes('--preview'); +``` + +Add `ABOUT_ME` to labels object (around line 66): + +```typescript +const labels: Record> = { + en: { + EXPERIENCE: 'Experience', + SKILLS: 'Skills', + PROJECTS: 'Projects', + ABOUT_ME: 'About me', + }, + vi: { + EXPERIENCE: 'Kinh nghiệm', + SKILLS: 'Kỹ năng', + PROJECTS: 'Dự án', + ABOUT_ME: 'Về tôi', + }, +}; +``` + +Replace PDF generation block (lines 160-178) with conditional: + +```typescript +// --- Generate output --- +const browser = await chromium.launch(); +const page = await browser.newPage(); +await page.setContent(html); + +if (previewMode) { + await page.bringToFront(); + console.log(`Preview opened in browser [${lang}] — close manually to exit`); + await new Promise(() => {}); // Keep browser open indefinitely +} else { + const langSuffix = lang === 'en' ? '' : `-${lang}`; + const outputPath = join(ROOT, `dist/resume${langSuffix}.pdf`); + await page.pdf({ + path: outputPath, + format: 'A4', + printBackground: true, + title: `Resume - ${profile.name} (${lang === 'en' ? 'English' : 'Vietnamese'})`, + author: profile.name, + }); + + await browser.close(); + console.log(`resume${langSuffix}.pdf generated at ${outputPath} [${lang}]`); +} +``` + +**Behavior:** +- `--preview` opens browser with rendered HTML, waits for user to close manually +- No PDF generated, no file saved +- User can inspect layout, test CSS changes, then re-run with `pnpm build:resume` to generate PDF +- `await new Promise(() => {})` — empty promise that never resolves, keeps process alive until user closes browser + +**Edge cases:** +- `--preview` with `--lang=vi` works correctly +- `--preview` cannot be combined with normal output (no PDF + preview at same time) — not a use case +- Ctrl+C still terminates the process (Node.js signal handling) + + +### Step 5: Add build:resume-preview Script + +**File:** `package.json` + +Add after `build:resume-all`: + +```json +{ + "scripts": { + "build:resume": "pnpm tsx scripts/generate-resume.ts", + "build:resume-all": "pnpm tsx scripts/generate-resume.ts --lang=en && pnpm tsx scripts/generate-resume.ts --lang=vi", + "build:resume-preview": "pnpm tsx scripts/generate-resume.ts --preview" + } +} +``` + +### Step 6: Remove Dead {{TAGLINE}} Replace + +**File:** `scripts/generate-resume.ts:144` + +Remove the dead replace since `{{TAGLINE}}` is also not in the template: + +```diff +- .replace('{{TAGLINE}}', resolveField(profile.taglineEn, profile.tagline)) +``` + +--- + +## Acceptance Criteria + +| # | Requirement | Status | +|---|-------------|--------| +| 1 | "About me" section appears after header, before Experience | ✅ | +| 2 | Bio content uses `resolveField` for bilingual support | ✅ | +| 3 | About me section title is bilingual (EN: "About me", VI: "Về tôi") | ✅ | +| 4 | About me section has page-break-inside: avoid | ✅ | +| 5 | About me flows on same page as header (no forced page break) | ✅ | +| 7 | `{{TAGLINE}}` dead code removed | ✅ | +| 8 | `build:resume-all` still generates both EN and VI PDFs | ✅ | +| 9 | `{{BIO}}` placeholder now rendered in template (no longer dead code) | ✅ | +| 10 | Source Sans 3 replaces Inter — Vietnamese diacritics render correctly | ✅ | + +--- + +## Tradeoffs + +| Aspect | Detail | +|--------|--------| +| About me page break | Uses `.section` class (page-break-before on subsequent sections) — About me is second section, header is first, so no page break triggered | +| Preview mode lifecycle | `await new Promise(() => {})` — process stays alive until Ctrl+C or browser window closed | +| Bio length | ~2 lines in English, ~2-3 lines in Vietnamese — fits comfortably on page 1 after header | +| CSS specificity | `.about-summary` is standalone class, no conflict with existing styles | +| Font change | Source Sans 3 ~900KB (4 weights) vs Inter ~800KB — slight size increase (~100KB) | + +--- + +## Files Changed + +| File | Action | Lines | +| `public/fonts/` | Replace | 4 files: Inter → Source Sans 3 (Regular, Medium, Semibold, Bold) | +| `public/resume-template.html` | Edit | +9 lines (CSS), +5 lines (HTML body), ~12 lines (section reorder) | +| `scripts/generate-resume.ts` | Edit | +3 lines (preview flag), +15 lines (labels ABOUT_ME), +15 lines (conditional generation), +3 lines (ABOUT_ME replace), -1 line (dead TAGLINE) | +| `package.json` | Edit | +1 line (new script) | + +--- + +## Bugs Fixed + +| # | Issue | Fix | ++---|-------|-----| ++ 1 | `@font-face` font-family was `'Inter'` but body uses `'Source Sans 3'` — PDF would fallback to system font | Changed `scripts/generate-resume.ts:55` to `font-family: 'Source Sans 3'` | + +--- + +## Progress + +- [x] Font: Replace Inter with Source Sans 3 (4 weights) in `public/fonts/`, script, and template +- [x] Step 1: CSS for About me section +- [x] Step 2: About me section in template +- [x] Step 3: Reorder sections (Projects → Skills) +- [x] Step 4: Add --preview flag, labels ABOUT_ME, and ABOUT_ME_LABEL replace +- [x] Step 5: Add build:resume-preview script +- [x] Step 6: Remove dead {{TAGLINE}} replace +- [x] Verify: `pnpm build:resume` generates correct PDF +- [x] Verify: `pnpm build:resume-preview` opens browser +- [x] Verify: `pnpm build:resume-all` generates both languages diff --git a/package.json b/package.json index 6b8fed8..32bb3bf 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,7 @@ "build": "tsc -b && vite build", "build:resume": "pnpm tsx scripts/generate-resume.ts", "build:resume-all": "pnpm tsx scripts/generate-resume.ts --lang=en && pnpm tsx scripts/generate-resume.ts --lang=vi", + "build:resume-preview": "pnpm tsx scripts/generate-resume.ts --preview", "lint": "oxlint", "preview": "vite preview" }, diff --git a/public/fonts/Inter-Bold.woff2 b/public/fonts/Inter-Bold.woff2 deleted file mode 100644 index 775f757..0000000 Binary files a/public/fonts/Inter-Bold.woff2 and /dev/null differ diff --git a/public/fonts/Inter-Medium.woff2 b/public/fonts/Inter-Medium.woff2 deleted file mode 100644 index 21db794..0000000 Binary files a/public/fonts/Inter-Medium.woff2 and /dev/null differ diff --git a/public/fonts/Inter-Regular.woff2 b/public/fonts/Inter-Regular.woff2 deleted file mode 100644 index 891fc5c..0000000 Binary files a/public/fonts/Inter-Regular.woff2 and /dev/null differ diff --git a/public/fonts/Inter-SemiBold.woff2 b/public/fonts/Inter-SemiBold.woff2 deleted file mode 100644 index da1c039..0000000 Binary files a/public/fonts/Inter-SemiBold.woff2 and /dev/null differ diff --git a/public/fonts/SourceSans3-Bold.woff2 b/public/fonts/SourceSans3-Bold.woff2 new file mode 100644 index 0000000..1c2cb41 Binary files /dev/null and b/public/fonts/SourceSans3-Bold.woff2 differ diff --git a/public/fonts/SourceSans3-Medium.woff2 b/public/fonts/SourceSans3-Medium.woff2 new file mode 100644 index 0000000..9cb2648 Binary files /dev/null and b/public/fonts/SourceSans3-Medium.woff2 differ diff --git a/public/fonts/SourceSans3-Regular.woff2 b/public/fonts/SourceSans3-Regular.woff2 new file mode 100644 index 0000000..181ee87 Binary files /dev/null and b/public/fonts/SourceSans3-Regular.woff2 differ diff --git a/public/fonts/SourceSans3-Semibold.woff2 b/public/fonts/SourceSans3-Semibold.woff2 new file mode 100644 index 0000000..31e52bc Binary files /dev/null and b/public/fonts/SourceSans3-Semibold.woff2 differ diff --git a/public/resume-template.html b/public/resume-template.html index 269ab09..ea8a0eb 100644 --- a/public/resume-template.html +++ b/public/resume-template.html @@ -17,7 +17,7 @@ *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; } body { - font-family: 'Inter', system-ui, -apple-system, sans-serif; + font-family: 'Source Sans 3', system-ui, -apple-system, sans-serif; font-size: 10pt; line-height: 1.5; color: #1a1a1a; @@ -59,9 +59,12 @@ line-height: 1.6; } - /* Section — all sections except first get page break */ - .section + .section { - page-break-before: always; + /* About me */ + .about-summary { + font-size: 9.5pt; + color: #4a4a4a; + line-height: 1.6; + margin-bottom: 12px; } .section-title { @@ -74,7 +77,6 @@ border-bottom: 1px solid #ccc; margin-bottom: 10px; } - /* Experience */ .exp-entry { margin-bottom: 12px; @@ -241,12 +243,8 @@ margin-top: 2px; } - /* Page break helpers */ - .avoid-break { page-break-inside: avoid; } - /* Version stamp footer */ .pdf-footer { - page-break-inside: avoid; text-align: center; font-size: 8pt; color: #999; @@ -271,12 +269,23 @@
+ +
+
{{BIO}}
+
+
{{EXPERIENCE_LABEL}}
{{EXPERIENCE}}
+ +
+
{{PROJECTS_LABEL}}
+ {{PROJECTS}} +
+
{{SKILLS_LABEL}}
@@ -285,12 +294,6 @@
- -
-
{{PROJECTS_LABEL}}
- {{PROJECTS}} -
-