feat: Declare & Use CSS Custom Properties (#3146)

less/common/mixins/button-color.less

@@ -0,0 +1,41 @@
+/**
+ * Should be used at the `:root` level to declare the color variations as custom CSS properties first.
+ * Then use the `.Button--color-auto()` below to use those variations on your element.
+ *
+ * `@name` parameter must be unique.
+ *
+ * For example:
+ * :root {
+ *   .Button--color-vars(green, white, 'button-success');
+ * }
+ *
+ * .Button--success {
+ *   .Button-color-auto('button-success');
+ * }
+ */
+.Button--color-vars(@color; @background; @name: 'button') {
+  @componentName: ~"@{name}";
+
+  --@{componentName}-color: @color;
+  --@{componentName}-bg: @background;
+  --@{componentName}-bg-hover: darken(fadein(@background, 5%), 5%);
+  --@{componentName}-bg-active: darken(fadein(@background, 10%), 10%);
+  --@{componentName}-bg-disabled: @background;
+}
+
+.Button--color-auto(@name: 'button') {
+  --button-color: var(~"--@{name}-color");
+  --button-bg: var(~"--@{name}-bg");
+  --button-bg-hover: var(~"--@{name}-bg-hover");
+  --button-bg-active: var(~"--@{name}-bg-active");
+  --button-bg-disabled: var(~"--@{name}-bg-disabled");
+}
+
+/**
+ * Legacy mixin, allows customizing button colors inline without declaring custom CSS properties at the root.
+ * For a better theming experience, declaring the custom CSS properties at the root first using `Button--color-vars()`
+ * then using `Button--color-auto()` is recommended.
+ */
+.Button--color(@color; @background) {
+  .Button--color-vars(@color, @background, 'button');
+}

less/common/mixins/header-background.less

@@ -1,17 +1,17 @@
 .header-background() {
-  background: @header-bg;
+  background: var(--header-bg);
   position: fixed;
   top: 0;
   left: 0;
   right: 0;
-  z-index: @zindex-header;
-  border-bottom: 1px solid @control-bg;
+  z-index: var(--zindex-header);
+  border-bottom: 1px solid var(--control-bg);
   transition: box-shadow 0.2s, transform 0.2s;
 
   @media @phone {
-    height: @header-height-phone;
+    height: var(--header-height-phone);
   }
   @media @tablet-up {
-    height: @header-height;
+    height: var(--header-height);
   }
 }

less/common/mixins/light-contents.less

@@ -1,26 +1,26 @@
 // This is a mixin which styles components (buttons, inputs, etc.) for use on
 // dark backgrounds.
-.light-contents(@color: #fff, @control-bg: fade(#000, 10%), @control-color: #fff) {
+.light-contents(@color: #fff; @control-bg: fade(#000, 10%); @control-color: #fff; @name: 'light-content') {
   &, a {
-    color: @color;
+    color: var(~"--@{name}-color", @color);
   }
   .Button--link, .Search-input {
-    color: @control-color;
+    color: var(~"--@{name}-control-color", @control-color);
   }
   .FormControl {
-    background: @control-bg;
+    background: var(~"--@{name}-control-bg", @control-bg);
     border: 0;
-    color: @control-color;
-    .placeholder(@control-color);
+    color: var(~"--@{name}-control-color", @control-color);
+    .placeholder(var(~"--@{name}-control-color", @control-color));
 
     &:focus {
       color: @color;
-      background: fadein(darken(@control-bg, 5%), 10%);
+      background: var(~"--@{name}-control-bg-shaded", fadein(darken(@control-bg, 5%), 10%));
     }
   }
   .Button, .Button:hover {
-    color: @control-color;
-    background: @control-bg;
+    color: var(~"--@{name}-control-color", @control-color);
+    background: var(~"--@{name}-control-bg", @control-bg);
   }
   .Button--flat {
     background: transparent;
@@ -30,7 +30,17 @@
   .Button:focus,
   .Button.focus,
   .open > .Dropdown-toggle.Button {
-    background: fadein(@control-bg, 5%);
-    color: @control-color;
+    background: var(~"--@{name}-control-bg-fadedin", fadein(@control-bg, 5%));
+    color: var(~"--@{name}-control-color", @control-color);
   }
 }
+
+.light-contents-vars(@color: #fff; @control-bg: fade(#000, 10%); @control-color: #fff; @name: 'light-content') {
+  @componentName: ~"@{name}";
+
+  --@{componentName}-color: @color;
+  --@{componentName}-control-color: @control-color;
+  --@{componentName}-control-bg: @control-bg;
+  --@{componentName}-control-bg-shaded: fadein(darken(@control-bg, 5%), 10%);
+  --@{componentName}-control-bg-fadedin: fadein(@control-bg, 5%);
+}