PhilosophyPage: prose column, paragraph spacing, no nested <p>, aria-labelledby wired to a real SectionHeading id. About/AboutPage, ProjectDetailPage, Experience/ExperiencePage, Contact/ContactPage, Projects, DownloadResume: inline fontSize/lineHeight/fontWeight/color/maxWidth replaced by .prose, .prose-lede, .page-body, .subheading, .project-section, .back-link, .section-cta, .link-label, .contact-link-sub, .achievement-impact, .achievement-metrics. App.css: add .download-resume-button as a variant of .contact-link. index.css: drop leftover .container-narrow from two responsive selector lists. Delete dead ui/Card.tsx and its barrel export. Specs: typography progress marked done with the verification log; .skip-link orphan closed in both v3 specs (strings.skipLink is gone too). tsc -b exit 0; vite build 538 modules / 24.86 kB CSS; built CSS carries every new class and none of the deleted selectors; oxlint diagnostics identical to HEAD (15 errors / 9 warnings, all pre-existing).
17 KiB
Specification — v3 Typography scale and readability
Document:
spec-v3-typography.mdVersion: 1.0.0 Parent:spec.md(IA/content readability), sibling ofspec-v3-theme-palette-gasatrya.mdPriority: P1 Status: Implemented. TSX sweep done,Carddeleted,tsc -band 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 <p> 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 <p>…</p> and was injected inside a <p> (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
- Font: admit
system-ui.--sansbecomessystem-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif. No webfont is loaded; the Source Sans 3 woff2 files stay inpublic/fonts/becausescripts/generate-resume.tsreads them from disk for the PDF. (User's call: keep the current look rather than restyle the whole site.) - Five scale tokens in
:root:--text-body: 18px,--text-lede: 20px,--text-meta: 15px,--leading-body: 1.65,--measure-prose: 600px. They live in:rootonly — sizes do not differ between dark and light, so they are not duplicated in the light block or the media bridge. - Reuse
.prose(App.css, previously defined and never rendered by any component) as the prose system instead of inventing a second convention. - 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. - Heading sizes:
h324 → 21px, andh418 /h516 /h615 made explicit (they previously fell back to 16px).h1/h2clamps and the globalh1-h6 { line-height: 1.2 }are untouched. - Paragraph rhythm lives only inside
.prose(.prose p { margin-bottom: 1em },:last-child0). The globalpkeepsmargin: 0from the reset, so hero, cards, section subtitles and contact tiles are unaffected. - 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. - No inline
fontSize/lineHeight/fontWeight/ textcolorin components. Layout-only inline styles (flex,gap, motionstyle={{y}}) are allowed. - Delete dead CSS and the unused
Cardcomponent rather than leaving unstyled scaffolding behind (list in §4.2).
4. Implementation details
4.1 src/index.css
:roottoken block:--max-narrowdeleted; added the five scale tokens after--max-content.--sans→ system stack (finding P5).--monounchanged (it already ends inui-monospace, monospace, so it resolves without a download).h3 { font-size: 21px }; newh4 { 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-narrowdeleted (no consumer), including its two leftover entries in the responsive padding selector lists.
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; }
.download-resume-button { justify-content: center; padding 12px 20px; color text-primary; } /* variant of .contact-link; replaces the DownloadButton inline style */
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 <SectionHeading id="philosophy-heading">; quotes wrapped in <div className="prose"> → <div className="philosophy-quote"> → plain <h3> + <div dangerouslySetInnerHTML> (no outer <p>, so the injected <p> 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 <h3> → .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 <h3 style> → plain <h3>; section cards → .project-section with plain <h4> / <p> |
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; DownloadButton inline layout + color → className="contact-link download-resume-button" |
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, .download-resume-button added, ~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
- Audit: every
font-size/line-heightinsrc/index.css+src/App.cssand every inline type style in TSX, with anchors - Line-length measured from real glyph metrics (Segoe UI as rendered, Source Sans 3 as shipped)
@font-faceabsence confirmed; decision recorded: keepsystem-ui, keep woff2 for the resume generator only- Scale tokens added to
src/index.css .proseturned into the live prose system;.prose-lede,.page-body,.subheading,.project-section,.back-link,.section-cta,.link-label,.contact-link-sub,.achievement-impact,.achievement-metricsadded- 10 existing selectors retuned to the scale
- Dead CSS deleted,
Cardcomponent deleted - Philosophy page: prose column, paragraph spacing, no nested
<p>, ARIA id wired - Inline type styles removed from the 8 TSX files — gate
style=\{\{[^}]*(fontSize|lineHeight|fontWeight|color|maxWidth)oversrc/→ 0 matches tsc -b+vite buildgreen after the TSX sweep- Manual browser pass (§7) on
/,/about,/experience,/projects,/projects/:id,/philosophy,/contact, dark and light
7. Verification plan
-
pnpm exec tsc -b→ exit 0 (theCarddeletion must not leave an import behind). -
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. -
Grep gate:
style=\{\{[^}]*(fontSize|lineHeight|fontWeight|color|maxWidth)oversrc/**/*.tsx→ zero matches;grep "Card"oversrc/→ zero matches. Result: 538 modules, CSS 24.8 KB (5.37 KB gzip). Built CSS contains--text-body,--measure-prose,.prose-lede,.prose,.page-body,.subheading,.project-section,.back-link,.section-cta,.link-label,.contact-link-sub,.achievement-impact,.achievement-metrics,.philosophy-quote,.download-resume-button; zero hits for.card{,card-elevated,card-featured,form-*,filter-*,article-*,engineering-tab*,breadcrumb*,page-header,container-narrow,--max-narrow.grep "Card"oversrc/→ 0 matches.oxlint against HEAD and against the working tree produce identical diagnostics (15 errors / 9 warnings): every one is pre-existing — oxlint treats the
useField/useFieldArrayhelpers insrc/i18n/useField.tsas hooks, plusNavigation.tsx:26set-state-in-effect. Out of scope here. -
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
- Wire Source Sans 3 later? It is already shipped and used by the PDF, and gasatrya uses it. Cost: four
@font-facerules, ~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. — closed..skip-linkorphanstrings.skipLinkno longer exists either:grep -i skipoversrc/→ 0 matches, so there is no orphan left in either direction.--leading-body1.65 vs the old 1.7 — 1.7 was applied only top; 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.