# Shared typography

New redesign sites enable `site.json.typography: {"version":1}`. Historical sites omit it; upgrading a kit does not opt them in or rewrite authored CSS. Preserve mode keeps captured typography. For an explicitly requested existing-site adoption, first inspect current source and preview, record its intended type roles, then opt in and repair every reported route through normal local acceptance. Publication remains separate.

Before building pages, declare `typography.roles` in `theme/defaults.json` for display, section, subheading, card-title, body, ui, caption and label. Each role declares `size` (CSS length/clamp), `weight` (numeric), `lineHeight`, `tracking`, and `font` (`body` or `display`, using the site's font families). The scaffold supplies complete defaults. Direction acceptance requires this concrete system, alongside the design rationale. Adjust the shared system to fit the selected identity; reuse it throughout expansion and revisions.

Starting sizes: body 1.125rem (18px), controls/navigation 1rem (16px), captions and labels .875rem (14px). Ordinary H3s share `subheading`, a 1.5–2rem responsive scale. H1 uses display; H2 section; H4 card-title; H5/H6 ui. Supporting text should not become the default body size. Readable text must render at least 12px at the default browser root, including small/sup/sub, diagrams, placeholders, generated text and scaled mockups. Use relative units so larger user text settings remain effective. Never shrink the root to fit a layout.

Use `--type-ROLE-size`, `--type-ROLE-weight`, `--type-ROLE-leading`, `--type-ROLE-tracking`, and `--type-ROLE-font`. Semantic headings inherit their roles. Use `data-type-role="card-title"` or another declared role where a different visual function is appropriate without changing heading semantics. Ordinary paragraphs inherit body; controls, nav links, labels, small and captions have matching defaults. Inline strong/em remains emphasis. Avoid isolated page/section font-size or font-weight overrides. Change the shared role when the same treatment is needed across pages.

A deliberate exception needs a reusable named variant in `typography.variants`, for example `{"feature":{"role":"subheading","reason":"Feature titles introduce the lead case study","size":"clamp(2rem,3vw,3rem)","weight":400}}`. Apply `data-type-variant="feature"` to the heading. The variant inherits its role's other properties; it must match the element's role. Use an explicit `data-type-role` if its semantic default differs. Do not generate variants merely to bless existing drift. Essential text in mockups remains readable; reflow it instead of scaling it below the floor.

The browser verifier waits for fonts and checks every authored route at mobile/desktop widths. It measures resting, tab, disclosure/menu, expanded details, and supported form validation/result states. It fails undersized text, undeclared/incompatible roles/variants, size/weight/family/leading/tracking drift and requested webfont weights without a loaded matching face. Browser reports contain `typography.captures` with route, width, state, selector, text, computed/rendered sizes and failures. Inspect pixels as well: role conformance is mechanical evidence, not visual approval. Add located manual checks for custom widgets not exposed through native details, tabs or ARIA disclosure controls.

Selected templates provide visual identity; they do not waive readability or shared roles. Translate their typography into this system before adapting sections. New template publications require a complete role declaration and passing original/branded typography checks on every route. Existing immutable template releases and teaching fixtures remain unchanged.