web-typography
Web-typography guides the selection, pairing, and implementation of typefaces for digital projects with emphasis on readability and performance. Use this skill when addressing font pairing decisions, responsive typography across devices, web font loading optimization, type hierarchy establishment, variable fonts, FOUT/FOIT handling, or typographic scales. It covers practical CSS implementation, legibility evaluation, and performance concerns while distinguishing between display typefaces for headlines and workhorse typefaces for body text that prioritize sustained reader comfort.
git clone --depth 1 https://github.com/wondelai/skills /tmp/web-typography && cp -r /tmp/web-typography/web-typography ~/.claude/skills/web-typographySKILL.md
# Web Typography
A practical guide to choosing, pairing, and implementing typefaces for the web. The best typography is invisible — it immerses readers in content rather than calling attention to itself.
## Core Principle
**Typography is the voice of your content.** The typeface you choose sets tone before a single word is read — a legal site shouldn't feel playful; a children's app shouldn't feel corporate. Follow the "clear goblet" principle: typography should be like a crystal-clear wine glass, keeping focus on the wine (content), not the glass (type).
## Scoring
**Goal: 10/10.** Rate any typography implementation 0-10 against the principles below. Always state the current score and the specific improvements needed to reach 10/10.
## Two Contexts for Type
All typography falls into two categories:
| Context | Purpose | Priorities |
|---------|---------|------------|
| **Type for a moment** | Headlines, buttons, navigation, logos | Personality, impact, distinctiveness |
| **Type to live with** | Body text, articles, documentation | Readability, comfort, endurance |
**Workhorse typefaces** excel at "type to live with" — versatile across sizes, weights, and contexts without drawing attention. Examples: Georgia, Source Sans, Freight Text, FF Meta.
## Typography Framework
### 1. How We Read
**Core concept:** Understanding reading mechanics is the foundation for every typography decision. Eyes don't scan smoothly — they jump in bursts.
**Why it works:** When typography aligns with how the brain processes text — word shapes, consistent rhythm, distinct letterforms — readers absorb content faster with less fatigue. Fighting these mechanics creates friction that drives readers away.
**Key insights:**
- **Saccades** — eyes jump in 7-9 character bursts; line length and letter spacing directly affect saccade efficiency
- **Fixations** — eyes pause briefly to absorb content; dense or poorly spaced text slows reading
- **Word shapes (bouma)** — experienced readers recognize word silhouettes, not individual letters
- **Legibility vs. readability** — legibility is whether characters can be distinguished (a typeface concern); readability is whether text can be comfortably read for extended periods (a typography concern: size, spacing, line length). A legible typeface can still be set unreadably
**Product applications:**
| Context | Application | Example |
|---------|------------|---------|
| Long-form content | Optimize for sustained comfort | 16-18px body, 1.5-1.7 line height, 45-75 char lines |
| Dashboard UI | Optimize for rapid scanning | Distinct weight hierarchy, whitespace between data groups |
| Mobile reading | Account for distance and lighting | Larger body (17-18px), higher contrast |
**Copy patterns:**
```css
.prose {
font-size: 1.125rem; /* 18px */
line-height: 1.6;
max-width: 65ch; /* ~45-75 characters */
}
```
**Ethical boundary:** Prioritize reader comprehension over visual novelty — sacrificing readability for aesthetics excludes readers.
See: [references/typeface-anatomy.md](references/typeface-anatomy.md) for terminology, letterform parts, and classification systems.
### 2. Evaluating Typefaces
**Core concept:** A typeface must pass technical, structural, and practical quality checks before it earns a place in a project. Beautiful specimens fail on screen.
**Why it works:** Screen rendering, variable bandwidth, and diverse devices impose constraints print never faced. Rigorous evaluation prevents costly mid-project typeface swaps.
**Key insights:**
- **Technical quality** — consistent stroke weights, even visual color across text blocks, good kerning pairs (AV, To, Ty), complete character set, multiple weights (minimum: regular, bold, italic)
- **Structural assessment** — generous x-height (better screen readability), open counters and apertures (a, e, c), distinct letterforms (Il1, O0, rn vs. m)
- **Practical needs** — test at actual use sizes on target screens, check file size, verify the license
- **Real content testing** — Lorem ipsum hides problems with character frequency, word length, and paragraph rhythm
**Product applications:**
| Context | Application | Example |
|---------|------------|---------|
| Body text selection | Prioritize x-height, open counters, even color | Source Serif Pro over Didot for long reads |
| UI/System text | Prioritize small-size legibility and weight range | Inter or SF Pro for interface elements |
| Multilingual product | Verify glyph coverage for target languages | Noto Sans for broad Unicode support |
**Copy patterns:**
```css
/* Stress-test at every actual use size */
body { font-size: 16px; }
.caption { font-size: 0.75rem; }
h1 { font-size: 3rem; }
```
**Ethical boundary:** Always verify licensing — unlicensed fonts create legal risk and undermine the type design community.
See: [references/evaluating-typefaces.md](references/evaluating-typefaces.md) for detailed quality assessment criteria and structural analysis.
### 3. Choosing Typefaces
**Core concept:** Start with purpose, not aesthetics. The content's tone, reading context, and duration should drive selection — not personal preference or trends.
**Why it works:** Purpose-driven choices feel inevitable rather than arbitrary, and survive stakeholder review because they can be justified with reasoning rather than taste.
**Key insights:**
- **Define the job first** — body text, headlines, and UI elements may each need different faces
- **Match tone to content** — a financial report needs a different voice than a bakery menu
- **Check the family** — confirm needed weights, italics, and styles exist before committing
- **Safe starting points** — body serif: Georgia, Source Serif Pro, Charter; body sans: system fonts, Source Sans Pro, Inter, IBM Plex Sans
**Product applications:**
| Context | Application | Example |
|---------|------------|---------|
| Content-heavy site | Workhorse serif or sans for sustained reading | Source Serif Pro or ChBuild lean, opinionated products using the 37signals philosophy from "Getting Real", "Rework", and "Shape Up". Use when the user mentions "Getting Real", "Rework", "Shape Up", "37signals", "Basecamp method", "six-week cycles", "fixed time variable scope", "appetite vs estimates", "betting table", "breadboarding", "fat marker sketch", "build less", "underdo the competition", "opinionated software", "we have too many meetings", "the project keeps growing", "how do we ship faster", or "stop overbuilding". Also trigger when cutting scope to ship sooner, fighting feature creep, running a small team, avoiding long-term roadmaps, or killing unnecessary meetings. Covers shaping, betting, building, and the art of saying no. For MVP validation, see lean-startup. For design sprints, see design-sprint.
Create uncontested market space using value innovation instead of competing head-to-head. Use when the user mentions "blue ocean", "red ocean", "strategy canvas", "ERRC framework", "value innovation", "non-customers", "buyer utility map", "uncontested market", "stop competing on price", "everyone is undercutting us", "the market is too crowded", or "how do we stand out". Also trigger when comparing pricing strategies, exploring new market categories, finding underserved or non-customers, or escaping a brutal price war. Covers the Four Actions Framework, buyer utility map, and value-cost trade-offs. For tech adoption strategy, see crossing-the-chasm. For product positioning, see obviously-awesome.
Structure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities. Use when the user mentions "architecture layers", "dependency rule", "ports and adapters", "hexagonal architecture", "onion architecture", "screaming architecture", "where should business logic go", "decouple from the database", "swap the framework without a rewrite", "business logic is tangled with the framework", or "keep business rules independent". Also trigger when deciding which layer code belongs in, isolating core logic from infrastructure, defining module boundaries, or debating whether the framework should call your code or the reverse. Covers component principles, boundaries, and SOLID. For code-level quality, see clean-code. For domain modeling, see domain-driven-design.
Write readable, maintainable code through disciplined naming, small functions, and clean error handling. Use when the user mentions "code review", "naming conventions", "function too long", "code smells", "readable code", "boy scout rule", "single responsibility", "unit test quality", "my code is hard to read", "this function is a mess", "clean up this code", or "hard to maintain". Also trigger when reviewing pull requests for readability, untangling messy functions, debating comment styles, or improving error handling patterns. Covers SRP, comment discipline, formatting, and unit testing. For refactoring techniques, see refactoring-patterns. For architecture, see clean-architecture.
Engineer word-of-mouth and virality using the STEPPS framework (Social Currency, Triggers, Emotion, Public, Practical Value, Stories). Use when the user mentions "go viral", "word of mouth", "shareable content", "social currency", "why people share", "viral loop", "referral program", "organic growth", "how do I get people to share this", "nobody is sharing it", or "make this spread". Also trigger when designing shareable features, crafting social campaigns, or building products that spread through peer recommendation. Covers environmental triggers and high-arousal emotional content. For sticky messaging, see made-to-stick. For persuasion tactics, see influence-psychology.
Build a weekly cadence of customer touchpoints using Opportunity Solution Trees, assumption mapping, and interview snapshots. Use when the user mentions "continuous discovery", "opportunity solution tree", "weekly interviews", "assumption testing", "discovery habits", "product trio", "outcome-based roadmap", "how do I talk to customers regularly", "we keep building things nobody uses", or "connect research to the roadmap". Also trigger when setting up regular customer feedback loops, prioritizing which experiments to run, or tying discovery insights to delivery work. Covers experience mapping, co-creation, and prioritizing opportunities. For interview technique, see mom-test. For team structure, see inspired-product.
Audit websites and landing pages for conversion issues and design evidence-based A/B tests. Use when the user mentions "landing page isnt converting", "conversion rate", "A/B test", "why visitors leave", "objection handling", "bounce rate", "split testing", "conversion funnel", "increase signups", "people add to cart but dont buy", or "improve conversions". Also trigger when diagnosing why signups are low, designing experiment hypotheses, or auditing checkout flows for friction points. Covers funnel mapping, persuasion assets, and objection/counter-objection frameworks. For overall marketing strategy, see one-page-marketing. For usability issues, see ux-heuristics.
Navigate the technology adoption lifecycle from early adopters to mainstream market. Use when the user mentions "crossing the chasm", "beachhead segment", "whole product", "early adopters vs mainstream", "tech go-to-market", "bowling pin strategy", "technology adoption lifecycle", "pragmatist buyers", "growth stalled after early adopters", "cant get mainstream customers", or "our go-to-market plan". Also trigger when a startup has early traction but cant grow beyond initial users, or when planning go-to-market for a technical product. Covers the D-Day analogy, bowling-pin strategy, and positioning against incumbents. For product positioning, see obviously-awesome. For new market creation, see blue-ocean-strategy.