Element Global - Theme

Theme is a foundational, SASS only component. It contains the colors and other basic units used throughout Element.

Basic usage

@use '@element/global/theme';
@use '@element/global/theme/mixins' as theme-mixins;
@use '@element/global/theme/functions' as theme-functions;

Getting a text color for a particular surface

It's a common task to need to fetch the proper text color for a given background surface type.

If you just want either white or black depending on which shows up better on $primary, $secondary, $background, $surface, or $error, you can just use the appropriate variable from:

• $on-primary
• $on-secondary
• $on-background
• $on-surface
• $on-error

Getting a text color for a particular surface AND text style

If you want to also specify a particular text style (e.g. primary, hint, disabled), you should use the prop() mixin.

The first argument is the CSS property that you would like to set. The second argument is a string in the form text-<TEXT_STYLE>-on-<SURFACE>.

For more information on the available text styles, please see the Text Styles section below.

The options for SURFACE are:

• background
• surface
• light
• dark

@use '@element/global/theme/mixins' as theme-mixins;

@include theme-mixins.prop(color, text-hint-on-background);
@include theme-mixins.prop(color, text-primary-on-surface);
@include theme-mixins.prop(color, text-disabled-on-light);
@include theme-mixins.prop(color, text-icon-on-dark);

Getting a text color for a non-standard background color

If you for some reason don't want to use one of the provided background colors, it is also possible to calculate a text color for a particular text style on any given background color using the theme-functions.ink-color-for-fill($text-style, $fill-color) function.

The first argument is kind of text you're trying to get the color for (e.g. primary, hint, disabled). See the Text Styles section below for a list of all possible options.

The second argument is the fill color that you want to display the text on.

@use '@element/global/theme';

color: theme.ink-color-for-fill(hint, #2b2b2b);
color: theme.ink-color-for-fill(disabled, $my-color-variable);

Note: Using the prop() mixin is preferred when possible because it has other logic around error checking and setting of CSS variables as well.

Text Styles

The text styles (referred to as <TEXT_STYLE> below) used in the color system:

Here are the example usages of primary text style:

• CSS Custom property: --element-theme-text-primary-on-light
• Class name: element-theme--text-primary-on-light
• Property name used in Sass: text-primary-on-light

Style Customization

Non-Sass customization

Only a very limited number of Material Design color customization features are supported for non-Sass clients. They are a set of CSS custom properties, and a set of CSS classes.

CSS Custom Properties

CSS Classes

Sass Variables

Configurable variables

Calculated variables

Sass Mixins

prop mixin

The properties below can be used as the $value argument for the prop mixin. Literal color values (e.g., rgba(0, 0, 0, .75)) may also be used.

@use "@element/global/theme";

.foo {
  // Set the `color` property to the theme's primary color
  @include theme.property(color, primary);
}

property mixin with CSS Custom Properties

Note The Sass map $value argument is intended only for use with color mixins.

The property mixin also accepts a Sass map for the $value argument. The map must contain the following fields:

For example, the following Sass...

@use "@element/global/theme";

.foo {
  @include theme.property(
    color,
    (
      varname: --foo-color,
      fallback: red,
    )
  );
}

...will produce the following CSS...

.foo {
  color: red;
  color: var(--foo-color, red);
}

The above output CSS will apply the fallback field's value for all supported browsers (including IE11) while allowing for CSS custom property use as a progressive enhancement. Browsers like IE11 that do not support CSS custom properties will apply the color: red; and ignore the color: var(--foo-color, red);. This argument type is intended for clients who need custom color application outside of the existing theme properties.

Sass Functions

prop-value($style)

This is an alternative to the prop mixin. This is mainly useful in situations where prop cannot be used directly (e.g., box-shadow).

If $style is a color (a literal color value, currentColor, or a CSS custom property), it is returned verbatim. Otherwise, $style is treated as a theme property name, and the corresponding value from $property-values is returned. If this also fails, an error is thrown.

Unlike the prop mixin, this function does not support CSS custom properties. It only returns the raw color value of the specified theme property.

@debug theme.prop-value(primary); // #3f51b5
@debug theme.prop-value(blue); // blue

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 theme.prop-value
• $text-style: Value must be one of primary, secondary, hint, disabled, icon (see $text-colors)

@debug theme.accessible-ink-color(
  secondary
); // rgba(0, 0, 0, .87) (text-primary-on-light)
@debug theme.accessible-ink-color(
  blue
); // white              (text-primary-on-dark)