angular-material-20.mdc

---
description: This rule provides comprehensive best practices and coding standards for Angular development with Angular Material, focusing on Material 3 (a.k.a. M3) design, theme configuration and various API usages.
globs: ["**/*.{ts,html,scss,css}"]
---

# Angular Material 20 Best Practices

This project adheres to modern Angular Material best practices, emphasizing maintainability, performance, accessibility, scalability and correct usage of APIs.

## Core Principles

### SCSS vs CSS
- **Prefer SCSS** for styling, especially when theme customization is required. Angular Material has APIs written in SCSS.
- **Use CSS only** when you need to use theme styles generated by `mat.theme` mixin. Modifications or customizations for Angular Material theming are not possible with CSS.

### Component & Directive Imports
Always import components and directives from `@angular/material` package. Avoid importing modules.

**Good:**
```ts
import { MatButton } from '@angular/material/button';
import { MatIcon } from '@angular/material/icon';
import { MatCard, MatCardContent } from '@angular/material/card';
```

**Bad:**
```ts
import { MatButtonModule } from '@angular/material/button';
import { MatIconModule } from '@angular/material/icon';
import { MatCardModule } from '@angular/material/card';
```

## Theming Configuration

Always use `mat.theme` mixin to configure the theme. **Avoid** using `mat.define-theme`, `mat.define-light-theme`, `mat.define-dark-theme` functions and `mat.core` mixin.

### Basic Theme Configuration

The `mat.theme` mixin takes a map with the following properties:
- **`color`**: Single color palette or a map of color palettes
- **`typography`**: Single typography or a map of typography properties  
- **`density`**: Integer from 0 to -5 (0 = default spacing, -5 = most dense)

### Simple Theme Example

```scss
@use '@angular/material' as mat;

html {
  color-scheme: light dark;
  @include mat.theme((
    color: mat.$violet-palette,
    typography: Roboto,
    density: 0
  ));
}
```

### Advanced Theme with Multiple Color Palettes

```scss
@use '@angular/material' as mat;

html {
  color-scheme: light dark;
  @include mat.theme((
    color: (
      primary: mat.$violet-palette,
      tertiary: mat.$orange-palette,
    ),
    typography: (
      plain-family: Roboto,
      brand-family: Open Sans,
      bold-weight: 900,
      medium-weight: 500,
      regular-weight: 300,
    ),
    density: 0
  ));
}
```

### Supporting Light and Dark Mode with Selectors

```scss
@use '@angular/material' as mat;

html {
  color-scheme: light;
  @include mat.theme((
    color: mat.$violet-palette,
    typography: Roboto,
    density: 0
  ));
}

body.dark-mode {
  color-scheme: dark;
}
```

### Multiple Themes

```scss
@use '@angular/material' as mat;

html {
  @include mat.theme((
    color: mat.$violet-palette,
    typography: Roboto,
    density: 0,
  ));
}

.example-bright-container {
  @include mat.theme((
    color: mat.$cyan-palette,
  ));
}
```

## Button Directives

Always use `matButton`, `matIconButton` & `matFab` selectors for Angular Material buttons' directives. **Avoid** using `mat-button`, `mat-raised-button`, `mat-stroked-button`, `mat-flat-button`, `mat-icon-button`, `mat-fab`, etc. selectors.

### Correct Button Usage

```html
<button matButton>Basic</button>
<button matButton="elevated">Elevated</button>
<button matButton="outlined">Outlined</button>
<button matButton="filled">Filled</button>
<button matButton="tonal">Tonal</button>
<button matIconButton aria-label="Example icon button with a vertical three dot icon">
    <mat-icon>more_vert</mat-icon>
</button>
<button matFab aria-label="Example icon button with a delete icon">
    <mat-icon>delete</mat-icon>
</button>
```

### Incorrect Button Usage (Avoid)

```html
<button mat-button>Basic</button>
<button mat-raised-button>Elevated</button>
<button mat-stroked-button>Outlined</button>
<button mat-flat-button>Filled</button>
<button mat-icon-button aria-label="Example icon button">
    <mat-icon>more_vert</mat-icon>
</button>
<button mat-fab aria-label="Example icon button">
    <mat-icon>delete</mat-icon>
</button>
```

## Using Theme Styles & System Variables

The `mat.theme` mixin emits CSS variables known as "System Variables" that can be used to style components.

### Basic Usage Example

```css
:host {
  background: var(--mat-sys-primary-container);
  color: var(--mat-sys-on-primary-container);
  border: 1px solid var(--mat-sys-outline-variant);
  font: var(--mat-sys-body-large);
}
```

### System Variables Reference

#### Colors

- `--mat-sys-primary`, `--mat-sys-on-primary`, `--mat-sys-primary-container`, `--mat-sys-on-primary-container`
- `--mat-sys-secondary`, `--mat-sys-tertiary`, and their `on-` and `container` variants
- `--mat-sys-surface`, `--mat-sys-on-surface`, `--mat-sys-surface-container`
- `--mat-sys-error`, `--mat-sys-on-error`, `--mat-sys-error-container`
- `--mat-sys-outline`, `--mat-sys-outline-variant`

#### Typography

- `--mat-sys-display-small`, `--mat-sys-display-medium`, `--mat-sys-display-large`
- `--mat-sys-headline-small`, `--mat-sys-title-medium`, `--mat-sys-body-large`
- `--mat-sys-label-medium`, etc.

#### Shape (Border Radius)

- `--mat-sys-corner-extra-small`, `--mat-sys-corner-medium`, `--mat-sys-corner-large`, etc.

#### Elevation (Shadow)

- `--mat-sys-level0` through `--mat-sys-level5`

See [Angular Material docs](https://material.angular.dev/guide/system-variables) for a full list.

## Customizing Tokens

Angular Material components allow for narrowly targeted customization through the `overrides` mixins.

### System Token Overrides

Use `mat.theme-overrides` mixin to change system-level tokens:

```scss
@use "@angular/material" as mat;

html {
  color-scheme: light dark;
  @include mat.theme((
    color: mat.$violet-palette,
    typography: Roboto,
    density: 0,
  ));

  .example-orange-primary-container {
    @include mat.theme-overrides((
      primary-container: #84ffff,
    ));
  }
}
```

### Multiple System Overrides

```scss
@use "@angular/material" as mat;

.example-container {
  @include mat.theme-overrides((
    primary: #ebdcff,
    on-primary: #230f46,
    body-medium: 500 1.15rem/1.3rem Arial,
    corner-large: 32px,
    level3: 0 4px 6px 1px var(--mat-sys-surface-dim),
  ));
}
```

### Component Token Overrides

Each Angular Material component defines an `overrides` mixin for customizing tokenized styles:

```scss
html {
  @include mat.card-overrides((
    elevated-container-color: red,
    elevated-container-shape: 32px,
    title-text-size: 2rem,
  ));
}
```

### When to Use Which Mixin

| Mixin                       | Use Case                                                                    | Ideal Usage Count                          |
| --------------------------- | --------------------------------------------------------------------------- | ------------------------------------------ |
| `mat.theme`                 | Theme for application                                                       | 1                                          |
| `mat.theme-overrides`       | Change system-level tokens (e.g., success theme with green color)          | Equals to contextual themes in application |
| `mat.<COMPONENT>-overrides` | Change component-level tokens (e.g., emphasis button colors for new feature) | As and when needed                         |

## Typography Binding to HTML Elements

By default, Angular Material doesn't bind typescale levels to HTML elements, but here are recommended bindings:

| Typescale Level | Size     | Native Element |
| --------------- | -------- | -------------- |
| `display`       | `large`  | `<h1>`         |
| `display`       | `medium` | `<h2>`         |
| `display`       | `small`  | `<h3>`         |
| `headline`      | `large`  | `<h4>`         |
| `headline`      | `medium` | `<h5>`         |
| `headline`      | `small`  | `<h6>`         |

## Best Practices Summary

1. **Always use `mat.theme` mixin** for theme configuration
2. **Import components and directives**, not modules
3. **Use new button directive syntax** (`matButton`, `matIconButton`, `matFab`)
4. **Leverage system variables** for consistent styling
5. **Use override mixins** for targeted customization
6. **Prefer SCSS** for theme-related styling
7. **Include `color-scheme` property** for proper light/dark mode support
8. **Never override styles by targeting internal class names.**