Skip to main content
The theme configuration in Quartz controls the visual appearance of your site, including color schemes for light and dark modes, typography, and font loading.

​
Theme Structure

Theme settings are nested within the configuration object:
quartz.config.ts
const config: QuartzConfig = {
  configuration: {
    theme: {
      fontOrigin: "googleFonts",
      cdnCaching: true,
      typography: {
        header: "Schibsted Grotesk",
        body: "Source Sans Pro",
        code: "IBM Plex Mono",
      },
      colors: {
        lightMode: { /* ... */ },
        darkMode: { /* ... */ },
      },
    },
  },
}

​
Typography

Define fonts for headers, body text, and code blocks.

​
Font Configuration

quartz.config.ts
const config: QuartzConfig = {
  configuration: {
    theme: {
      typography: {
        header: "Schibsted Grotesk",
        body: "Source Sans Pro",
        code: "IBM Plex Mono",
      },
    },
  },
}
​
typography.header
string
required
Font family for headings (h1, h2, h3, etc.). Example: "Schibsted Grotesk"
​
typography.body
string
required
Font family for body text and paragraphs. Example: "Source Sans Pro"
​
typography.code
string
required
Monospace font for code blocks and inline code. Example: "IBM Plex Mono"

​
Font Loading

​
fontOrigin
'googleFonts' | 'local'
default:"googleFonts"
Where to load fonts from:
  • "googleFonts" - Load from Google Fonts CDN
  • "local" - Use locally hosted font files
​
cdnCaching
boolean
default:true
Enable CDN caching for faster font loading. Only applies when fontOrigin is "googleFonts".
theme: {
  fontOrigin: "googleFonts",
  cdnCaching: true,
  typography: {
    header: "Inter",
    body: "Inter",
    code: "JetBrains Mono",
  },
}
Fonts are automatically loaded from Google Fonts. Ensure font names match exactly.

​
Color Schemes

Quartz supports separate color schemes for light and dark modes. Each mode defines a complete color palette.

​
Color Structure

Both lightMode and darkMode use the same color properties:
​
light
string
Background color for the main content area
​
lightgray
string
Background for secondary UI elements (sidebars, cards)
​
gray
string
Border colors and subtle dividers
​
darkgray
string
Secondary text color (metadata, captions)
​
dark
string
Primary text color for body content
​
secondary
string
Primary accent color (links, buttons)
​
tertiary
string
Secondary accent color (hover states, tags)
​
highlight
string
Background highlight for selections and hover states
​
textHighlight
string
Text highlight color (like a marker)
​
danger
string
Error and warning text color
​
dangerSubtle
string
Background for error/warning messages

​
Light Mode Colors

Example from the Siebenlande configuration:
quartz.config.ts
colors: {
  lightMode: {
    light: "#faf8f8",
    lightgray: "#e5e5e5",
    gray: "#b8b8b8",
    darkgray: "#4e4e4e",
    dark: "#2b2b2b",
    secondary: "#284b63",
    tertiary: "#84a59d",
    highlight: "rgba(143, 159, 169, 0.15)",
    textHighlight: "#fff23688",
    danger: "#d1242f",
    dangerSubtle: "#ffebe9",
  },
}

Background

light: #faf8f8
Warm off-white for comfortable reading

Primary Accent

secondary: #284b63
Deep blue for links and interactive elements

Secondary Accent

tertiary: #84a59d
Muted sage green for tags and metadata

​
Dark Mode Colors

Example from the Siebenlande configuration:
quartz.config.ts
colors: {
  darkMode: {
    light: "#161618",
    lightgray: "#393639",
    gray: "#646464",
    darkgray: "#d4d4d4",
    dark: "#ebebec",
    secondary: "#7b97aa",
    tertiary: "#84a59d",
    highlight: "rgba(143, 159, 169, 0.15)",
    textHighlight: "#b3aa0288",
    danger: "#f85149",
    dangerSubtle: "rgba(248, 81, 73, 0.1)",
  },
}

Background

light: #161618
Near-black with subtle warmth

Primary Accent

secondary: #7b97aa
Desaturated blue for reduced eye strain

Secondary Accent

tertiary: #84a59d
Consistent sage green across both modes

​
Complete Theme Example

Here’s the full theme configuration from Siebenlande:
quartz.config.ts
import { QuartzConfig } from "./quartz/cfg"

const config: QuartzConfig = {
  configuration: {
    theme: {
      fontOrigin: "googleFonts",
      cdnCaching: true,
      typography: {
        header: "Schibsted Grotesk",
        body: "Source Sans Pro",
        code: "IBM Plex Mono",
      },
      colors: {
        lightMode: {
          light: "#faf8f8",
          lightgray: "#e5e5e5",
          gray: "#b8b8b8",
          darkgray: "#4e4e4e",
          dark: "#2b2b2b",
          secondary: "#284b63",
          tertiary: "#84a59d",
          highlight: "rgba(143, 159, 169, 0.15)",
          textHighlight: "#fff23688",
          danger: "#d1242f",
          dangerSubtle: "#ffebe9",
        },
        darkMode: {
          light: "#161618",
          lightgray: "#393639",
          gray: "#646464",
          darkgray: "#d4d4d4",
          dark: "#ebebec",
          secondary: "#7b97aa",
          tertiary: "#84a59d",
          highlight: "rgba(143, 159, 169, 0.15)",
          textHighlight: "#b3aa0288",
          danger: "#f85149",
          dangerSubtle: "rgba(248, 81, 73, 0.1)",
        },
      },
    },
  },
}

export default config

​
Color Guidelines

Ensure sufficient contrast between text and background colors:
  • Body text: Minimum 4.5:1 contrast ratio (WCAG AA)
  • Large text (18pt+): Minimum 3:1 contrast ratio
  • Use tools like WebAIM Contrast Checker
Test both light and dark modes for accessibility.
Light mode: Higher contrast, brighter colors
  • Use darker text on lighter backgrounds
  • More saturated accent colors work well
Dark mode: Reduced contrast, muted colors
  • Avoid pure white (#ffffff) - use off-white (#ebebec)
  • Desaturate accent colors to reduce eye strain
  • Lower opacity for highlights and overlays
Transparent colors (rgba) are useful for:
  • Highlights: rgba(143, 159, 169, 0.15)
  • Text highlights: #fff23688 (hex with alpha)
  • Overlays: Semi-transparent backgrounds
Ensure transparent colors work on all background variations.
Color properties have semantic meanings:
  • light → dark: Background to foreground hierarchy
  • secondary: Primary interactive elements
  • tertiary: Secondary interactive elements
  • danger: Errors, warnings, destructive actions
Maintain these semantic relationships for consistency.
typography: {
  header: "Inter",
  body: "Inter",
  code: "JetBrains Mono",
}
Clean, professional, excellent readability.

​
Testing Your Theme

After configuring your theme:
  1. Build your site: npx quartz build
  2. Test both modes: Toggle between light and dark mode
  3. Check contrast: Verify text is readable in all contexts
  4. Test interactive states: Hover over links, buttons, and other elements
  5. Validate on devices: Check appearance on desktop, tablet, and mobile
Changes to theme configuration require rebuilding your site to take effect.

Site Settings

Configure page title, locale, and behavior

Layout Configuration

Organize components and page structure

Build docs developers (and LLMs) love

Get started for freeTalk to us