Convert .btn and mixins to use CSS variables

2 files changed, 40 insertions, 9 deletions

diff --git a/site/assets/scss/_buttons.scss b/site/assets/scss/_buttons.scss
index b266d3e88e..adbc39ed9c 100644
--- a/site/assets/scss/_buttons.scss
+++ b/site/assets/scss/_buttons.scss
@@ -2,6 +2,7 @@
 //
 // Custom buttons for the docs.
 
+// scss-docs-start btn-css-vars-example
 .btn-bd-primary {
   font-weight: 600;
   color: $white;
@@ -19,6 +20,7 @@
     box-shadow: 0 0 0 3px rgba($bd-purple-bright, .25);
   }
 }
+// scss-docs-end btn-css-vars-example
 
 .btn-bd-download {
   font-weight: 600;
diff --git a/site/content/docs/5.1/components/buttons.md b/site/content/docs/5.1/components/buttons.md
index 4e90c398ee..9a01bb66fd 100644
--- a/site/content/docs/5.1/components/buttons.md
+++ b/site/content/docs/5.1/components/buttons.md
@@ -72,13 +72,24 @@ Fancy larger or smaller buttons? Add `.btn-lg` or `.btn-sm` for additional sizes
 <button type="button" class="btn btn-secondary btn-sm">Small button</button>
 {{< /example >}}
 
+You can even roll your own custom sizing with CSS variables:
+
+{{< example >}}
+<button type="button" class="btn btn-primary"
+        style="--bs-btn-padding: .25rem .5rem; --bs-btn-font-size: .75rem;">
+  Custom button
+</button>
+{{< /example >}}
+
 ## Disabled state
 
 Make buttons look inactive by adding the `disabled` boolean attribute to any `<button>` element. Disabled buttons have `pointer-events: none` applied to, preventing hover and active states from triggering.
 
 {{< example >}}
-<button type="button" class="btn btn-lg btn-primary" disabled>Primary button</button>
-<button type="button" class="btn btn-secondary btn-lg" disabled>Button</button>
+<button type="button" class="btn btn-primary" disabled>Primary button</button>
+<button type="button" class="btn btn-secondary" disabled>Button</button>
+<button type="button" class="btn btn-outline-primary" disabled>Primary button</button>
+<button type="button" class="btn btn-outline-secondary" disabled>Button</button>
 {{< /example >}}
 
 Disabled buttons using the `<a>` element behave a bit different:
@@ -89,8 +100,8 @@ Disabled buttons using the `<a>` element behave a bit different:
 - Disabled buttons using `<a>` *should not* include the `href` attribute.
 
 {{< example >}}
-<a class="btn btn-primary btn-lg disabled" role="button" aria-disabled="true">Primary link</a>
-<a class="btn btn-secondary btn-lg disabled" role="button" aria-disabled="true">Link</a>
+<a class="btn btn-primary disabled" role="button" aria-disabled="true">Primary link</a>
+<a class="btn btn-secondary disabled" role="button" aria-disabled="true">Link</a>
 {{< /example >}}
 
 ### Link functionality caveat
@@ -98,8 +109,8 @@ Disabled buttons using the `<a>` element behave a bit different:
 To cover cases where you have to keep the `href` attribute on a disabled link, the `.disabled` class uses `pointer-events: none` to try to disable the link functionality of `<a>`s. Note that this CSS property is not yet standardized for HTML, but all modern browsers support it. In addition, even in browsers that do support `pointer-events: none`, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, in addition to `aria-disabled="true"`, also include a `tabindex="-1"` attribute on these links to prevent them from receiving keyboard focus, and use custom JavaScript to disable their functionality altogether.
 
 {{< example >}}
-<a href="#" class="btn btn-primary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Primary link</a>
-<a href="#" class="btn btn-secondary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Link</a>
+<a href="#" class="btn btn-primary disabled" tabindex="-1" role="button" aria-disabled="true">Primary link</a>
+<a href="#" class="btn btn-secondary disabled" tabindex="-1" role="button" aria-disabled="true">Link</a>
 {{< /example >}}
 
 ## Block buttons
@@ -227,13 +238,31 @@ buttons.forEach(function (button) {
 })
 ```
 
-## Sass
+## CSS
 
 ### Variables
 
+<small class="d-inline-flex px-2 py-1 font-monospace text-muted border rounded-3">Added in v5.2.0</small>
+
+As part of Bootstrap's evolving CSS variables approach, buttons now use local CSS variables on `.btn` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
+
+{{< scss-docs name="btn-css-vars" file="scss/_buttons.scss" >}}
+
+Each `.btn-*` modifier class updates the appropriate CSS variables to minimize additional CSS rules with our `button-variant()`, `button-outline-variant()`, and `button-size()` mixins.
+
+Here's an example of building a custom `.btn-*` modifier class like we do for the buttons unique to our docs by reassigning Bootstrap's CSS variables with a mixture of our own CSS and Sass variables.
+
+<div class="bd-example">
+  <button type="button" class="btn btn-bd-primary">Custom button</button>
+</div>
+
+{{< scss-docs name="btn-css-vars-example" file="site/assets/scss/_buttons.scss" >}}
+
+### Sass variables
+
 {{< scss-docs name="btn-variables" file="scss/_variables.scss" >}}
 
-### Mixins
+### Sass mixins
 
 There are three mixins for buttons: button and button outline variant mixins (both based on `$theme-colors`), plus a button size mixin.
 
@@ -243,7 +272,7 @@ There are three mixins for buttons: button and button outline variant mixins (bo
 
 {{< scss-docs name="btn-size-mixin" file="scss/mixins/_buttons.scss" >}}
 
-### Loops
+### Sass loops
 
 Button variants (for regular and outline buttons) use their respective mixins with our `$theme-colors` map to generate the modifier classes in `scss/_buttons.scss`.