Hallmark Typography Rules: The Design-First System from Nutlope/hallmark

Hallmark enforces a strict "2+1" font pairing system with banned defaults, ratio-based scales, and a maximum of three font families per page to eliminate typographic "slop."

The Nutlope/hallmark repository implements a design-first typography system that governs every aspect of text rendering across themes. These Hallmark typography rules specify exact font families, weight contrasts, scale ratios, and prohibited defaults to ensure intentional visual hierarchy. The system is codified in skills/hallmark/references/typography.md and implemented through CSS custom properties in site/css/tokens.css.

Core Principles

Hallmark operates on five non-negotiable principles that prioritize intentional design over default browser behavior.

Every page is a pairing, not a single font. The system requires at minimum one display face plus one body face, with single-font pages permitted only for deliberate aesthetic choices like monospaced terminal designs. Weight extremes signal intent—juxtaposing 200 against 800 reads as intentional rather than accidental. Size steps follow mathematical ratios (major-third 1.25, perfect-fourth 1.333, perfect-fifth 1.5, or golden 1.618) rather than arbitrary increments. Line-height varies with size, running tight for display text (1.05–1.2) and comfortable for body (1.5–1.65). Measure stays bounded between 45–75 characters per line, defaulting to max-width: 65ch.

The 2+1 Rule: Maximum Three Font Families

The central constraint of Hallmark typography rules limits any page to three font families total: one display, one body, and one optional outlier.

• Display: Used for headings, hero sections, and focal points
• Body: Used for prose, UI elements, and forms
• Optional Outlier: Reserved for single-use cases like wordmarks, hero stats, pull-quotes, or mastheads

As stated in skills/hallmark/references/typography.md (lines 13-16): "Four families is slop. Two is canonical. Three is the ceiling, used sparingly."

Outlier Constraints

The optional third font faces strict usage restrictions:

• Maximum two usages on the entire page
• Single role—it must tag a specific content type (e.g., wordmark only)
• Mono counts as a face—adding Geist Mono consumes one of your three slots
• Weight variations don't add families—using Fraunces at 400 and 700 still counts as one family

Banned Default Fonts

Hallmark explicitly prohibits common system and web-font defaults unless accompanied by a deliberate design justification. These fonts are considered "on-distribution for every LLM" and must be avoided.

Banned sans-serifs: Inter, Roboto, Open Sans, Lato, Poppins, Source Sans, Nunito, Montserrat, Raleway, Work Sans, system-ui, Arial, Helvetica

Banned serifs: Merriweather, Playfair Display (as body), Lora, Source Serif, Georgia (as default)

Banned monos: Courier New, Consolas (as default), system mono

Scale and Size System

The system defaults to a major-third ratio (1.25) built on a 16 px body baseline. CSS custom properties in site/css/tokens.css define the scale:

/* site/css/tokens.css – scale definitions */
:root {
  --text-xs:    0.75rem;   /* 12 px */
  --text-sm:    0.875rem;  /* 14 px */
  --text-base:  1rem;     /* 16 px */
  --text-md:    1.125rem; /* 18 px */
  --text-lg:    1.375rem; /* 22 px */
  --text-xl:    1.75rem;  /* 28 px */
  --text-2xl:   2.25rem;  /* 36 px */
  --text-display: clamp(3.0rem, 5.5vw + 1.0rem, 5.75rem);
}

Display headings use a clamp function to maintain responsive scaling without excessive wrapping: clamp(2.75rem, 5vw + 1rem, 5.25rem). The system caps display size at 5.5rem (88 px) to prevent line-wrap drama.

Implementation in Code

CSS Tokens

The root variables establish the 2+1 pairing and weight contrasts:

/* site/css/tokens.css – core typography tokens */
:root {
  --font-display: "Fraunces", ui-serif, Georgia, serif;
  --font-body:    "Geist", ui-sans-serif, system-ui, sans-serif;
  --font-outlier: "Geist Mono", ui-monospace, monospace;

  /* Scale */
  --text-base:    1rem;            /* 16 px */
  --text-display: clamp(2.75rem, 5vw + 1rem, 5.25rem);
  
  /* Weight contrast */
  --display-weight: 340;          /* variable display weight */
}

HTML Application

Applying the 2+1 rule in markup:

<!DOCTYPE html>
<html lang="en" data-theme="studio">
<head>
  <link rel="stylesheet" href="/site/css/tokens.css">
  <style>
    .wordmark { 
      font-family: var(--font-outlier); 
      font-weight: 600; 
    }
    h1 { font-family: var(--font-display); }
    p  { font-family: var(--font-body); }
  </style>
</head>
<body>
  <header class="wordmark">Hallmark</header>
  <h1>Design-first typography</h1>
  <p>Body text uses the Geist family at 16px with 1.5 line-height.</p>
</body>
</html>

This implements the canonical pairing: Fraunces (display), Geist (body), and Geist Mono (outlier for the wordmark only).

Summary

• Hallmark typography rules enforce a "2+1" system: maximum three font families (display, body, optional outlier) per page
• Banned defaults include Inter, Roboto, Open Sans, and other common LLM-trained fonts
• Scale ratios must be mathematical (major-third 1.25, perfect-fourth 1.333, etc.) rather than arbitrary increments
• Measure defaults to max-width: 65ch (45–75 characters) for optimal readability
• Weight contrast requires at least 300 units between body and headings (e.g., 400 vs 700)
• Source files: Rules defined in skills/hallmark/references/typography.md, tokens implemented in site/css/tokens.css

Frequently Asked Questions

What is the "2+1 Rule" in Hallmark typography?

The 2+1 Rule limits every page to a maximum of three font families: one display face, one body face, and one optional outlier. Two fonts is the canonical standard; three is the absolute ceiling. Four families constitutes "slop" and violates the design system.

Why are Inter and Roboto banned in Hallmark?

These fonts appear in the "Banned defaults" list because they are standard system fonts heavily represented in LLM training data. Hallmark prohibits them to force intentional typographic choices rather than reaching for familiar defaults. The ban also extends to Arial, Helvetica, Georgia, and Courier New.

How does Hallmark handle responsive font sizing?

The system uses CSS clamp() functions for display text, such as clamp(2.75rem, 5vw + 1rem, 5.25rem), which scales fluidly between minimum and maximum values. The scale itself follows mathematical ratios (major-third 1.25 by default) rather than fixed pixel increments.

What line-height should I use for body text versus headings?

Body text requires a comfortable line-height between 1.5 and 1.65, while display headings use tighter spacing between 1.05 and 1.2. This variation is essential to the Hallmark system—line-height must change with size to maintain proper visual density.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}