Components: docs-bug(COMPONENT): Angular Material Theming

[peternixey]

Documentation Feedback

The documentation on theming angular material is terribly lacking. There are multiple themes included with material, none of which are listed in the documentation. There is no description of how to produce color maps for material, there's no description of how to marry together foreground and background maps. There's no clarity on how dividers etc. are themed and there's no real guidance on how to build custom themes.

I would like to see:

• a clear list of the maps that a theme requires to be complete
• clear instructions on what maps should be used
• a list of the maps that actually ship with the theme and guidance on how to use them
• clearer SCSS functions to build the theme
• clear guidance on how to build up custom typography suites
• ideally a page that would allow you to put in colors and typography and would then generate the scss for it

OR... at the very least it would be helpful for the documentation to at least state what it's not covering. There's so much stuff that you have to go rooting around in the source code to find (like what the existing color maps are and what the SCSS functions do). If the documentation at least listed out what the user needed to know that would be a helpful start. But the docs glance across all of the key subjects without going into adequate depth and the reader is left completely unclear as to whether she is being stupid or the docs are incomplete.

Here's an example of a question that the docs just don't answer:

https://stackoverflow.com/questions/43438305/how-to-change-font-color-of-primary-palette-in-angular-material2

This stuff is really hard and confusing and some good documentation would make the world of difference - thank you so much!

Affected documentation page: Insert a link to the affected page on material.angular.io

https://material.angular.io/guide/theming
https://material.angular.io/guide/typography

[mrmokwa]

I'd like to add this article written by Tomas Trajan to the discution, since it helped me alot with theming
https://medium.com/@tomastrajan/the-complete-guide-to-angular-material-themes-4d165a9d24d1

[peternixey]

Thank you @mrmokwa - that article is indeed really useful and was one of the articles that I pored over trying to figure this out. This is something I spent a bunch of time on at the start of the year and I've recently come back to.

Since putting in this bug report though I've actually managed to get more of a handle on it and have copied what I did below. In essence, all I've done is explicitly set the different pallettes in long-hand.

Just doing this has been incredibly liberating. Simply knowing what I was missing was a huge help and being able to specify it got me pretty much the whole way there. That said I'm not entirely sure what I don't have included here. I suspect there are a a couple of palettes missing (and there's still no way to set the color of href links apart from brute forcing).

In terms of docs, I think that simply listing the details below out explicitly would go a long way to making things simpler.

Best
Peter

````

palettes.scss

// Generated using:
// http://mcg.mbitson.com/#!?mcgpalette0=%23ee5835&mcgpalette1=%2326a69a&mcgpalette3=%23f7b87d&themename=materialdemo

// Key colour associated with the applciation (and shades)
$primary-palette: (
50 : #def7f5,
100 : #a0e9e2,
200 : #72dfd4,
300 : #38d1c3,
400 : #2cbfb1,
500 : #26a69a,
600 : #208d83,
700 : #1b746c,
800 : #155b55,
900 : #0f423e,
A100 : #cefdf9,
A200 : #6cf9ec,
A400 : #1ce3d0,
A700 : #25c0b2,
contrast: (
50 : #000000,
100 : #000000,
200 : #000000,
300 : #000000,
400 : #000000,
500 : #ffffff,
600 : #ffffff,
700 : #ffffff,
800 : #ffffff,
900 : #ffffff,
A100 : #000000,
A200 : #000000,
A400 : #000000,
A700 : #000000,
)
);

// Accent colour (and shades)
$accent-palette: (
50 : #fdebe7,
100 : #facdc2,
200 : #f7ac9a,
300 : #f38a72,
400 : #f17153,
500 : #ee5835,
600 : #ec5030,
700 : #e94728,
800 : #e73d22,
900 : #e22d16,
A100 : #ffffff,
A200 : #ffe2e0,
A400 : #ffb4ad,
A700 : #ff9d93,
contrast: (
50 : #000000,
100 : #000000,
200 : #000000,
300 : #000000,
400 : #000000,
500 : #000000,
600 : #ffffff,
700 : #ffffff,
800 : #ffffff,
900 : #ffffff,
A100 : #000000,
A200 : #000000,
A400 : #000000,
A700 : #000000,
)
);

// Our preferred warning colour (and shades)
$warn-palette: (
50 : #ffffff,
100 : #ffffff,
200 : #fffafa,
300 : #fbb7b7,
400 : #f99a9a,
500 : #f77d7d,
600 : #f56060,
700 : #f34343,
800 : #f22727,
900 : #eb0e0e,
A100 : #ffffff,
A200 : #ffffff,
A400 : #ffa8a8,
A700 : #fb9292,
contrast: (
50 : #000000,
100 : #000000,
200 : #000000,
300 : #000000,
400 : #000000,
500 : #000000,
600 : #000000,
700 : #ffffff,
800 : #ffffff,
900 : #ffffff,
A100 : #000000,
A200 : #000000,
A400 : #000000,
A700 : #000000,
)
);

// The palette to be used for background colours (in this case assuming dark theme)
$background: (
status-bar: #3E3E4B,
app-bar: map-get($mat-grey, 900),
background: #3E3E4B,
hover: rgba(white, 0.04), // TODO(kara): check style with Material Design UX
card: map-get($mat-grey, 800),
dialog: map-get($mat-grey, 800),
disabled-button: rgba(white, 0.12),
raised-button: map-get($mat-grey, 800),
focused-button: $light-focused,
selected-button: map-get($mat-grey, 900),
selected-disabled-button: map-get($mat-grey, 800),
disabled-button-toggle: black,
unselected-chip: map-get($mat-grey, 700),
disabled-list-option: black,
tooltip: map-get($mat-grey, 700),
);

// Pallette for foreground colours
$foreground: (
base: black,
divider: $light-dividers,
dividers: $light-dividers,
disabled: $light-disabled-text,
disabled-button: rgba(white, 0.3),
disabled-text: $light-disabled-text,
elevation: black,
hint-text: $light-disabled-text,
secondary-text: $light-secondary-text,
icon: white,
icons: white,
text: white,
slider-min: white,
slider-off: rgba(white, 0.3),
slider-off-active: rgba(white, 0.3)
);

// link color (as far as I can tell this isn't specified by Material)
$linkColor: #95FFF5;

````

Having defined the palettes, we then plug them into the theme along with any typography choices:

````
// custom-theme.scss

// Custom Theming for Angular Material
// For more information: https://material.angular.io/guide/theming
@import '~@angular/material/theming';
@import "styles/palettes";

// Include the common styles for Angular Material
// Be sure that you only ever include this mixin once!
@include mat-core();
// --------------------------------
// Typography

// Add any levels that you'd like to override along with their attributes e.g.
// $custom-typography: mat-typography-config(
// $font-family: 'Roboto, monospace',
// $headline: mat-typography-level(32px, 48px, 700),
// $body-1: mat-typography-level(16px, 24px, 500)
// );
// More details: https://material.angular.io/guide/typography

$custom-typography: mat-typography-config(
$font-family: 'Roboto, "Helvetica Neue", sans-serif'
);
@include mat-base-typography($custom-typography);

// --------------------------------
// Color palettes

// Define the palettes for your theme using the Material Design palettes available in palette.scss
// (imported above). For each palette, you can optionally specify a default, lighter, and darker
// hue. Available color palettes: https://material.io/design/color/
$primary-mat-palette: mat-palette($primary-palette);
$secondary-mat-palette: mat-palette($accent-palette);
$warn-mat-palette: mat-palette($warn-palette);

// Create the theme object
@function create-theme($primary, $accent, $warn, $foreground, $background) {
@return (
primary: $primary,
accent: $accent,
warn: $warn,
is-dark: false,
foreground: $foreground,
background: $background,
);
}

$custom-theme: create-theme($primary-mat-palette,
$secondary-mat-palette,
$warn-mat-palette,
$dark-foreground,
$dark-background);
@include angular-material-theme($custom-theme);

// --------------------------------
// Specify link color (I can't see this formally defined in Material)
.mat-typography a{
color: $linkColor;
}
````

If the above really covers what's required then it's actually pretty straightforward. It's just that the current docs are (to put it mildly) a bit cryptic in how they go about describing this!

[c-kunz]

I feel you. I've just been struggling on how to customize theming in Angular Material beyond just the simple primary / accent / warn palettes.

I have created this document that outlines how to create a complete color-configuration from scratch: https://gist.github.com/c-kunz/6934f450c3e2036d3ba5669cbc17b698

This unfortunately does not include any typography customization (yet?). I hope it helps anyone coming across this problem.

[Baffour]

@c-kunz that's awesome! I updated our theming yesterday, and I had to chuck in a rainbow of colours and just see what changed, wish I'd followed this!

One thing I would suggest is to do a map-merge of the default background/foreground colours so you always fall back on those keys in they're not defined. (It looks like the theming only checks if a map exists, and doesn't fallback on keys). So you might do:

map-merge($mat-light-theme-background,(
    background: #f4f4f4,
    hover:  #E0E0E0,
    card: aliceblue
))

Reason being that I updated from a version where tooltip background wasn't part of the palette, and I spent ages searching for a bug related to z-index/stacking context/overlays before realising the tooltips were actually showing up, but they had white text and no background!
Another benefit of this is if you just want to change on or two things, you can leave the default colours for other things intact,