typography

Elegant, modern typography sets the foundation for professional interfaces.

Typography

Elegant, modern typography sets the foundation for professional interfaces.

Font Selection

Primary Fonts

1. Zen (https://hanzo.ai/font) - USE FOR ALL UI TEXT

Hanzo's own family, drawn for interfaces. It ships in @hanzo/font, so a project carries it rather than fetching it.

Characteristics:

• Excellent legibility at all sizes
• Perfect for UI text and content
• Crisp rendering on all displays
• Variable font with flexible weights

Use Zen for:

• Body text and paragraphs
• Headings and titles
• UI labels and buttons
• Navigation and menus
• Form fields and inputs
• 95% of all typography

font-family: 'Zen', -apple-system, BlinkMacSystemFont, sans-serif;

2. Zen Mono (https://hanzo.ai/font) - USE FOR ALL CODE/TECHNICAL

Purpose-built for developers.

Characteristics:

• Increased height for better readability
• Ligatures for common code patterns (=>, >=, !=)
• Clear distinction between similar characters (0/O, 1/l/I)
• Optimized for long reading sessions

Use Zen Mono for:

• Code blocks and snippets
• Terminal output
• Log viewers
• Diff displays
• File paths
• Technical identifiers
• Minimum 14px font size

font-family: 'Zen Mono', 'Fira Code', Consolas, monospace;
font-size: 14px; /* minimum */
font-variant-ligatures: common-ligatures; /* enable ligatures */

Alternative Elegant Fonts

If Zen or Zen Mono are unavailable:

Sans-serif alternatives:

• IBM Plex Sans - Professional, humanist, good brand font
• Space Grotesk - Modern, geometric, good for headlines

Monospace alternatives:

• Zen Mono - the companion monospace
• Fira Code - Excellent ligatures, widely supported
• Berkeley Mono - Premium option if budget allows
• Cascadia Code - Microsoft's code font with ligatures

System font fallback:

/* If custom fonts fail to load */
-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif

Font Loading Strategy

Use optimal loading to prevent FOIT (Flash of Invisible Text):

One import declares both faces, already set to font-display: swap:

import '@hanzo/font/css';

It expands to this, which is what to write by hand if you are self-hosting the files rather than taking the package:

@font-face {
  font-family: 'Zen';
  src: url('/fonts/zen-sans/Zen-Variable.woff2') format('woff2');
  font-display: swap; /* Show fallback immediately, swap when loaded */
  font-weight: 100 900; /* Variable font weight range */
}

@font-face {
  font-family: 'Zen Mono';
  src: url('/fonts/zen-mono/ZenMono-Variable.woff2') format('woff2');
  font-display: swap;
  font-weight: 100 900;
}

Typography Scales

Use a modular scale for consistent hierarchy.

Common scales:

• 1.25 (major third) - compact, good for dense interfaces
• 1.333 (perfect fourth) - balanced, most versatile
• 1.5 (perfect fifth) - generous, good for marketing

Example: 1.25 scale (recommended):

:root {
  --font-size-xs: 0.64rem;   /* 10.24px */
  --font-size-sm: 0.8rem;    /* 12.8px */
  --font-size-base: 1rem;    /* 16px */
  --font-size-lg: 1.25rem;   /* 20px */
  --font-size-xl: 1.563rem;  /* 25px */
  --font-size-2xl: 1.953rem; /* 31.25px */
  --font-size-3xl: 2.441rem; /* 39px */
  --font-size-4xl: 3.052rem; /* 48.8px */
}

Usage:

body {
  font-size: var(--font-size-base);
  line-height: 1.6;
}

h1 { font-size: var(--font-size-4xl); }
h2 { font-size: var(--font-size-3xl); }
h3 { font-size: var(--font-size-2xl); }
h4 { font-size: var(--font-size-xl); }

small { font-size: var(--font-size-sm); }

Line Height

Body text: 1.5-1.6 for readability Headings: 1.1-1.3 for impact Code: 1.5-1.6 for clarity

body {
  line-height: 1.6;
}

h1, h2, h3, h4, h5, h6 {
  line-height: 1.2;
}

code, pre {
  line-height: 1.6;
}

Font Weights

Zen supports variable weights (100-900):

• 300 (light) - Use sparingly
• 400 (regular) - Body text
• 500 (medium) - UI emphasis
• 600 (semibold) - Headings, buttons
• 700 (bold) - Strong emphasis

Zen Mono:

• 400 (regular) - Most code
• 700 (bold) - Emphasis in code

/* Semantic weight variables */
:root {
  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  --font-weight-bold: 700;
}

Best Practices

Do:

• ✅ Limit to 2 font families maximum (one sans, one mono)
• ✅ Use Zen for 95% of text
• ✅ Reserve Zen Mono exclusively for code
• ✅ Use font-display: swap for faster rendering
• ✅ Prefer variable fonts (smaller file size, flexible weights)
• ✅ Set minimum 14px for code fonts
• ✅ Enable ligatures in monospace fonts
• ✅ Use semantic weight variables

Don't:

• ❌ Mix multiple sans-serif fonts
• ❌ Mix multiple monospace fonts
• ❌ Use decorative fonts in interfaces
• ❌ Set code font smaller than 14px
• ❌ Forget fallback fonts
• ❌ Block rendering waiting for fonts (use swap)
• ❌ Use Comic Sans (ever)

Accessibility

Minimum sizes:

• Body text: 16px (1rem)
• Small text: 14px (0.875rem)
• Code: 14px minimum

Contrast requirements:

• Normal text: 4.5:1 contrast ratio
• Large text (18pt+): 3:1 contrast ratio
• Use tools like WebAIM Contrast Checker

Example Complete Setup

/* CSS Variables */
:root {
  /* Font families */
  --font-sans: 'Zen', -apple-system, BlinkMacSystemFont, sans-serif;
  --font-mono: 'Zen Mono', 'Fira Code', Consolas, monospace;
  
  /* Font sizes (1.25 scale) */
  --font-size-xs: 0.64rem;
  --font-size-sm: 0.8rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.25rem;
  --font-size-xl: 1.563rem;
  --font-size-2xl: 1.953rem;
  --font-size-3xl: 2.441rem;
  --font-size-4xl: 3.052rem;
  
  /* Font weights */
  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  --font-weight-bold: 700;
}

/* Base styles */
body {
  font-family: var(--font-sans);
  font-size: var(--font-size-base);
  line-height: 1.6;
  font-weight: var(--font-weight-normal);
}

/* Code elements */
code, pre, kbd, samp {
  font-family: var(--font-mono);
  font-size: 14px; /* minimum readable size */
  line-height: 1.6;
  font-variant-ligatures: common-ligatures;
}

/* Headings */
h1 { 
  font-size: var(--font-size-4xl);
  font-weight: var(--font-weight-bold);
  line-height: 1.2;
}

h2 { 
  font-size: var(--font-size-3xl);
  font-weight: var(--font-weight-semibold);
  line-height: 1.2;
}

h3 { 
  font-size: var(--font-size-2xl);
  font-weight: var(--font-weight-semibold);
  line-height: 1.3;
}

Loading Fonts in Next.js/React

Zen and ZenMono arrive already built — subsetting, display: swap and the fallback metrics are baked in, so there is nothing to call and nothing to pass.

// app/layout.tsx or _app.tsx
import { Zen, ZenMono } from '@hanzo/font';

export default function RootLayout({ children }) {
  return (
    <html className={`${Zen.variable} ${ZenMono.variable}`}>
      <body>{children}</body>
    </html>
  );
}

They publish --font-zen-sans and --font-zen-mono.

Quick Reference

| Element | Font | Size | Weight | |---------|------|------|--------| | Body text | Zen | 16px (1rem) | 400 | | UI labels | Zen | 14-16px | 500 | | Headings | Zen | Scale-based | 600-700 | | Buttons | Zen | 14-16px | 500-600 | | Code blocks | Zen Mono | 14px min | 400 | | Terminal | Zen Mono | 14px | 400 | | Small text | Zen | 14px min | 400 |