skip to content

In Angular Material 22, how do you build a custom `mat.theme` from a brand colour, a brand font and a density step?

level: middleimportance: must knowfreq 52%

answer

  1. one mixin, three categories
  2. palette value or color map
  3. twelve prebuilt palettes, none teal
  4. theme-color schematic takes a hex
  5. density integers from 0 to -5

basics

~20 s

Generate palettes from the brand hex with ng generate @angular/material:theme-color, then pass them, a font and a density step from 0 to -5 to mat.theme under html. It emits the CSS variables every component reads.

solid answer

~50 s

`mat.theme` takes one map with up to three keys. `color` is either a single M3 palette such as `mat.$violet-palette`, which fills primary, secondary and tertiary, or a map with `primary`, an optional `tertiary` and `theme-type`. None of the twelve prebuilt palettes is teal, so for a transit brand teal you run `ng generate @angular/material:theme-color` with the hex; it writes `_theme-colors.scss` exporting `$primary-palette` and `$tertiary-palette`. `typography` is a font family, used for all text with 700/500/400 weights, or a map with `plain-family`, `brand-family` and the three weights. `density` is an integer from 0 to -5, each step 4px smaller down to a component's minimum. Include it under `html`: it emits colour, typography and density variables only for the keys you pass (the `--mat-sys-*` set, plus component density variables below 0), always adds the shape and state variables, and adds no component selectors. Loading the font files stays your job.

code

scss · 18 lines
scss
@use '@angular/material' as mat;
// Generated by: ng generate @angular/material:theme-color
@use './theme-colors' as transit;

html {
  color-scheme: light dark;
  @include mat.theme((
    color: (
      primary: transit.$primary-palette,
      tertiary: transit.$tertiary-palette,
    ),
    typography: (
      plain-family: Roboto,
      brand-family: 'Transit Sans',
    ),
    density: 0,
  ));
}

go deeper

for a junior

Recall the three keys of mat.theme and that the prebuilt palettes are names like mat.$azure-palette. Know that the theme-color schematic turns a brand hex into palettes.

for a middle

Explain single palette versus color map, why secondary comes from the primary palette's nested tones, and what typography and density values the mixin accepts.

for a senior

Show judgment on the output: only the passed categories, no component selectors, fonts loaded separately, and why negative density can cost accessibility on touch screens.

for a principal

Weigh generated palettes checked into each repo against a shared theme package that wraps mat.theme for several products, and who owns regenerating them when the brand changes.

## The shape of `mat.theme` Angular Material 22 themes components with one Sass mixin from `@use '@angular/material' as mat;`: ```scss html { @include mat.theme(( color: ..., typography: ..., density: ..., )); } ``` The mixin turns its inputs into **CSS custom properties** (CSS variables), declared on the selector you include it in: the `--mat-sys-` system set, plus component-level `--mat-` density variables when density is below 0. Components never read your Sass; they read those variables at runtime. That is why one `html` rule themes the whole app, and why the mixin should always sit inside a selector. Each top-level key is optional. Colour, typography and density variables are emitted **only for the keys you pass**; shape and state variables are emitted by every call. ## Colour: three ways to supply it | You pass | What the mixin does | Typical use | |---|---|---| | A palette, e.g. `mat.$violet-palette` | Uses it for primary and tertiary, takes secondary, neutral and error tones from it, and emits light and dark values | A quick theme from one prebuilt hue | | A map `(primary: ..., tertiary: ..., theme-type: ...)` | Primary palette, a separate tertiary (defaults to primary) and an explicit mode (`color-scheme`, `light` or `dark`) | Two hues, or one fixed mode | | A generated palette from the theme-color schematic, inside that map | Same as the map, with tones computed from your brand colour | A brand colour no prebuilt palette matches | The **twelve prebuilt M3 palettes** are `$red-palette`, `$green-palette`, `$blue-palette`, `$yellow-palette`, `$cyan-palette`, `$magenta-palette`, `$orange-palette`, `$chartreuse-palette`, `$spring-green-palette`, `$azure-palette`, `$violet-palette` and `$rose-palette`. Each is a **tonal palette**: tones 0 to 100, plus nested `secondary`, `neutral`, `neutral-variant` and `error` palettes. The color map reads only `primary`, `tertiary` and `theme-type`; the secondary colour always comes from the primary palette's nested tones. ## Generating a palette from a brand colour A city transit journey planner with a teal brand has no matching prebuilt palette. The kit's answer is a schematic: 1. Run `ng generate @angular/material:theme-color`. 2. Answer the required **primaryColor** prompt with the hex. Optional prompts take a secondary, tertiary, neutral, neutral-variant or error colour; left blank, they are derived from the primary. 3. Choose whether to emit **high-contrast override mixins** (`includeHighContrast`), the output **directory**, and Sass or CSS (`isScss`, default Sass). 4. In Sass mode it writes `_theme-colors.scss`, which exports `$primary-palette` and `$tertiary-palette` with the secondary, neutral and error tones merged in. Pass both into the color map. In CSS mode it instead writes `theme.css`, declaring every system variable directly with `light-dark()` values, for projects without Sass. The README recommends the Sass output because the mixin validates input and keeps working if variable names change. ## Typography - A **single family** (`typography: Roboto`) is used for all component text, with bold 700, medium 500 and regular 400. - A **map** sets `plain-family` (body text, required), `brand-family` (headings and titles, defaults to plain) and `bold-weight`, `medium-weight`, `regular-weight`. - `mat.theme` only names the font. The font files must be loaded separately, in `index.html` or with `@font-face`; otherwise the browser falls back silently. ## Density `density` takes an integer from **0** (default spacing) to **-5** (most compact). Each step down reduces the affected sizes by **4px**, stopping at the smallest size at which a component still renders coherently. A density of 0 emits no density variables at all. The theming guide warns that negative density can reduce accessibility, and density does not change pop-up surfaces such as the datepicker. ## What the output is, and what it is not - **Is:** a set of `--mat-sys-*` declarations on your selector, which components consume through `var()`. - **Is not:** component selectors or restyled component CSS; the M3 API promises not to add selectors. - **Is not:** a font loader, a mode switcher (that is the CSS `color-scheme` property) or a per-component override tool. ## Mistakes interviewers listen for - Passing an **M2 palette** such as `mat.$m2-teal-palette`. It is a hue map (50 to 900 with contrast colours), not a tonal palette, so it does not work as an M3 palette. - Adding a `secondary` key to the color map and wondering why nothing changes; give the colour to the schematic instead. - Hand-editing the generated `_theme-colors.scss`. Its header says it was generated; regenerate it when the brand colour changes, so the tones stay computed rather than guessed. - Including the mixin at the stylesheet's top level instead of inside `html`, or forgetting to load the brand font file.

  • The designers also gave a secondary colour. Where does it go in the mat.theme color map?
    Nowhere in the map: `mat.theme` reads only `primary`, `tertiary` and `theme-type`. Give the colour to the schematic's secondaryColor prompt instead; it is merged into the generated `$primary-palette` as its nested `secondary` palette, which the mixin reads.
  • What does the theme-color schematic's high-contrast option add?
    With `includeHighContrast` the Sass output also defines a `high-contrast-overrides()` mixin taking `light`, `dark` or `color-scheme`. You include it inside `@media (prefers-contrast: more)` so users who ask for more contrast get higher-contrast system colours. The CSS output wraps those values in the same media query.
  • Why does the mixin belong inside an html rule rather than at the stylesheet's top level?
    It emits CSS custom property declarations, which must sit in a rule, and custom properties inherit, so declaring them on `html` reaches every component. The same mixin under another selector themes only that subtree.

  • mat.$m2-teal-palette works as an M3 palette in mat.theme
  • The color map takes primary, secondary and tertiary keys
  • mat.theme loads the font files it names
  • Density accepts positive values for a roomier layout
  • mat.theme generates restyled CSS for every component selector

Assumes Angular Material 22; the mat.theme mixin replaced the define-theme config as the recommended API in v19.