Customising a theme's CSS without re-deploying
How to use the Custom Theme tab in admin to override theme CSS variables on the fly — perfect for tweaking spacing, fonts, or accent colours without touching the theme file.
Every shipped VeloCMS theme exposes its design tokens as CSS variables — accent colour, surface, foreground, type scale, all of it. The admin's Custom Theme tab gives you a small editor that writes per-tenant overrides on top of those variables, and the changes go live without re-deploying. Useful when a reader points out the link colour is unreadable on dark mode and you don't want to wait for a full build cycle.
Open the editor
Navigate to /admin/themes/custom. The form lists every overridable variable for the currently active theme. Change a value, click Save, refresh your blog tab — that's the entire workflow. Overrides are stored in the `tenant_themes` PocketBase collection and merged on top of the preset at render time.
What you can override
Each theme exposes a different set, but the common ones across all 38:
- --bg, --fg — base background and foreground colours
- --accent, --accent-fg — primary accent (links, CTA buttons)
- --muted, --muted-fg — secondary colour for meta text
- --surface, --border — card and divider colours
- --font-sans, --font-serif, --font-mono — font family stack
- --space-1, --space-2, ..., --space-8 — vertical rhythm scale
The form validates colour values as OKLCH or hex; invalid entries surface inline before Save fires.
Reset to default
Toggle the "Enabled" switch off on the Custom Theme page and your blog falls back to the preset's defaults instantly. The override values stay in the database, so you can flip enabled back on later without re-typing anything.
When you need more than a variable
If you need to change a layout — say, move the sidebar from right to left, or hide the byline date — that's outside the variable system; you'd fork the theme. Variables are for design tokens, not structural changes. For structural edits, copy your theme to `src/components/themes/<your-slug>/`, register it in `theme-registry.ts`, and push.