Font Pairing Generator

How the Pairing Generator Works

The generator walks every heading and body font in the Font Blend dataset, scores each pair, and returns the top six. The score is a weighted sum of six factors, each scaled 0 to 100. No machine learning, no embedding model, no API calls.

• Classification contrast (20%). A serif heading with a sans body earns more contrast than two sans-serifs. The same family earns the lowest score.
• X-height compatibility (15%). Two fonts with the same x-height grade read more harmoniously than mismatched grades.
• Weight compatibility (15%). The heading needs a heavy weight for hierarchy. The body needs a readable weight for legibility.
• Readability (20%). Both fonts must include a usable body weight, or the pair loses points.
• Curated relationship (20%). If the pair is already in the curated dataset, it earns a bonus. The dataset encodes designer judgment.
• Use-case fit (10%). Both fonts must match the requested use case, such as blog, saas, or documentation.

The final score is rounded to a whole number, with a small deterministic jitter (under 4 points) so the same seed produces slightly varied rankings. Locking a heading or body fixes that font and reruns the search for the other.

Tips for Choosing Font Pairings

A good pairing earns contrast where hierarchy matters and consistency where legibility matters. These four checks cover most cases.

1. Contrast by classification. Pair a serif heading with a sans body, or a display heading with a neutral sans. Two faces from the same classification often blur together.
2. Match x-heights. Two fonts with similar x-heights share a perceived size. Mismatched x-heights make the smaller font look weak.
3. Limit to two families. One heading face and one body face cover most projects. A third family adds a UI font only when the body font is too decorative for navigation.
4. Test at every size. A pairing that looks great at 48 pixels can fall apart at 14 pixels. Test headings, body, captions, and buttons on the actual surfaces you ship.

Step-By-step First Run

The generator opens with six pairings already loaded, picked by the default filters. To find a pairing for a specific project, work through these steps in order.

1. Pick a use case. The use case dropdown (blog, saas, documentation, editorial, portfolio, or ecommerce) filters both the heading and body font candidates. This is the fastest way to narrow the list without reading every font in the catalog.
2. Set the mood filter. The mood selector (geometric, humanist, editorial, modern, or classic) acts as a secondary filter. The generator returns results that match both the use case and the mood. If no results appear, relax one of the two filters.
3. Read the score. Each pairing card shows a 0 to 100 score. Higher scores mean the pair passes more of the six weighted criteria. A score above 75 is a strong pairing. Scores between 60 and 75 are usable with minor adjustments to weight or size.
4. Lock one font and regenerate. Click the lock icon on a heading or body font to hold it fixed. The generator searches for the closest match to that locked choice and updates the other five cards. This is the fastest way to integrate a brand font you already use.
5. Export the result. Click any pairing card to open its detail view. The export panel gives you CSS custom properties, a Google Fonts @import URL, and a Tailwind config snippet. Paste the @import into your stylesheet or the Tailwind snippet into your config file.

What the Export Formats Give You

Every pairing in the generator exports three ways. The right format depends on how your project is set up.

CSS custom properties

A set of --font-heading and --font-body variables plus the font-family stack. Drop these into your root selector and reference them wherever the heading or body font is needed. This format works in any project that uses CSS variables, regardless of framework.

Google Fonts @import URL

A single URL that loads both fonts from Google Fonts with the correct weights. Paste it into the top of your main stylesheet. The URL includes the subset parameter and the display=swap flag for better performance. If you self-host fonts instead, the URL tells you which weights to download.

Tailwind config snippet

A partial fontFamily object ready to paste into your tailwind.config file. The heading and body fonts become font-serif and font-sans (or whichever category applies) in your design system. You still need to add the Google Fonts @import to your HTML.

Frequently Asked Questions

Why does the generator return different results each time?

The generator uses a random seed to break ties between pairings with the same score. Locking both a heading and a body font produces the same result every time. If you see different pairings on each visit, the seed changes on page load. Open the URL in the browser bar and press Enter to reload without changing the seed.

Can I use the generator without a Google Fonts API key?

Yes. The generator uses the public Google Fonts CSS API with no authentication. The API has a rate limit that handles normal use. If you hit the limit during a large batch export, wait 24 hours or self-host the fonts to bypass it.

What is the difference between the generator and the curated pairings page?

The generator produces algorithmic results from font metadata. The curated pairings page shows pairs that a designer has evaluated by hand, with notes on why the pairing works and what weight to start with. If the generator returns a pairing that is also on the curated page, it earned bonus points for that curated relationship. If it does not appear in the curated set, the generator found a usable pairing without a human review.

How does the generator handle variable fonts?

Variable fonts in the dataset are scored on their axis ranges. If a font has a weight axis from 100 to 900, the generator treats it as usable at any weight and scores it against the readability and weight compatibility factors. The pairing card shows the variable tag if the font is variable, and the export includes the axis range in the font URL.

Why does my pairing score lower than expected?

The score combines six factors, and any single low factor drags the total down. A pair with high classification contrast but mismatched x-heights will score in the 60s. Check whether the two fonts are from the same classification or have very different default x-heights. Locking one font and regenerating often surfaces a better match that avoids the original mismatch.

Related Tools

The generator fits between two other tools. The curated pairings browse shows pairings we have written designer notes for. The playground takes any generated pairing and lets you live-edit text, color, and scale.