Move reassigned Sass maps for colors to another stylesheet

[mdo]

Fixes #34756.

The intent of the new CSS variables and the Sass maps that power them was improved customization, but it complicates things and breaks a common workflow. There's no great way around this unfortunately as the problem is how we create new variables and maps based on existing ones. For example, we extend $theme-colors into $theme-colors-rgb and two maps for .text-* and .bg-* utilities. As of v5.1.1, those other maps do not get updated after $theme-colors are modified.

There are two viable solutions I can see:

1. Re-declare every map, like so:

@import "functions";
@import "variables";
@import "mixins";

$custom: #df711b;

$custom-theme-colors: (
"custom": $custom
);

$theme-colors: map-merge($theme-colors, $custom-theme-colors);
$theme-colors-rgb: map-loop($theme-colors, to-rgb, "$value");
$utilities-colors: map-merge($utilities-colors, $theme-colors-rgb);
$utilities-text-colors: map-loop($utilities-colors, rgba-css-var, "$key", "text");
$utilities-bg-colors: map-loop($utilities-colors, rgba-css-var, "$key", "bg");

2. Or, as this PR does, split those maps out to another stylesheet so we can have folks place modified values between variables and the new maps so they can be updated accordingly. Like so:

// Configuration
@import "functions";
@import "variables";

$starorange: #df711b !default;

$custom-theme-colors: (
  "starorange": $starorange
) !default;

$theme-colors: map-merge($theme-colors, $custom-theme-colors); // stylelint-disable-line scss/dollar-variable-default

@import "maps";
@import "mixins";
@import "utilities";

// Layout & components
// ...

---

Todos

• Document this somewhere
• Verify other maps that need moving

/cc @twbs/css-review

[ffoodd]

This looks fine to me, and totally makes senses. 👌

It needs some docs indeed, and we must ensure we're not forgetting any example somewhere.

[ffoodd]

LGTM, the migration guide is very clear 👌 Thanks!

[isaumya]

Hi @mdo,
Is there any ETA on when the v5.2.0 is going to release? The reason I am asking this is that I am going to start a new project and I thought I can use the new improved overwriting system that is coming in v5.2 instead of using the hacky system we are using now.