# 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())`.
