Sass Variable Overrides vs CSS Custom Properties for Bulma Runtime Theming

Dividing Customization Responsibilities

For projects requiring both structural changes and runtime theme switching, Sass variables should govern structural tokens (e.g., border-radius, spacing) and CSS custom properties should govern visual state tokens (e.g., colors, accents).

This division is necessary because Bulma does not map every Sass variable to a CSS custom property. Structural tokens are often compiled into static values during the build process; attempting to override them via CSS variables at runtime will have no effect if the compiled CSS contains hardcoded units rather than var() references.

Determining Property Exposure

Since there is no exhaustive documentation for every exposed CSS variable in Bulma v1, you must verify the compiled output. To determine if a property is exposed without manually scanning the entire stylesheet, use the following verification method:

1. Search the compiled CSS file for the property name (e.g., border-radius).
2. Check the assigned value: if it uses var(--variable-name), it is exposed for runtime control. If it is a static value (e.g., 4px), it is a Sass-only token that requires a rebuild to change.

Preventing Value Drift

To avoid maintaining parallel layers of values, implement a Single Source of Truth pattern. Define your tokens in a dedicated Sass variables file and map them to both the Bulma Sass variables and the :root CSS properties simultaneously.

// _tokens.scss
$my-brand-primary: #00d1b2;
$my-brand-radius: 0.5rem;

// Override Bulma Sass variables (Build-time)
$primary: $my-brand-primary;
$radius: $my-brand-radius;

// Map to CSS Custom Properties (Runtime)
:root {
  --primary: #{$my-brand-primary};
  --radius: #{$my-brand-radius};
}

This ensures that any change to the token file updates both the structural build and the runtime variables in a single compilation cycle. This approach assumes the use of Bulma v1.0+; earlier versions lack the native CSS variable architecture required for this pattern.