Customizing Colors and Fonts

Choosing a Color Palette

Your curriculum's color palette sets its personality before readers engage with a single word. Here's how to choose wisely.

Start With Your Primary Color

The primary color is your brand. It appears on:

Call-to-action buttons
Hover states
Accent borders on callouts and concept cards
Links (in some themes)

Academic/Serious: Deep blues (#1e40af), dark grays (#374151), forest green (#166534)

Warm/Inviting: Terracotta (#9a3412), amber (#b45309), burgundy (#991b1b)

Modern/Tech: Electric blue (#2563eb), purple (#7c3aed), teal (#0d9488)

Keep Enough Contrast

Whatever primary you choose, ensure your text remains readable:

/* Good: High contrast */
--color-text: #1f2937;        /* Dark gray text */
--color-background: #ffffff;  /* White background */

/* Bad: Low contrast */
--color-text: #9ca3af;        /* Light gray text */
--color-background: #f3f4f6;  /* Light gray background */

Example: Academic Blue Theme

:root {
  --color-primary: #1e40af;
  --color-primary-hover: #1e3a8a;
  --color-accent: #3b82f6;
  --color-background: #ffffff;
  --color-surface: #ffffff;
  --color-text: #1f2937;
  --color-text-muted: #6b7280;
  --color-border: #1e40af;
  --color-border-light: #dbeafe;
}

This palette says "scholarly but approachable"—the blue connotes trust and authority without being cold.

Choosing Fonts

Fonts have distinct personalities. Choose based on what your curriculum communicates.

System Fonts (Default)

--font-heading: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
--font-body: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;

Pros: Loads instantly, looks native on each platform, no external dependencies Best for: Technical curricula, minimalist design, performance priority

Serif Fonts

--font-heading: Georgia, 'Times New Roman', serif;
--font-body: Georgia, 'Times New Roman', serif;

Pros: Traditional, academic feel, excellent for long-form reading Best for: Humanities, philosophy, literary analysis

Custom Sans-Serif (Inter)

First, add to src/app.html in the <head>:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">

Then in src/app.css:

--font-heading: 'Inter', system-ui, sans-serif;
--font-body: 'Inter', system-ui, sans-serif;

Pros: Modern, highly legible, excellent for web Best for: Contemporary topics, design-focused curricula

Mixed Pairing

--font-heading: Georgia, 'Times New Roman', serif;
--font-body: system-ui, -apple-system, sans-serif;

Serif headings add gravitas; sans-serif body maintains readability.

Testing Your Choices

After making changes, walk through the site:

Homepage: Is the hero card inviting? Do cluster cards feel cohesive?
Curriculum listing: Can you scan cluster titles easily?
Lesson page: Is body text comfortable to read? Do code blocks stand out?
Mobile: Do colors and fonts work at smaller sizes?

Common Mistakes

Too Many Colors

Stick to 3-4 colors maximum:

Primary (brand)
Background
Text
One accent (optional)

More than this creates visual noise.

Low Contrast Text

Gray text on gray backgrounds might look "sophisticated" but destroys readability. Your readers will unconsciously strain and leave.

Slow-Loading Fonts

Every custom font adds load time. If you use Google Fonts, use display=swap and limit weights:

<!-- Good: Only needed weights -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap">

<!-- Bad: All weights -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@100;200;300;400;500;600;700;800;900">

Next Steps

Colors and fonts are the foundation. The next lesson covers advanced customization—border radius, shadows, and custom CSS for when the theme variables aren't enough.

Assignment

Apply a custom color palette to your curriculum site:

Open src/app.css in your editor
Choose a color palette from the styling guide (or create your own)
Update the color variables in the :root section
Run pnpm dev and preview your changes
Test the palette across multiple pages

Bonus: Try a custom font. Add a Google Fonts link to src/app.html and update the font variables.

Read: Styling Guide - Color Palettes

Color Semantics

Colors aren't just aesthetic—they communicate meaning:

Primary: Your brand identity. Used for buttons, accents, emphasis.
Background/Surface: The canvas. Usually white or very light.
Text: Must have high contrast with background for readability.
Border: Defines boundaries. Can be subtle or bold.

When choosing colors, think about what each will communicate.

Font Pairing

The site uses two font variables:

--font-heading: For titles, navigation, emphasis
--font-body: For paragraphs, descriptions, lists

Common approaches:

Same font for both: Clean, unified look (most common)
Serif headings, sans body: Classic, academic feel
Sans headings, serif body: Modern but readable

System fonts (the default) load instantly. Custom fonts add personality but require loading.

Contrast and Accessibility

Your text must be readable. The WCAG guidelines recommend:

Regular text: 4.5:1 contrast ratio with background
Large text: 3:1 contrast ratio

The default theme uses black on white (21:1 ratio)—maximum contrast. If you lighten text or darken backgrounds, verify you maintain readability.

Use a contrast checker like WebAIM's tool.

What's the difference between --color-primary and --color-accent?

Hint: Think about frequency of use and where each appears.

Why might you choose system fonts over a custom font like Inter?

Hint: Consider loading performance and dependencies.

Realtime Colors

Juxtopposed

Generate and preview color palettes in real-time.