Every colour, corner and font resolves to a --brand-* property set by theme in
site.config.ts.
Overriding tokens
Section titled “Overriding tokens”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 |
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.
Add a preset
Section titled “Add a preset”-
Write the CSS.
Copy
src/styles/presets/warm.csstosrc/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. -
Import it.
src/styles/global.css @import "./presets/<name>.css"; -
Register it.
src/config/presets.ts { name: '<name>', description: '…', ogColors: { bg: '#…', fg: '#…', primary: '#…', primaryFg: '#…', muted: '#…' } },pnpm checknow accepts the name. -
Use it and test it.
site.config.ts theme: { preset: '<name>' },pnpm test themeasserts registration and contrast;pnpm og:defaultregeneratespublic/og-default.png.
Verify
Section titled “Verify”| 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 |
Worth knowing
Section titled “Worth knowing”pnpm check:configrefuses a Tailwind class (anything startingbg-,text-,border-,ring-,fill-,stroke-,font-orrounded-) 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 "<".ogColorsinsrc/config/presets.tsrepeats the palette in hex for the OG renderer: change a brand colour and its hex together. Only a hextheme.tokens.primaryreaches the images.lineStrong(inputs, checkboxes, outline buttons) must hold 3:1 on every background, orpnpm test themefails.radiusis the only corner you set: cards 1.5× (rounded-brand-lg), buttons and badges 3× (rounded-brand-pill),radiusSmthe logo tile.system(the default) fetches nothing;fontsource,googleandbunnyself-host the weights you list.preloadWeightmust be one ofweights, orpnpm check:configstops:theme.font.preloadWeight: must be one of weights [400, 600, 700].theme.iconsis the bundle allow-list of lucide names; everycategories[].iconis merged in, a name outside it is missing. Your ownacme-mark.svginsrc/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".
Dark mode
Section titled “Dark mode”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 |
Configuration
Section titled “Configuration”theme.preset, theme.tokens and theme.darkTokens (raw CSS values, not class names), theme.darkMode, theme.font, theme.icons and theme.viewTransitions — theme.
Directory
src/Directory
styles/global.css— Tailwind entry, the@theme inlinemap, the radius multiplesDirectory
presets/— one file per preset;default.cssis the baseline- …
theme.ts—themeCss()and the dark-mode bootstrap script
Directory
config/presets.ts— the registry: names, descriptions,ogColorsschema.ts— the token vocabulary and the CSS-value rules
components/site/ThemeToggle.astro— the toggle and its inline scriptDirectory
icons/— your own SVGs, thelocal:collection- …
tests/unit/theme.test.ts— the registration and contrast assertions
Related
Section titled “Related”Make it yoursName, domain, categories and colours in one pass.
OG imagesThe images read the preset's hex colours, not the CSS.
Configuration referenceEvery theme field, its type and its default.