A three-layer system
Every visual value in WallabyX follows a clear inheritance chain. Themes define the defaults, users customize them, blocks can override locally.
Layer 1
Theme defaults
siteDefaults.* in your theme file. Defines the base colors, typography, spacing, and button styles for the entire site.
Layer 2
User customizations
Saved in theme_customizations table. Users can tweak any value exposed in customizableSettings — without touching code.
Layer 3
Block overrides
Individual block props. Only applied when a user explicitly overrides a value on a specific block. Everything else inherits from above.
What a theme controls
Colors
Primary, background, foreground, accent, border. All global, all customizable per-site.
Typography
H1/H2/H3 size, weight, line height with clamp() for responsive scaling. Body size and color too.
Menu
Background, padding, hover colors, submenu styles, mobile drawer position and breakpoint.
Layout & Spacing
Content max width, container padding, section vertical spacing, block gap — all via Tailwind classes.
How to create a theme
Three steps. One file. Full control.
01
Create the file
Create themes/my-theme.ts and export a Theme object. Set id, name, schemaVersion: 'v1', and all the siteDefaults, menuSettings and customizableSettings your theme needs.
02
Register it
Open themes/index.ts, import your theme and add it to the themes array. The CMS will discover it automatically on next build.
03
Expose controls
Define customizableSettings to let users tweak your theme without code. The CMS auto-generates the UI controls from your definitions.
Customizable controls
Declare which settings users can tweak. The CMS generates the control UI automatically — no extra code needed.
Good to know
Keep id stable
The theme id is saved in the sites table in the database. Never change it after launch — it would break the theme association for all sites using it.
Use clamp() for typography
Set h1Size, h2Size and h3Size using clamp() expressions for fluid, responsive typography that scales between screen sizes without media queries.
Tailwind classes for layout
Use contentMaxWidthClass (max-w-3xl to max-w-5xl), contentPaddingClass (px-*) and blockGapClass (space-y-3 to space-y-8) to control the overall layout rhythm.
DB migrations for new fields
If you add a new property that needs to be persisted in the database, add a migration in supabase/migrations/ and update the relevant defaults.
Ready to build your theme?
Read the full theme documentation and start from the built-in example themes.