Typography

Typography

Typography sits on top of Google Fonts and adds agent-friendly tools for the three things AI assistants actually get asked about fonts: "find me a font that feels like X", "what should I pair this with", and "give me a full type scale I can paste into my project".

When to use which tool

• typography_search — the user described a vibe (warm, playful, technical, editorial, brutalist, geometric, friendly, …). Returns ranked families with the curated tag paths that matched. Always pass query even if it's a single word.
• typography_pair_suggest — the user already picked a heading family and needs a body face. Returns 3–5 candidates with a one-line rationale each.
• typography_system — the user committed to a heading + body and wants the deliverable. Returns the type scale, a Google Fonts CSS link, ready-to-paste CSS variables and base rules, and a small HTML preview.
• typography_list_tags — surface the full curated mood/style taxonomy so the user can pick from real labels instead of guessing. Useful for tab completion and "what categories exist?" prompts.

For raw catalog browsing (every family, every variant, all download URLs), use the lower-level google_webfonts_list_fonts tool from the google-webfonts bundle. Typography is for opinionated selection and deliverables.

Mood / tag taxonomy (Google's curated tags)

Tags come back as path strings with a 0–100 weight per family. The high-level groups:

• /Sans/* — Humanist, Geometric, Grotesque, Neo-Grotesque, Rounded, Glyphic
• /Serif/* — Old Style, Transitional, Modern, Slab, Didone, Humanist
• /Display/* — display faces grouped by feel
• /Handwriting/* and /Calligraphy/* — script faces
• /Monospace/* — code faces
• /Expressive/* — semantic mood overlays (Business, Playful, Calm, Cute, Innovative, Stiff, Awkward, …)
• /Technology/* — Modern, Retro, Futuristic, Industrial
• /Calligraphy/* — Brush, Formal, Casual

When typography_search returns results, the matched_tags field shows exactly which tag paths drove each family's score, so you can explain why a recommendation fits.

Pairing heuristic

typography_pair_suggest returns body candidates that:

1. Use a different category from the heading (serif heading → sans-serif body, and vice versa). Display and handwriting are never recommended as body.
2. Cover the same scripts the heading covers (so multilingual UI doesn't fall back to a system font).
3. Carry a complete weight ramp (regular, 500+, and an italic) so app-level emphasis works.
4. Rank near the top by overall popularity — popular body faces have been battle-tested at small sizes.

Each candidate includes a rationale string. Read it back to the user when presenting the choice.

Modular type scales

typography_system builds a scale from a base font-size and a ratio. Common ratios:

• minor-second 1.067 — very tight, dense editorial layouts
• major-second 1.125 — subtle, web app default
• minor-third 1.200 — comfortable web body
• major-third 1.250 — modern marketing default (recommended)
• perfect-fourth 1.333 — punchy hero pages
• augmented-fourth 1.414 — dramatic display
• perfect-fifth 1.500 — very dramatic
• golden 1.618 — magazine / poster scale

Each step in the returned scale has name (caption → display), size_px, size_rem, and line_height. The css block is paste-ready: it declares CSS custom properties for every step plus font-family rules wired to the heading and body. The google_fonts_link is a single <link rel="stylesheet"> covering both families with the variants the scale needs.

Interactive composer

Every tool in this bundle forwards its result to the Typography Composer app that opens in the same panel. The composer tabs:

• Search — mood query in, ranked specimen cards out, each rendered in the actual font.
• Pair — heading family in, body candidates rendered side-by-side under the heading specimen.
• System — heading + body + scale ratio in, every scale step rendered live in the chosen font with copy-to-clipboard CSS underneath.

Call typography_open_app when the user wants the composer visible before any data tool runs (Studio opens it automatically on bundle load). Otherwise calling any data tool above makes the panel appear and update.

Panel routing — start here

When the composer panel is open, call the read that matches the tab — do not re-open the app.

User intent	First panel read	Composer tab
Cold-open the composer	open app	Mount hero
Mood / keyword font search	search	Search specimens
Heading + body pairing	pair suggest	Pair side-by-side
Full scale + paste-ready CSS	system	System steps + CSS
Tag taxonomy reference only	list tags	Chat-first — no panel update

Gotchas

• Family names are case-sensitive. Roboto Mono works, roboto-mono returns empty. Tools accept the canonical form Google publishes.
• Subsets matter for non-Latin scripts. Always pass subset="cyrillic" (or arabic, devanagari, japanese, …) when the user's content isn't Latin. The pairing tool also respects this.
• Display / handwriting families are never returned as body candidates by typography_pair_suggest — even if Google scores them high. They are for headings only.
• The CSS link uses the separate Google Fonts CSS API (fonts.googleapis.com/css2), which is unauthenticated and free. The API key only authenticates the metadata endpoint we use server-side.
• Licensing: every family is open-source (OFL / Apache 2.0 / Ubuntu Font License). Commercial embedding is allowed; attribution is encouraged, not required.