# Specification — v3 Typography scale and readability > **Document:** `spec-v3-typography.md` > **Version:** 1.0.0 > **Parent:** `spec.md` (IA/content readability), sibling of `spec-v3-theme-palette-gasatrya.md` > **Priority:** P1 > **Status:** Implemented in source. `tsc -b` and the production build are green; the visual pass is the user's in a real browser (project rule: no headless verification). --- ## 1. Problem Reported: the Philosophy page reads small and hard to follow. Measured, the cause is four things at once, and the same drift exists on every page. | # | Finding | Evidence | |---|---|---| | P1 | Philosophy body copy is the smallest in the app: **16px / 1.7**, while About's bio and the project-detail summary — the same "lead paragraph" role — are 18px | `PhilosophyPage.tsx:17` (no `font-size`, falls back to `:root { font-size: 16px }`) vs `AboutPage.tsx:22` and `ProjectDetailPage.tsx:37` inline `18px` | | P2 | **No space between paragraphs.** `* , ::before, ::after { margin: 0 }` resets `p`, and nothing re-adds it, so the three paragraphs of a quote render as one block | `index.css` reset, `strings.ts:82-87` (three `

` blocks per quote) | | P3 | **Measure too wide**: `.container-content` = 800px − 48px padding = 752px of text; Philosophy has no narrower cap (About caps itself at 700px inline) | `index.css` `.container-content`, `AboutPage.tsx:21` | | P4 | Markup bug: the quote HTML already contains `

…

` and was injected **inside** a `

` (nested paragraphs). `aria-labelledby="engineering-heading"` pointed at an id no element had (`SectionHeading` only takes `id` as a prop) | `PhilosophyPage.tsx:9,17`, `SectionHeading.tsx:5,10` | | P5 | **No `@font-face` anywhere in the app.** `--sans` named `Inter`, which is neither shipped nor linked, so the SPA always rendered `system-ui` (Segoe UI on Windows). The four woff2 files in `public/fonts/` are Source Sans 3 and are read only by `scripts/generate-resume.ts:21-24,43-57` | repo-wide grep for `@font-face` → 0 hits in `src/`, `index.html` | | P6 | Same role, many sizes: body copy 16 / 18 / 14px; sub-headings 24 (global `h3`) / 20 / 18 / 16 / 14px; `h4-h6` had no size at all and fell back to 16px | audit table, §2 | | P7 | `line-height` drift: `p` got 1.7, every `div`/`li`/`a` inherited 1.6 from `:root`, and `.project-card-summary` was explicitly set to 1.6 while the same 14px `.philosophy-card p` inherited 1.7 | `App.css` `.project-card-summary`, `.philosophy-card p` | | P8 | ~20 inline `style` objects in TSX carried the type decisions, and **no `@media` block anywhere changes `font-size` or `line-height`** | `PhilosophyPage.tsx:13,17`, `AboutPage.tsx:21,22,26,43`, `About.tsx:14,15,19,36`, `ProjectDetailPage.tsx:28,37,43,55,60,70,73,74`, `ExperiencePage.tsx:33,37`, `Experience.tsx:28,78`, `ContactPage.tsx:18,19,27,28,36,37`, `Contact.tsx:25,45,48,70,73,95,98`, `Projects.tsx:36`, `DownloadResume.tsx:96` | ## 2. Measurements Method: `fontTools` over the shipped `public/fonts/SourceSans3-Regular.woff2` and the font that actually renders today (`C:/Windows/Fonts/segoeui.ttf`), summing glyph advances of one 221-character English sample from the Philosophy text. No browser involved. | Font | x-height | cap height | avg advance | 16px | 18px | |---|---|---|---|---|---| | Segoe UI (what renders today) | 0.500 em | 0.700 em | 0.4273 em | 6.84 px/char | 7.69 px/char | | Source Sans 3 (shipped, resume-only) | 0.486 em | 0.660 em | 0.3996 em | 6.39 px/char | 7.19 px/char | Characters per line at each candidate measure: | Measure @ size | Segoe UI | Source Sans 3 | |---|---|---| | 752px @16px — **before** | 110 | 118 | | 700px @16px — About's own cap | 102 | 110 | | **600px @18px — after** | **78** | **83** | | 560px @18px — stricter editorial band | 73 | 78 | Reading bands used: 45-75 characters (Bringhurst), 38-80 (Butterick). Before: 110-118. After: 78-83. ## 3. Decisions 1. **Font: admit `system-ui`.** `--sans` becomes `system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif`. No webfont is loaded; the Source Sans 3 woff2 files stay in `public/fonts/` because `scripts/generate-resume.ts` reads them from disk for the PDF. (User's call: keep the current look rather than restyle the whole site.) 2. **Five scale tokens** in `:root`: `--text-body: 18px`, `--text-lede: 20px`, `--text-meta: 15px`, `--leading-body: 1.65`, `--measure-prose: 600px`. They live in `:root` only — sizes do not differ between dark and light, so they are not duplicated in the light block or the media bridge. 3. **Reuse `.prose`** (`App.css`, previously defined and never rendered by any component) as the prose system instead of inventing a second convention. 4. **Role sizes.** Body copy 18px/1.65 everywhere a paragraph is the main content; lead paragraphs 20px/1.55; dense secondary copy (timeline bullets, achievement context and impact, expertise skill lists, card summaries, contact sub-labels) 15px/1.65. Literal 12-14px stays reserved for chrome: `.tag`, `.badge`, `.achievement-metric`, `.footer-text`, `.footer-link`, `.timeline-duration`, `.project-card-cta`, `.lang-toggle`, `pre`. 5. **Heading sizes**: `h3` 24 → **21px**, and `h4` 18 / `h5` 16 / `h6` 15 made explicit (they previously fell back to 16px). `h1`/`h2` clamps and the global `h1-h6 { line-height: 1.2 }` are untouched. 6. **Paragraph rhythm lives only inside `.prose`** (`.prose p { margin-bottom: 1em }`, `:last-child` 0). The global `p` keeps `margin: 0` from the reset, so hero, cards, section subtitles and contact tiles are unaffected. 7. **Headings carry their own top margin** (`.subheading { margin-top: 32px }`, `.prose h3 { margin-top: 1.5em }`, `.philosophy-quote h3 { margin-top: 0 }`); lead paragraphs carry no bottom margin. Sibling margins collapse, so each gap is a single value rather than a sum. 8. **No inline `fontSize` / `lineHeight` / `fontWeight` / text `color` in components.** Layout-only inline styles (`flex`, `gap`, motion `style={{y}}`) are allowed. 9. **Delete dead CSS and the unused `Card` component** rather than leaving unstyled scaffolding behind (list in §4.2). ## 4. Implementation details ### 4.1 `src/index.css` - `:root` token block: `--max-narrow` deleted; added the five scale tokens after `--max-content`. - `--sans` → system stack (finding P5). `--mono` unchanged (it already ends in `ui-monospace, monospace`, so it resolves without a download). - `h3 { font-size: 21px }`; new `h4 { 18px }`, `h5 { 16px }`, `h6 { 15px }`. - `p { font-size: var(--text-body); line-height: var(--leading-body); color: var(--text-secondary); }` — was implicit 16px / 1.7. - `.container-narrow` deleted (no consumer). ### 4.2 `src/App.css` Prose system (rewritten in place of the dead `.prose` block): ``` .prose { max-width: var(--measure-prose); } .prose h2 { margin: 48px 0 16px; font-size: 28px; } .prose h3 { margin: 1.5em 0 0.65em; } /* 21px inherited */ .prose h4 { margin: 1.25em 0 8px; font-size: 16px; line-height: 1.3; } .prose p { margin-bottom: 1em; } .prose p:last-child { margin-bottom: 0; } .prose ul, .prose ol { margin-bottom: 16px; padding-left: 24px; } .prose li { margin-bottom: 8px; color: var(--text-secondary); font-size: var(--text-body); line-height: var(--leading-body); } .prose blockquote { …unchanged… } .prose-lede { max-width: var(--measure-prose); font-size: var(--text-lede); line-height: 1.55; } .page-body { max-width: 700px; } .subheading { margin: 32px 0 12px; } .philosophy-quote + .philosophy-quote { margin-top: 48px; } .philosophy-quote h3 { margin-top: 0; } .project-section { background/border/radius/padding 16px; margin-bottom: 16px; inset highlight; } .project-section h4 { margin-top: 0; } .project-section p { font-size: var(--text-meta); line-height: var(--leading-body); } .back-link, .section-cta { font-size: var(--text-meta); font-weight: 500; color: var(--accent); } .link-label { font-weight: 500; color: var(--text-primary); } .contact-link-sub { font-size: var(--text-meta); line-height: 1.5; color: var(--text-muted); } .achievement-impact { font-size: var(--text-meta); line-height: var(--leading-body); color: var(--text-secondary); margin-bottom: 8px; } .achievement-metrics { margin-bottom: 8px; } ``` Existing rules retuned to the scale: | Selector | Was | Now | |---|---|---| | `.expertise-skill` | 14px, inherited 1.6 | `var(--text-meta)` / `var(--leading-body)` | | `.timeline-title` | 20px, inherited 1.6 | 20px + `line-height: 1.3` | | `.timeline-company` | 16px, inherited 1.6 | 16px + `line-height: 1.4` | | `.timeline-responsibilities li` | 14px / 1.6 | `--text-meta` / `--leading-body` | | `.achievement-title` | 18px / 1.6 | 18px + `line-height: 1.3` | | `.achievement-context` | 14px / 1.6 | `--text-meta` / `--leading-body` | | `.project-card-summary` | 14px / 1.6 | `--text-meta` / `--leading-body` | | `.philosophy-card h3` | 18px / 1.6 | 18px + `line-height: 1.25` | | `.philosophy-card p` | 14px / 1.7 (inherited) | `--text-meta` / `--leading-body` | | `.contact-link` | 16px / 1.6 | 16px + `line-height: 1.4` | Deleted as dead (no component rendered any of them; verified by grepping every class name against `src/**/*.tsx`): `.card`, `.card:hover`, `.card-elevated`, `.card-featured` (and `src/components/ui/Card.tsx` plus its barrel export), `.page-header`, `.breadcrumb*`, `.form-group/label/input/textarea`, `.filter-bar`, `.filter-pill*`, `.article-card`, `.article-meta`, `.engineering-tabs`, `.engineering-tab*`, `.container-narrow`, `--max-narrow`. ### 4.3 TSX | File | Change | |---|---| | `src/pages/PhilosophyPage.tsx` | whole body: `aria-labelledby="philosophy-heading"` matched by ``; quotes wrapped in `

` → `
` → plain `

` + `
` (no outer `

`, so the injected `

` blocks are no longer nested); inline styles and the stale "Placeholder for expanded content" comment removed | | `src/pages/AboutPage.tsx`, `src/components/sections/About.tsx` | `maxWidth:'700px'` div → `.page-body`; bio → `.prose-lede`; both `

` → `.subheading` | | `src/pages/ProjectDetailPage.tsx` | back link → `.back-link`; summary → `.prose-lede`; narrative wrapped in `.prose`; four `marginBottom:'32px'` block wrappers unwound (rhythm now comes from `.prose h3`); four `

` → plain `

`; section cards → `.project-section` with plain `

` / `

` | | `src/pages/ExperiencePage.tsx`, `src/components/sections/Experience.tsx` | impact div → `.achievement-impact`; metrics wrapper → `.achievement-metrics`; `maxWidth:'700px'` → `.page-body` | | `src/pages/ContactPage.tsx`, `src/components/sections/Contact.tsx` | label divs → `.link-label`; sub-labels → `.contact-link-sub`; `maxWidth:'700px'` → `.page-body` | | `src/components/sections/Projects.tsx` | "view all" link → `.section-cta` | | `src/components/sections/DownloadResume.tsx` | option label → `.link-label` | | `src/components/ui/Card.tsx` | deleted; export removed from `src/components/index.ts` | ## 5. Affected files | File | Change | |---|---| | `src/index.css` | token block (5 added, `--max-narrow` deleted), `--sans`, `h3`-`h6`, `p`, `.container-narrow` deleted | | `src/App.css` | prose system added/rewritten, 10 selectors retuned, ~170 lines of dead CSS deleted | | 8 page/section TSX files | inline type styles → classes (see §4.3) | | `src/components/ui/Card.tsx` | deleted | | `src/components/index.ts` | `Card` export removed | | `AGENTS.md` | `External Assets` font line corrected to Source Sans 3 (resume-only), `CSS Architecture` line corrected to the real theme blocks, new `Typography` section | | `docs/design/specs/v3/spec-v3-theme-palette-gasatrya.md` | card inset-highlight row now moot (`.card*` deleted) | ## 6. Progress tracking - [x] Audit: every `font-size` / `line-height` in `src/index.css` + `src/App.css` and every inline type style in TSX, with anchors - [x] Line-length measured from real glyph metrics (Segoe UI as rendered, Source Sans 3 as shipped) - [x] `@font-face` absence confirmed; decision recorded: keep `system-ui`, keep woff2 for the resume generator only - [x] Scale tokens added to `src/index.css` - [x] `.prose` turned into the live prose system; `.prose-lede`, `.page-body`, `.subheading`, `.project-section`, `.back-link`, `.section-cta`, `.link-label`, `.contact-link-sub`, `.achievement-impact`, `.achievement-metrics` added - [x] 10 existing selectors retuned to the scale - [x] Dead CSS deleted, `Card` component deleted - [x] Philosophy page: prose column, paragraph spacing, no nested `

`, ARIA id wired - [ ] Inline type styles removed from the 8 TSX files — in flight, tracked here - [ ] `tsc -b` + `vite build` green after the TSX sweep - [ ] Manual browser pass (§7) on `/`, `/about`, `/experience`, `/projects`, `/projects/:id`, `/philosophy`, `/contact`, dark and light ## 7. Verification plan 1. `pnpm exec tsc -b` → exit 0 (the `Card` deletion must not leave an import behind). 2. `pnpm exec vite build --outDir dist-verify` → module count and CSS size; grep the built CSS for `--text-body`, `--measure-prose`, `.prose-lede`, and for the absence of `.card{`, `.form-input`, `.filter-pill`, `.article-card`, `.engineering-tab`, `.breadcrumb`, `.page-header`, `.container-narrow`. 3. Grep gate: `style=\{\{[^}]*(fontSize|lineHeight|fontWeight|color|maxWidth)` over `src/**/*.tsx` → zero matches; `grep "Card"` over `src/` → zero matches. 4. Manual, real browser (no headless, per project rule): - `/philosophy`: three paragraphs visibly separated, ~600px column, 18px body, quote title 21px, no wall of text. - `/about`: bio 20px capped at 600px, section titles 21px, cards unchanged in width. - `/projects/:id`: narrative capped at 600px, section cards keep their box, h4 16px over 15px body. - `/experience`: bullets and impact 15px/1.65, achievement title 18px/1.3. - `/contact`: sub-labels 15px, tile labels 500 weight. - Both themes, mobile ≤768px: prose column narrows to the viewport, ~40-60 characters per line. ## 8. Risks | Risk | Mitigation | |---|---| | Body copy 16 → 18px makes every page taller | Only role-defined body copy moved; chrome (tags, badges, pills, footer, timeline meta) kept at 12-14px. Review `/experience` and `/projects` heights. | | Deleting `.form-*`, `.filter-*`, `.article-*`, `.engineering-tabs*`, `.breadcrumb*`, `.page-header`, `.card*` removes scaffolding that `spec-v2-blog.md` and `spec-v3-ui-enhancements.md` plan to use | Those specs keep the design intent; the CSS is re-written when the feature actually ships, together with its markup. Nothing in `src/` referenced them. | | 600px prose column looks narrower than the 752px container | Intentional: 78-83 characters per line instead of 110-118. `.container-content` still sizes the page; `.prose` sizes the reading column inside it. | | No responsive type scale | Unchanged from before (there was none). 18px on a 320-375px viewport yields 40-50 characters per line, which is comfortable; revisit only if the manual pass says otherwise. | | `.prose li` at body size could look large in dense lists | Only `.prose` lists are affected; `.expertise-skills` and `.timeline-responsibilities` are outside `.prose` and stay at 15px. | ## 9. Open questions 1. **Wire Source Sans 3 later?** It is already shipped and used by the PDF, and gasatrya uses it. Cost: four `@font-face` rules, ~75 KB per weight, and its x-height is 0.486 em vs Segoe UI's 0.500 — the scale would need +1px to read the same. Deferred by user decision. 2. **`.skip-link` orphan** (shared with the palette spec): the rules were deleted from `src/index.css` in the working tree and no component renders the class, while `strings.skipLink` (`src/i18n/strings.ts:98`) still exists. Restore markup + CSS or delete the string. 3. **`--leading-body` 1.65 vs the old 1.7** — 1.7 was applied only to `p`; 1.65 is now applied to body copy in every element role. Whether 1.6 or 1.7 reads better at 18px is a call for the manual pass.