How to override map variables in subtheme and compile SASS

Problem/Motivation

After adding custom colors by following the instructions in the FAQ, I am unable to compile SCSS.

Steps to reproduce

1. Generate a subtheme as per docs (https://git.drupalcode.org/project/bootstrap5/-/blob/4.0.x/README.md?ref...)
2. Add custom color as per docs (https://git.drupalcode.org/project/bootstrap5/-/blob/4.0.x/README.md?ref...)
3. Attempt to compile subtheme SCSS (https://git.drupalcode.org/project/bootstrap5/-/blob/4.0.x/README.md?ref...)

> sass -q scss/style.scss css/style.css
Error: Undefined variable.

The issue being $theme-colors is undefined.

// Merge the maps
$theme-colors: map-merge($theme-colors, $custom-colors);

Proposed resolution

One issue is it's not possible to override a map variable in your subtheme's scss/_variables_bootstrap.scss

Adding custom color to theme: adding (code snippet)[https://getbootstrap.com/docs/5.3/customize/sass/#add-to-map] to scss/_variables_bootstrap.scss.

According to the bootstrap docs (https://getbootstrap.com/docs/5.3/customize/sass/#importing) you can't override a map variable at the point at which scss/_variables_bootstrap.scss is included (i.e. before these variables are imported).

// Sub theme styling.
@import 'variables_drupal';

// Bootstrap overridden variables.
// @see https://getbootstrap.com/docs/5.2/customize/sass/#variable-defaults.
@import 'variables_bootstrap';

// Include bootstrap.
@import '../../../../themes/contrib/bootstrap5/scss/style';

A second subsidary "issue" is that Bootstrap5 parent theme loads it's own variables_drupal and variables_bootstrap on top of the subtheme, meaning the parent will override any attempt to set e.g. $navbar-brand-image-height (variables_drupal) or $legend-font-size (variables_bootstrap) in the subtheme. This might be intentional, but then why include these variables in the subtheme scss indicating that they can be overriden?

It's actually been really difficult to override the default color map, as you can't simply do it after loading the parent theme style.scss either. This is what my subtheme style.scss looks like with a working color map override:

// Include functions first (so you can manipulate colors, SVGs, calc, etc)
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/functions";

// Include any default variable overrides
@import 'variables_drupal';
@import 'variables_bootstrap';

// Include remainder of required Bootstrap stylesheets (including any separate color mode stylesheets)
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/variables";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/variables-dark";

// Include any default map overrides
@import 'maps_bootstrap.scss';

// Include remaining bootstrap components
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/maps";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/mixins";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/utilities";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/root";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/reboot";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/type";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/images";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/containers";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/grid";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/tables";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/forms";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/buttons";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/transitions";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/dropdown";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/button-group";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/nav";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/navbar";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/card";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/accordion";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/breadcrumb";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/pagination";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/badge";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/alert";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/progress";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/list-group";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/close";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/toasts";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/modal";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/tooltip";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/popover";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/carousel";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/spinners";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/offcanvas";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/placeholders";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/helpers";
@import "../../../../themes/contrib/bootstrap5/dist/bootstrap/5.3.8/scss/utilities/api";

// Include remaining Drupal Bootstrap5 theme scss
@import '../../../../themes/contrib/bootstrap5/scss/mixins';
@import '../../../../themes/contrib/bootstrap5/scss/drupal';
@import '../../../../themes/contrib/bootstrap5/scss/bootstrap_fix';

Remaining tasks

I could be missing something here (hence the support ticket). If not...

I think the FAQ section needs to be updated? Changes to style.scss are probably required to facilitate map overrrides?

User interface changes

n/a

API changes

n/a

Data model changes

n/a