feat(theme): Add accessible-ink-color function (#1719)

New mixin: `mdc-theme-accessible-ink-color($fill-color, $text-style: primary)`

packages/mdc-theme/README.md

@@ -236,3 +236,19 @@ It only returns the raw color value of the specified theme property.
 @debug mdc-theme-prop-value(primary); // #3f51b5
 @debug mdc-theme-prop-value(blue);    // blue
 ```
+
+#### `mdc-theme-accessible-ink-color($fill-color, $text-style: primary)`
+
+Returns an accessible ink color that has sufficient contrast against the given fill color.
+
+Params:
+
+- `$fill-color`: Supports the same values as `mdc-theme-prop-value`
+- `$text-style`: Value must be one of `primary`, `secondary`, `hint`, `disabled`, `icon` (see `$mdc-theme-text-colors`)
+
+> NOTE: This function is defined in `_variables.scss` instead of `_functions.scss` to avoid circular imports.
+
+```scss
+@debug mdc-theme-accessible-ink-color(secondary); // rgba(0, 0, 0, .87) (text-primary-on-light)
+@debug mdc-theme-accessible-ink-color(blue);      // white              (text-primary-on-dark)
+```

packages/mdc-theme/_variables.scss

@@ -164,3 +164,15 @@ $mdc-theme-property-values: (
 
   @return map-get($mdc-theme-property-values, $property);
 }
+
+// NOTE: This function must be defined in _variables.scss instead of _functions.scss to avoid circular imports.
+@function mdc-theme-accessible-ink-color($fill-color, $text-style: primary) {
+  $fill-color-value: mdc-theme-prop-value($fill-color);
+  $color-map-for-tone: map-get($mdc-theme-text-colors, mdc-theme-contrast-tone($fill-color-value));
+
+  @if not map-has-key($color-map-for-tone, $text-style) {
+    @error "Invalid $text-style: '#{$text-style}'. Choose one of: #{map-keys($color-map-for-tone)}";
+  }
+
+  @return map-get($color-map-for-tone, $text-style);
+}