SCSS Compiler

How it works

If you edit one of the files in your child-theme folder /assets/scss/, the compiler fetches source from the parent theme (falling back automatically to the parent theme’s copy for any file that doesn’t exist in your child theme) and compiles it with your custom code to child-theme /assets/css/bootscore.min.css.

Unlike older versions of Bootscore, saving a file no longer recompiles automatically on the next page load. Compiling now happens in your browser, so you need to trigger it yourself: click Recompile Once from the WordPress admin bar (SCSS Compiler menu) after making changes, or use Recompile Continuously while actively editing (see below). The one exception is right after activating a theme: if bootscore.min.css doesn’t exist yet, it’s compiled automatically the first time an administrator visits the frontend.

_bootscore-variables.scss

In _bootscore-variables.scss you can change the default variables of Bootstrap. Available variables can be found in _variables.scss and _variables-dark.scss.

Variables replaces compiled Bootstrap CSS snippets in bootscore.min.css.

Simple

Add following variable to _bootscore-variables.scss, save and refresh your page. All primary blue color is now red.

$primary: #FF0000;

Advanced

Following variables are a good starting point to edit your theme in more detail, included color-system, border-radius, navbar, links and fonts.

Note that this are the default Bootstrap values. If you just copy them to your file and refresh page, you will see no changes. Start by changing the $blue color value.

// Nothing here

Prefix

Note that theme.json and the plugin’s CSS do not go through the compiler and use fixed variables like var(--bs-primary) instead of var(--#{$prefix}primary). If the bs- prefix has been changed (e.g., $prefix: myprefix-;), plugins and block colors will not work.

_bootscore-custom.scss

Add your own CSS or SCSS in _bootscore-custom.scss. Because this file is compiled after Bootstrap, you’re also able to use Bootstrap mixins for better code.

Changing the primary color

Option 1

@use "../../../bootscore/assets/scss/bootstrap/bootstrap" as * with (
  $blue: oklch(56% 0.24 300deg)
);

Option 2

@use "../../../bootscore/assets/scss/bootstrap/bootstrap" as * with (
  $colors: (
    "brand": oklch(56% 0.24 300deg)
  ),
  $theme-colors: (
    "primary": (
      "base": var(--brand-500),
      "fg": light-dark(var(--brand-600), var(--brand-400)),
      "fg-emphasis": light-dark(var(--brand-800), var(--brand-200)),
      "bg": var(--brand-500),
      "bg-subtle": light-dark(var(--brand-100), var(--brand-900)),
      "bg-muted": light-dark(var(--brand-200), var(--brand-800)),
      "border": light-dark(var(--brand-300), var(--brand-600)),
      "focus-ring": light-dark(color-mix(in oklch, var(--brand-500) 50%, var(--bg-body)), color-mix(in oklch, var(--brand-500) 75%, var(--bg-body))),
      "contrast": var(--white)
    )
  )
);

Option 3

:root {
  --brand: oklch(56% 0.24 300deg);

  --primary-base: var(--brand);
  --primary-bg: var(--brand);
  --primary-fg: light-dark(color-mix(in oklch, black 16%, var(--brand)), color-mix(in oklch, white 20%, var(--brand)));
  --primary-fg-emphasis: light-dark(color-mix(in oklch, black 48%, var(--brand)), color-mix(in oklch, white 60%, var(--brand)));
  --primary-bg-subtle: light-dark(color-mix(in oklch, white 80%, var(--brand)), color-mix(in oklch, black 64%, var(--brand)));
  --primary-bg-muted: light-dark(color-mix(in oklch, white 60%, var(--brand)), color-mix(in oklch, black 48%, var(--brand)));
  --primary-border: light-dark(color-mix(in oklch, white 40%, var(--brand)), color-mix(in oklch, black 16%, var(--brand)));
  --primary-focus-ring: color-mix(in oklch, var(--brand) 50%, var(--bg-body));
  --primary-contrast: var(--white);
}

Code overrides or extends Bootstrap compiled CSS snippets in bootscore.min.css.

CSS

.card {
  color: var(--bs-light);
  background-color: var(--bs-dark);
}

.card a {
  color: var(--bs-danger);
}

.card h2 a {
  color: var(--bs-warning);
}

SCSS

The same result like above using SCSS syntax.

.card {
  color: var(--#{$prefix}light);
  background-color: var(--#{$prefix}dark);

  a {
    color: var(--#{$prefix}danger);
  }

  h2 {
    a {
      color: var(--#{$prefix}warning);
    }
  }
}

Mixins

Any file that calls a Bootstrap mixin, function, or variable must @use the file it’s defined in — access isn’t inherited from other files. @use "path/to/file" as *; loads that file’s mixins, functions, and variables into the current file; the path is relative to the file doing the @use, and as * makes them usable without a namespace prefix.

@use "../../../bootscore/assets/scss/bootstrap/layout/breakpoints" as *;

@include media-breakpoint-down(md) {
  body {
    color: var(--#{$prefix}danger);
    background-color: var(--#{$prefix}dark);
  }
}

@include media-breakpoint-up(md) {
  body {
    color: var(--#{$prefix}success);
    background-color: var(--#{$prefix}light);
  }
}

.btn-red {
  @include button-variant(#EF4444, #EF4444);
}

Extend

@extend is a powerful Sass function to add Bootstrap styles to another classes. For example, using a WordPress plugin with custom button styles and it’s not possible to change the classes in the plugin HTML. Instead of unhandy changing the classes with JavaScript, the styles can simply added to the button by extend.

.plugin-button-class {
  @extend .btn;
  @extend .btn-primary;
}

Offset

Bootscore uses scroll-margin-top to create an offset when scrolling to anchor IDs, ensuring content is not hidden behind the navbar. The default value is 55px, which matches the default navbar height. You can override this value using a variable to suit your needs:

:root {
  --scroll-margin-top: 200px;
}

WooCommerce Colors

Bootscore uses custom variables to override WooCommerce colors with a fallback to Bootstrap variables. It first searches if var(--#{$prefix}wc-price) is defined in your child. If not, Bootstrap color var(--#{$prefix}secondary-color) is used. When inspecting the site, you will find something like this:

.woocommerce div.product p.price,
.woocommerce div.product span.price,
.card .price {
  color: var(--bs-wc-price, var(--bs-secondary-color));
}

To use custom colors, just add them to the :root:

:root {
  --#{$prefix}wc-price: #339900;
}

_bootscore-utilities.scss

This file allows to create custom utilities using the Bootstrap Utility API. For example, a responsive border-radius:

$utilities: map-merge($utilities,
  ("rounded": (responsive: true,
      property: border-radius,
      class: rounded,
      values: (null: var(--#{$prefix}border-radius),
        0: 0,
        1: var(--#{$prefix}border-radius-sm),
        2: var(--#{$prefix}border-radius),
        3: var(--#{$prefix}border-radius-lg),
        4: var(--#{$prefix}border-radius-xl),
        5: var(--#{$prefix}border-radius-xxl),
        circle: 50%,
        pill: var(--#{$prefix}border-radius-pill))),
  ));

Creates this classes:

rounded-md
rounded-md-0
...

rounded-lg
rounded-lg-0
rounded-lg-1
rounded-lg-2
rounded-lg-3
rounded-lg-4
rounded-lg-5
...

bootscore.scss

This file collects all other scss files and source from parent. Add more using @import. Create file _header.scss with an underscore and place it in same folder. Add @import "header"; to bootscore.scss and do your styles for the header in _header.scss. Add as many files as you want, all styles will be compiled to one single CSS file.

Optimize

ToDo: List filesizes and explain how to shrink

Bootscore imports all Bootstrap components which results in a very large bootscore.min.css.

Where	Filesize
Bootstrap All compnents, utilities etc.	~ 360kb
Bootscore – Theme Required for WordPress and the basic functionality	~ 30kb
Bootscore – Woocommerce Required only if WooCommerce	~ 50kb
Overall compiled `bootscore.min.css`	~ 440kb

As Bootstrap’s documentation recommend, comment out all files that are not needed in your project in bootscore.scss.

// scss-docs-start import-stack
@forward "banner";

// Configuration variables and maps, such as $utilities. Forwarding config makes
// them configurable from this entrypoint with `@use ... with (...)`. Emits no CSS.
@forward "config";

@forward "colors";

// Theme color maps ($theme-colors, $theme-bgs, etc.). Forwarding makes them
// configurable from this entrypoint with `@use ... with (...)`. Emits no CSS.
@forward "theme";

// Global CSS variables, layer definitions, and configuration
@forward "root";

// Subdir imports
@forward "content";       // Required
@forward "layout";
@forward "forms";
@forward "buttons";

// Components
@forward "accordion";
@forward "alert";
@forward "avatar";
@forward "badge";
@forward "breadcrumb";
@forward "calendar";
@forward "chip";
@forward "card";
@forward "carousel";
@forward "datepicker";
@forward "dialog";
@forward "menu";
@forward "list-group";
@forward "nav";
@forward "nav-overflow";
@forward "navbar";
@forward "drawer";
@forward "pagination";
@forward "placeholder";
@forward "popover";
@forward "progress";
@forward "spinner";
@forward "stepper";
@forward "toasts";
@forward "tooltip";
@forward "transitions";

// Helpers
@forward "helpers";

// Utilities
@forward "utilities/api";
// scss-docs-end import-stack

editor-style

This registers the compiled bootscore.min.css to the Gutenberg editor, ensuring that the backend has the same styles as the frontend by using classes in the block’s Advanced tab:

There are known minor issues with styles for cards and badges in the backend because the editor, for example, has problems displaying something like display: inline-block; correctly. However, both components work well in the frontend. You may want to take a look at our new prebuilt Block patterns.

theme.json

The theme.json file adds the defined colors from _bootscore_variables.scss file to the block editor.

The Compiler

Bootscore compiles SCSS to CSS directly in your browser, using [Dart Sass](https://sass-lang.com/dart-sass/) — the same engine used to build Bootstrap itself — instead of a PHP-based compiler. This means full support for Bootstrap’s Sass module system (`@use`/`@forward`), which older PHP compilers weren’t able to process.

Only administrators can trigger a compile, and only you see the compiling process — regular visitors never load the compiler or reach out to any external service. It works like this:

You click Recompile Once (or Recompile Continuously) from the SCSS Compiler menu in the WordPress admin bar.
Your browser loads Dart Sass from a CDN, fetches every SCSS file your `bootscore.scss` needs (child theme first, automatically falling back to the parent theme for any file only the parent has), and compiles them together.
A status bar at the bottom shows progress and, once done, the resulting file size.
The compiled CSS is sent back to your site and saved as `assets/css/bootscore.min.css` — the same file every visitor’s browser then loads normally, no different from before.

Because compiling happens in your browser rather than on the server, you need to be online for it to work, and a full compile can take a little while (Bootstrap’s SCSS is spread across many separate files, each fetched individually).

Filters

Enable source map

Off by default. A source map lets browser dev tools show you which original .scss file and line a compiled CSS rule came from — useful while actively debugging styles, but unnecessary (and slightly slower) for normal use.

/**
 * Enable source map
 */
add_filter('bootscore/compiler/enable_sourcemap', '__return_true');

Modify the SCSS before it compiles

This filter runs on the raw SCSS content of bootscore.scss right before it’s sent to the compiler, letting you add to or change it programmatically — without editing the file on disk. Useful if you ever need to inject variable overrides dynamically (for example, from values saved elsewhere in WordPress) rather than hardcoding them in _bootscore-variables.scss.

add_filter('bootscore/compiler/main_sass', function ($sass) {
  // Prepend a variable override before the real entry content compiles
  return '$primary: #e63946;' . "\n" . $sass;
});

Errors

If something in your code went wrong, for example a missing close } or ;, the compiler shows an error in a status bar at the bottom of the page instead of compiling:

SCSS error
expected "}". ╷ 45 │ } │ ^ ╵ _docs-breadcrumb.scss 45:2 @import https://bootscore.me/wp-content/themes/bootscore-custom-child/assets/scss/stdin.scss 73:9 root stylesheet

The message tells you the exact file and line the problem is in — in this example, line 45 of _docs-breadcrumb.scss is missing a closing }. Fix the file and trigger a recompile again.

Recompile Once vs. Recompile Continuously

Both are available from the SCSS Compiler menu in the WordPress admin bar (visible to administrators only):

Recompile Once compiles a single time, saves the result, then returns you to the normal page after a few seconds. Use this after you’re done making changes.
Recompile Continuously keeps recompiling automatically every few seconds, so you can edit a .scss file, save it, and just refresh the page to see the update — without clicking Recompile again each time. Use this while actively working on styles, and switch back to a normal page (via the same admin bar menu, now labeled Stop SCSS Compiler) when you’re done, since it keeps using your browser and network in the background otherwise.