fix(site): render docs prose through the shared type module

[tnunamak]

The site had two typography systems, and they had drifted apart.

Marketing pages sized their text through Text, a React module that maps a size token name such as lede onto one step in the site's type scale — a fixed list of font-size/line-height pairs, each pair called a rung below. The specification pages sized the same elements through hand-written CSS aimed at bare h1/h2/p selectors. Neither knew about the other, so an h3 was 17.9px on docs and something else on marketing, and every future change had to be made twice or drift again.

The duplication also caused a live bug. The two systems compete through the browser's cascade — the mechanism that resolves conflicting CSS rules, normally by picking whichever loaded last — so which rule won depended on stylesheet load order. A duplicate .flex rule beat a responsive rule shipped by fumadocs, the framework that renders the Markdown for these pages, and the table of contents never collapsed on narrow screens.

This branch routes documentation prose through the same Text module and deletes the CSS that duplicated it. Documentation keeps its own content source — Markdown rendered by fumadocs — but no longer its own type system.

Prose on /specification is deliberately larger: body 17px → 19px, h3 17.9px → 20px, h2 28.8px → 27px, now the same rungs as the rest of the site. Every value was measured in a browser before and after, not read off the stylesheet.

Four smaller pieces of the same problem came with it. The component tree was flattened — everything lived under components/pdpp-concept/, a folder named after a prototype route that no longer exists, and now sits under layout/, sections/, elements/, typography/. Two components that each carried their own copy-to-clipboard state machine now share one. Boolean props that switched a component between two rendering modes were replaced by one named module per mode, or deleted where nothing called them. And /self-host/coverage, the last page on the old CSS classes, moved onto Text — fixing a quiet bug where .pdpp-caption, the class styling that page's small table labels, was defined twice under the same name and the wrong one always won, rendering table headers in italic serif for no reason.

The duplicate-CSS bug got a real fix rather than a better patch. This site runs Tailwind — a CSS framework that generates classes like .flex on demand from source code — twice: once for the whole site, once more for pages needing extra CSS variables the main build can't see. Tailwind scans the whole source tree by default, so each build scanned pages the other exclusively owns and generated the same classes twice. Scoping each build's scan with @source not — a directive telling one build to ignore files it doesn't serve — cut overlapping selectors from 680 to 4, without merging the two builds. Two earlier attempts tried merging the builds instead and both broke --container-page, the variable that sets the site's maximum content width: a page came out a different width depending on which merged build produced its width rule. The override lived in specification.css, the stylesheet holding the spec pages' own rules — the same file the duplicated type CSS came out of — and is now deleted outright.

Review notes

• The typeface trap. Text deliberately doesn't set font-family; it inherits whatever font its parent wrapper already declares (the marketing pages' outer wrapper, for example, sets a sans-serif default). An earlier attempt at this migration silently switched headings from serif to sans because of it. Here the ambient default already matches what the old CSS hardcoded, verified by measurement, but a different parent wrapper would change that.
• <strong> keeps an explicit weight. The shared module styles <strong> at 500 (medium weight), but the specification uses it as inline mini-headers where that's nearly invisible against body text. A scoped 700 (bold) rule remains. No marketing page uses <strong>, so there was no second place to check a shared weight change against.
• The deferred rename is done. pdpp-concept — the retired prototype name — survived in data-slot attributes and --pdpp-concept-* CSS variables across 295 places and 27 distinct names, all now pdpp-editorial, matching the term the brand README already used for this surface. Verified with the same computed-style differ described above, run both as a self-control (baseline served against itself, to separate real diffs from two known-flaky pages) and as the real before/after comparison: zero differences on every route beyond the disclosed flakes. The built CSS was also grepped directly for the old name: zero matches.
• .flex still appears once per build. Not leftover overlap — docs-only and marketing-only elements each use it independently, so removing it from either build would mean merging both.
• Verification. This branch adds apps/site/scripts/style-differ.mjs, which opens this branch's build and main's build side by side in a real browser and compares each element's computed style — the final font-size, colour, and position after the cascade resolves, not what the source CSS alone suggests. It checks six representative pages at two widths (desktop and mobile). Marketing routes show zero differences; the specification route's differences are the intended type changes plus the rows that shift beneath them as taller text pushes content down. The table of contents sidebar switches from hidden to visible at exactly 1280px; both sides of that line (1279px and 1281px) were measured directly and matched before and after.
• What I have not verified. Only the light colour scheme was measured. The Text rungs are shared, so a dark-mode regression is unlikely but untested.

Assisted-by: AI

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pdpp	Ready	Preview	Aug 18, 2026 9:56pm