Files
skills/public/typography.md

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