Bulma Admin & Architecture Guide

This guide is the deep reference for engineers, architects, and design-system maintainers who integrate, customize, build, or extend Bulma v1.0.4 — the modern, CSS-only framework by Jeremy Thomas (jgthms). It documents the Sass module architecture, the CSS custom-property engine that powers theming, the complete customization surface, the build pipeline, security posture, and the internals needed to reproduce or fork the project.

1. Executive Summary

Bulma is a pure CSS framework. Its sole runtime artifact is one stylesheet (css/bulma.css and its minified twin css/bulma.min.css). It ships zero JavaScript and has no runtime dependencies — the published npm package contains only Sass source, compiled CSS, the license, and the README.

Three architectural decisions define the project:

1. CSS custom properties as the configuration layer. Bulma 1.0 registers hundreds of --bulma-* variables at :root and on component selectors, then builds every rule from them. This is what enables runtime theming, dark mode, and per-subtree overrides without recompiling Sass.
2. HSL-based, accessibility-aware color generation. Each base color is decomposed into hue/saturation/lightness variables; Sass functions derive 20 numbered shades plus light/dark/soft/bold/invert variants, automatically selecting WCAG-contrasting text/background pairings.
3. Modern Dart Sass modules. The codebase uses @use/@forward exclusively (no @import), organized into clear layers: utilities → themes → base → elements → form → components → grid → layout → helpers.

2. Architecture

2.1 Module graph

The compiled stylesheet is produced from a single root entry point that pulls in one aggregator:

// bulma.scss
@charset "utf-8";
/*! bulma.io v1.0.4 | MIT License | github.com/jgthms/bulma */
@use "sass";

sass/_index.scss forwards the layers in a deliberate cascade order:

@forward "utilities";   // variables, functions, controls (no output on their own)
@forward "themes";      // registers --bulma-* variables (light default + dark + setup)
@forward "base";        // minireset, generic element styles, keyframes
@forward "elements";    // button, tag, title, box, table, …
@forward "form";        // input, select, file, field, control, …
@forward "components";  // navbar, card, modal, dropdown, menu, …
@forward "grid";        // columns + smart grid
@forward "layout";      // container, hero, level, media, section, footer
@forward "base/skeleton";
@forward "helpers";      // utility classes (loaded last so !important wins)

Note

Order matters. utilities and themes must come first because every later module reads the --bulma-* variables they define. helpers come last so their !important utility rules reliably override component defaults.

bulma.scss
└── sass/_index.scss
    ├── utilities/  initial-variables, functions, derived-variables, controls,
    │               css-variables, mixins, extends   (the engine — mostly no CSS output)
    ├── themes/      light.scss, dark.scss, setup.scss  (register --bulma-* values)
    ├── base/        minireset.scss, generic.scss, animations.scss, skeleton.scss
    ├── elements/    block, box, button, content, delete, icon, image, loader,
    │               notification, progress, table, tag, title
    ├── form/        shared, input-textarea, checkbox-radio, select, file, tools
    ├── components/  breadcrumb, card, dropdown, menu, message, modal, navbar,
    │               pagination, panel, tabs
    ├── grid/        columns.scss, grid.scss
    ├── layout/      container, footer, hero, level, media, section
    └── helpers/     aspect-ratio, border, color, flexbox, float, gap, overflow,
                    position, spacing, typography, visibility, other

2.2 The CSS custom-property engine (utilities/css-variables.scss)

This file is the heart of Bulma 1.0. It defines the helper API that every other file uses to register and read variables:

Components never hard-code colors. Instead each component file:

1. Declares Sass $variables with sensible defaults (overridable via @use … with).
2. Calls register-vars(...) on its own selector to publish those as --bulma-<component>-* custom properties.
3. Builds its rules with getVar(...), so the same compiled CSS can be re-themed at runtime.

A representative excerpt (the box element):

$box-background-color: cv.getVar("scheme-main") !default;
$box-radius: cv.getVar("radius-large") !default;

.box {
  @include cv.register-vars((
    "box-background-color": #{$box-background-color},
    "box-radius": #{$box-radius},
  ));
  background-color: cv.getVar("box-background-color");
  border-radius: cv.getVar("box-radius");
}

2.3 Color system

Colors live as HSL component variables, not opaque hex values. For each color name, Bulma registers --bulma-<name>-h, -s, -l and then generate-color-palette() derives:

• 20 numbered lightness shades: --bulma-<name>-00-l through --bulma-<name>-100-l (steps of 5), each with a matching --bulma-<name>-<digit> color and an -invert-l.
• Semantic variants: -invert, -light, -dark, -soft, -bold, plus their inverts.
• -on-scheme-l: a lightness adjusted (via a luminance contrast loop, target ratio > 5) to remain readable on the current scheme background.

The contrast machinery uses bulmaColorLuminance() (WCAG relative luminance) and bulmaColorBrightness() in utilities/functions.scss. This is why a single $primary: #6c5ce7 override cascades into dozens of accessible, theme-aware tints automatically.

2.4 Theming (sass/themes/)

The themes index wires these to four targets:

:root { @include light.light-theme; @include setup.setup-theme; }            // default
@include cv.system-theme("light") { @include light.light-theme; }            // prefers-color-scheme: light
@include cv.system-theme("dark")  { @include dark.dark-theme; }              // prefers-color-scheme: dark
@include cv.bulma-theme("light")  { @include light.light-theme; @include setup.setup-theme; } // [data-theme=light], .theme-light
@include cv.bulma-theme("dark")   { @include dark.dark-theme;  @include setup.setup-theme; }  // [data-theme=dark],  .theme-dark

Important

A forced theme (data-theme / .theme-*) always re-runs setup-theme, so derived colors are recomputed for that subtree. Switching themes at runtime is therefore a single attribute change — no stylesheet swap required.

2.5 Base layer

• minireset.scss — a minimal reset (v0.0.6): zeroes margins/padding on block elements, normalizes box-sizing to border-box, strips list styles, collapses table borders.
• generic.scss — opinionated defaults for html, body, links, code, pre, hr, strong, tables, and focus-visible outlines, all sourced from --bulma-* variables.
• animations.scss — the spinAround and pulsate keyframes used by loaders and skeletons.

3. Requirements

Warning

Compiling Bulma 1.0 with the deprecated node-sass or Ruby Sass engines will fail — the codebase relies on the Dart Sass module system (@use, @forward, with) and the modern sass:color / sass:math modules.

4. Customization Reference

There are two override surfaces: Sass variables (build time) and CSS custom properties (runtime).

4.1 Build-time: Sass @use … with

@use "bulma/sass" with (
  $primary: #6c5ce7,
  $link: #0a84ff,
  $family-primary: '"Nunito", sans-serif',
  $radius: 0.5rem,
  $control-border-width: 2px,
  $custom-colors: ("twitter": #1da1f2)
);

Initial variables (utilities/initial-variables.scss)

Derived variables (utilities/derived-variables.scss)

Map raw palette colors to semantic roles, all overridable:

Tip

To add a brand color that flows into every is-/has- class, pass $custom-colors: ("brand": #ff3860). mergeColorMaps() accepts either a single color (Bulma derives invert/light/dark) or a list (base, invert, light, dark) for full control.

4.2 Runtime: CSS custom properties

Every value above is also published as --bulma-* and can be overridden in plain CSS at any scope:

:root {
  --bulma-primary-h: 270deg;
  --bulma-primary-s: 100%;
  --bulma-primary-l: 60%;
  --bulma-radius: 1rem;
  --bulma-link-h: 210deg;
}

/* Scoped override — only this subtree */
.promo {
  --bulma-body-background-color: #111;
}

Per-component variables follow the pattern --bulma-<component>-<property> (e.g. --bulma-button-padding-horizontal, --bulma-card-radius, --bulma-navbar-height). Component files register dozens each; inspect the relevant sass/**/<name>.scss register-vars block for the exhaustive list.

5. Build & Deployment Pipeline

All build logic lives in package.json scripts (the framework package.json, not the docs one):

5.1 Prebuilt variants (versions/)

Note

The CSS-variable prefix (--bulma-) is fixed by $cssvars-prefix and is independent of $class-prefix. Prefixing classes does not rename the custom properties.

5.2 Reproducing the published artifacts

git clone https://github.com/jgthms/bulma
cd bulma
npm install          # installs Dart Sass, postcss-cli, cssnano, prettier, rimraf
npm run deploy       # clean → build-all → minify-all  ⇒ css/ + css/versions/

The files array in package.json defines what npm publishes: css, sass, versions, bulma.scss, LICENSE, README.md. Nothing else (no docs site, no tests) ships to consumers.

6. Security Analysis

Bulma's attack surface is exceptionally small because it is a static stylesheet.

Caution

Interactive components are styled, not behaviorally secured. Accessibility and security of modals, dropdowns, and menus (focus management, aria-*, escape handling, dismissal) are the integrator's responsibility because Bulma ships no JavaScript.

7. Operations

7.1 Integration patterns

• Static / CDN: link bulma.min.css. Zero build. Best for content sites.
• Bundler (Vite/webpack/Rollup): import "bulma/css/bulma.min.css" or import the Sass entry for customization.
• Component frameworks (React/Vue/Svelte): Bulma is class-only, so it composes cleanly. Toggle is-active etc. via your framework's state.
• Design system: compile from sass/ with @use … with (...), forwarding only the modules you use to control bundle size.

7.2 Reducing stylesheet size

Because Bulma 1.0 emits a comprehensive variable and helper surface, the compiled CSS is large (~678 KB minified). Strategies:

• [ ] Build from Sass and @forward only the modules you actually use (e.g. drop grid or helpers).
• [ ] Use the bulma-no-helpers prebuilt variant.
• [ ] Enable gzip/brotli on your server — the variable-heavy CSS compresses very well.
• [ ] Run a CSS tree-shaker (e.g. PurgeCSS) against your final markup as a build step.

7.3 Theming operations

• Default theme follows prefers-color-scheme.
• Force a theme by setting data-theme="dark" (or theme-dark class) on <html> or any subtree.
• Persist a user choice in localStorage and apply it on load: document.documentElement.dataset.theme = saved.

8. Code Quality & Conventions

• Single source of truth per value. Defaults are declared once as Sass !default variables, published once via register-vars, and consumed via getVar. Changing a default ripples everywhere consistently.
• Strict module boundaries. Files declare their dependencies explicitly with @use aliases (cv = css-variables, iv = initial-variables, dv = derived-variables, mx = mixins). No global leakage.
• Logical properties throughout. margin-inline, inset-inline, border-start-*-radius, etc., give partial RTL support and better internationalization than physical left/right.
• Placeholders + mixins for shared behavior (%control, %block, %unselectable, %overlay, %loader, %arrow, %delete) keep the output DRY via @extend.
• Responsive mixins (mobile, tablet, desktop, widescreen, fullhd, touch, *-only, plus container-query helpers container-from/container-until) centralize breakpoint logic.
• Formatting is enforced with Prettier (the docs site also uses a Liquid plugin).
• Legacy test fixtures in test/dart-sass, test/node-sass, test/ruby-sass remain in the tree for historical compilation checks; only Dart Sass is supported in 1.0.

9. Potential Improvements & Known Issues

Drawn from the source and the project's open community issues.

Negative knowledge (what does NOT exist in v1.0.4)

• No JavaScript of any kind.
• No .tile / tiles component.
• No is-error color modifier.
• No support for Node Sass or Ruby Sass compilation.
• No runtime npm dependencies.

10. Contributing / Forking

The project is a single-package repository:

• Framework source: sass/ (the product), bulma.scss (entry), versions/ (prebuilt variants), css/ (generated — do not edit by hand).
• Documentation site: docs/ — a separate Jekyll (Ruby) site with its own package.json, plus a React-based "Bulma Customizer" under docs/_react/bulma-customizer. The docs build is independent of the framework build.

To work on the framework:

npm install
npm start            # watch-compile bulma.scss → css/bulma.css

To work on the docs site (per docs/README.md): install Ruby 2.x and Jekyll, copy _config.yml to _config.local.yml, point its url: at http://localhost:4000, then run jekyll serve --incremental --config _config.local.yml. A docker-compose.yml using the jekyll/jekyll:pages image is provided as an alternative. Note: changing the framework Sass requires npm run start to rebuild the docs' CSS; Jekyll then serves it.

Note

Edits belong in sass/ and bulma.scss. The contents of css/ are build artifacts regenerated by npm run deploy; never patch them directly.

11. Quick Reference

Build commands

npm run build-bulma     # compile main stylesheet
npm run minify-bulma    # minify with cssnano
npm run build-all       # main + all variants
npm run deploy          # clean + build-all + minify-all (full reproducible build)
npm start               # watch mode

Customization cheat sheet

// Build-time
@use "bulma/sass" with (
  $primary: #6c5ce7,
  $radius: 0.5rem,
  $class-prefix: "bulma-",
  $custom-colors: ("brand": #ff3860)
);

/* Runtime */
:root {
  --bulma-primary-h: 270deg;
  --bulma-radius: 1rem;
}
html[data-theme="dark"] { /* dark overrides applied automatically */ }

Breakpoints

Module layers (cascade order)

utilities → themes → base → elements → form → components → grid → layout → skeleton → helpers

Key file map