Directive selectors follow the ng* prefix shown in each Aria guide page (https://angular.dev/guide/aria/toolbar etc.); check the specific page for the pattern you use.
Material specifics
Dialogs: inject(MatDialog).open(EditOrderDialog, { data }) with a typed result; inside, inject(MatDialogRef<EditOrderDialog, Result>) and inject(MAT_DIALOG_DATA). Focus is restored automatically on close.
Never style Material internals with ::ng-deep or ViewEncapsulation.None; use the component's CSS custom properties / M3 token overrides.
Material's own animations no longer require provideAnimations()/provideAnimationsAsync() in current versions; do not add @angular/animations for Material. (Check the Material version notes if a component still asks for it.)
Styling
Component styles are scoped by default (emulated encapsulation); :host for the root, :host-context() sparingly, CSS custom properties for theming across the boundary.
Layout with CSS grid/flex and logical properties (margin-inline, padding-block) so RTL works.
Respect prefers-reduced-motion and prefers-color-scheme in global styles; expose design tokens as custom properties on :root.
Bind classes and styles directly ([class.x], [style.--token]); ngClass/ngStyle are legacy (schematics remove them).
Animation (no @angular/animations)
@angular/animations is deprecated; provideNoopAnimations has "intent to remove in v23". Use CSS with the built-in enter/leave bindings:
<div animate.enter="fade-in" animate.leave="fade-out">…</div>
<div [animate.enter]="enterClass()">…</div>
<div (animate.leave)="onLeave($event)">…</div> <!-- hand off to a JS library; call $event.animationComplete() when done -->
State transitions (open/closed) are class toggles plus CSS transition. Migration of existing trigger()/transition() code: angular-migration → references/animations-to-css.md.
Images
NgOptimizedImage (@angular/common): <img ngSrc="hero.jpg" width="1200" height="600" priority> for the LCP image, fill for container-sized images, sizes + automatic srcset for responsive images, placeholder with a loader. Configure a CDN loader once: provideImgixLoader('https://…'), provideCloudinaryLoader, provideImageKitLoader, provideNetlifyLoader, or a custom IMAGE_LOADER.
Accessibility
Semantic elements first: <button> for actions, <a href> for navigation, native inputs with <label for>; icon-only controls get aria-label.
Focus: move focus to the dialog on open, back to the trigger on close (Material/Aria do this), to the heading on route change, to the error summary on failed submit; LiveAnnouncer or role="status" for async results.
Colour contrast 4.5:1 for text, 3:1 for large text and UI components (WCAG 2.2 AA); touch targets ≥ 24×24 CSS px.
Enable @angular-eslint/template accessibility rules in CI; run axe in component or Playwright tests (@axe-core/playwright).
Security in templates
Angular sanitises bindings by context (HTML, style, URL, resource URL). Never build templates from user input, never call bypassSecurityTrust* on user-controlled values, and prefer rendering Markdown through a sanitising renderer over [innerHTML]. For CSP use nonces (ngCspNonce attribute or the CSP_NONCE token) and Trusted Types policies angular and angular#bundler (add angular#unsafe-bypass only if you bypass sanitisation). Full rules: the frontend-security instructions file in this catalog.
i18n
Build-time: @angular/localize — i18n attributes in templates, $localize in code, one build per locale, ng extract-i18n.
Runtime switching or translator-friendly JSON: Transloco. Decide once per app (angular-architecture); never hardcode user-facing strings either way.
Hydrated SSR apps with @angular/localize need provideClientHydration(withI18nSupport()).
# UI libraries, styling, animation, accessibility and i18n
Verified 2026-09 against https://angular.dev/guide/aria/overview, https://angular.dev/guide/animations, https://angular.dev/guide/legacy-animations, https://angular.dev/guide/image-optimization, https://angular.dev/best-practices/security, https://material.angular.dev.
## Choosing the UI layer
| Need | Pick | Notes |
|---|---|---|
| Ready-styled components, Material Design look | Angular Material | Import per component (`MatButtonModule`, `MatTableModule`…) into the standalone `imports`; theme with M3 tokens (`mat.theme(...)` in `styles.scss`) |
| Behaviour primitives (overlay, drag-drop, virtual scroll, focus trap, breakpoints) | Angular CDK | `Overlay`, `A11yModule` (`cdkTrapFocus`, `LiveAnnouncer`), `DragDropModule`, `ScrollingModule`, `BreakpointObserver` → `toSignal` |
| Bespoke design system with your own CSS | Angular Aria (`@angular/aria`, stable v22) | Headless, accessible directives: Combobox, Listbox, Select, Multiselect, Autocomplete, Menu, Menubar, Toolbar, Accordion, Tabs, Tree, Grid — keyboard, ARIA and focus handled for you, no styles |
| Data-heavy enterprise grids | Material table + CDK virtual scroll, or a commercial grid | Evaluate bundle size and a11y before adopting |
### Angular Aria example
```ts
import { Toolbar, ToolbarWidget, ToolbarWidgetGroup } from '@angular/aria/toolbar';
@Component({
selector: 'app-editor-toolbar',
imports: [Toolbar, ToolbarWidget, ToolbarWidgetGroup],
template: `
<div ngToolbar aria-label="Formatting">
<div ngToolbarWidgetGroup>
<button ngToolbarWidget (click)="bold()">Bold</button>
<button ngToolbarWidget (click)="italic()">Italic</button>
</div>
</div>`,
})
export class EditorToolbar { /* … */ }
```
Directive selectors follow the `ng*` prefix shown in each Aria guide page (https://angular.dev/guide/aria/toolbar etc.); check the specific page for the pattern you use.
## Material specifics
- Dialogs: `inject(MatDialog).open(EditOrderDialog, { data })` with a typed result; inside, `inject(MatDialogRef<EditOrderDialog, Result>)` and `inject(MAT_DIALOG_DATA)`. Focus is restored automatically on close.
- Never style Material internals with `::ng-deep` or `ViewEncapsulation.None`; use the component's CSS custom properties / M3 token overrides.
- Material's own animations no longer require `provideAnimations()`/`provideAnimationsAsync()` in current versions; do not add `@angular/animations` for Material. (Check the Material version notes if a component still asks for it.)
## Styling
- Component styles are scoped by default (emulated encapsulation); `:host` for the root, `:host-context()` sparingly, CSS custom properties for theming across the boundary.
- Layout with CSS grid/flex and logical properties (`margin-inline`, `padding-block`) so RTL works.
- Respect `prefers-reduced-motion` and `prefers-color-scheme` in global styles; expose design tokens as custom properties on `:root`.
- Bind classes and styles directly (`[class.x]`, `[style.--token]`); `ngClass`/`ngStyle` are legacy (schematics remove them).
## Animation (no `@angular/animations`)
`@angular/animations` is deprecated; `provideNoopAnimations` has "intent to remove in v23". Use CSS with the built-in enter/leave bindings:
```html
<div animate.enter="fade-in" animate.leave="fade-out">…</div>
<div [animate.enter]="enterClass()">…</div>
<div (animate.leave)="onLeave($event)">…</div> <!-- hand off to a JS library; call $event.animationComplete() when done -->
```
```css
.fade-in { animation: fade 200ms ease-out; }
.fade-out { animation: fade 150ms ease-in reverse; }
@keyframes fade { from { opacity: 0; transform: translateY(4px); } to { opacity: 1; transform: none; } }
@media (prefers-reduced-motion: reduce) { .fade-in, .fade-out { animation: none; } }
```
State transitions (open/closed) are class toggles plus CSS `transition`. Migration of existing `trigger()`/`transition()` code: `angular-migration` → `references/animations-to-css.md`.
## Images
`NgOptimizedImage` (`@angular/common`): `<img ngSrc="hero.jpg" width="1200" height="600" priority>` for the LCP image, `fill` for container-sized images, `sizes` + automatic `srcset` for responsive images, `placeholder` with a loader. Configure a CDN loader once: `provideImgixLoader('https://…')`, `provideCloudinaryLoader`, `provideImageKitLoader`, `provideNetlifyLoader`, or a custom `IMAGE_LOADER`.
## Accessibility
- Semantic elements first: `<button>` for actions, `<a href>` for navigation, native inputs with `<label for>`; icon-only controls get `aria-label`.
- Focus: move focus to the dialog on open, back to the trigger on close (Material/Aria do this), to the heading on route change, to the error summary on failed submit; `LiveAnnouncer` or `role="status"` for async results.
- Colour contrast 4.5:1 for text, 3:1 for large text and UI components (WCAG 2.2 AA); touch targets ≥ 24×24 CSS px.
- Enable `@angular-eslint/template` accessibility rules in CI; run axe in component or Playwright tests (`@axe-core/playwright`).
## Security in templates
Angular sanitises bindings by context (HTML, style, URL, resource URL). Never build templates from user input, never call `bypassSecurityTrust*` on user-controlled values, and prefer rendering Markdown through a sanitising renderer over `[innerHTML]`. For CSP use nonces (`ngCspNonce` attribute or the `CSP_NONCE` token) and Trusted Types policies `angular` and `angular#bundler` (add `angular#unsafe-bypass` only if you bypass sanitisation). Full rules: the frontend-security instructions file in this catalog.
## i18n
- Build-time: `@angular/localize` — `i18n` attributes in templates, `$localize` in code, one build per locale, `ng extract-i18n`.
- Runtime switching or translator-friendly JSON: Transloco. Decide once per app (`angular-architecture`); never hardcode user-facing strings either way.
- Hydrated SSR apps with `@angular/localize` need `provideClientHydration(withI18nSupport())`.