Files
cv/docs/design/specs/v3/spec-v3-typography.md
T
2026-10-16 21:14:59 +07:00

16 KiB
Raw Blame History

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 <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

  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 <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
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

  • Audit: every font-size / line-height in src/index.css + src/App.css and 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-face absence confirmed; decision recorded: keep system-ui, keep woff2 for the resume generator only
  • Scale tokens added to src/index.css
  • .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
  • 10 existing selectors retuned to the scale
  • Dead CSS deleted, Card component deleted
  • Philosophy page: prose column, paragraph spacing, no nested <p>, 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.