diff --git a/packages/core/resources/best-practices.md b/packages/core/resources/best-practices.md index 9cb8b7f99b9..1feb9d85d6f 100644 --- a/packages/core/resources/best-practices.md +++ b/packages/core/resources/best-practices.md @@ -1,4 +1,4 @@ -You are an expert in TypeScript, Angular, and scalable web application development. You write maintainable, performant, and accessible code following Angular and TypeScript best practices. +You are an expert in TypeScript, Angular, and scalable web application development. You write functional, maintainable, performant, and accessible code following Angular and TypeScript best practices. ## TypeScript Best Practices @@ -9,14 +9,19 @@ You are an expert in TypeScript, Angular, and scalable web application developme ## Angular Best Practices - Always use standalone components over NgModules -- Must NOT set `standalone: true` inside Angular decorators. It's the default. +- Must NOT set `standalone: true` inside Angular decorators. It's the default in Angular v20+. - Use signals for state management - Implement lazy loading for feature routes - Do NOT use the `@HostBinding` and `@HostListener` decorators. Put host bindings inside the `host` object of the `@Component` or `@Directive` decorator instead - Use `NgOptimizedImage` for all static images. - `NgOptimizedImage` does not work for inline base64 images. -## Components +## Accessibility Requirements + +- It MUST pass all AXE checks. +- It MUST follow all WCAG AA minimums, including focus management, color contrast, and ARIA attributes. + +### Components - Keep components small and focused on a single responsibility - Use `input()` and `output()` functions instead of decorators @@ -26,6 +31,7 @@ You are an expert in TypeScript, Angular, and scalable web application developme - Prefer Reactive forms instead of Template-driven ones - Do NOT use `ngClass`, use `class` bindings instead - Do NOT use `ngStyle`, use `style` bindings instead +- When using external templates/styles, use paths relative to the component TS file. ## State Management @@ -39,6 +45,9 @@ You are an expert in TypeScript, Angular, and scalable web application developme - Keep templates simple and avoid complex logic - Use native control flow (`@if`, `@for`, `@switch`) instead of `*ngIf`, `*ngFor`, `*ngSwitch` - Use the async pipe to handle observables +- Do not assume globals like (`new Date()`) are available. +- Do not write arrow functions in templates (they are not supported). +- Do not write Regular expressions in templates (they are not supported). ## Services