docs-bug(navbar): navbar color usage (primary and primary-container tokens)

[julien-deramond]

Documentation Feedback

Hello there,

I'm relatively new to Material, particularly Angular Material, and I may have identified a potential issue in the docs navbar color usage.

Context

I'm exploring the creation of an Angular Material custom theme. For a better Developer eXperience, I recompiled the docs with this custom theme.

My understanding is as follows:

• For a custom theme, there isn't necessarily a direct, systematic relationship between primary and primary-container colors.
• background properties should ideally use --mat-sys-* or --mat-sys-*-container color tokens, while the corresponding color properties should use the "on" variants (e.g., --mat-sys-on-primary) of these tokens to ensure sufficient contrast and semantic consistency.

Docs Rendering (Custom Theme)

In the live documentation at https://material.angular.dev/, you can observe an issue by modifying the CSS in the Developer Tools. Setting the following variables:

html {
  --mat-sys-primary: #005cbb;
  --mat-sys-primary-container: #096bd0; /* Close to #005cbb, or even equal to it */
  --mat-sys-on-primary: #fff;
  --mat-sys-on-primary-container: #fff;
}

causes the navbar items to become nearly invisible, especially when --mat-sys-primary-container is identical to --mat-sys-primary.

Analysis

The app-navbar component applies the following style:

[_nghost-ng-c3920750817] {
  color:var(--mat-sys-primary);
  background:var(--mat-sys-primary-container);
}

Changing the color to var(--mat-sys-on-primary-container) only affects the theme selector:

The other navbar items are affected by this rule, which defaults to the primary color:

.mat-mdc-button:not(:disabled) {
  color:var(--mat-button-text-label-text-color, var(--mat-sys-primary))
}

From my current understanding, the theme selector and the buttons should rather use a "--mat-sys-on-*" value, as they are used for a text/foreground color.

Possible fixes

Based on this analysis, several approaches could address the button color issue:

• Use tonal buttons instead of basic buttons in the navbar.
• Override the .mat-mdc-button:not(:disabled) rule specifically within the navbar to use a different color, such as a "--mat-sys-on-*" value.
• Modify the overall background color of the navbar.

If any of the button solutions are applied, the theme selector's styling should be adjusted accordingly.

Next steps

Please feel free to close this issue if this behavior is intentional or already known, considered a minor issue, or if my understanding of the primary and primary container color usage is incorrect.

If this issue worth to be fixed, I am willing to create a PR. Please indicate which of the proposed approaches (or any others) would be the most suitable solution.

Affected documentation page

https://material.angular.dev/