Understanding the Theme System

How Styling Works in This Template

Every component in this site—cards, buttons, headers, code blocks—gets its colors, fonts, and sizes from CSS custom properties defined in one central file.

Here's a simplified view of how it works:

/* In src/app.css */
:root {
  --color-primary: #000000;
}

/* In a component */
.button {
  background-color: var(--color-primary);
}

When you change --color-primary to #2563eb (a blue), every element using that variable updates automatically. You don't need to find and replace colors throughout the codebase.

The Theme File

All theme variables live in src/app.css. Open this file and you'll see sections for:

Section	What It Controls
Colors	Primary, background, text, borders
Typography	Font families, weights
Border Radius	Corner roundness
Shadows	Depth effects
Spacing	Consistent margins and padding

Each section has comments explaining the options and how to change them.

What Components Use the Theme

The theme variables are used by every visual element:

Cards and Panels

Cluster cards on the curriculum page
Lesson cards in cluster views
Concept cards within lessons
Assignment and knowledge check sections

Interactive Elements

Call-to-action buttons
Navigation links
Copy buttons on code blocks

Content Elements

Headings and body text
Code blocks and inline code
Blockquotes and callouts

The "No Surprises" Principle

The theme system follows a simple principle: changing a value should do exactly what you expect, everywhere.

Change --color-primary? All primary-colored elements update.
Change --radius-base? All card corners update.
Change --font-heading? All headings update.

There are no hidden dependencies or surprising side effects. If you change a color, it changes that color—nothing more, nothing less.

Trying It Out

The best way to understand the theme system is to experiment:

Open src/app.css in your editor
Find --color-primary: #000000;
Change it to --color-primary: #dc2626; (a red)
Save and watch the dev server hot-reload
See how buttons, accents, and borders all change

Now you understand the power of the theme system. The next lesson covers practical customization of colors and typography.

CSS Custom Properties

The site uses CSS custom properties (also called CSS variables) to control its appearance. These are defined once in src/app.css and used throughout all components.

For example, --color-primary defines your main brand color. Change it once, and every button, link, and accent updates automatically.

This means you can transform the entire look of the site by editing a handful of values in one file.

The Three Layers

The site is built in three distinct layers:

Content — Markdown files in content/. Managed by the CMS.
Structure — Svelte components in src/routes/. Defines layout and behavior.
Styling — CSS variables in src/app.css. Controls visual appearance.

You customize layer 3 (styling) without touching layers 1 or 2. This separation means your visual changes won't break content or functionality.

Safe vs. Unsafe Changes

Safe to change:

Values of CSS variables (colors, fonts, sizes)
Adding custom CSS rules at the end of app.css

Unsafe to change:

Variable names (components reference these exactly)
HTML structure in Svelte files
Field names in the CMS config

Stick to changing values, not names, and you'll never break anything.

Where are all the theme variables defined?

Hint: It's a single CSS file at the root of the src directory.

Why is it safe to change variable values but not variable names?

Hint: Think about what happens when a component tries to use a variable that doesn't exist.