From b81513fe4e4d1121cc60f3bd21c3d97757904a29 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Mon, 22 Dec 2025 14:09:17 -0800
Subject: [PATCH] Clean up button vars, docs, fix up .btn-link

---
 scss/_variables.scss                         | 24 --------------------
 scss/buttons/_button-group.scss              | 16 ++++++++-----
 scss/buttons/_button-variables.scss          | 23 +++++++++----------
 scss/buttons/_button.scss                    |  6 +++--
 site/src/content/docs/components/buttons.mdx | 16 ++++++++++---
 5 files changed, 38 insertions(+), 47 deletions(-)

diff --git a/scss/_variables.scss b/scss/_variables.scss
index 5ff0a10a28..b6e670e55f 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -337,30 +337,6 @@ $mark-color:                  $body-color !default;
 $mark-bg:                     var(--yellow-100) !default;
 // scss-docs-end type-variables
 
-
-// Buttons + Forms
-//
-// Shared variables that are reassigned to `$input-` and `$btn-` specific variables.
-
-// scss-docs-start input-btn-variables
-$input-btn-padding-y:         .375rem !default;
-$input-btn-padding-x:         .75rem !default;
-$input-btn-font-family:       null !default;
-$input-btn-font-size:         $font-size-base !default;
-$input-btn-line-height:       $line-height-base !default;
-
-$input-btn-padding-y-sm:      .25rem !default;
-$input-btn-padding-x-sm:      .5rem !default;
-$input-btn-font-size-sm:      $font-size-sm !default;
-
-$input-btn-padding-y-lg:      .5rem !default;
-$input-btn-padding-x-lg:      1rem !default;
-$input-btn-font-size-lg:      $font-size-lg !default;
-
-$input-btn-border-width:      var(--border-width) !default;
-// scss-docs-end input-btn-variables
-
-
 // Z-index master list
 //
 // Warning: Avoid customizing these values. They're used for a bird's eye view
diff --git a/scss/buttons/_button-group.scss b/scss/buttons/_button-group.scss
index f384053b14..4ed0a3457f 100644
--- a/scss/buttons/_button-group.scss
+++ b/scss/buttons/_button-group.scss
@@ -15,17 +15,21 @@
     > [class*="btn-"] {
       position: relative;
       flex: 1 1 auto;
+
+      &:hover {
+        z-index: 1;
+      }
     }
 
-    // Bring the hover, focused, and "active" buttons to the front to overlay
-    // the borders properly
     > .btn-check:has(input:checked),
-    > .btn-check:has(input:focus),
-    > [class*="btn-"]:hover,
-    > [class*="btn-"]:focus,
     > [class*="btn-"]:active,
     > [class*="btn-"].active {
-      z-index: 1;
+      z-index: 2;
+    }
+
+    > .btn-check:has(input:focus),
+    > [class*="btn-"]:focus {
+      z-index: 3;
     }
   }
 
diff --git a/scss/buttons/_button-variables.scss b/scss/buttons/_button-variables.scss
index f89ac33c91..4ce60d10bd 100644
--- a/scss/buttons/_button-variables.scss
+++ b/scss/buttons/_button-variables.scss
@@ -7,11 +7,10 @@
 
 // scss-docs-start btn-variables
 $btn-color:                   var(--fg-body) !default;
-$btn-padding-y:               $input-btn-padding-y !default;
-$btn-padding-x:               $input-btn-padding-x !default;
-$btn-font-family:             $input-btn-font-family !default;
-$btn-font-size:               $input-btn-font-size !default;
-$btn-line-height:             $input-btn-line-height !default;
+$btn-padding-y:               .375rem !default;
+$btn-padding-x:               .75rem !default;
+$btn-font-size:               var(--font-size-base) !default;
+$btn-line-height:             var(--line-height-base) !default;
 $btn-white-space:             null !default; // Set to `nowrap` to prevent text wrapping
 
 $btn-padding-y-xs:            .125rem !default;
@@ -19,14 +18,14 @@ $btn-padding-x-xs:            .375rem !default;
 $btn-font-size-xs:            var(--font-size-xs) !default;
 $btn-line-height-xs:          1.125rem !default;
 
-$btn-padding-y-sm:            $input-btn-padding-y-sm !default;
-$btn-padding-x-sm:            $input-btn-padding-x-sm !default;
+$btn-padding-y-sm:            .25rem !default;
+$btn-padding-x-sm:            .5rem !default;
 $btn-font-size-sm:            var(--font-size-sm) !default;
 $btn-line-height-sm:          1.125rem !default;
 
-$btn-padding-y-lg:            $input-btn-padding-y-lg !default;
-$btn-padding-x-lg:            $input-btn-padding-x-lg !default;
-$btn-font-size-lg:            16px !default;
+$btn-padding-y-lg:            .5rem !default;
+$btn-padding-x-lg:            1rem !default;
+$btn-font-size-lg:            var(--font-size-md) !default;
 $btn-line-height-lg:          1.25rem !default;
 
 // Intentionally left for folks who want it
@@ -35,9 +34,9 @@ $btn-line-height-lg:          1.25rem !default;
 // $btn-font-size-xl:            var(--font-size-lg) !default;
 // $btn-line-height-xl:          1.5rem !default;
 
-$btn-border-width:            $input-btn-border-width !default;
+$btn-border-width:            var(--border-width) !default;
 
-$btn-font-weight:             $font-weight-normal !default;
+$btn-font-weight:             var(--font-weight-normal) !default;
 $btn-disabled-opacity:        .65 !default;
 
 $btn-link-color:              var(--link-color) !default;
diff --git a/scss/buttons/_button.scss b/scss/buttons/_button.scss
index fe7424ae2e..7cc3999fbc 100644
--- a/scss/buttons/_button.scss
+++ b/scss/buttons/_button.scss
@@ -138,7 +138,7 @@ $btn-variant-selectors: () !default;
     --btn-min-height: 2.25rem;
     --btn-padding-x: #{$btn-padding-x};
     --btn-padding-y: #{$btn-padding-y};
-    --btn-font-family: #{$btn-font-family};
+    // --btn-font-family: #{$btn-font-family};
     --btn-font-size: #{$btn-font-size};
     --btn-font-weight: #{$btn-font-weight};
     --btn-line-height: #{$btn-line-height};
@@ -156,7 +156,7 @@ $btn-variant-selectors: () !default;
     justify-content: center;
     min-height: var(--btn-min-height);
     padding: var(--btn-padding-y) var(--btn-padding-x);
-    font-family: var(--btn-font-family);
+    // font-family: var(--btn-font-family);
     font-size: var(--btn-font-size);
     font-weight: var(--btn-font-weight);
     line-height: var(--btn-line-height);
@@ -300,8 +300,10 @@ $btn-variant-selectors: () !default;
     --btn-bg: transparent;
     --btn-border-color: transparent;
     --btn-hover-color: #{$btn-link-hover-color};
+    --btn-hover-bg: transparent;
     --btn-hover-border-color: transparent;
     --btn-active-color: #{$btn-link-hover-color};
+    --btn-active-bg: transparent;
     --btn-active-border-color: transparent;
     --btn-disabled-color: #{$btn-link-disabled-color};
     --btn-disabled-border-color: transparent;
diff --git a/site/src/content/docs/components/buttons.mdx b/site/src/content/docs/components/buttons.mdx
index 3819ea1eaf..9c30b4987b 100644
--- a/site/src/content/docs/components/buttons.mdx
+++ b/site/src/content/docs/components/buttons.mdx
@@ -31,12 +31,22 @@ Compare all variants at once:
 <Example class="bd-example-buttons" code={[...getData('theme-colors').map((themeColor) => `<button type="button" class="btn-solid theme-${themeColor.name} justify-self-start">${themeColor.title}</button>
 <button type="button" class="btn-outline theme-${themeColor.name} justify-self-start">${themeColor.title}</button>
 <button type="button" class="btn-subtle theme-${themeColor.name} justify-self-start">${themeColor.title}</button>
-<button type="button" class="btn-text theme-${themeColor.name} justify-self-start">${themeColor.title}</button>
-`), `
-<button type="button" class="btn btn-link">Link</button>`]} />
+<button type="button" class="btn-text theme-${themeColor.name} justify-self-start">${themeColor.title}</button>`)]} />
 
 <Details name="warning-color-assistive-technologies" />
 
+## Link buttons
+
+Use the `.btn-link` class to create a button that looks like a link.
+
+<Example code={`<button type="button" class="btn btn-link">Link</button>`} />
+
+The `.btn-link` class is intended to be a starting point for your own custom link styles, while our provided link variants  used in conjunction with our link variants, or to serve as a basis for your own custom styles.
+
+<Callout>
+When using `.btn-link` without a modifier, be sure to add some explicit `:focus-visible` styles.
+</Callout>
+
 ## Styled buttons
 
 Add visual depth to solid buttons with gradients and shadows using the `.btn-styled` modifier class. This provides a more three-dimensional appearance that can be customized further with CSS variables.