feat(theme): Add new tone mixins and deprecate old one (#1546)

The old mixin name is confusing. It's also cumbersome to use if you just want to get the tone of a color directly, and you don't care about the text color that pairs with it.

.stylelintrc.yaml

@@ -241,6 +241,7 @@ rules:
       - if
       - mixin
       - return
+      - warn
   # Disallow "@extend" in scss.
   # http://csswizardry.com/2016/02/mixins-better-for-performance/
   # http://vanseodesign.com/css/sass-mixin-or-extend/
@@ -259,7 +260,7 @@ rules:
   selector-no-qualifying-type: true
   # In general, we should not be modifying elements within our components, since we can't
   # predict the use cases in which users would add a certain type of element into a component.
-  selector-max-type: 
+  selector-max-type:
     - 0
     - ignoreTypes:
         - /fieldset/

packages/mdc-button/_mixins.scss

@@ -22,11 +22,11 @@
 @import "./variables";
 
 @mixin mdc-button-filled-accessible($container-fill-color) {
-  $light-or-dark: mdc-theme-light-or-dark($container-fill-color);
+  $fill-tone: mdc-theme-tone($container-fill-color);
 
   @include mdc-button-container-fill-color($container-fill-color);
 
-  @if ($light-or-dark == "light") {
+  @if ($fill-tone == "dark") {
     @include mdc-button-ink-color(text-primary-on-dark);
     @include mdc-ripple-color(text-primary-on-dark, $mdc-filled-button-ripple-opacity);
   } @else {

packages/mdc-fab/_mixins.scss

@@ -21,12 +21,11 @@
 @import "@material/theme/mixins";
 
 @mixin mdc-fab-accessible($container-color) {
-  @include mdc-fab-container-color($container-color);
+  $fill-tone: mdc-theme-tone($container-color);
 
-  // Calculate whether to use dark or light text on top of given color.
-  $light-or-dark-text: mdc-theme-light-or-dark($container-color);
+  @include mdc-fab-container-color($container-color);
 
-  @if ($light-or-dark-text == "light") {
+  @if ($fill-tone == "dark") {
     @include mdc-fab-ink-color(text-primary-on-dark);
     @include mdc-ripple-color(text-primary-on-dark, $mdc-ripple-pressed-light-ink-opacity);
   } @else {

packages/mdc-theme/README.md

@@ -182,12 +182,20 @@ Calculates the contrast ratio between two colors.
 @debug mdc-theme-contrast(#9c27b0, #000); // 3.33071
 ```
 
-#### `mdc-theme-light-or-dark($color)`
+#### `mdc-theme-tone($color)`
+
+Determines whether the given color is "light" or "dark".
+
+```scss
+@debug mdc-theme-tone(#9c27b0); // dark
+```
+
+#### `mdc-theme-contrast-tone($color)`
 
 Determines whether to use light or dark text on top of a given color.
 
 ```scss
-@debug mdc-theme-light-or-dark(#9c27b0); // light
+@debug mdc-theme-contrast-tone(#9c27b0); // light
 ```
 
 #### `mdc-theme-light-variant($color)` and `mdc-theme-dark-variant($color)`

packages/mdc-theme/_functions.scss

@@ -40,21 +40,35 @@ $_mdc-theme-tonal-offset: 7%;
   @return max($backLum, $foreLum) / min($backLum, $foreLum);
 }
 
-// Determine whether to use dark or light text on top of given color.
-// Returns "dark" for dark text and "light" for light text.
-@function mdc-theme-light-or-dark($color) {
+// Determine whether the color is "light" or "dark".
+@function mdc-theme-tone($color) {
   $minimumContrast: 3.1;
 
   $lightContrast: mdc-theme-contrast($color, white);
   $darkContrast: mdc-theme-contrast($color, rgba(black, .87));
 
   @if ($lightContrast < $minimumContrast) and ($darkContrast > $lightContrast) {
-    @return "dark";
-  } @else {
     @return "light";
+  } @else {
+    @return "dark";
   }
 }
 
+// Determine whether to use dark or light text on top of given color to meet accessibility standards for contrast.
+// Returns "dark" if the given color is light and "light" if the given color is dark.
+@function mdc-theme-contrast-tone($color) {
+  @return if(mdc-theme-tone($color) == "dark", "light", "dark");
+}
+
+// DEPRECATED. Use mdc-theme-contrast-tone instead.
+@function mdc-theme-light-or-dark($color) {
+  // stylelint-disable indentation
+  @warn "The 'mdc-theme-light-or-dark' mixin is DEPRECATED and will be REMOVED in a future version. " +
+        "Please use 'mdc-theme-contrast-tone' or 'mdc-theme-tone' (as applicable) instead.";
+  @return mdc-theme-contrast-tone($color);
+  // stylelint-enable indentation
+}
+
 // lighten() and darken() require values to be between 0% and 100%.
 @function mdc-theme-clamp-percentage_($percentage) {
   @return max(0%, min(100%, $percentage));

packages/mdc-theme/_variables.scss

@@ -39,15 +39,15 @@ $mdc-theme-background: #fff !default; // White
 // Which set of text colors to use for each main theme color (light or dark).
 //
 
-$mdc-theme-primary-tone: mdc-theme-light-or-dark($mdc-theme-primary) !default;
-$mdc-theme-primary-light-tone: mdc-theme-light-or-dark($mdc-theme-primary-light) !default;
-$mdc-theme-primary-dark-tone: mdc-theme-light-or-dark($mdc-theme-primary-dark) !default;
+$mdc-theme-primary-tone: mdc-theme-contrast-tone($mdc-theme-primary) !default;
+$mdc-theme-primary-light-tone: mdc-theme-contrast-tone($mdc-theme-primary-light) !default;
+$mdc-theme-primary-dark-tone: mdc-theme-contrast-tone($mdc-theme-primary-dark) !default;
 
-$mdc-theme-secondary-tone: mdc-theme-light-or-dark($mdc-theme-secondary) !default;
-$mdc-theme-secondary-light-tone: mdc-theme-light-or-dark($mdc-theme-secondary-light) !default;
-$mdc-theme-secondary-dark-tone: mdc-theme-light-or-dark($mdc-theme-secondary-dark) !default;
+$mdc-theme-secondary-tone: mdc-theme-contrast-tone($mdc-theme-secondary) !default;
+$mdc-theme-secondary-light-tone: mdc-theme-contrast-tone($mdc-theme-secondary-light) !default;
+$mdc-theme-secondary-dark-tone: mdc-theme-contrast-tone($mdc-theme-secondary-dark) !default;
 
-$mdc-theme-background-tone: mdc-theme-light-or-dark($mdc-theme-background) !default;
+$mdc-theme-background-tone: mdc-theme-contrast-tone($mdc-theme-background) !default;
 
 //
 // Text colors according to light vs dark and text type.