[BSv5] Fix SCSS functions import issue, and replace darken()

[chalin]

⚠️ See below for an IMPORTANT DESIGN NOTE!

This PR:

• Contributes to Upgrade to Bootstrap 5.2 #470
• Imports Bootstrap's functions first! For details, see the design note below.
• Replaces darken() by other functions, getting some guidance from:
  • Bootstrap did it (#30622)
  • Sass darken() documentation , which describes suitable replacements

Followup:

• Simplify how code color is defined #1387

---

⚠️ Design note regarding functions import fix

Is this fix really necessary?

Without the import fix included in this PR, use of Bootstrap functions can result in bogus errors like the following:

argument $color of <some-bs-function>(...) must be a color

when in fact the argument is a color.

Learn more

For details concerning the need to import functions.scss first, see the Bootstrap migration guide under New _maps.scss

Design choice: double import vs. inlining many imports

In this PR, I'm proposing to @import "functions" before our variable overrides, and then import the full Bootstrap suite of SCSS. This will result in the "functions" file being loaded twice, but according to the Sass @import documentation:

If the same stylesheet is imported more than once, it will be evaluated again each time. If it just defines functions and mixins, this usually isn’t a big deal, but if it contains style rules they’ll be compiled to CSS more than once.

The _functions.scss file doesn't contain any style rules, so we should be ok. The alternative would be to inline all of the 40+ imports in https://github.com/twbs/bootstrap/blob/main/scss/bootstrap.scss, which would be a significant maintenance overhead, one that I think that we can avoid (until proven otherwise).

[chalin]

See the opening comment of this PR for a design rationale.

[chalin]

While I followed BS's upgrade path and generally replaced darken() by shade-color(), in this case the resulting color didn't look as good, so I opted for a call to adjust-color() --matching the previous color exactly.

[LisaFC]

Makes sense to me! I don't see any obvious (or easy to maintain) alternative to this approach.