Should a Bulma theme rely on Sass variable overrides or CSS custom properties for runtime switching?

Direct Answer

Use multiple compiled stylesheets for runtime theme switching. Bulma 1.x's documented, stable theming API is the Sass variable layer; CSS custom property coverage is partial, undocumented, and not a supported runtime extension point.

Why Custom Properties Alone Won't Work

Bulma 1.x exposes a subset of design tokens (font family, weight, line-height, border radius, shadows) as --bulma-* custom properties. However, most component styles—buttons, navigation, cards, forms, tables—are authored with compiled Sass values ($primary, $link, $danger, etc.) that resolve to static color values in the output CSS. Changing --bulma-primary at runtime will not recolor a .button.is-primary because that rule uses a hard-coded hex value, not var(--bulma-primary).

The custom properties that do exist are largely limited to typographic and spacing tokens. Color tokens—the most common theme-switching target—are almost entirely absent from the custom property layer.

Recommended Pattern: Compile Per Theme

1. Create a theme entry file per variant (e.g., theme-light.scss, theme-dark.scss).
2. In each, override the full set of Sass variables ($primary, $dark, $light, $text, $background, etc.) before @use 'bulma'.
3. Compile each entry to a separate CSS bundle (theme-light.css, theme-dark.css).
4. At runtime, swap the <link rel="stylesheet"> reference or toggle a data-theme attribute that loads the appropriate bundle via a build-time import map or dynamic import.

This keeps you on the supported API, avoids forking Bulma, and gives complete control over every component color.

Verification Steps for Your Build

Before committing, confirm the exact custom property surface in your Bulma version:

# In your project root
npm exec -- sass --load-path=node_modules --style=expanded - <<'SCSS'
@use 'bulma' as *;
@debug 'Custom properties in output:';
SCSS
# Then inspect the compiled CSS for var(--bulma-*) occurrences
grep -n 'var(--bulma-' node_modules/bulma/css/bulma.css || echo 'Check your compiled bundle'

You can also set :root { --bulma-primary: red; } in devtools and observe which elements actually react—expect very few.

One Missing Detail

Do you need instant client-side switching without a full page reload, or is a navigation-triggered stylesheet swap acceptable? The answer affects whether you preload all theme bundles or load them on demand.