From c1373d7b8a057e86538630ae89a3548f8335c490 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Kuna?=
 <1282324+codecalm@users.noreply.github.com>
Date: Thu, 24 Sep 2026 23:02:41 +0200
Subject: [PATCH] Add `--tblr-hover-bg` and use it for button and nav hover
 backgrounds (#3183)

---
 .changeset/hover-bg-variable.md           |  5 +++++
 core/scss/_variables-dark.scss            |  1 -
 core/scss/_variables-deprecated.scss      |  3 +++
 core/scss/_variables.scss                 | 20 ++++++++++----------
 core/scss/layout/_root.scss               |  3 ++-
 core/scss/ui/_buttons.scss                |  6 +++---
 core/scss/ui/_cards.scss                  |  2 +-
 core/scss/ui/_datepicker.scss             |  2 +-
 core/scss/ui/_lists.scss                  |  6 +++---
 core/scss/ui/_nav.scss                    |  2 +-
 core/scss/ui/_segmented.scss              |  2 +-
 core/scss/ui/_type.scss                   |  4 ++--
 core/scss/ui/forms/_form-selectgroup.scss |  2 +-
 13 files changed, 33 insertions(+), 25 deletions(-)
 create mode 100644 .changeset/hover-bg-variable.md

diff --git a/.changeset/hover-bg-variable.md b/.changeset/hover-bg-variable.md
new file mode 100644
index 000000000..841cbe1ff
--- /dev/null
+++ b/.changeset/hover-bg-variable.md
@@ -0,0 +1,5 @@
+---
+"@tabler/core": minor
+---
+
+Added `--tblr-hover-bg` variable and used it for the hover background of buttons, nav links, dropdown items and list groups.
diff --git a/core/scss/_variables-dark.scss b/core/scss/_variables-dark.scss
index 238f45198..6b478bf5d 100644
--- a/core/scss/_variables-dark.scss
+++ b/core/scss/_variables-dark.scss
@@ -6,7 +6,6 @@
 // Dark mode
 //
 $darken-dark: adjust-lightness-css(var(--dark), -2%) !default;
-$lighten-dark: adjust-lightness-css(var(--dark), 2%) !default;
 $border-color-dark: adjust-lightness-css(var(--dark), 8%) !default;
 $border-color-translucent-dark: rgba(128, 150, 172, 0.2) !default;
 $border-dark-color-dark: adjust-lightness-css(var(--dark), 4%) !default;
diff --git a/core/scss/_variables-deprecated.scss b/core/scss/_variables-deprecated.scss
index 17c04b233..5f1b7edfe 100644
--- a/core/scss/_variables-deprecated.scss
+++ b/core/scss/_variables-deprecated.scss
@@ -9,6 +9,9 @@
 @use 'variables' as *;
 @use 'mixins/functions' as *;
 
+// deprecated(2.0): `--active-bg` now carries its own dark value in `$active-bg`
+$lighten-dark: adjust-lightness-css(var(--dark), 2%) !default;
+
 // deprecated(2.0): the focus ring is an outline, see `$focus-ring-width`,
 // `$focus-ring-offset`, `$focus-ring-color` and `$focus-ring-opacity`
 $focus-ring-blur: 0 !default;
diff --git a/core/scss/_variables.scss b/core/scss/_variables.scss
index abcc3b00d..caa133799 100644
--- a/core/scss/_variables.scss
+++ b/core/scss/_variables.scss
@@ -569,13 +569,13 @@ $border-active-color: var(--gray-400) !default;
 $border-active-opacity: 44.8% !default;
 $border-active-color-translucent: color-transparent(var(--gray-800), $border-active-opacity) !default;
 
-$active-bg: color-transparent(var(--primary), 0.04) !default;
+$active-bg: light-dark(color-transparent(var(--primary), 0.04), color-transparent(var(--primary), 0.12)) !default;
 $active-color: var(--primary) !default;
 $active-border-color: var(--primary) !default;
 
 $selection-bg: light-dark(color-transparent(var(--primary), 0.1), color-transparent(var(--primary), 0.4)) !default;
 
-$hover-bg: color-transparent(var(--secondary), 0.08) !default;
+$hover-bg: light-dark(color-transparent(var(--body-color), 0.06), color-transparent(var(--body-color), 0.08)) !default;
 
 $disabled-bg: var(--bg-surface-secondary) !default;
 $disabled-color: color-transparent(var(--body-color), 0.4) !default;
@@ -1391,7 +1391,7 @@ $dropdown-box-shadow: var(--shadow-dropdown) !default;
 
 $dropdown-link-color: inherit !default;
 $dropdown-link-hover-color: inherit !default;
-$dropdown-link-hover-bg: $hover-bg !default;
+$dropdown-link-hover-bg: var(--hover-bg) !default;
 $dropdown-link-active-color: var(--primary) !default;
 $dropdown-link-active-bg: var(--active-bg) !default;
 $dropdown-link-disabled-color: var(--tertiary-color) !default;
@@ -1568,7 +1568,7 @@ $navbar-light-brand-color: var(--body-color) !default;
 $navbar-light-active-color: var(--body-color) !default;
 $navbar-light-hover-color: var(--body-color) !default;
 $navbar-light-disabled-color: var(--disabled-color) !default;
-$navbar-light-active-bg: color-transparent(var(--primary), 0.08) !default;
+$navbar-light-active-bg: var(--active-bg) !default;
 $navbar-light-icon-color: color-transparent(var(--body-color), 0.75) !default;
 // Monochrome: painted with `--navbar-toggler-icon-color` through `mask-icon()`.
 $navbar-toggler-icon-bg: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'><path stroke='black' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/></svg>") !default;
@@ -1577,7 +1577,7 @@ $navbar-light-brand-hover-color: $navbar-light-active-color !default;
 
 $navbar-dark-color: color-transparent(var(--white), $text-secondary-opacity) !default;
 $navbar-dark-hover-color: color-transparent(var(--white), 0.75) !default;
-$navbar-dark-active-bg: color-transparent(var(--white), 0.06) !default;
+$navbar-dark-active-bg: var(--active-bg) !default;
 $navbar-dark-brand-color: $white !default;
 $navbar-dark-active-color: $white !default;
 $navbar-dark-disabled-color: var(--disabled-color) !default;
@@ -1600,7 +1600,7 @@ $navbar-toggler-transition: box-shadow 0.15s ease-in-out !default;
 $navbar-toggler-animation-time: 0.2s !default;
 $navbar-overlap-height: 9rem !default;
 
-$navbar-nav-link-hover-bg: color-transparent(var(--nav-link-color), 0.06) !default;
+$navbar-nav-link-hover-bg: var(--hover-bg) !default;
 
 $navbar-active-border-color: var(--primary) !default;
 // scss-docs-end navbar-variables
@@ -1676,7 +1676,7 @@ $pagination-focus-color: var(--link-hover-color) !default;
 $pagination-focus-bg: var(--secondary-bg) !default;
 
 $pagination-hover-color: var(--link-hover-color) !default;
-$pagination-hover-bg: var(--active-bg) !default;
+$pagination-hover-bg: var(--hover-bg) !default;
 $pagination-hover-border-color: var(--pagination-border-color) !default; // Todo in v6: remove this?
 
 $pagination-active-color: $component-active-color !default;
@@ -1790,7 +1790,7 @@ $table-active-bg: var(--active-bg) !default;
 
 $table-hover-color: $table-color !default;
 $table-hover-bg-factor: 0.075 !default;
-$table-hover-bg: color-transparent(var(--emphasis-color), $table-hover-bg-factor) !default;
+$table-hover-bg: var(--hover-bg) !default;
 
 $table-caption-color: var(--secondary-color) !default;
 
@@ -1902,7 +1902,7 @@ $list-group-border-radius: var(--border-radius) !default;
 $list-group-item-padding-y: $card-cap-padding-y !default;
 $list-group-item-padding-x: $card-cap-padding-x !default;
 
-$list-group-hover-bg: $hover-bg !default;
+$list-group-hover-bg: var(--hover-bg) !default;
 $list-group-active-color: inherit !default;
 $list-group-active-bg: var(--active-bg) !default;
 $list-group-active-border-color: $list-group-border-color !default;
@@ -1913,7 +1913,7 @@ $list-group-disabled-bg: $list-group-bg !default;
 $list-group-action-color: inherit !default;
 $list-group-action-hover-color: var(--emphasis-color) !default;
 $list-group-action-active-color: var(--body-color) !default;
-$list-group-action-active-bg: var(--secondary-bg) !default;
+$list-group-action-active-bg: var(--active-bg) !default;
 $list-group-header-padding-y: 0.5rem !default;
 
 // Color variants: a tinted row, matched to the `bg-{color}-lt` utilities
diff --git a/core/scss/layout/_root.scss b/core/scss/layout/_root.scss
index 03562c84a..5c6820c59 100644
--- a/core/scss/layout/_root.scss
+++ b/core/scss/layout/_root.scss
@@ -46,7 +46,8 @@
 
   --icon-color: #{$icon-color};
 
-  --active-bg: light-dark(#{$active-bg}, #{$lighten-dark});
+  --active-bg: #{$active-bg};
+  --hover-bg: #{$hover-bg};
 
   --disabled-bg: #{$disabled-bg};
   // $disabled-color already derives from var(--body-color) at compute time, so it
diff --git a/core/scss/ui/_buttons.scss b/core/scss/ui/_buttons.scss
index 3cd428b85..c1f4bce13 100644
--- a/core/scss/ui/_buttons.scss
+++ b/core/scss/ui/_buttons.scss
@@ -12,10 +12,10 @@
   --btn-bg: var(--bg-surface);
   --btn-color: var(--body-color);
   --btn-border-color: #{$btn-border-color};
-  --btn-hover-bg: var(--btn-bg);
+  --btn-hover-bg: var(--hover-bg);
   --btn-hover-border-color: var(--border-active-color);
   --btn-active-color: #{$active-color};
-  --btn-active-bg: #{$active-bg};
+  --btn-active-bg: var(--active-bg);
   --btn-active-border-color: #{$active-border-color};
   position: relative;
 
@@ -89,7 +89,7 @@
   --btn-bg: transparent;
   --btn-border-color: transparent;
   --btn-box-shadow: none;
-  --btn-hover-bg: var(--bg-surface-secondary);
+  --btn-hover-bg: var(--hover-bg);
   --btn-hover-border-color: transparent;
   --btn-hover-color: var(--body-color);
 }
diff --git a/core/scss/ui/_cards.scss b/core/scss/ui/_cards.scss
index 15f66f749..13eebfbed 100644
--- a/core/scss/ui/_cards.scss
+++ b/core/scss/ui/_cards.scss
@@ -152,7 +152,7 @@
 
   &:hover {
     text-decoration: none;
-    background: $active-bg;
+    background: var(--active-bg);
   }
 
   & + & {
diff --git a/core/scss/ui/_datepicker.scss b/core/scss/ui/_datepicker.scss
index 4f975000f..21345d705 100644
--- a/core/scss/ui/_datepicker.scss
+++ b/core/scss/ui/_datepicker.scss
@@ -19,7 +19,7 @@
   --calendar-font-size: #{$datepicker-calendar-font-size};
   --calendar-header-font-weight: #{$datepicker-calendar-header-font-weight};
   --calendar-weekday-color: var(--secondary);
-  --calendar-day-hover-bg: #{color-transparent(var(--body-color), 6%)};
+  --calendar-day-hover-bg: var(--hover-bg);
   --calendar-day-selected-bg: var(--primary);
   --calendar-day-selected-color: var(--primary-fg);
   --calendar-day-today-bg: #{color-transparent(var(--body-color), 6%)};
diff --git a/core/scss/ui/_lists.scss b/core/scss/ui/_lists.scss
index f4b2427ea..f96d636d0 100644
--- a/core/scss/ui/_lists.scss
+++ b/core/scss/ui/_lists.scss
@@ -31,12 +31,12 @@
   &.disabled,
   &:disabled {
     color: $gray-500;
-    background-color: $dropdown-link-hover-bg;
+    background-color: var(--hover-bg);
   }
 }
 
 .list-group-item.active {
-  background-color: $dropdown-link-hover-bg;
+  background-color: var(--active-bg);
   border-inline-start-color: $component-active-bg;
   border-inline-start-width: $border-width-wide;
 }
@@ -57,7 +57,7 @@
     &:active,
     &:focus,
     &:hover {
-      background-color: $dropdown-link-hover-bg;
+      background-color: var(--hover-bg);
     }
   }
 
diff --git a/core/scss/ui/_nav.scss b/core/scss/ui/_nav.scss
index 4705eae6b..8c3e7d7a5 100644
--- a/core/scss/ui/_nav.scss
+++ b/core/scss/ui/_nav.scss
@@ -1,7 +1,7 @@
 @use '../config' as *;
 
 .nav {
-  --nav-link-hover-bg: #{color-transparent(var(--nav-link-color), 0.04)};
+  --nav-link-hover-bg: var(--hover-bg);
   // Read by `.nav-vertical .nav-link.active` below; without it that rule's
   // color declaration was invalid and the active link fell back to the
   // inherited color.
diff --git a/core/scss/ui/_segmented.scss b/core/scss/ui/_segmented.scss
index 3c9f9e2a2..060d48323 100644
--- a/core/scss/ui/_segmented.scss
+++ b/core/scss/ui/_segmented.scss
@@ -49,7 +49,7 @@
     &:hover,
     &.hover {
       color: var(--body-color);
-      background: rgba(0, 0, 0, 0.04);
+      background: var(--hover-bg);
     }
 
     &.disabled,
diff --git a/core/scss/ui/_type.scss b/core/scss/ui/_type.scss
index 7c7de26d9..966f6f7e1 100644
--- a/core/scss/ui/_type.scss
+++ b/core/scss/ui/_type.scss
@@ -218,7 +218,7 @@ a:hover:has(.icon) {
   &:hover {
     color: var(--primary);
     text-decoration: none;
-    background: color-transparent(var(--secondary), 0.04);
+    background: var(--hover-bg);
   }
 }
 
@@ -249,7 +249,7 @@ Mentions
     &:hover,
     &.hover {
       text-decoration: underline;
-      background: var(--bg-surface-secondary);
+      background: var(--hover-bg);
     }
   }
 }
diff --git a/core/scss/ui/forms/_form-selectgroup.scss b/core/scss/ui/forms/_form-selectgroup.scss
index 4a49c5809..2e8bcdc4a 100644
--- a/core/scss/ui/forms/_form-selectgroup.scss
+++ b/core/scss/ui/forms/_form-selectgroup.scss
@@ -102,7 +102,7 @@ Select group
 .form-selectgroup-input:checked + .form-selectgroup-label {
   z-index: 1;
   color: #{$active-color};
-  background: #{$active-bg};
+  background: var(--active-bg);
   border-color: #{$active-border-color};
 }