Cursor rule

1---
2description: 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.
3alwaysApply: false
4globs: *.html,*.ts,*.scss,*.css
5---
6 
7# Angular Material 20 Best Practices
8 
9This project adheres to modern Angular Material best practices, emphasizing maintainability, performance, accessibility, scalability and correct usage of APIs.
10 
11## Core Principles
12 
13### SCSS vs CSS
14 
15- **Prefer SCSS** for styling, especially when theme customization is required. Angular Material has APIs written in SCSS.
16- **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.
17 
18### Component & Directive Imports
19 
20Always import components and directives from `@angular/material` package. Avoid importing modules.
21 
22**Good:**
23 
24```ts
25import { MatButton } from '@angular/material/button';
26import { MatIcon } from '@angular/material/icon';
27import { MatCard, MatCardContent } from '@angular/material/card';
28```
29 
30**Bad:**
31 
32```ts
33import { MatButtonModule } from '@angular/material/button';
34import { MatIconModule } from '@angular/material/icon';
35import { MatCardModule } from '@angular/material/card';
36```
37 
38## Theming Configuration
39 
40Always 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.
41 
42### Basic Theme Configuration
43 
44The `mat.theme` mixin takes a map with the following properties:
45 
46- **`color`**: Single color palette or a map of color palettes
47- **`typography`**: Single typography or a map of typography properties
48- **`density`**: Integer from 0 to -5 (0 = default spacing, -5 = most dense)
49 
50### Simple Theme Example
51 
52```scss
53@use '@angular/material' as mat;
54 
55html {
56  color-scheme: light dark;
57  @include mat.theme(
58    (
59      color: mat.$violet-palette,
60      typography: Roboto,
61      density: 0,
62    )
63  );
64}
65```
66 
67### Advanced Theme with Multiple Color Palettes
68 
69```scss
70@use '@angular/material' as mat;
71 
72html {
73  color-scheme: light dark;
74  @include mat.theme(
75    (
76      color: (
77        primary: mat.$violet-palette,
78        tertiary: mat.$orange-palette,
79      ),
80      typography: (
81        plain-family: Roboto,
82        brand-family: Open Sans,
83        bold-weight: 900,
84        medium-weight: 500,
85        regular-weight: 300,
86      ),
87      density: 0,
88    )
89  );
90}
91```
92 
93### Supporting Light and Dark Mode with Selectors
94 
95```scss
96@use '@angular/material' as mat;
97 
98html {
99  color-scheme: light;
100  @include mat.theme(
101    (
102      color: mat.$violet-palette,
103      typography: Roboto,
104      density: 0,
105    )
106  );
107}
108 
109body.dark-mode {
110  color-scheme: dark;
111}
112```
113 
114### Multiple Themes
115 
116```scss
117@use '@angular/material' as mat;
118 
119html {
120  @include mat.theme(
121    (
122      color: mat.$violet-palette,
123      typography: Roboto,
124      density: 0,
125    )
126  );
127}
128 
129.example-bright-container {
130  @include mat.theme(
131    (
132      color: mat.$cyan-palette,
133    )
134  );
135}
136```
137 
138## Button Directives
139 
140Always 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.
141 
142### Correct Button Usage
143 
144```html
145<button matButton>Basic</button>
146<button matButton="elevated">Elevated</button>
147<button matButton="outlined">Outlined</button>
148<button matButton="filled">Filled</button>
149<button matButton="tonal">Tonal</button>
150<button
151  matIconButton
152  aria-label="Example icon button with a vertical three dot icon">
153  <mat-icon>more_vert</mat-icon>
154</button>
155<button matFab aria-label="Example icon button with a delete icon">
156  <mat-icon>delete</mat-icon>
157</button>
158```
159 
160### Incorrect Button Usage (Avoid)
161 
162```html
163<button mat-button>Basic</button>
164<button mat-raised-button>Elevated</button>
165<button mat-stroked-button>Outlined</button>
166<button mat-flat-button>Filled</button>
167<button mat-icon-button aria-label="Example icon button">
168  <mat-icon>more_vert</mat-icon>
169</button>
170<button mat-fab aria-label="Example icon button">
171  <mat-icon>delete</mat-icon>
172</button>
173```
174 
175## Using Theme Styles & System Variables
176 
177The `mat.theme` mixin emits CSS variables known as "System Variables" that can be used to style components.
178 
179### Basic Usage Example
180 
181```css
182:host {
183  background: var(--mat-sys-primary-container);
184  color: var(--mat-sys-on-primary-container);
185  border: 1px solid var(--mat-sys-outline-variant);
186  font: var(--mat-sys-body-large);
187}
188```
189 
190### System Variables Reference
191 
192#### Colors
193 
194- `--mat-sys-primary`, `--mat-sys-on-primary`, `--mat-sys-primary-container`, `--mat-sys-on-primary-container`
195- `--mat-sys-secondary`, `--mat-sys-tertiary`, and their `on-` and `container` variants
196- `--mat-sys-surface`, `--mat-sys-on-surface`, `--mat-sys-surface-container`
197- `--mat-sys-error`, `--mat-sys-on-error`, `--mat-sys-error-container`
198- `--mat-sys-outline`, `--mat-sys-outline-variant`
199 
200#### Typography
201 
202- `--mat-sys-display-small`, `--mat-sys-display-medium`, `--mat-sys-display-large`
203- `--mat-sys-headline-small`, `--mat-sys-title-medium`, `--mat-sys-body-large`
204- `--mat-sys-label-medium`, etc.
205 
206#### Shape (Border Radius)
207 
208- `--mat-sys-corner-extra-small`, `--mat-sys-corner-medium`, `--mat-sys-corner-large`, etc.
209 
210#### Elevation (Shadow)
211 
212- `--mat-sys-level0` through `--mat-sys-level5`
213 
214See [Angular Material docs](https://material.angular.dev/guide/system-variables) for a full list.
215 
216## Customizing Tokens
217 
218Angular Material components allow for narrowly targeted customization through the `overrides` mixins.
219 
220### System Token Overrides
221 
222Use `mat.theme-overrides` mixin to change system-level tokens:
223 
224```scss
225@use '@angular/material' as mat;
226 
227html {
228  color-scheme: light dark;
229  @include mat.theme(
230    (
231      color: mat.$violet-palette,
232      typography: Roboto,
233      density: 0,
234    )
235  );
236 
237  .example-orange-primary-container {
238    @include mat.theme-overrides(
239      (
240        primary-container: #84ffff,
241      )
242    );
243  }
244}
245```
246 
247### Multiple System Overrides
248 
249```scss
250@use '@angular/material' as mat;
251 
252.example-container {
253  @include mat.theme-overrides(
254    (
255      primary: #ebdcff,
256      on-primary: #230f46,
257      body-medium: 500 1.15rem/1.3rem Arial,
258      corner-large: 32px,
259      level3: 0 4px 6px 1px var(--mat-sys-surface-dim),
260    )
261  );
262}
263```
264 
265### Component Token Overrides
266 
267Each Angular Material component defines an `overrides` mixin for customizing tokenized styles:
268 
269```scss
270html {
271  @include mat.card-overrides(
272    (
273      elevated-container-color: red,
274      elevated-container-shape: 32px,
275      title-text-size: 2rem,
276    )
277  );
278}
279```
280 
281### When to Use Which Mixin
282 
283| Mixin                       | Use Case                                                                     | Ideal Usage Count                          |
284| --------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------ |
285| `mat.theme`                 | Theme for application                                                        | 1                                          |
286| `mat.theme-overrides`       | Change system-level tokens (e.g., success theme with green color)            | Equals to contextual themes in application |
287| `mat.<COMPONENT>-overrides` | Change component-level tokens (e.g., emphasis button colors for new feature) | As and when needed                         |
288 
289## Typography Binding to HTML Elements
290 
291By default, Angular Material doesn't bind typescale levels to HTML elements, but here are recommended bindings:
292 
293| Typescale Level | Size     | Native Element |
294| --------------- | -------- | -------------- |
295| `display`       | `large`  | `<h1>`         |
296| `display`       | `medium` | `<h2>`         |
297| `display`       | `small`  | `<h3>`         |
298| `headline`      | `large`  | `<h4>`         |
299| `headline`      | `medium` | `<h5>`         |
300| `headline`      | `small`  | `<h6>`         |
301 
302## CSS Classes
303 
304Avoid applying CSS classes to inner components/elements of Angular Material components. If needed, wrap them in a container and apply classes to container.
305 
306For example, avoid doing this:
307 
308```html
309<button matButton class="flex items-center gap-2">
310  <mat-icon class="ml-1">add</mat-icon>
311  Add
312</button>
313```
314 
315Instead, do this:
316 
317```html
318<button matButton>
319  <mat-icon>add</mat-icon>
320  Add
321</div>
322```
323 
324## SVGs vs mat-icons
325 
326Try to use `mat-icon` for icons that are part of the Material Design icon set. For other icons, use `MatIconRegistry` to register the icon and use it in the template using `svgIcon` attribute.
327 
328```angular-ts
329import { MatIconRegistry } from '@angular/material/icon';
330import { DomSanitizer } from '@angular/platform-browser';
331 
332const ICON = `SVG Icon HTML string`;
333 
334constructor(private matIconRegistry: MatIconRegistry, private sanitizer: DomSanitizer) {
335  this.matIconRegistry.addSvgIconLiteral('custom-icon', this.sanitizer.bypassSecurityTrustHtml(ICON));
336}
337```
338 
339```angular-html
340<mat-icon svgIcon="custom-icon"></mat-icon>
341```
342 
343## Best Practices Summary
344 
3451. **Always use `mat.theme` mixin** for theme configuration
3462. **Import components and directives**, not modules
3473. **Use new button directive syntax** (`matButton`, `matIconButton`, `matFab`)
3484. **Leverage system variables** for consistent styling
3495. **Use override mixins** for targeted customization
3506. **Prefer SCSS** for theme-related styling
3517. **Include `color-scheme` property** for proper light/dark mode support
3528. **Never override styles by targeting internal class names.**
353