Skip to main content
Angular Material provides two approaches to styling custom components to match the application’s theme:
  • CSS variables included by mat.theme() prefixed with --mat-sys
  • Utility classes included by mat.system-classes() for applying styles directly in templates
By using system tokens, your application will automatically support both light and dark mode using the color-scheme CSS property.

​
Colors

Material Design uses color to create accessible, personal color schemes that communicate your product’s hierarchy, state, and brand.

​
Primary Colors

Primary backgrounds are useful for key components with greater importance: 
.mat-bg-primary {
  background-color: var(--mat-sys-primary);
}
Always use on-primary text color with primary backgrounds to ensure good contrast and accessibility.

​
Secondary Colors

Secondary backgrounds are useful for less prominent components: 
.mat-bg-secondary {
  background-color: var(--mat-sys-secondary);
}

.mat-bg-secondary-container {
  background-color: var(--mat-sys-secondary-container);
}

​
Error Colors

Error backgrounds indicate error states or important notifications: 
.mat-bg-error {
  background-color: var(--mat-sys-error);
}

.mat-text-error {
  color: var(--mat-sys-error);
}

​
Surface Colors

Surfaces provide backgrounds for components with varying elevation levels:
  • surface-container-lowest - Least emphasis
  • surface-container-low - Less emphasis
  • surface-container - Default surface
  • surface-container-high - More emphasis
  • surface-container-highest - Most emphasis
.mat-bg-surface-container-high {
  background-color: var(--mat-sys-surface-container-high);
}

​
Typography

Material Design provides five categories of font types with three sizes each:

Body

Default text content

Display

Large, impactful text

Headline

Page and section titles

Label

Buttons and UI labels

Title

Card and component titles

​
Body Typography

.mat-font-body-sm {
  font: var(--mat-sys-body-small);
  letter-spacing: var(--mat-sys-body-small-tracking);
}

​
Display Typography

Display typefaces are useful for short, high-impact text: 
.mat-font-display-lg {
  font: var(--mat-sys-display-large);
  letter-spacing: var(--mat-sys-display-large-tracking);
}

​
Label Typography

Labels are useful for buttons, chips, and menu items: 
.mat-font-label-lg {
  font: var(--mat-sys-label-large);
  letter-spacing: var(--mat-sys-label-large-tracking);
}

​
Shape

Material Design uses border radius to help direct attention and communicate state: 
.mat-corner-xs {
  border-radius: var(--mat-sys-corner-extra-small);
}
Used for: snackbars, tooltips

​
Elevation

Material Design uses borders and shadows to create depth and hierarchy.

​
Borders

.mat-border {
  border: 1px solid var(--mat-sys-outline);
}

.mat-border-subtle {
  border: 1px solid var(--mat-sys-outline-variant);
}

​
Shadows

1

Level 1

Slight elevation for cards
.mat-shadow-1 {
  box-shadow: var(--mat-sys-level1);
}
2

Level 2

Standard elevation for menus
.mat-shadow-2 {
  box-shadow: var(--mat-sys-level2);
}
3

Level 3

Raised elevation for FABs
.mat-shadow-3 {
  box-shadow: var(--mat-sys-level3);
}
4

Level 4-5

Reserved for hover/focus states

​
Practical Examples

​
Using CSS Variables

.widget-a  {
  background-color: var(--mat-sys-surface);
  color: var(--mat-sys-on-surface);    
  font: var(--mat-sys-body-medium);
}

.widget-b {
  background-color: var(--mat-sys-primary);
  color: var(--mat-sys-on-primary);
}

​
Using Utility Classes

<widget-a class="mat-bg-surface mat-text-on-surface mat-font-body-medium"/>

<widget-b class="mat-bg-primary mat-text-on-primary"/>

​
Material Design 2 Support

If using Material Design 2 APIs with theme configs, you need to enable system tokens:
@use '@angular/material' as mat;

$theme: mat.m2-define-light-theme((
  color: (
    primary: mat.define-palette(mat.$indigo-palette, 500),
  ),
  ...
));

html {
  @include mat.core-theme($theme);
  @include mat.button-theme($theme);
  ...
  @include mat.m2-theme($theme);
  @include mat.system-classes();
}

​
Available System Tokens

/* Primary */
--mat-sys-primary
--mat-sys-on-primary
--mat-sys-primary-container
--mat-sys-on-primary-container

/* Secondary */
--mat-sys-secondary
--mat-sys-on-secondary
--mat-sys-secondary-container

/* Error */
--mat-sys-error
--mat-sys-on-error
--mat-sys-error-container

/* Surface */
--mat-sys-surface
--mat-sys-on-surface
--mat-sys-surface-variant
Each category has: font, line-height, size, tracking, and weight
  • body-small, body-medium, body-large
  • display-small, display-medium, display-large
  • headline-small, headline-medium, headline-large
  • label-small, label-medium, label-large
  • title-small, title-medium, title-large
--mat-sys-corner-extra-small: 4px
--mat-sys-corner-small: 8px
--mat-sys-corner-medium: 12px
--mat-sys-corner-large: 16px
--mat-sys-corner-extra-large: 28px
--mat-sys-corner-full: 9999px

​
Learn More

Material Design Color

Official Material Design 3 color guidance

Typography

Material Design typography system

Shape

Corner radius scale documentation

Elevation

Elevation and shadows guide

Build docs developers (and LLMs) love

Get started for freeTalk to us