best-practices

Hallmark's 2+1 Font Discipline: How to Manage Display, Body, and Outlier Fonts

August 13, 2026 Nutlope/hallmark ↗

Hallmark enforces a strict "2+1" font discipline that limits any page to at most three font families: one display font, one body font, and optionally one outlier font for accent elements.

The Hallmark design system, as implemented in Nutlope/hallmark, codifies typographic restraint through this rule. This article explains the 2+1 discipline's structure, implementation in CSS tokens, and enforcement through automated audits.

What the 2+1 Font Discipline Means

The "2+1" rule (also referred to as "2+I" where "I" stands for the outlier) establishes hard limits on typographic variety:

  • Two primary fonts form the canonical pairing: a display font for headings and hero elements, and a body font for prose and UI elements.
  • One outlier font may be introduced for no more than two locations on a page—typically a wordmark, hero statistic, pull quote, or masthead.
  • Three families maximum; anything beyond is rejected as "slop" by the Hallmark audit pipeline.

This discipline appears in [typography.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/typography.md), which states that "three faces is the ceiling."

How Font Families Are Counted

Understanding what constitutes a distinct family is critical to following the discipline:

Scenario Family Count
Geist 400 + Geist 700 1 family (same typeface, different weights)
Geist (sans) + Fraunces (serif) 2 families
Geist + Fraunces + Geist Mono 3 families (at the limit)
Geist + Fraunces + Geist Mono + JetBrains Mono 4 families (violates 2+1)

The rule counts distinct typeface families, not font weights or styles. A monospace variant of a sans-serif face counts as a separate family.

CSS Token Implementation

Hallmark implements the 2+1 discipline through CSS custom properties defined in [site/css/tokens.css](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). Each theme declares --font-display, --font-body, and --font-outlier on the :root selector via attribute-specific targeting.

Example: Lumen Theme Definition

[data-theme="lumen"] {
  --font-display: "Instrument Serif", "Tiempos Headline", ui-serif, Georgia, serif;
  --font-body:    "Geist", ui-sans-serif, system-ui, sans;
  --font-outlier: "Geist Mono", ui-monospace, monospace;
}

Example: Hum Theme Definition

[data-theme="hum"] {
  --font-display: "Plus Jakarta Sans", "Geist", "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-body:    "Geist", ui-sans-serif, system-ui, sans;
  --font-outlier: "JetBrains Mono", ui-monospace, monospace;
}

Each variable includes a fallback chain ending in generic family names, ensuring graceful degradation if custom fonts fail to load.

Practical Application in Markup

Using the 2+1 discipline in a Hallmark page requires referencing the CSS variables and respecting the outlier limit.

<!DOCTYPE html>
<html data-theme="hum">
<head>
  <link rel="stylesheet" href="/site/css/tokens.css">
</head>
<body>
  <h1 class="hero-headline">Design Systems at Scale</h1>
  <p class="prose">Hallmark's 2+1 font discipline ensures visual consistency...</p>
  <div class="stat-large">99.9%</div>
  <span class="wordmark">Hallmark</span>
</body>
</html>

/* Applied font families */
.hero-headline {
  font-family: var(--font-display);
}

.prose {
  font-family: var(--font-body);
}

.stat-large,
.wordmark {
  font-family: var(--font-outlier);
  /* Two locations only—compliant with 2+1 */
}

The stat-large and wordmark classes share the outlier font, consuming both permitted usages.

Outlier Font Usage Rules

The outlier font operates under strict constraints documented in Hallmark's references:

  • Maximum two locations per page
  • Purpose-driven placement: reserved for elements requiring distinct visual weight (wordmarks, hero statistics, pull quotes, mastheads)
  • No systemic use: cannot be applied to body text, headings, or recurring UI elements

Violating these constraints triggers audit failures.

Automated Audit Enforcement

Hallmark's design system includes automated verification through its audit pipeline. The [audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) reference describes how pages are scanned for font-family violations.

Conceptual implementation:

// Hallmark audit verification (conceptual structure)
import { parseCSS } from '@hallmark/css-parser';

function validateFontDiscipline(css) {
  const families = new Set();
  
  css.rules.forEach(rule => {
    const declaration = rule.declarations['font-family'];
    if (declaration) {
      const primaryFamily = declaration
        .split(',')[0]
        .trim()
        .replace(/["']/g, '');
      families.add(primaryFamily);
    }
  });
  
  return {
    compliant: families.size <= 3,
    familyCount: families.size,
    families: Array.from(families)
  };
}

Pages exceeding three families receive critical design-system drift status and must be corrected before deployment.

Banned Default Fonts

The 2+1 discipline includes a banned defaults list prohibiting common web fonts unless explicitly selected from the approved catalog. Per [typography.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/typography.md), fonts like Inter, Roboto, and Courier New are restricted. This prevents unintentional "safe" choices that undermine the system's intentional typography.

Why the 2+1 Discipline Matters

Benefit Mechanism
Visual hierarchy Display and body fonts create clear information structure; outlier provides single accent
Brand consistency Prevents "font soup" that dilutes identity across pages and themes
Performance Fewer font files reduce network requests and CSS payload
Maintainability Limited choices simplify decision-making for designers and developers
Audit reliability Quantifiable rule enables automated enforcement

Summary

  • Two primary fonts (display + body) form the foundation of every Hallmark page
  • One outlier font permitted for ≤2 accent locations (wordmark, stat, pull quote, masthead)
  • Three families maximum; additional families trigger audit failures
  • CSS custom properties (--font-display, --font-body, --font-outlier) implement the discipline per-theme in tokens.css
  • Automated audits enforce compliance through the Hallmark verification pipeline

Frequently Asked Questions

What happens if a page needs more than three font families?

Hallmark's audit pipeline flags the page as critical design-system drift. The build or deployment process blocks publication until the violation is resolved—either by removing extraneous fonts or requesting formal exception review.

Can the outlier font be used for more than two elements if they're the same component?

No. The limit is two locations per page, not two component instances. A wordmark appearing in header and footer counts as two locations; adding a hero statistic would exceed the limit.

Do italic or bold variants of the same family count separately?

No. Weight and style variations of a single typeface family count as one family. Geist 400, Geist 700, and Geist Italic collectively represent one family; Geist Mono introduces a second distinct family.

Where are the official font definitions stored?

Font families for each theme are defined as CSS custom properties in [site/css/tokens.css](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). The complete rules and philosophy appear in [skills/hallmark/references/typography.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/typography.md).

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →