Imported from yatin-rai/ui-ux-consultant-skill (src/ui-ux-consultant/SKILL.md). Install upstream with npx skills add yatin-rai/ui-ux-consultant-skill --skill ui-ux-consultant. Copyright stays with the author.

Framework Router

Detect the framework from context, then read the matching reference:

For Angular requests: Continue reading this SKILL.md — all Angular content is below. For other frameworks: Read the matching stack file above, then return here for universal UX rules if needed.

Design Catalog

Use these when the user needs aesthetic direction, color, typography, or product-type guidance:

Angular UI/UX Design Intelligence

Angular-specific design guidance for building production-quality UIs. All examples use Angular 17+ standalone component syntax with signals-first patterns.

Section 1: Decision Tree — What Are You Building?

These routes apply to Angular projects. For other frameworks see the Framework Router above.

Use this routing guide to load the right reference file before implementing:

When in doubt: start with references/components.md, then references/patterns.md.

Section 2: Design Philosophy

Component-First Architecture

Angular's core mental model is composition of focused, testable components with clear input() / output() signal contracts. Good UI design in Angular means good component decomposition — each component should own a single visual responsibility and surface its API through typed signal inputs. Avoid "god components" that manage multiple concerns (e.g., a dashboard that owns its own HTTP calls, layout, and child state simultaneously). Aim for components under 200 lines of template and under 100 lines of class. When a template grows beyond two levels of conditional nesting, extract the inner content into a sub-component.

Angular Material 3 as Default

Angular Material is the default recommendation for virtually all Angular UIs. It is the only Angular component library that is officially maintained by the Angular team, ships with full Material Design 3 spec compliance, and has first-class accessibility built in. Deviations — choosing NG-ZORRO for data-dense enterprise UIs, PrimeNG for e-commerce richness, or a fully custom system — require a deliberate justification. When in doubt, use Material. When the design spec calls for something Material cannot do, layer CDK primitives underneath your own components rather than pulling in a second library.

Signals-First Reactive UI (Angular 17+)

signal(), computed(), and effect() replace most subscribe() patterns for local UI state. RxJS remains essential for async data pipelines (HTTP, WebSockets, complex event merging) but should terminate at the component boundary via toSignal(). Never expose Observable subscriptions that outlive component teardown — use takeUntilDestroyed() if you must subscribe manually, or prefer toSignal() which handles teardown automatically. Template control flow (@if, @for, @switch, @defer) replaces *ngIf, *ngFor, *ngSwitch structural directives and is more readable and slightly more efficient.

OnPush by Default

Every new component should be created with changeDetection: ChangeDetectionStrategy.OnPush. Combined with signals, this eliminates virtually all unnecessary re-renders. Zone.js-based default change detection (the pre-17 default) runs on every async event in the entire application — a click handler, a setTimeout, an HTTP response. OnPush narrows updates to when inputs change or signals emit. This is not a micro-optimization; at scale it is the difference between a snappy UI and a laggy one. Set OnPush at component creation time — retrofitting it later is painful and error-prone.

Standalone Components and Lazy Loading

Angular 17+ defaults to standalone components (standalone: true is now implicit). No NgModules means the imports array on each component is its explicit dependency list — this is a design asset, not boilerplate. It makes lazy-loaded routes trivial (loadComponent: () => import('./page').then(m => m.PageComponent)), keeps bundle splitting automatic, and keeps the mental model simple. Never reintroduce NgModules unless integrating a library that still requires them.

Performance as UX

@defer blocks, NgOptimizedImage, and route-level code splitting are UX decisions as much as engineering ones. A dashboard that defers its chart section until it enters the viewport delivers perceived performance that no visual design trick can replicate. NgOptimizedImage automatically generates srcset, enforces width/height to prevent layout shift, and lazy-loads non-priority images. SSR hydration (Angular Universal / provideClientHydration()) is the right choice for any content-heavy or SEO-sensitive page. These are design choices that should be made in the planning phase, not retrofitted.

Section 3: Top 20 Angular Material 3 Components

Section 4: Angular-Specific UX Anti-Patterns

Rule 1: Don't nest @if more than 2 levels deep

DON'T:

@if (user()) {
  @if (user()!.isAdmin) {
    @if (user()!.permissions.includes('edit')) {
      <button>Edit</button>
    }
  }
}

DO: Extract a canEdit = computed(() => ...) signal and use it in a single @if, or extract the inner content to a sub-component that receives the resolved data as an input.

Rule 2: Don't subscribe() in the component body without cleanup

DON'T:

ngOnInit() {
  this.userService.getUser().subscribe(u => this.user = u); // memory leak
}

DO: Use toSignal() for simple cases, or takeUntilDestroyed() for complex pipelines:

readonly user = toSignal(this.userService.getUser());
// OR, when you need the Observable pipeline:
private destroyRef = inject(DestroyRef);
ngOnInit() {
  this.userService.getUser()
    .pipe(takeUntilDestroyed(this.destroyRef))
    .subscribe(u => this.user.set(u));
}

Rule 3: Don't use ViewChild to read state

DON'T:

@ViewChild('myInput') inputRef!: ElementRef;
getInputValue() { return this.inputRef.nativeElement.value; }

DO: Bind to a FormControl or signal() — let Angular own the state, not the DOM:

readonly inputValue = signal('');
// In template: <input [value]="inputValue()" (input)="inputValue.set($event.target.value)" />
// Or with reactive forms: this.form.controls.field.value

Rule 4: Don't use default (Zone.js) change detection for new components

DON'T:

@Component({ selector: 'app-card', ... })
export class CardComponent { ... }  // defaults to CheckAlways

DO:

@Component({
  selector: 'app-card',
  changeDetection: ChangeDetectionStrategy.OnPush,
  ...
})
export class CardComponent { ... }

Rule 5: Don't use inline styles for theming

DON'T:

<button mat-flat-button style="background-color: #2563EB; color: white;">Save</button>

DO: Use Angular Material's CSS custom properties or the theming API:

// In component SCSS:
:host {
  --mat-filled-button-container-color: var(--primary-brand);
}
// Or override globally in styles.scss:
html {
  --mat-toolbar-container-background-color: #1e293b;
}

Rule 6: Don't block routing with synchronous guards

DON'T:

canActivate(): boolean {
  return this.authService.isLoggedIn; // sync property read — fragile
}

DO: Use functional guards with async resolution:

export const authGuard = () => {
  const auth = inject(AuthService);
  const router = inject(Router);
  return auth.isAuthenticated$.pipe(
    take(1),
    map(ok => ok ? true : router.createUrlTree(['/login']))
  );
};

Rule 7: Don't omit track in @for with mutable lists

DON'T:

@for (item of items()) {
  <app-item [item]="item" />
}

DO:

@for (item of items(); track item.id) {
  <app-item [item]="item" />
}

Without track, Angular destroys and recreates DOM nodes on every list mutation, causing flicker and destroying component state (form values, animation state, focus).

Rule 8: Don't use ::ng-deep for component styling

DON'T:

::ng-deep .mat-mdc-form-field-subscript-wrapper { display: none; }

DO: Use Angular Material's CSS custom properties, the MAT_FORM_FIELD_DEFAULT_OPTIONS injection token, or wrap the component in a host element with a class and target that:

// styles.scss — globally, intentionally:
html {
  --mat-form-field-subscript-overflow: hidden;
}
// Or in component SCSS with a host selector:
:host {
  --mat-form-field-container-height: 48px;
}

::ng-deep is deprecated and will be removed. It also breaks style encapsulation silently.

Section 5: Style Recommendations by App Category

Section 6: Angular Material 3 Color Palettes

These palettes are starting points for mat.define-theme(). Use the mat.$*-palette named palettes or supply a custom tonal palette with mat.define-palette().

Section 7: Angular Material 3 Theming Quick Reference

Core Theming API

// styles.scss
@use '@angular/material' as mat;

// Include core styles once (resets, tokens)
@include mat.core();

// Define the theme
$theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: mat.$azure-palette,      // M3 tonal palette
    tertiary: mat.$orange-palette,    // Accent/CTA color role
  ),
  typography: (
    brand-family: 'Inter, system-ui, sans-serif',
    plain-family: 'Inter, system-ui, sans-serif',
    bold-weight: 700,
    medium-weight: 500,
    regular-weight: 400,
  ),
  density: (
    scale: 0,   // 0 = default, -1 = compact, -2 = very compact
  ),
));

// Apply to root
html {
  @include mat.all-component-themes($theme);
  // Or selectively:
  // @include mat.button-theme($theme);
  // @include mat.form-field-theme($theme);
}

// Dark mode via class toggle
.dark-theme {
  $dark-theme: mat.define-theme((
    color: (
      theme-type: dark,
      primary: mat.$azure-palette,
      tertiary: mat.$orange-palette,
    ),
  ));
  @include mat.all-component-colors($dark-theme);
}

Available Named M3 Palettes

mat.$red-palette, mat.$pink-palette, mat.$purple-palette, mat.$violet-palette, mat.$indigo-palette, mat.$blue-palette, mat.$azure-palette, mat.$cyan-palette, mat.$teal-palette, mat.$green-palette, mat.$olive-palette, mat.$yellow-palette, mat.$orange-palette, mat.$brown-palette, mat.$rose-palette, mat.$chartreuse-palette

CSS Custom Property Overrides

Use --mat-* properties for targeted overrides without re-defining the full theme:

html {
  // Toolbar
  --mat-toolbar-container-background-color: #1e293b;
  --mat-toolbar-container-text-color: #f8fafc;

  // Buttons
  --mat-filled-button-container-color: #2563eb;
  --mat-filled-button-label-text-color: #ffffff;

  // Cards
  --mat-card-elevated-container-color: #ffffff;
  --mat-card-elevated-container-elevation: 0 1px 3px rgba(0,0,0,0.1);

  // Form fields
  --mat-form-field-container-height: 52px;

  // Sidenav
  --mat-sidenav-container-width: 260px;
}

Angular Material Typography Scale (M3)

$theme: mat.define-theme((
  typography: (
    brand-family: 'Geist, Inter, sans-serif',
    plain-family: 'Geist, Inter, sans-serif',
    // M3 type scale roles: display-large → label-small
    // Override individual roles:
  ),
));

Reference type roles: display-large, display-medium, display-small, headline-large, headline-medium, headline-small, title-large, title-medium, title-small, body-large, body-medium, body-small, label-large, label-medium, label-small

Section 8: Signals-First UI Patterns

Local UI State

import { Component, signal, computed, ChangeDetectionStrategy } from '@angular/core';

@Component({
  selector: 'app-counter',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <p>Count: {{ count() }} — Doubled: {{ doubled() }}</p>
    <button mat-stroked-button (click)="increment()">+1</button>
    <button mat-stroked-button (click)="reset()">Reset</button>
  `,
})
export class CounterComponent {
  readonly count = signal(0);
  readonly doubled = computed(() => this.count() * 2);

  increment() { this.count.update(n => n + 1); }
  reset() { this.count.set(0); }
}

Async Loading State Pattern

import { Component, signal, inject, ChangeDetectionStrategy } from '@angular/core';
import { ItemService } from './item.service';

interface Item { id: number; name: string; }

@Component({
  selector: 'app-item-list',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    @if (loading()) {
      <mat-progress-bar mode="indeterminate" />
    } @else if (error()) {
      <p class="error">{{ error() }}</p>
      <button mat-button (click)="load()">Retry</button>
    } @else {
      @for (item of data(); track item.id) {
        <app-item-card [item]="item" />
      } @empty {
        <p class="empty-state">No items found.</p>
      }
    }
  `,
})
export class ItemListComponent {
  private service = inject(ItemService);

  readonly loading = signal(false);
  readonly error = signal<string | null>(null);
  readonly data = signal<Item[]>([]);

  async load() {
    this.loading.set(true);
    this.error.set(null);
    try {
      this.data.set(await this.service.getItems());
    } catch (e) {
      this.error.set('Failed to load items. Please try again.');
    } finally {
      this.loading.set(false);
    }
  }
}

Converting Observable to Signal (toSignal)

import { toSignal } from '@angular/core/rxjs-interop';
import { inject } from '@angular/core';

@Component({ ... })
export class UserComponent {
  private userService = inject(UserService);

  // Automatically subscribes and unsubscribes; initial value is undefined
  readonly user = toSignal(this.userService.currentUser$);

  // With initial value to avoid undefined checks:
  readonly items = toSignal(this.itemService.items$, { initialValue: [] as Item[] });
}

Optimistic UI Updates

async toggleItem(item: Item) {
  const previous = this.items(); // snapshot for rollback

  // Immediately update UI
  this.items.update(list =>
    list.map(i => i.id === item.id ? { ...i, done: !i.done } : i)
  );

  try {
    await this.api.toggleItem(item.id);
  } catch {
    // Rollback on failure
    this.items.set(previous);
    this.snackBar.open('Update failed — changes reverted', 'Dismiss', { duration: 4000 });
  }
}

Derived State with computed()

readonly searchQuery = signal('');
readonly allItems = signal<Item[]>([]);
readonly statusFilter = signal<'all' | 'active' | 'done'>('all');

readonly filteredItems = computed(() => {
  const q = this.searchQuery().toLowerCase();
  const status = this.statusFilter();
  return this.allItems()
    .filter(item => !q || item.name.toLowerCase().includes(q))
    .filter(item => status === 'all' || (status === 'done' ? item.done : !item.done));
});

readonly resultCount = computed(() => this.filteredItems().length);

Input Signals (Angular 17.1+)

import { input, output, model } from '@angular/core';

@Component({ selector: 'app-item-card', ... })
export class ItemCardComponent {
  // Required input — type-safe, signal-based
  readonly item = input.required<Item>();

  // Optional input with default
  readonly variant = input<'compact' | 'full'>('full');

  // Two-way binding (model signal)
  readonly selected = model(false);

  // Output
  readonly deleted = output<Item>();

  delete() { this.deleted.emit(this.item()); }
}

// Usage:
// <app-item-card [item]="item" [(selected)]="isSelected" (deleted)="onDelete($event)" />

Section 9: Angular Form UX

Typed Reactive Forms

import { Component, ChangeDetectionStrategy } from '@angular/core';
import { FormGroup, FormControl, Validators, ReactiveFormsModule } from '@angular/forms';
import { MatFormFieldModule } from '@angular/material/form-field';
import { MatInputModule } from '@angular/material/input';
import { MatButtonModule } from '@angular/material/button';

interface SignupForm {
  email: FormControl<string>;
  password: FormControl<string>;
  displayName: FormControl<string>;
}

@Component({
  selector: 'app-signup-form',
  standalone: true,
  imports: [ReactiveFormsModule, MatFormFieldModule, MatInputModule, MatButtonModule],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <form [formGroup]="form" (ngSubmit)="submit()">
      <mat-form-field appearance="outline">
        <mat-label>Email</mat-label>
        <input matInput [formControl]="form.controls.email" type="email" autocomplete="email" />
        <mat-error>{{ emailError }}</mat-error>
      </mat-form-field>

      <mat-form-field appearance="outline">
        <mat-label>Password</mat-label>
        <input matInput [formControl]="form.controls.password" type="password" />
        <mat-hint>At least 8 characters</mat-hint>
        <mat-error>{{ passwordError }}</mat-error>
      </mat-form-field>

      <mat-form-field appearance="outline">
        <mat-label>Display Name</mat-label>
        <input matInput [formControl]="form.controls.displayName" autocomplete="name" />
        <mat-error *ngIf="form.controls.displayName.hasError('required')">
          Name is required
        </mat-error>
      </mat-form-field>

      <button mat-flat-button type="submit" [disabled]="form.invalid || submitting()">
        @if (submitting()) {
          <mat-spinner diameter="20" />
        } @else {
          Create Account
        }
      </button>
    </form>
  `,
})
export class SignupFormComponent {
  submitting = signal(false);

  readonly form = new FormGroup<SignupForm>({
    email: new FormControl('', {
      nonNullable: true,
      validators: [Validators.required, Validators.email],
      updateOn: 'blur',  // Validate on blur, not on every keystroke
    }),
    password: new FormControl('', {
      nonNullable: true,
      validators: [Validators.required, Validators.minLength(8)],
      updateOn: 'blur',
    }),
    displayName: new FormControl('', {
      nonNullable: true,
      validators: [Validators.required],
      updateOn: 'blur',
    }),
  });

  get emailError(): string {
    const ctrl = this.form.controls.email;
    if (!ctrl.touched) return '';
    if (ctrl.hasError('required')) return 'Email is required';
    if (ctrl.hasError('email')) return 'Enter a valid email address';
    return '';
  }

  get passwordError(): string {
    const ctrl = this.form.controls.password;
    if (!ctrl.touched) return '';
    if (ctrl.hasError('required')) return 'Password is required';
    if (ctrl.hasError('minlength')) return 'Password must be at least 8 characters';
    return '';
  }

  async submit() {
    if (this.form.invalid) { this.form.markAllAsTouched(); return; }
    this.submitting.set(true);
    try {
      await this.authService.signup(this.form.getRawValue());
    } finally {
      this.submitting.set(false);
    }
  }
}

Form UX Rules

1. Use updateOn: 'blur' — never validate on every keystroke for non-search fields.
2. Call markAllAsTouched() on submit attempt to surface all errors at once.
3. Always show <mat-hint> for format expectations before the user types, <mat-error> after touched.
4. Disable the submit button while submitting() is true and show a spinner inside it.
5. Use nonNullable: true on FormControl to get properly typed .value (non-undefined).
6. Prefer FormGroup<T> typed form groups for type-safe .controls access.
7. For long multi-step forms, use Angular CDK Stepper (mat-stepper) and validate per-step.
8. Autocomplete attributes (autocomplete="email", autocomplete="current-password") are UX, not optional.

Search / Filter UX with Debounce

readonly searchControl = new FormControl('', { nonNullable: true });

// In constructor or ngOnInit:
this.searchControl.valueChanges.pipe(
  debounceTime(300),
  distinctUntilChanged(),
  takeUntilDestroyed(),
).subscribe(query => this.searchQuery.set(query));

Section 10: Performance Design Checklist

• OnPush on every component — set changeDetection: ChangeDetectionStrategy.OnPush at component creation
• track item.id in every @for — prevents full DOM reconstruction on list mutation
• @defer (on viewport) for below-fold sections — e.g. charts, secondary panels, comment sections
• NgOptimizedImage on all <img> tags — add priority attribute to the LCP image
• Lazy-loaded routes with loadComponent: () => import('./page').then(m => m.PageComponent)
• toSignal() instead of .subscribe() in components — automatic teardown, no leaks
• SSR-aware code — no window/document/localStorage in constructors; use afterRender() or isPlatformBrowser()
• @defer (on idle) for non-critical UI loaded after page is interactive
• provideClientHydration() in app.config.ts for SSR + hydration
• trackBy on mat-table — provide trackBy function to <mat-table [dataSource]>
• Virtual scrolling for long lists (500+ items) — use cdk-virtual-scroll-viewport
• Bundle size — check ng build --stats-json + webpack-bundle-analyzer; no library imported in root if only used in one lazy route

@defer Patterns

<!-- Defer chart section until it enters viewport -->
@defer (on viewport) {
  <app-analytics-chart [data]="chartData()" />
} @placeholder {
  <div class="chart-skeleton" style="height: 300px; background: #f1f5f9; border-radius: 8px;"></div>
} @loading (minimum 500ms) {
  <mat-progress-bar mode="indeterminate" />
} @error {
  <p>Chart failed to load.</p>
}

<!-- Defer non-critical panel until browser is idle -->
@defer (on idle) {
  <app-recommendations-panel />
}

<!-- Conditional defer — only load when user triggers it -->
@defer (on interaction(triggerEl)) {
  <app-heavy-modal />
}
<button #triggerEl mat-button>Show Details</button>

NgOptimizedImage

// In component imports:
import { NgOptimizedImage } from '@angular/common';

// In template:
// LCP image — add priority:
<img ngSrc="/hero.webp" width="1200" height="600" priority alt="Hero banner" />

// Standard lazy-loaded image:
<img ngSrc="/thumbnail.webp" width="300" height="200" alt="Product photo" />

// Dynamic from CDN with loader:
<img [ngSrc]="product.imageUrl" width="400" height="400" alt="{{ product.name }}" />

Section 11: Reference Files

These files contain expanded catalogs, code patterns, and decision matrices. Instruct Claude to read them when the task requires deeper detail:

Quick Access Prompts

When helping with a specific task, pre-load context with:

• Read references/components.md for the mat-table section — for sortable/filterable table UX
• Read references/theming.md for the dark mode section — for dark/light toggle implementation
• Read references/patterns.md for the smart/dumb split — for component decomposition guidance
• Read references/animations.md for route transitions — for page-to-page motion design
• Read references/accessibility.md for keyboard nav — for ARIA and CDK FocusTrap patterns

Quick Reference: Angular 17+ Standalone Component Template

import {
  Component,
  ChangeDetectionStrategy,
  signal,
  computed,
  input,
  output,
  inject,
} from '@angular/core';
import { MatButtonModule } from '@angular/material/button';
import { MatCardModule } from '@angular/material/card';

@Component({
  selector: 'app-my-component',
  standalone: true,
  imports: [MatButtonModule, MatCardModule],
  changeDetection: ChangeDetectionStrategy.OnPush,
  host: { class: 'app-my-component' },
  styles: `
    :host {
      display: block;
    }
  `,
  template: `
    <mat-card>
      <mat-card-header>
        <mat-card-title>{{ title() }}</mat-card-title>
      </mat-card-header>
      <mat-card-content>
        @if (loading()) {
          <mat-progress-bar mode="indeterminate" />
        } @else {
          <p>{{ content() }}</p>
        }
      </mat-card-content>
      <mat-card-actions>
        <button mat-flat-button (click)="confirm.emit()">Confirm</button>
        <button mat-button (click)="cancel.emit()">Cancel</button>
      </mat-card-actions>
    </mat-card>
  `,
})
export class MyComponent {
  // Inputs
  readonly title = input.required<string>();
  readonly content = input<string>('');

  // Outputs
  readonly confirm = output<void>();
  readonly cancel = output<void>();

  // Local state
  readonly loading = signal(false);

  // Derived state
  readonly hasContent = computed(() => this.content().length > 0);

  // Services
  private myService = inject(MyService);
}

This skill covers Angular 17+ with standalone components, signals, and Angular Material 3. For Angular 14–16 NgModule-based patterns, note that the core UX guidance remains valid but syntax differs (use ngOnDestroy + Subject for cleanup, *ngIf/*ngFor directives, and @NgModule imports arrays).