In Angular Material 22, how do you build a custom `mat.theme` from a brand colour, a brand font and a density step?
answer
- one mixin, three categories
- palette value or color map
- twelve prebuilt palettes, none teal
- theme-color schematic takes a hex
- density integers from 0 to -5
basics
~20 sGenerate 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@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
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.
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.
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.
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.