angular-material-developer
Generates Angular Material code and guidance for Angular projects using `@angular/material` with the Material 3 (M3) theming system. Covers installation, Sass-based theming via `mat.theme()` and the prebuilt palettes, density and typography customisation, component usage across all categories (form controls, buttons, overlays, layout, data display, navigation), `@angular/cdk` primitives (Overlay, Portal, Drag-Drop, Virtual Scroll, A11y), ReactiveForms / Signal Forms integration via `mat-form-field`, accessibility, and the M2 → M3 migration. Use when the user mentions Angular Material, `@angular/material`, `mat-*` components, M3 / Material 3, design tokens, OR when the Angular project's `package.json` contains `@angular/material`. Pairs with `angular-developer` for Angular fundamentals.
Mofiro Jean · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add mofirojean/angular-ui-skills --skill angular-material-developer技能说明
name: angular-material-developer
description: Generates Angular Material code and guidance for Angular projects using @angular/material with the Material 3 (M3) theming system. Covers installation, Sass-based theming via mat.theme() and the prebuilt palettes, density and typography customisation, component usage across all categories (form controls, buttons, overlays, layout, data display, navigation), @angular/cdk primitives (Overlay, Portal, Drag-Drop, Virtual Scroll, A11y), ReactiveForms / Signal Forms integration via mat-form-field, accessibility, and the M2 → M3 migration. Use when the user mentions Angular Material, @angular/material, mat-* components, M3 / Material 3, design tokens, OR when the Angular project's package.json contains @angular/material. Pairs with angular-developer for Angular fundamentals.
license: MIT
metadata:
author: Mofiro Jean
version: '0.0.1'
Angular Material Developer Guidelines
Pairs with
angular-developer, that skill provides Angular fundamentals (signals, DI, routing, forms, SSR, accessibility). This skill focuses on Angular Material specifics. Install both for the best experience.
Compatibility
- Tracks:
@angular/material@22.1.1(Angular v22), paired with@angular/cdk@22.1.1(Material peers an exact cdk version, keep the two pinned together). The v21-aligned line remains at21.2.xfor legacy projects. - Animations peer dropped (v21.2+): Material no longer declares an
@angular/animationspeer dependency and animates via native CSS.ng add @angular/materialon 21.2+/22 does not wireprovideAnimationsAsync()and does not require@angular/animations, do not add either to a fresh Material 22 app. (Earlier v21.x and all v18-20 apps still need the provider; see setup.md.) - Works for: Material v19 → v22 projects (M3 theming system landed in v19; older majors used M2 with the now-legacy
mat.define-light-theme/mat.define-dark-themeAPI). - Angular: v19 or newer required. v22 requires Node 22 or 26 and TypeScript 6. The skill assumes standalone components, control flow (
@if/@for), and signal-based APIs. - Sass: required for theming. The build pipeline must support
.scss(Angular CLI does by default). Standalone CSS-only theming is not supported by Material's theming engine. - Not supported: Material v18 and below (M2-only with
mat.define-*-theme()API), Angular v18 or below (NgModule patterns + older animations API).
v22 breaking changes (from v21)
The v21 → v22 jump has real API drift, not just an Angular version bump. Watch for:
- Combobox: legacy combobox and autocomplete promoted / removed.
SimpleComboboxpromoted toComboboxwith allsimpleCombobox*symbols renamed tocombobox*. - List:
MatListOption.checkboxPositionremoved, usetogglePositioninstead.MatListOptionCheckboxPositionrenamed toMatListOptionTogglePosition. - CDK:
injectorparameter is now required onConfigurableFocusTrapandFocusTrapconstructors.ConfigurableFocusTrapFactory.createboolean parameter replaced with a config object.DropListRef.dropevent parameter is now required.ContextMenuTrackerrenamed toMenuTracker. Removed:CDK_DESCRIBEDBY_HOST_ATTRIBUTE,CDK_DESCRIBEDBY_ID_PREFIX,MESSAGES_CONTAINER_ID. - Multiple components: input/model rename from
valuestovalueacross Combobox, Listbox, Tree, Menu, Toolbar, Select. Constructors with rest arguments removed (affects code that extends Material or CDK components). - Dialog / Overlay:
ArrowViewStateandArrowViewStateTransitiontypes removed.
Most of these have automatic ng update migrations. When in doubt, run ng update @angular/material and let the schematic do the work before hand-editing.
v22 new features worth knowing
- Signal Forms stable (was experimental in v21). Angular's signal-based form API is now safe to use in production.
mat-form-fieldcomposes with bothReactiveFormsModuleand Signal Forms. - Angular Aria stable (was preview). New accessibility primitives ship in the framework, which reduces the need to reach for CDK's a11y module for some patterns.
- Button progress indicator support inside
<button>component. - Portal directives support on
ComponentPortal. - Separate tab animation durations (per-tab enter/exit timing).
-
Check the project's Material version before answering. Material's M3 theming engine was introduced in v19 (
mat.theme()mixin replacingmat.define-light-themeandmat.define-dark-theme). Code generated against M3 will silently break on M2 projects.package.jsonis the source of truth. -
Detect the theming generation in
styles.scss:- If you see
@include mat.theme((...))→ M3 (v19+, default). Usemat.theme(), Material's prebuilt palettes, and CSS variable overrides. - If you see
mat.define-light-theme(...)ormat.define-dark-theme(...)plus@include mat.all-component-themes($theme)→ M2 (legacy). Recommend migrating, see migration.md. - The two systems compile and behave very differently. See theming.md.
- If you see
-
Components are standalone since v15. Always import the standalone class (e.g.
MatButtonfrom'@angular/material/button'), not the legacyMatButtonModule. The modules still re-export everything for backwards compatibility but should not be added to new code. -
After generating Material code, run
ng build. The most common AI mistakes are: (a) using v17-eramat.define-light-themesyntax in a v19+ project (compiles but silently emits no CSS vars); (b) forgettingprovideAnimationsAsync(), which makes ripples, menu open/close, and dialog backdrop animations no-op; (c) missing@angular/cdkpeer dep, Material imports cascade through it; (d) usingMatTablewithout aMatSort/MatPaginatorwiring up, the column header sort UI appears but d