7.3 KiB
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 |