Convert .btn and mixins to use CSS variables

diff --git a/scss/_buttons.scss b/scss/_buttons.scss
index ee4287c9201d3035e6b7fc38935836e53fd25597..7a7ae2a3d287cd33a239b9b65266f8878a31b29a 100644 (file)
--- a/scss/_buttons.scss
+++ b/scss/_buttons.scss
@@ -1,51 +1,98 @@
+// stylelint-disable custom-property-empty-line-before
+
 //
 // Base styles
 //
 
 .btn {
+  // scss-docs-start btn-css-vars
+  --#{$variable-prefix}btn-padding-x: #{$btn-padding-x};
+  --#{$variable-prefix}btn-padding-y: #{$btn-padding-y};
+  --#{$variable-prefix}btn-font-family: #{$btn-font-family};
+  @include rfs($btn-font-size, --#{$variable-prefix}btn-font-size);
+  --#{$variable-prefix}btn-font-weight: #{$btn-font-weight};
+  --#{$variable-prefix}btn-line-height: #{$btn-line-height};
+  --#{$variable-prefix}btn-color: #{$body-color};
+  --#{$variable-prefix}btn-bg: transparent;
+  --#{$variable-prefix}btn-border-width: #{$btn-border-width};
+  --#{$variable-prefix}btn-border-color: transparent;
+  --#{$variable-prefix}btn-border-radius: #{$btn-border-radius};
+  --#{$variable-prefix}btn-box-shadow: #{$btn-box-shadow};
+  --#{$variable-prefix}btn-disabled-opacity: #{$btn-disabled-opacity};
+  --#{$variable-prefix}btn-focus-box-shadow: 0 0 0 #{$btn-focus-width} rgba(var(--#{$variable-prefix}btn-focus-shadow-rgb), .5);
+  // scss-docs-end btn-css-vars
+
   display: inline-block;
-  font-family: $btn-font-family;
-  font-weight: $btn-font-weight;
-  line-height: $btn-line-height;
-  color: $body-color;
+  padding: var(--#{$variable-prefix}btn-padding-y) var(--#{$variable-prefix}btn-padding-x);
+  font-family: var(--#{$variable-prefix}btn-font-family);
+  font-size: var(--#{$variable-prefix}btn-font-size);
+  font-weight: var(--#{$variable-prefix}btn-font-weight);
+  line-height: var(--#{$variable-prefix}btn-line-height);
+  color: var(--#{$variable-prefix}btn-color);
   text-align: center;
   text-decoration: if($link-decoration == none, null, none);
   white-space: $btn-white-space;
   vertical-align: middle;
   cursor: if($enable-button-pointers, pointer, null);
   user-select: none;
-  background-color: transparent;
-  border: $btn-border-width solid transparent;
-  @include button-size($btn-padding-y, $btn-padding-x, $btn-font-size, $btn-border-radius);
+  border: var(--#{$variable-prefix}btn-border-width) solid var(--#{$variable-prefix}btn-border-color);
+  @include border-radius(var(--#{$variable-prefix}btn-border-radius));
+  @include gradient-bg(var(--#{$variable-prefix}btn-bg));
+  @include box-shadow(var(--#{$variable-prefix}btn-box-shadow));
   @include transition($btn-transition);
 
   &:hover {
-    color: $body-color;
+    color: var(--#{$variable-prefix}btn-hover-color);
     text-decoration: if($link-hover-decoration == underline, none, null);
+    background-color: var(--#{$variable-prefix}btn-hover-bg);
+    border-color: var(--#{$variable-prefix}btn-hover-border-color);
   }
 
   .btn-check:focus + &,
   &:focus {
+    color: var(--#{$variable-prefix}btn-hover-color);
+    @include gradient-bg(var(--#{$variable-prefix}btn-hover-bg));
+    border-color: var(--#{$variable-prefix}btn-hover-border-color);
     outline: 0;
-    box-shadow: $btn-focus-box-shadow;
+    // Avoid using mixin so we can pass custom focus shadow properly
+    @if $enable-shadows {
+      box-shadow: var(--#{$variable-prefix}btn-box-shadow), var(--#{$variable-prefix}btn-focus-box-shadow);
+    } @else {
+      box-shadow: var(--#{$variable-prefix}btn-focus-box-shadow);
+    }
   }
 
   .btn-check:checked + &,
   .btn-check:active + &,
   &:active,
-  &.active {
-    @include box-shadow($btn-active-box-shadow);
+  &.active,
+  .show > &.dropdown-toggle {
+    color: var(--#{$variable-prefix}btn-active-color);
+    background-color: var(--#{$variable-prefix}btn-active-bg);
+    // Remove CSS gradients if they're enabled
+    background-image: if($enable-gradients, none, null);
+    border-color: var(--#{$variable-prefix}btn-active-border-color);
+    @include box-shadow(var(--#{$variable-prefix}btn-active-shadow));
 
     &:focus {
-      @include box-shadow($btn-focus-box-shadow, $btn-active-box-shadow);
+      // Avoid using mixin so we can pass custom focus shadow properly
+      @if $enable-shadows {
+        box-shadow: var(--#{$variable-prefix}btn-active-shadow), var(--#{$variable-prefix}btn-focus-box-shadow);
+      } @else {
+        box-shadow: var(--#{$variable-prefix}btn-focus-box-shadow);
+      }
     }
   }
 
   &:disabled,
   &.disabled,
   fieldset:disabled & {
+    color: var(--#{$variable-prefix}btn-disabled-color);
     pointer-events: none;
-    opacity: $btn-disabled-opacity;
+    background-color: var(--#{$variable-prefix}btn-disabled-bg);
+    background-image: if($enable-gradients, none, null);
+    border-color: var(--#{$variable-prefix}btn-disabled-border-color);
+    opacity: var(--#{$variable-prefix}btn-disabled-opacity);
     @include box-shadow(none);
   }
 }
@@ -76,24 +123,24 @@
 
 // Make a button look and behave like a link
 .btn-link {
-  font-weight: $font-weight-normal;
-  color: $btn-link-color;
-  text-decoration: $link-decoration;
+  --#{$variable-prefix}btn-font-weight: #{$font-weight-normal};
+  --#{$variable-prefix}btn-color: #{$btn-link-color};
+  --#{$variable-prefix}btn-bg: transparent;
+  --#{$variable-prefix}btn-border-color: transparent;
+  --#{$variable-prefix}btn-hover-color: #{$btn-link-hover-color};
+  --#{$variable-prefix}btn-hover-border-color: transparent;
+  --#{$variable-prefix}btn-active-border-color: transparent;
+  --#{$variable-prefix}btn-disabled-color: #{$btn-link-disabled-color};
+  --#{$variable-prefix}btn-disabled-border-color: transparent;
+  --#{$variable-prefix}btn-box-shadow: none;
 
-  &:hover {
-    color: $btn-link-hover-color;
-    text-decoration: $link-hover-decoration;
-  }
+  text-decoration: $link-decoration;
 
+  &:hover,
   &:focus {
     text-decoration: $link-hover-decoration;
   }
 
-  &:disabled,
-  &.disabled {
-    color: $btn-link-disabled-color;
-  }
-
   // No need for an active state here
 }
 

diff --git a/scss/mixins/_buttons.scss b/scss/mixins/_buttons.scss
index b67499668164c4b442904af85ec15c158498e15d..82e0c4992afb88da735350b08e1fe56de5f0ff36 100644 (file)
--- a/scss/mixins/_buttons.scss
+++ b/scss/mixins/_buttons.scss
@@ -1,3 +1,5 @@
+// stylelint-disable custom-property-empty-line-before
+
 // Button variants
 //
 // Easily pump out default styles, as well as :hover, :focus, :active,
@@ -18,59 +20,20 @@
   $disabled-border: $border,
   $disabled-color: color-contrast($disabled-background)
 ) {
-  color: $color;
-  @include gradient-bg($background);
-  border-color: $border;
-  @include box-shadow($btn-box-shadow);
-
-  &:hover {
-    color: $hover-color;
-    @include gradient-bg($hover-background);
-    border-color: $hover-border;
-  }
-
-  .btn-check:focus + &,
-  &:focus {
-    color: $hover-color;
-    @include gradient-bg($hover-background);
-    border-color: $hover-border;
-    @if $enable-shadows {
-      @include box-shadow($btn-box-shadow, 0 0 0 $btn-focus-width rgba(mix($color, $border, 15%), .5));
-    } @else {
-      // Avoid using mixin so we can pass custom focus shadow properly
-      box-shadow: 0 0 0 $btn-focus-width rgba(mix($color, $border, 15%), .5);
-    }
-  }
-
-  .btn-check:checked + &,
-  .btn-check:active + &,
-  &:active,
-  &.active,
-  .show > &.dropdown-toggle {
-    color: $active-color;
-    background-color: $active-background;
-    // Remove CSS gradients if they're enabled
-    background-image: if($enable-gradients, none, null);
-    border-color: $active-border;
-
-    &:focus {
-      @if $enable-shadows {
-        @include box-shadow($btn-active-box-shadow, 0 0 0 $btn-focus-width rgba(mix($color, $border, 15%), .5));
-      } @else {
-        // Avoid using mixin so we can pass custom focus shadow properly
-        box-shadow: 0 0 0 $btn-focus-width rgba(mix($color, $border, 15%), .5);
-      }
-    }
-  }
-
-  &:disabled,
-  &.disabled {
-    color: $disabled-color;
-    background-color: $disabled-background;
-    // Remove CSS gradients if they're enabled
-    background-image: if($enable-gradients, none, null);
-    border-color: $disabled-border;
-  }
+  --#{$variable-prefix}btn-color: #{$color};
+  --#{$variable-prefix}btn-bg: #{$background};
+  --#{$variable-prefix}btn-border-color: #{$border};
+  --#{$variable-prefix}btn-hover-color: #{$hover-color};
+  --#{$variable-prefix}btn-hover-bg: #{$hover-background};
+  --#{$variable-prefix}btn-hover-border-color: #{$hover-border};
+  --#{$variable-prefix}btn-focus-shadow-rgb: #{to-rgb(mix($color, $border, 15%))};
+  --#{$variable-prefix}btn-active-color: #{$active-color};
+  --#{$variable-prefix}btn-active-bg: #{$active-background};
+  --#{$variable-prefix}btn-active-border-color: #{$active-border};
+  --#{$variable-prefix}btn-active-shadow: #{$btn-active-box-shadow};
+  --#{$variable-prefix}btn-disabled-color: #{$disabled-color};
+  --#{$variable-prefix}btn-disabled-bg: #{$disabled-background};
+  --#{$variable-prefix}btn-disabled-border-color: #{$disabled-border};
 }
 // scss-docs-end btn-variant-mixin
 
@@ -82,52 +45,26 @@
   $active-border: $color,
   $active-color: color-contrast($active-background)
 ) {
-  color: $color;
-  border-color: $color;
-
-  &:hover {
-    color: $color-hover;
-    background-color: $active-background;
-    border-color: $active-border;
-  }
-
-  .btn-check:focus + &,
-  &:focus {
-    box-shadow: 0 0 0 $btn-focus-width rgba($color, .5);
-  }
-
-  .btn-check:checked + &,
-  .btn-check:active + &,
-  &:active,
-  &.active,
-  &.dropdown-toggle.show {
-    color: $active-color;
-    background-color: $active-background;
-    border-color: $active-border;
-
-    &:focus {
-      @if $enable-shadows {
-        @include box-shadow($btn-active-box-shadow, 0 0 0 $btn-focus-width rgba($color, .5));
-      } @else {
-        // Avoid using mixin so we can pass custom focus shadow properly
-        box-shadow: 0 0 0 $btn-focus-width rgba($color, .5);
-      }
-    }
-  }
-
-  &:disabled,
-  &.disabled {
-    color: $color;
-    background-color: transparent;
-  }
+  --#{$variable-prefix}btn-color: #{$color};
+  --#{$variable-prefix}btn-border-color: #{$color};
+  --#{$variable-prefix}btn-hover-color: #{$color-hover};
+  --#{$variable-prefix}btn-hover-bg: #{$active-background};
+  --#{$variable-prefix}btn-hover-border-color: #{$active-border};
+  --#{$variable-prefix}btn-focus-shadow-rgb: #{to-rgb($color)};
+  --#{$variable-prefix}btn-active-color: #{$active-color};
+  --#{$variable-prefix}btn-active-bg: #{$active-background};
+  --#{$variable-prefix}btn-active-border-color: #{$active-border};
+  --#{$variable-prefix}btn-active-shadow: #{$btn-active-box-shadow};
+  --#{$variable-prefix}btn-disabled-color: #{$color};
+  --#{$variable-prefix}btn-disabled-bg: transparent;
+  --#{$variable-prefix}gradient: none;
 }
 // scss-docs-end btn-outline-variant-mixin
 
 // scss-docs-start btn-size-mixin
 @mixin button-size($padding-y, $padding-x, $font-size, $border-radius) {
-  padding: $padding-y $padding-x;
-  @include font-size($font-size);
-  // Manually declare to provide an override to the browser default
-  @include border-radius($border-radius, 0);
+  --#{$variable-prefix}btn-padding: #{$padding-y} #{$padding-x};
+  @include rfs($font-size, --#{$variable-prefix}btn-font-size);
+  --#{$variable-prefix}btn-radius: #{$border-radius};
 }
 // scss-docs-end btn-size-mixin

diff --git a/site/assets/scss/_buttons.scss b/site/assets/scss/_buttons.scss
index b266d3e88edfd6f3cf7be74fe327b6165ce9ffbe..adbc39ed9cac18313589332ad1dd332b1d805416 100644 (file)
--- 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 4e90c398ee9e250aa64a6a5813ee2cd78bcf3012..9a01bb66fde0e0daf1a0d042434cd4c2e9271317 100644 (file)
--- 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`.