Material-components-web-components: Styling documentation

[mercmobily]

Hi,

From the readme:

Rebuild CSS for components
Components define their css using SASS. The SASS output is built into a javascript module which exports the component's styling as a lit-html template.
To compile the component SASS run:
npm run update-styling

...che?!?
There are three levels here:

• MDC Web, the foundation for material-components-web-components, uses SASS and plain JS
• material-components-web-components uses lit-html
• Now we have the SASS output of MDC Web which _is built into a javascript module which exports the component's styling as a lit-html template_ . The only problem here is that I am not 100% sure I understand the previous sentence, and I _definitely_ have no idea why I would have to "Rebuild the component's CSS" -- do I need to do that for styling?

Please update the docs so that they explain:

• Why you would want to rebuild the CSS for components
• A practical example of a simple component's output, and how lit-html template is generated from that component
• What to DO with that lit-html template
• How to theme/change these elements

It's probably all too obvious once you know it... but...

[galanovnick]

@mercmobily

Why you would want to rebuild the CSS for components

I think it's about components development. If you are going to contribute to their (MWC) elements, and if you need to change some styles, you'll need to rebuild the CSS.

[elyobo]

It would be useful to have some docs that explain how to apply your own theme appropriately - using the mcw base you get the ability to theme things by setting the appropriate SASS variables, but that no longer works here (and even CSS variables don't seem to be used as they could, e.g. https://github.com/material-components/material-components-web-components/issues/272).

Is there some guidance on how to theme these components? Note https://github.com/material-components/material-components-web-components/issues/28 also asks the same I guess.

[Westbrook]

@elyobo Have you checked out the new break down between the base and the full component that just went down. Not sure if that change is all the way out the NPM yet, but that would be my suggestion.

You could either cut the styling out together and extend from the _base_ or use something like:

import {csss} from '@material/mwc-base/base-element';

@customElement('your-button' as any)
export class YourButton extends Button {
  static styles = [...super.style, css`:host { content: 'customize here';}`];
}

[elyobo]

Thanks @Westbrook, I did notice the difference, and that's useful for making changes to button specific styles - but changing the theme primary and secondary colours, for example, shouldn't require changing the element code for every element that you want to obey your themes.

It seems like this could be solved if the background-color rules respected the CSS variables.

Edit: they _do_ seem to be respecting the CSS variables (so maybe just some docs that points people in the right direction would be helpful).

[Westbrook]

100% agreed! I know the team has discussed that as having come back into the product plans after a long while of focusing on direct 1 for 1 implementation of the MCW packages. However, it's not on the current sprint https://github.com/material-components/material-components-web-components/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Sprint+7+July+9-22%22 so it's hard to say when it would hit active development, though the base + styled breakdown seem a precursor to that work.

For now, the base + styled breakdown would give you similar abilities locally (albiet with a very manual lift) if you're wanting to get into that sooner.

[elyobo]

Thanks, I was overlooking that the button _does_ support the standard CSS variables for styling, so I think that it's functionally fine as is but some extra docs on how to style these components as a consumer would be useful.

[aomarks]

We're in the process of adding READMEs to all components, which will include a table of all relevant custom properties (see https://github.com/material-components/material-components-web-components/tree/master/packages/snackbar for example).

We're tracking this at https://github.com/material-components/material-components-web-components/issues/348, so closing this one, can resume discussion there.

[elyobo]

Thanks @aomarks, that's looking great and will make these much easier to use :+1: