| name | angular-material |
| description | Guides Angular Material v3 (M3) theming — the mat.theme() mixin, system-level --mat-sys-* CSS tokens, color/typography/density configuration, and system/component token overrides. Angular Material v3's theme API is a near-total rewrite of v2's (M2's define-light-theme/define-dark-theme + all-component-themes pattern), so trigger this skill whenever the user is setting up a new Material theme, styling a custom component to match the Material theme, switching between light/dark mode, generating a custom color palette, adjusting density, or migrating an existing Material app from v2/M2 theming to v3/M3 theming — even if they just say "add Material theming", "make my component look like Material", or "fix my Material colors" without naming M3 explicitly. |
Angular Material v3 Theming
Angular Material v3 (M3 — the default palette system since Angular Material v17, with a rewritten single-mixin Sass API since v19) replaced the old primary/accent/warn theme-building pattern with one mat.theme() mixin and a set of --mat-sys-* CSS custom properties that both Material components and your own components can read. Don't reach for mat.define-light-theme, mat.define-dark-theme, mat.all-component-themes, or color="accent" — those are the v2 (M2) API and are either gone or deprecated compatibility shims in v3.
Before you start
Check the installed @angular/material version (package.json or npm ls @angular/material) — the theming API changed twice, so which one applies depends on the version:
- v19+: use
mat.theme() — the current API, described below.
- v17–v18: M3 is the default palette system, but the single-mixin
mat.theme() API doesn't exist yet. Use mat.define-theme() plus the older component mixins — see references/migration-from-v2.md.
- v16 or older: the app is still on M2 (primary/accent/warn palettes,
mat.define-light-theme, mat.all-component-themes). Point the user at references/migration-from-v2.md to move it to M3.
Quick start
@use '@angular/material' as mat;
html {
color-scheme: light dark;
@include mat.theme((
color: mat.$violet-palette,
typography: Roboto,
density: 0,
));
}
One @include mat.theme(...) on html replaces the entire old pattern of building primary/accent/warn palettes by hand, wrapping them in define-light-theme/define-dark-theme, and calling all-component-themes. It emits both the Sass-driven component styles and the --mat-sys-* CSS custom properties in one pass.
ng add @angular/material scaffolds a file like this for a new project. ng generate @angular/material:theme-color generates a custom color palette from a source color instead of using a prebuilt one.
Reference files
- theme-api.md — the full
mat.theme() config map (color, typography, density), overriding system and per-component tokens, the --mat-sys-* CSS variables, mat.system-classes() utility classes, and mat.strong-focus-indicators(). Read this for anything about configuring or customizing a v3 theme.
- migration-from-v2.md — what changed from M2 to M3 (terminology, API shape, the new per-include selector-wrapping requirement), the
color-variants-backwards-compatibility mixin, get-theme-version, and the pre-v19 mat.define-theme() API. Read this when touching an app that still has M2 (or early M3) theming.
Styling your own components
Don't hardcode colors or font sizes in custom components that live inside a Material-themed app — read the theme through the --mat-sys-* CSS variables instead (e.g. color: var(--mat-sys-on-surface)), or use the mat.system-classes() utility classes. Both stay in sync automatically when the user switches light/dark mode or changes the palette, which hand-picked colors never do. Details and common token names are in theme-api.md.
