Suggestion for improvements to the Guides for new developers

[mikejunt]

I would categorize this as a suggestion instead of a bug, but as someone who spent the weekend learning to use Angular Material, I have three suggestions that I think would significantly assist new user uptake, both in relation to the use of themes:

Firstly, I suggest moving the informational snippet about needing content to be contained within a <mat-sidenav-container> or having the mat-app-background class in place to a more prominent role in the theming instructions. This information is necessary to implement theming and it is easy to miss on first glance.

Secondly, I suggest adding documentation in the component docs regarding which components do and do not function in the absence of a conventional HTML element. I found that <mat-form-field> elements do absolutely nothing if they are located on the parent level of their HTML file: they must be included in a conventional HTML element (like a div) to work. This would be useful information to include.

Thirdly, I suggest the addition of simple customizable components for basic page roles for background theming, particularly a generic way to add a primary or accent color background. If this is not desirable, better documentation of the selector specificity used by Angular Material would be welcome. It currently requires element inspection or examination of the theme css to determine the specificity of Material themed elements (like mat-toolbar) if you wish to change their color.

Existing elements (like <mat-toolbar>) can serve some of these roles but tend to have other specific styling (such as the set font size in mat-toolbar). Better tools to create your own themed elements (or documentation on how the theme colors are applied so that you can interact with them) would, in my view, improve accessibility.

Simply borrowing the existing theme classes (such as mat-primary or mat-accent) doesn't work due to specificity. Having to re-create header-color CSS in individual component scss files results in a lot of duplication of effort: these are exactly the things you'd include at the top level, where they're ignored in favor of the greater specificity of "body>.mat-app-background.mat-typography".

I understand that AM wants to deal in entirely pre-formed components, but I believe that better explanation of how to customize other content around it would be very helpful.

[Splaktar]

First

This appears to be related to the Theming Angular Material Guide. This guidance is already pretty prominently placed within the section on "Using a pre-built theme".

To confirm, you ran into this while using a pre-built theme in an app without a sidenav?

Second

Can you please provide a StackBlitz demonstration of this issue?

Third

I think that we expect most production apps to use a custom theme. Here is an example of overriding the app's background to be white instead of grey when using a Custom Theme. You can replace this with custom colors as desired.

You can find the Sass for mat-toolbar theming here. https://material.angular.io/guide/theming#theming-only-certain-components demonstrates how you can use these to provide per-component theme customization in your app.

If you are running into issues of "selector specificity", then you are most likely taking the wrong approach and not using the Sass mixins provided by the library.

For Typography, as you can see in https://github.com/angular/components/blob/9eeb4b5aa0473c0815a73bfe3c2ed6164d86a3b3/src/material/toolbar/_toolbar-theme.scss#L58-L69, the title Typography value is the only one that mat-toolbar uses. You can learn more about how to override the value of title for all components, or just the toolbar, in the Typography Guide. You can find more detail about how the Typography Configuration works in the Typography Sass: https://github.com/angular/components/blob/d9977bdb1101e107312580c124acf0a9f410452e/src/material/core/typography/_typography.scss#L20-L70.

We've recently added more emphasis in the guides to indicate that understanding Sass functions and features is important. You can check out the Sass guide for a quick intro to some of these features.

That said, I think that we need to do a better job of documenting all of the features of our Sass mixins, functions, and variables in a more clear, searchable, understandable, and comprehensive way. Currently it requires too much looking at the source Sass and being able to understand the code's purpose and intention.

[mikejunt]

I imported the commit of my repo that was having the issue to Stackblitz and it worked properly, so I will offer a "I guess I should have re-served it" on that one.

As far as documentation notes go, I think you're correct both in regards to full production applications using custom themes, and that users making use of that are not likely to run into issues. It does inhibit using the pre-built themes as a plug-and-play solution for basic presentability, though that may not be their intended usage in the first place.

[mikejunt]

So having worked now quite a bit with Material and having figured out the problems I was encountering, I found myself wanting to try to assist in improving clarity in the guides for inexperienced users. I forked the repo hoping to tweak them and send them back as a pull request, but I found that the guides are static files served from outside the application. I tried saving one to edit but it appears to me that they have been generated by some sort of application for SEO optimization. I would be still be interested in attempting to make these tweaks, but I would need a little guidance as to how the guides were generated in the first place.

If that is not an area where contributions are desired, I'm glad to close out the issue.

[Splaktar]

The source for the guides can be found in the angular/components repo under guides/.

However, the process of updating a guide in Markdown and then seeing it rendered in HTML as part of the docs site is overly complex, not well documented, and generally requires that your changes to get merged to master of angular/components. (that's because there is an intermediate repo that holds the docs, guides, and examples)

So for now, your best bet is to just work with the Markdown guides in angular/components. After your changes get merged, if it doesn't look quite right on the docs site, you'd need to send another PR to tweak it.

We're planning some changes to how we build the docs site that should improve this situation in the future.