feat(system-level-variables): Allow calling component mixins without specific theme

[marklagendijk]

Feature Description

System level CSS variables are awesome. They give full control over theming:

• Theme variable values are available at runtime.
• Theme variable values can be adjusted at runtime.
• Changing the entire theme is just a matter of supplying different values for the sys- variables.
• Using any theme variable anywhere in the app can be done using the CSS variables. No need for importing any SASS logic from @angular/material.

Defining and using a theme is as simple as:

@use "@angular/material" as mat;

$theme: mat.define-theme(
  (
    color: (
      theme-type: light,
      primary: mat.$cyan-palette,
      tertiary: mat.$magenta-palette,
      use-system-variables: true,
    ),
    typography: (
      use-system-variables: true,
    ),
  )
);

html {
  @include mat.system-level-colors($theme);
  @include mat.system-level-typography($theme);
}

With this one can easily define a bunch of such defined themes, and then load one based on user settings. Alternatively a backend endpoint could render the CSS file with the sys- variables.

The issue

Everything in Angular Material nicely supports system-level themes, except the component theming mixins.
We still are still required to do something like:

html {
    @include mat.all-component-themes($theme);
}

This is not nice, because we now have generic styling code that needs to use a specific theme.

A solution would be to allow passing something like this:

html {
  @include mat.all-component-themes((use-system-variables: true));
  // Or available on mat.
  @include mat.all-component-themes(mat.$system-variables-theme);
  // Or allow passing no theme
  @include mat.all-component-themes();
}

Workaround

Create your own $system-variables-theme, and use it:

html {
  $system-variables-theme: mat.define-theme(
    (
      color: (
        use-system-variables: true,
      ),
      typography: (
        use-system-variables: true,
      ),
    )
  );
  @include mat.all-component-themes($system-variables-theme);
}

Use Case

Easy and clean theming, with minimal theme files.
I'm not sure whether the current workaround is 'ergonomic' enough. If it is, it should at least be added to the documentation.

[crisbeto]

Are the changes in #29275 what you're looking for?

[marklagendijk]

@crisbeto I have no clue what that PR is doing. The library and its usage of SASS are so complex / non-common that most code is quite unreadable to those not familiar with it.

My issue is about making system level variables first-class citizens. For me that includes being able to call the mixins without an actual theme being present.
My workaround accomplishes this, but I think it might be more clean if the library accommodates this usecase specifically.

[crisbeto]

The PR will add an API that lets you override specific tokens without having to pass in a theme. That being said, with the system-level variables you can already set the values directly. The system-level-colors and system-level-typography mixins are there primarily to make it easier to generate the tokens if you already have a theme.

[marklagendijk]

Right. If you ask me, the system level variables approach should be the default / recommended approach.
CSS variables are a lot easier to understand, and a lot more powerful to work with.
In that sense the 3th option (making $theme argument optional, omitting means system level variables) might be the nicest:

@include mat.all-component-themes();

I do love the system-level-colors and system-level-typography mixins. They take away the hassle for when you define your theme via SASS.

[crisbeto]

Closing since we're in the progress of documenting a simplified theming API based primarily on system variables.

[marklagendijk]

@crisbeto is this documentation available already? Where can I find it?

[crisbeto]

Each component has a "Styling" tab in the next version of the docs site: https://next.material.angular.io/components/card/styling. After v19 final the docs will be available on the main site as well.

[marklagendijk]

@crisbeto are in v19 the default values set to the system variables?
So is it no longer necessary to call @include mat.all-component-themes?

html {
  $system-variables-theme: mat.define-theme(
    (
      color: (
        use-system-variables: true,
      ),
      typography: (
        use-system-variables: true,
      ),
    )
  );
  @include mat.all-component-themes($system-variables-theme);
}

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}