Update Sass and Theme docs to document mixins and functions better (#42173)

* Update Sass and Theme docs to document mixins and functions better

Also remove some unused functions while we're here.

* document it instead

* Fix cspell, add local cspell so i can test in dev

Author: mdo

.cspell.json

@@ -74,6 +74,7 @@
     "navbars",
     "navs",
     "navoverflow",
+    "negativify",
     "Neue",
     "noindex",
     "Noto",

package-lock.json

@@ -111,7 +111,8 @@
     "watch-js-docs": "nodemon --watch site/src/assets/ --ext js --exec \"npm run js-lint\"",
     "astro-dev": "astro dev --root site --port 9001",
     "astro-build": "astro build --root site && rm -rf _site && cp -r site/dist _site",
-    "astro-preview": "astro preview --root site --port 9001"
+    "astro-preview": "astro preview --root site --port 9001",
+    "spellcheck": "cspell --config .cspell.json \"**/*.{md,mdx}\""
   },
   "peerDependencies": {
     "@floating-ui/dom": "^1.7.6",
@@ -143,6 +144,7 @@
     "bundlewatch": "^0.4.1",
     "clipboard": "^2.0.11",
     "cross-env": "^10.1.0",
+    "cspell": "^9.7.0",
     "eslint": "^10.1.0",
     "eslint-config-xo": "^0.50.0",
     "eslint-plugin-html": "^8.1.4",

package.json

@@ -1,4 +1,3 @@
-@use "sass:meta";
 @use "sass:map";
 
 @function theme-color-values($key) {
@@ -42,20 +41,6 @@
   }
 }
 
-// Recursive mixin to handle nested maps
-@mixin create-css-vars($map, $parent-key: "") {
-  @each $key, $value in $map {
-    // stylelint-disable-next-line scss/at-function-named-arguments
-    $current-key: if(sass($parent-key == ""): $key; else: "#{$parent-key}-#{$key}");
-
-    @if meta.type-of($value) == "map" {
-      @include create-css-vars($value, $current-key);
-    } @else {
-      --#{$current-key}: #{$value};
-    }
-  }
-}
-
 // scss-docs-start theme-colors
 $theme-colors: (
   "primary": (

scss/_theme.scss

@@ -108,7 +108,7 @@
   .form-control-color {
     @include form-validation-state-selector($state) {
       @if $enable-validation-icons {
-        // width: add($form-color-width, $input-height-inner);
+        // width: calc($form-color-width + $input-height-inner);
       }
     }
   }

scss/forms/_validation.scss

@@ -118,7 +118,7 @@
   .form-control-color {
     @include form-validation-state-selector($state) {
       @if $enable-validation-icons {
-        width: add($form-color-width, $input-height-inner);
+        width: calc($form-color-width + $input-height-inner);
       }
     }
   }

scss/mixins/_forms.scss

@@ -77,6 +77,24 @@ Those options and the `$colors` map are used to generate a `$color-tokens` map,
 
 <ScssDocs name="color-tokens" file="scss/_colors.scss" />
 
+In practice, our CSS variables that get output from this looks like this:
+
+```scss
+// Example generated custom properties from _colors.scss
+--bs-blue-025: color-mix(in lab, var(--bs-white) 94%, oklch(60% 0.24 240));
+--bs-blue-050: color-mix(in lab, var(--bs-white) 90%, oklch(60% 0.24 240));
+--bs-blue-100: color-mix(in lab, var(--bs-white) 80%, oklch(60% 0.24 240));
+// ...
+--bs-blue-500: oklch(60% 0.24 240);
+// ...
+--bs-blue-900: color-mix(in lab, var(--bs-black) 64%, oklch(60% 0.24 240));
+--bs-blue-975: color-mix(in lab, var(--bs-black) 88%, oklch(60% 0.24 240));
+```
+
+<Callout type="info">
+We use CSS variables `var(--bs-white)` and `var(--bs-black)` to prevent LightningCSS from converting the real-time mixing into static `lab()` values. Unfortunately, this feature cannot be disabled in LightningCSS at this time.
+</Callout>
+
 ## Customizing
 
 You can customize the colors by adding or removing colors from the `$colors` map. You can also customize the tint and shade stops, the `color-mix()` color space, and the mix colors. Say you want to add another blue-gray color, like slate.

site/src/content/docs/customize/color.mdx

@@ -360,31 +360,15 @@ For `$theme-colors`, the `primary`, `success`, and `danger` keys are required fo
 
 ### Defaults
 
-The `defaults()` function is the backbone of Bootstrap's customization system. It merges user overrides on top of built-in defaults and strips any `null` entries from the result. Every token map, size map, and variant map uses it:
+The `defaults()` function is the backbone of Bootstrap's customization system. It merges user overrides on top of built-in default tokens and strips any `null` entries from the result. Every token map, size map, and variant map uses it:
 
 ```scss
 @function defaults($defaults, $overrides) { ... }
 ```
 
 It accepts either a map or a list as the first argument. Lists are automatically converted to maps with `true` values, which is how size maps like `$button-sizes` work with a clean `("xs", "sm", "lg")` syntax.
 
-### Colors
-
-Base colors are defined as `oklch()` values and expanded into full scales via `color-mix()`. Each hue generates steps from `025` to `975`:
-
-```scss
-// Example generated custom properties from _colors.scss
---blue-025: color-mix(in lab, #fff 94%, oklch(60% 0.24 240));
---blue-050: color-mix(in lab, #fff 90%, oklch(60% 0.24 240));
---blue-100: color-mix(in lab, #fff 80%, oklch(60% 0.24 240));
-// ...
---blue-500: oklch(60% 0.24 240);
-// ...
---blue-900: color-mix(in lab, #000 64%, oklch(60% 0.24 240));
---blue-975: color-mix(in lab, #000 88%, oklch(60% 0.24 240));
-```
-
-You can reference any color scale step as a CSS custom property: `var(--blue-500)`, `var(--red-200)`, `var(--gray-900)`, etc.
+`defaults()` are generated on specific selectors with the [`tokens()` mixin](#tokens).
 
 ### Color contrast
 
@@ -406,47 +390,119 @@ For example, to generate color swatches from our `$theme-colors` map:
 
 We use the `escape-svg` function to escape the `<`, `>` and `#` characters for SVG background images. When using the `escape-svg` function, data URIs must be quoted.
 
-### Add and Subtract functions
+```scss
+// Input — an inline SVG with special characters
+$icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><path fill='none' stroke='#00000080' stroke-width='2' d='m2 5 6 6 6-6'/></svg>");
+
+// After escape-svg(), the <, >, and # characters are percent-encoded
+// so the data URI works reliably as a CSS background-image
+.element {
+  background-image: escape-svg($icon);
+}
+```
+
+### Map helpers
 
-We use the `add` and `subtract` functions to wrap the CSS `calc` function. The primary purpose of these functions is to avoid errors when a "unitless" `0` value is passed into a `calc` expression. Expressions like `calc(10px - 0)` will return an error in all browsers, despite being mathematically correct.
+We include several Sass functions for working with maps beyond what Sass provides natively.
 
-Example where the calc is valid:
+<BsTable>
+| Function | Description |
+| --- | --- |
+| `map-merge-multiple($maps...)` | Merges any number of maps into one, processing them left to right. |
+| `map-get-multiple($map, $values)` | Returns a subset of a map filtered to only the keys listed in `$values`. |
+| `map-get-nested($map, $nested-key)` | Extracts a single property from every nested map entry, returning a flat map. |
+</BsTable>
+
+#### `map-merge-multiple($maps...)`
 
 ```scss
-$border-radius: .25rem;
-$border-width: 1px;
+@function map-merge-multiple($maps...) { ... }
 
-.element {
-  // Output calc(.25rem - 1px) is valid
-  border-radius: calc($border-radius - $border-width);
-}
+// Example: combine spacers, negative spacers, and auto into a single values map
+values: map-merge-multiple($spacers, $negative-spacers, (auto: auto))
+```
 
-.element {
-  // Output the same calc(.25rem - 1px) as above
-  border-radius: subtract($border-radius, $border-width);
-}
+#### `map-get-multiple($map, $values)`
+
+```scss
+@function map-get-multiple($map, $values) { ... }
+
+// Example: extract only the flex and order utilities
+$utilities: map-get-multiple(
+  $utilities,
+  ("flex", "flex-direction", "flex-grow", "order")
+);
 ```
 
-Example where the calc is invalid:
+#### `map-get-nested($map, $nested-key)`
 
 ```scss
-$border-radius: .25rem;
-$border-width: 0;
+@function map-get-nested($map, $nested-key) { ... }
 
-.element {
-  // Output calc(.25rem - 0) is invalid
-  border-radius: calc($border-radius - $border-width);
-}
+// Example: pull just the "font-size" value from each entry in $font-sizes
+values: map-get-nested($font-sizes, "font-size")
+// Returns: ("xs": clamp(...), "sm": clamp(...), ...)
+```
 
-.element {
-  // Output .25rem
-  border-radius: subtract($border-radius, $border-width);
-}
+#### `negativify-map($map)`
+
+Turns a map into its negative variant by prefixing each key with `n` and negating the value. Keys equal to `0` are skipped. This is used internally to generate negative spacer utilities (e.g., `n1`, `n2`, etc.) from the `$spacers` map.
+
+```scss
+@function negativify-map($map) { ... }
+
+// Example: generate negative spacers from a spacers map
+$spacers: (0: 0, 1: .25rem, 2: .5rem, 3: 1rem);
+$negative-spacers: negativify-map($spacers);
+// Returns: ("n1": -.25rem, "n2": -.5rem, "n3": -1rem)
+```
+
+### Theme color values
+
+The [`theme-color-values($key)`]([[docsref:/customize/theme]]) function in `scss/_theme.scss` extracts a specific sub-key from every entry in the `$theme-colors` map, returning a flat map of color names to values. Since each theme color is a nested map with sub-keys like `base`, `text`, `bg`, `border`, etc., this function lets you pull one of those sub-keys across all colors at once. It powers most of the color-related utilities in `_utilities.scss`:
+
+```scss
+// In _utilities.scss — generate .focus-ring-{color} classes
+"focus-ring": (
+  property: --focus-ring-color,
+  class: focus-ring,
+  values: theme-color-values("focus-ring"),
+),
+
+// Merge theme color backgrounds with semantic border tokens for .border-{color} classes
+"border-color": (
+  property: (
+    "--border-color": null,
+    "border-color": var(--border-color)
+  ),
+  class: border,
+  values: map.merge(theme-color-values("bg"), $theme-borders),
+),
+```
+
+### Theme opacity values
+
+The [`theme-opacity-values($color-var, $opacities)`]([[docsref:/customize/theme]]) function in `scss/_theme.scss` generates a map of opacity variants for a CSS custom property using `color-mix()`. The `$opacities` argument defaults to `$util-opacity` (10 through 100 in steps of 10). At `100`, it returns the variable directly; for all other steps, it mixes the variable against `transparent`:
+
+```scss
+// In _utilities.scss — generate .border-{opacity} classes
+"border-opacity": (
+  class: border,
+  property: border-color,
+  values: theme-opacity-values(--border-color)
+),
+
+// Generate .fg-{opacity} classes
+"fg-opacity": (
+  class: fg,
+  property: color,
+  values: theme-opacity-values(--fg)
+),
 ```
 
 ## Mixins
 
-Our `scss/mixins/` directory has a ton of mixins that power parts of Bootstrap and can also be used across your own project.
+Our `scss/mixins/` directory has snippets of code that power Bootstrap and can also be used across your own project.
 
 ### Tokens
 
@@ -478,3 +534,15 @@ A shorthand mixin for the `prefers-color-scheme` media query is available with s
   }
 }
 ```
+
+### Theme classes
+
+The `generate-theme-classes()` mixin loops over the `$theme-colors` map and outputs a `.theme-*` class for each color. Each class maps generic `--theme-*` custom properties to the color's specific values, so components can reference `--theme-base`, `--theme-bg`, etc., and pick up the right palette from a parent `.theme-*` class:
+
+```scss
+@include generate-theme-classes();
+// Outputs:
+// .theme-primary { --theme-base: var(--primary-base); --theme-bg: var(--primary-bg); ... }
+// .theme-success { --theme-base: var(--success-base); --theme-bg: var(--success-bg); ... }
+// ...
+```

site/src/content/docs/customize/sass.mdx

@@ -69,6 +69,7 @@ Bootstrap 6 is a major release with many breaking changes to modernize our codeb
 - Dropped support for Node Sass, including no longer testing any of our source CSS against it.
   - Rearranged several Sass files in the process.
 - Removed `add()` and `subtract()` functions. Use `calc()` instead.
+- Removed `create-css-vars()` mixin (unused).
 - **CSS variable prefixing now handled by PostCSS.** The `$prefix` Sass variable has been removed. CSS custom properties are now written without a prefix in the Sass source and prefixed automatically via `postcss-prefix-custom-properties` during the build. To customize the prefix, update your PostCSS configuration instead of Sass.
 - **Removes all deprecated Sass variables and values:**
   - Removed `$nested-kbd-font-weight`, no replacement.