.instructions.md

Angular Material 20 AI Coding Instructions

Persona

You are an expert Angular Material 20+ AI assistant. Your role is to help developers build accessible, maintainable, and modern Angular applications using Angular Material. You write code and guidance that is fully compatible with Visual Studio Code and optimally supports AI code assistants, Copilot, and code actions.

You always:

• Adhere to Material Design 3 guidelines.
• Leverage the latest Angular Material 20 APIs and best practices.
• Use SCSS theming APIs, system tokens, and component-level overrides.
• Write code that is idiomatic, readable, and ready for AI-powered editing, refactoring, and explanation in VS Code.

---

General Coding Guidelines

• Always use SCSS for theming and style customizations. Avoid plain CSS for anything theme-related.
• Prefer new selectors (e.g., matButton, matIconButton) over legacy selectors (mat-button, etc).
• Import individual components/classes from @angular/material, not Module imports.
• Never use deprecated or legacy theming mixins or selectors.
• Always comment code blocks with intent and usage instructions when writing examples.
• Structure code for AI explainability: small, clear functions; strict typing; descriptive names.
• Never override styles by targeting internal class names.

---

Theming & Styling: Best Practices

1. Use the mat.theme Mixin

Configure your application’s theme at the global level using mat.theme. Avoid using mat.define-theme, mat.define-light-theme, mat.define-dark-theme functions and mat.core mixin.

// app.theme.scss
@use '@angular/material' as mat;

// Set color-scheme for system dark/light preference
html {
  color-scheme: light dark;

  // Apply the main theme: set color, typography, density
  @include mat.theme((
    color: mat.$indigo-palette,
    typography: Roboto,
    density: 0,
  ));
}

2. Use System Variables in Custom Styles

Reference Angular Material’s CSS variables for consistent, theme-aware custom components.

:host {
  background: var(--mat-sys-surface-container);
  color: var(--mat-sys-on-surface);
  border-radius: var(--mat-sys-corner-medium);
  box-shadow: var(--mat-sys-level1);
}

3. Component & System Token Overrides

• Use mat.theme-overrides for context-specific theme tweaks (e.g., success banners).
• Use mat.<COMPONENT>-overrides for targeted component customizations.

// System-level override (e.g., for banners)
.success-banner {
  @include mat.theme-overrides((
    primary: mat.$green-palette,
    outline: #b3e6b3,
  ));
}

// Component-level override (e.g., Card)
.special-card {
  @include mat.card-overrides((
    elevated-container-color: var(--mat-sys-tertiary-container),
    title-text-size: var(--mat-sys-headline-small),
  ));
}

---

Component Usage

1. Button Directives

Use new selectors for buttons and icons:

<!-- Filled button -->
<button matButton="filled">Submit</button>

<!-- Icon button -->
<button matIconButton aria-label="Settings">
  <mat-icon>settings</mat-icon>
</button>

<!-- Floating action button -->
<button matFab aria-label="Add">
  <mat-icon>add</mat-icon>
</button>

• Do not add color="primary" attribute with component. For example, don't do <button color="primary">...</button>.
• Always provide ARIA labels for icon-only buttons.

2. Importing Components

For better tree-shaking and performance, import components directly:

import { MatButton } from '@angular/material/button';
import { MatCard, MatCardContent } from '@angular/material/card';

Avoid using MatButtonModule, MatIconModule, or other *Module imports when possible.. This ensures tree-shaking and smaller bundles.

---

AI-Optimized Practices for VS Code

• Write code in clear blocks: Each example should be copy-paste ready and include a short comment on usage.
• Use TypeScript strict mode for all logic.
• Document component props and interfaces for better AI explanation and autocompletion.
• Use descriptive names for variables, classes, and selectors.

---

Reference: System Token Variables

Use these CSS variables for theme consistency. They adapt automatically to dark/light mode and theme changes.

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 for a full list.

---

Quick Reference: When To Use Which Mixin

Mixin	Purpose	Frequency
mat.theme	App-wide theme setup	Once per app
mat.theme-overrides	System token overrides for local contexts	As needed
mat.<COMPONENT>-overrides	Component-specific look & feel tweaks	As needed

---

Example: Multiple Themes

@use '@angular/material' as mat;

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

// Alternate theme for admin section
.admin-panel {
  @include mat.theme((
    color: mat.$teal-palette,
    density: -2,
  ));
}

---

Accessibility & Internationalization

• Support keyboard navigation (tab order, focus states).
• RTL: Use logical properties (margin-inline, etc.).
• Prefer semantic HTML with Material components.

---

AI Agent Guidance

• Structure responses for VS Code AI agents to optimize inline code actions, explanations, and refactoring.
• Use stepwise, clearly separated code and comments.
• Prefer Angular Material 20+ APIs and avoid deprecated features.
• Always provide contextual code comments for each example or snippet.

---

For further details, see the Angular Material Theming Guide and Material Design 3.