typography-system

typography-system

Turn a style constraint into a full typographic system: pick a verified font pairing, derive a modular scale, and emit DTCG $type: "typography" tokens through the design-tokens toolchain.

A two-stage Method: stage 1 (below) is the style path — a mood/idiom constraint drives the pairing. Stage 2 is the brand-aware path — when a brand layer exists, the brand archetype filters the pairing first. The skill degrades gracefully: with no brand layer, only stage 1 runs.

When to use

• Choosing heading/body fonts for a new product or rebrand.
• Building or overhauling a typographic scale (sizes, line-height, weights).
• Any request to "set the typography" or "pick fonts" for a design system.
• Before calling design-tokens for a new project — typography tokens belong in tokens.json alongside color tokens, not hand-coded in CSS.

Procedure

1. Take a style/idiom constraint from the design-intelligence idiom corpus — a mood keyword (e.g. elegant, modern, playful) or a named idiom that carries typographic intent.
2. Query font-pairings-reference.csv (Reference layer) — filter by the Mood/Style Keywords column; surface the top 1–2 matching pairings with their Heading Font, Body Font, Best For, and Google Fonts URL.
3. Derive the type scale — pick a modular ratio (1.25 Minor Third or 1.333 Perfect Fourth for most products); compute sizes for xs / sm / base / lg / xl / 2xl / 3xl; set line-height (1.5 for body, 1.2 for display); assign weights (400 body, 600–700 heading).
4. Emit DTCG $type: "typography" tokens through design-tokens (scripts/tokens.ts) — add a typography section to tokens.json with $type: "typography" and $value objects carrying fontFamily, fontSize, fontWeight, lineHeight.
5. Verify — confirm both chosen fonts exist on Google Fonts (check the Google Fonts URL column in the CSV — this is an availability check, "does this font exist?", and is deliberately separate from the delivery decision, "how does it get onto the page?" — see § Delivery below; conflating the two is what produced a single hard-wired hotlink); run ./scripts-run <skills-root>/design-tokens/scripts/tokens validate --dir src/ to confirm no hardcoded font-size or font-family values remain outside the token file; exit code 0 is the evidence.

Stage 2 — brand-aware path (when a brand layer exists)

When a brand archetype is known (a confirmed brand-strategy / brand-identity constraint set, or a consumer brand profile), filter the pairing by the archetype before the mood match — the brand constrains the style, not the other way around.

1. Resolve the archetype from the active brand layer (e.g. Ruler, Lover, Magician).

2. Query the brand typography Grounding domain for the archetype → pairing-filter (Heading Class, Body Class, Mood, plus confidence + evidence gap):

   ./scripts-run <skills-root>/corpus-grounding/scripts/ground search \
     --manifest <skills-root>/brand/data/manifest.json \
     "<archetype + sector>" --domain typography --json
   

3. Filter font-pairings-reference.csv by that pairing-filter — keep only pairings whose Heading/Body classes satisfy the archetype filter (e.g. a Ruler / law-firm brief keeps serif-containing pairings; a Magician / SaaS brief keeps geometric-sans pairings). Then apply the stage-1 mood match within the filtered set.

4. Surface the corpus confidence + evidence_gap for the archetype row, then emit DTCG type tokens exactly as stage 1 (steps 4–5 above).

5. Trigger-eval invariant: a "law-firm redesign" brief MUST route to a serif-containing pairing (the archetype filter is Ruler → serif). This is the recorded brand-aware regression test (recorded in Phase D).

Consumer brand tokens outrank the corpus filter (brand-source-of-truth) — if the brand already registers fonts, use them and skip the filter.

Delivery — hosting mode (self-hosted by default)

The delivery policy is owned by design-fidelity-mechanics § Asset & imagery discipline (ADR-205); this skill is a consumer and emits the route, never a competing policy. A font CDN link transmits the visitor's IP to that third party on every page view — a German court (LG München I) ruled on exactly that for hotlinked Google Fonts.

Default: self-hosted. Take the row's Self-Hosted Route column and resolve it against the detected target stack:

Hotlink: opt-in only. Emit the row's CSS Import value only when the consumer explicitly asked for the CDN route, and state in the same breath that it transmits the visitor's IP to the third party. Never pick it because it is the shorter line.

Output format

1. Chosen pairing + rationale — heading font, body font, the CSV row's Best For field, and the one-line mood match that drove the selection.
2. DTCG type-token block — the typography section ready to paste into tokens.json (DTCG $type: "typography", $value with fontFamily, fontSize, fontWeight, lineHeight per level).
3. Font delivery block — the self-hosted route for the detected stack per § Delivery (from the row's Self-Hosted Route column), and the Tailwind fontFamily config snippet from Tailwind Config. The row's CSS Import hotlink appears here only under an explicit consumer opt-in, with its IP-transmission note.

Gotcha

• Stale CSV URL → silent system-font fallback (opt-in hotlink path only). font-pairings-reference.csv is Reference data on a freshness contract — never substitute a live Google Fonts API call. If a font was retired or renamed, the @import URL 404s at build time and the browser silently falls back to the system font, shipping broken visual design with no obvious error. This caveat still applies verbatim to the opt-in hotlink route: verify the URL resolves (Step 5) before emitting the import line; if it 404s, surface the error and ask the user to pick an alternative pairing from the CSV.
• The self-hosted default replaces that failure mode, it does not delete it. For a package route (next/font, @fontsource/*) resolution moves to install time, where a wrong name fails loudly instead of 404-ing at build. What remains is a family-name mismatch: the emitted CSS asks for font-family: 'Inter' while the installed package provides a differently-named family (Inter Tight), which renders the system font at runtime with no error at all — the same silence, one layer later. Assert the family name in the emitted CSS matches the one the installed package declares; the row's Google Fonts URL stays useful as the reference spelling to compare against.

Do NOT

• Do NOT hardcode font sizes outside the token scale (e.g. font-size: 18px inline) — every size belongs in tokens.json under the typography layer.
• Do NOT bypass design-tokens and write raw CSS custom properties for fonts — tokens.json is the single source; hand-crafted --font-* vars drift.
• Do NOT emit a font-CDN @import / <link> as the default deliverable — the self-hosted route is the default and the hotlink is an explicit opt-in (§ Delivery). Reaching for the CDN line because the stack was not detected is the exact substitution this skill used to hard-wire.
• Do NOT treat font-pairings-reference.csv as decision logic — it is Reference data; the agent picks based on the style constraint, not by iterating the CSV as a rules engine.
• Do NOT skip step 5 (validate) before claiming the type system is complete — unchecked hardcoded values in component files are the canonical failure mode.

See also

• design-canon.md — named-systems + typography-craft (foundry/theory) grounding index; pull to escape the AI-default fonts.
• design-tokens — toolchain that generates CSS vars and the Tailwind snippet from tokens.json.
• design-intelligence — idiom corpus that supplies the style constraint consumed in Step 1.
• iconography — companion visual-identity skill (icon set selection, sizing scale).
• fe-design — broader frontend design skill that consumes the token system produced here.
• brand — supplies the archetype → pairing-filter Grounding (typography domain) consumed by stage 2.

Why this skill is rich

Typography is one of the highest-leverage design decisions and one of the most commonly mis-applied by AI agents (defaulting to Inter + arbitrary sizes). The skill carries 73 curated font pairings (heading + body + mono combinations with Google Fonts URLs and Tailwind config), 6 worked-through modular-scale examples across different use-cases (marketing, dashboard, docs, e-commerce, SaaS, editorial), and per-pairing line-height + weight guidance. Condensing to "use a 1.25 modular scale" loses the worked examples that teach agents the difference between a 14/17.5/21.8/27.2 rounded scale and an invented arbitrary scale. Without the worked examples, agents produce: 16, 20, 24, 28 (arbitrary) instead of a properly grounded typographic system.