Skip to content
Early bird + Black Friday · 73% off

Get ZeroDirs for $179 $49

Claim $49 deal

Theming

Every colour, corner and font resolves to a --brand-* property set by theme in site.config.ts.

theme.preset in site.config.ts picks the palette:

Preset Brand radius / radiusSm
default blue, oklch(0.55 0.2 260), white background 0.75rem / 0.375rem
warm terracotta, oklch(0.555 0.165 40), warm off-white paper 1rem / 0.5rem
mono near-black, oklch(0.16 0 0), neutral greys 0 / 0, square
site.config.ts
theme: {
preset: 'warm',
tokens: { primary: 'oklch(0.55 0.19 15)', radius: '0.75rem' },
darkTokens: { primary: 'oklch(0.75 0.15 15)' },
font: { provider: 'fontsource', family: 'Inter', weights: [400, 600, 700], preloadWeight: 600 },
},

Only the tokens you name change.

  1. Write the CSS.

    Copy src/styles/presets/warm.css to src/styles/presets/<name>.css, scoped to :root[data-preset=<name>] and :root[data-preset=<name>][data-theme=dark]. Every colour and radius token goes in both blocks.

  2. Import it.

    src/styles/global.css
    @import "./presets/<name>.css";
  3. Register it.

    src/config/presets.ts
    { name: '<name>', description: '…', ogColors: { bg: '#…', fg: '#…', primary: '#…', primaryFg: '#…', muted: '#…' } },

    pnpm check now accepts the name.

  4. Use it and test it.

    site.config.ts
    theme: { preset: '<name>' },

    pnpm test theme asserts registration and contrast; pnpm og:default regenerates public/og-default.png.

Where You should see
The config parses pnpm check:config site.config.ts OK — <your site name> (https://your-domain.com)
The palette holds up pnpm test theme Test Files 1 passed: text at 4.5:1 and lineStrong at 3:1 on every background, light and dark
The registration the same run every preset in PRESETS has its file, @import and dark block; schema.ts and default.css agree on token names
The pages pnpm build, then pnpm preview http://localhost:4321/ in the new colours; the toggle switches without a flash and a reload keeps the choice
  • pnpm check:config refuses a Tailwind class (anything starting bg-, text-, border-, ring-, fill-, stroke-, font- or rounded-) or a ;, } or < in a token: site.config.ts › theme.tokens.primary: must be a CSS value, not a Tailwind class name, must not contain ";", "}" or "<".
  • ogColors in src/config/presets.ts repeats the palette in hex for the OG renderer: change a brand colour and its hex together. Only a hex theme.tokens.primary reaches the images.
  • lineStrong (inputs, checkboxes, outline buttons) must hold 3:1 on every background, or pnpm test theme fails.
  • radius is the only corner you set: cards 1.5× (rounded-brand-lg), buttons and badges 3× (rounded-brand-pill), radiusSm the logo tile.
  • system (the default) fetches nothing; fontsource, google and bunny self-host the weights you list. preloadWeight must be one of weights, or pnpm check:config stops: theme.font.preloadWeight: must be one of weights [400, 600, 700].
  • theme.icons is the bundle allow-list of lucide names; every categories[].icon is merged in, a name outside it is missing. Your own acme-mark.svg in src/icons/ renders as <Icon name="local:acme-mark" />; keep that folder’s README, or every build prints [astro-icon] Failed to load icons from "src/icons".
theme.darkMode What happens
'system' (default) follows the OS; the header shows a toggle, and a choice is remembered in localStorage
'light' / 'dark' fixed: data-theme is written on <html> at build time, no toggle and no script

theme.preset, theme.tokens and theme.darkTokens (raw CSS values, not class names), theme.darkMode, theme.font, theme.icons and theme.viewTransitions — theme.

  • Directorysrc/
    • Directorystyles/
      • global.css — Tailwind entry, the @theme inline map, the radius multiples
      • Directorypresets/ — one file per preset; default.css is the baseline
        • …
      • theme.ts — themeCss() and the dark-mode bootstrap script
    • Directoryconfig/
      • presets.ts — the registry: names, descriptions, ogColors
      • schema.ts — the token vocabulary and the CSS-value rules
    • components/site/ThemeToggle.astro — the toggle and its inline script
    • Directoryicons/ — your own SVGs, the local: collection
      • …
  • tests/unit/theme.test.ts — the registration and contrast assertions