font-setup

Font Setup

Install and configure fonts for production web projects with zero layout shift and optimal loading.

Process

Step 1: Detect Project Framework

Read package.json, next.config.*, vite.config.*, astro.config.* to determine:

• Next.js → use next/font/local or next/font/google
• Vite/React → use Fontsource packages or manual @font-face
• Astro → use @fontsource packages or manual @font-face
• Plain HTML → manual @font-face with preload

Step 2: Based on Input

If user specifies a Google Font:

# Option A: Fontsource (recommended)
npm install @fontsource-variable/[font-name]
# Import in entry: import '@fontsource-variable/[font-name]';

# Option B: Self-host WOFF2
mkdir -p public/fonts
# Download from fontsource API or Google Fonts Helper

If user specifies a premium font (Season Mix, GT Alpina, etc.):

1. Provide purchase link and trial availability
2. Generate the directory structure for font files
3. Generate all @font-face declarations
4. Generate CSS custom properties
5. Generate Tailwind config
6. Generate framework-specific setup (next/font/local, etc.)
7. Generate fallback font metrics for zero CLS

If user says list: Show curated anti-slop font recommendations categorized by:

• Premium display fonts
• Free display fonts
• Body text fonts
• Monospace fonts

If user says audit: Scan the project for:

• Missing @font-face declarations
• Fonts loaded from CDN instead of self-hosted
• Missing font-display property
• Missing <link rel="preload"> for primary fonts
• Unused font files in public/fonts/
• Inconsistent font-family references
• Missing fallback font metrics
• Font files not in WOFF2 format (larger than needed)

Step 3: Generate Complete Font Config

Output all files needed:

1. @font-face CSS — declarations with proper font-display, unicode-range
2. CSS variables — --font-display, --font-body, --font-mono
3. Tailwind config — fontFamily extension
4. Framework config — next/font setup or Fontsource imports
5. Preload tags — <link rel="preload"> for primary font only
6. Fallback metrics — ascent-override, descent-override, size-adjust for zero CLS

Step 4: Verify

• Fonts render correctly in browser
• No FOUT (flash of unstyled text) — font-display: swap for body, optional for display
• No CLS — fallback metrics match real font closely
• WOFF2 format used (best compression)
• Only needed weights loaded (don't load all 9 weights)
• Variable font used if 3+ weights needed (single file)

Season Mix Quick Setup

For the Season Collection (the premium anti-slop pairing):

/source-design:font-setup Season Mix

Generates:

• Directory: public/fonts/season/
• @font-face for Season Mix (display) + Season Sans (body)
• CSS variables matching the site's original usage:
  • Display: "Season Mix", "Season Sans", system-ui, -apple-system, sans-serif at 62px/62px
  • Body: seasonSans, "seasonSans Fallback", sans-serif at 15px/18px
• Tailwind fontFamily config
• Next.js localFont config
• Fallback font metrics
• Variable font setup with SERF axis (0=Sans, 50=Mix, 100=Serif)