ui-ux-consultant-cli 1.0.0

package/assets/ui-ux-consultant/references/accessibility.md

@@ -0,0 +1,175 @@
+# Angular CDK A11y and Accessibility Patterns
+
+## Section 1: Angular CDK A11y Module
+
+```typescript
+import { A11yModule } from '@angular/cdk/a11y';
+// or individual:
+import { FocusTrap, FocusMonitor, LiveAnnouncer } from '@angular/cdk/a11y';
+```
+
+---
+
+## Section 2: Focus Management
+
+**Trap focus inside modals/dialogs:**
+```html
+<div cdkTrapFocus cdkTrapFocusAutoCapture>
+  <h2>Dialog Title</h2>
+  <button cdkFocusInitial>First focused element</button>
+  <!-- Tab cycles within this div -->
+</div>
+```
+Note: `MatDialog` handles this automatically. Use `cdkTrapFocus` for custom overlays.
+
+**FocusMonitor — detect keyboard vs mouse focus:**
+```typescript
+private focusMonitor = inject(FocusMonitor);
+private elementRef = inject(ElementRef);
+
+ngAfterViewInit() {
+  this.focusMonitor.monitor(this.elementRef, true).subscribe(origin => {
+    // origin: 'keyboard' | 'mouse' | 'touch' | 'program' | null
+    if (origin === 'keyboard') {
+      // Show visible focus indicator
+    }
+  });
+}
+```
+
+**LiveAnnouncer — announce dynamic content to screen readers:**
+```typescript
+private announcer = inject(LiveAnnouncer);
+
+async save() {
+  await this.saveData();
+  this.announcer.announce('Changes saved successfully', 'polite');
+}
+
+async delete() {
+  await this.deleteItem();
+  this.announcer.announce('Item deleted', 'assertive');  // immediate
+}
+```
+
+---
+
+## Section 3: ARIA Patterns
+
+**Current page in nav:**
+```html
+<mat-nav-list>
+  @for (link of navLinks; track link.path) {
+    <a mat-list-item [routerLink]="link.path" routerLinkActive="active"
+       [attr.aria-current]="isActive(link.path) ? 'page' : null">
+      {{ link.label }}
+    </a>
+  }
+</mat-nav-list>
+```
+
+**Loading states:**
+```html
+<div role="status" aria-live="polite" aria-label="Loading content">
+  @if (loading()) { <mat-spinner /> }
+</div>
+```
+
+**Buttons that toggle:**
+```html
+<button mat-icon-button [attr.aria-expanded]="isOpen()" [attr.aria-label]="isOpen() ? 'Collapse menu' : 'Expand menu'"
+  (click)="isOpen.update(v => !v)">
+  <mat-icon>{{ isOpen() ? 'expand_less' : 'expand_more' }}</mat-icon>
+</button>
+```
+
+**Icon buttons need labels:**
+```html
+<!-- BAD -->
+<button mat-icon-button><mat-icon>delete</mat-icon></button>
+
+<!-- GOOD -->
+<button mat-icon-button aria-label="Delete item"><mat-icon>delete</mat-icon></button>
+<!-- or: -->
+<button mat-icon-button [matTooltip]="'Delete'" [attr.aria-label]="'Delete'">
+  <mat-icon>delete</mat-icon>
+</button>
+```
+
+**Data tables:**
+```html
+<table mat-table [dataSource]="data()" aria-label="Users list">
+  <ng-container matColumnDef="name">
+    <th mat-header-cell *matHeaderCellDef scope="col">Name</th>
+    <td mat-cell *matCellDef="let row">{{ row.name }}</td>
+  </ng-container>
+</table>
+```
+
+---
+
+## Section 4: Keyboard Navigation
+
+**Skip links** (first element on page):
+```html
+<!-- app.component.html - very first element -->
+<a href="#main-content" class="skip-link">Skip to main content</a>
+<mat-sidenav-container>
+  <mat-sidenav>...</mat-sidenav>
+  <mat-sidenav-content>
+    <main id="main-content">
+      <router-outlet />
+    </main>
+  </mat-sidenav-content>
+</mat-sidenav-container>
+```
+```scss
+.skip-link {
+  position: absolute; transform: translateY(-100%);
+  &:focus { transform: translateY(0); }
+}
+```
+
+**Manage focus on route change:**
+```typescript
+constructor() {
+  inject(Router).events.pipe(
+    filter(e => e instanceof NavigationEnd),
+    takeUntilDestroyed(),
+  ).subscribe(() => {
+    // Move focus to main heading after navigation
+    const heading = document.querySelector('h1');
+    if (heading) { heading.setAttribute('tabindex', '-1'); heading.focus(); }
+  });
+}
+```
+
+---
+
+## Section 5: Color Contrast Requirements
+
+| Text Type | Minimum Contrast | Enhanced |
+|---|---|---|
+| Normal text (< 18pt) | 4.5:1 (AA) | 7:1 (AAA) |
+| Large text (≥ 18pt bold or ≥ 24pt) | 3:1 (AA) | 4.5:1 (AAA) |
+| UI components / icons | 3:1 (AA) | — |
+| Decorative elements | No requirement | — |
+
+Angular Material 3 palettes are designed to meet AA by default. Always verify when using custom colors. Use: https://webaim.org/resources/contrastchecker/
+
+---
+
+## Section 6: Accessibility Checklist
+
+| Check | Implementation |
+|---|---|
+| All icon buttons have aria-label | `[attr.aria-label]="'Action description'"` |
+| Form fields have labels | `<mat-label>` inside `<mat-form-field>` |
+| Errors are associated | `<mat-error>` auto-associates with input |
+| Images have alt text | `alt="..."` always; `alt=""` for decorative |
+| Focus is visible | Angular Material handles this; test with keyboard |
+| Skip link present | First element in app.component.html |
+| Dynamic content announced | `LiveAnnouncer` for async updates |
+| Color not sole indicator | Icons + text + pattern alongside color |
+| Reduced motion respected | CSS `prefers-reduced-motion` media query |
+| ARIA current on nav | `[attr.aria-current]="isActive ? 'page' : null"` |

package/assets/ui-ux-consultant/references/alt-libraries.md

@@ -0,0 +1,90 @@
+# Angular UI Library Decision Guide
+
+## Decision Matrix
+
+| Criteria | Angular Material | NG-ZORRO | PrimeNG | Tailwind CSS |
+|---|---|---|---|---|
+| Best for | Consumer apps, Google-style | Enterprise admin, data-heavy | Data grids, charts, reports | Custom design systems |
+| Component count | 35+ | 70+ | 90+ | 0 (utility only) |
+| Design spec | Material Design 3 | Ant Design | Custom/Fluent-ish | None |
+| Bundle size | Small | Medium | Large | Very small |
+| Theming | M3 token-based | CSS vars + Less | CSS vars + styled-components | Tailwind config |
+| Accessibility | Excellent (CDK) | Good | Good | Manual |
+| Angular version | 17+ recommended | 17+/21+ | 17+ | Any |
+| Data table | Basic mat-table | Advanced + virtual scroll | Most powerful | Manual |
+| Tree/Hierarchical | CDK tree | Yes | Yes | Manual |
+| Rich text / editors | No | No | Yes | No |
+
+---
+
+## Angular Material — When to Choose
+
+- Consumer-facing apps, PWAs, mobile-first
+- Google/Material aesthetic preferred
+- Need best-in-class accessibility (Angular CDK underpins everything)
+- Small team that wants a battle-tested system
+- SSR / hydration support is important
+- **Install:** `ng add @angular/material`
+
+---
+
+## NG-ZORRO — When to Choose
+
+- Enterprise admin dashboards with complex layouts
+- Need: advanced data tables, tree components, complex forms, rich menu systems
+- Ant Design aesthetic (enterprise-grade, clean)
+- Heavy data display requirements
+- **Install:** `ng add ng-zorro-antd`
+
+```typescript
+// app.config.ts
+import { provideNzI18n, en_US } from 'ng-zorro-antd/i18n';
+providers: [provideNzI18n(en_US)]
+```
+
+Top NG-ZORRO components beyond Angular Material: `nz-table` (virtual scroll, expandable rows), `nz-tree-select`, `nz-transfer`, `nz-cascader`, `nz-date-picker` (range picker), `nz-upload`
+
+---
+
+## PrimeNG — When to Choose
+
+- Heavy data analysis apps with charts + grids
+- Need: advanced data table (filtering, grouping, frozen columns), `p-chart` (Chart.js), `p-tree`, rich text editor
+- Large component variety needed quickly
+- **Install:** `npm install primeng`
+
+Top PrimeNG components: `p-table` (most feature-complete Angular data table), `p-chart`, `p-treeTable`, `p-fileUpload`, `p-calendar` (with time picker), `p-multiSelect`
+
+---
+
+## Tailwind CSS + Angular — When to Choose
+
+- Custom brand design system (no Material/Ant aesthetic)
+- Rapid prototyping or utility-first workflow
+- Combining with headless UI (Angular CDK primitives)
+- **Install:**
+
+```bash
+npm install tailwindcss @tailwindcss/vite
+```
+
+```typescript
+// vite.config.ts (or angular.json for build-based setup)
+import tailwindcss from '@tailwindcss/vite';
+plugins: [tailwindcss()]
+```
+
+```css
+/* styles.css */
+@import "tailwindcss";
+```
+
+Pair with Angular CDK for accessible headless components (dialogs, listboxes, etc.)
+
+---
+
+## Mixing Libraries
+
+- **Angular Material + Tailwind:** Works well. Material for complex components (dialogs, forms), Tailwind for layout and custom styling. Avoid using Tailwind on Material components (conflicts with `::ng-deep` warnings).
+- **NG-ZORRO + custom Tailwind layout:** Common pattern. NG-ZORRO components, Tailwind for page layout.
+- **Never mix Angular Material + NG-ZORRO + PrimeNG:** Bundle bloat, style conflicts, accessibility inconsistency.

package/assets/ui-ux-consultant/references/animations.md

@@ -0,0 +1,448 @@
+# Angular Animations Reference
+
+Angular Animations module guide with motion design principles.
+
+---
+
+## Section 1: Setup
+
+```typescript
+// main.ts or app.config.ts
+import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideAnimationsAsync()],
+};
+```
+
+`provideAnimationsAsync()` is preferred over `provideAnimations()` — it defers animation loading until first interaction, improving initial load performance.
+
+---
+
+## Section 2: Core Animation API
+
+### Imports
+
+```typescript
+import {
+  trigger, state, style, transition, animate,
+  keyframes, query, stagger, group, sequence,
+} from '@angular/animations';
+```
+
+### Building Blocks
+
+| Function | Purpose |
+|---|---|
+| `trigger(name, [...])` | Named animation attached to a template element |
+| `state(name, style)` | A named style state the element can be in |
+| `transition('a => b', [...])` | Animation to run when moving between two states |
+| `animate('timing', style)` | The actual tween — duration, easing, target styles |
+| `query(selector, [...])` | Target child elements within an animation |
+| `stagger(delay, [...])` | Add incremental delays to a group of animated elements |
+| `group([...])` | Run multiple animations in parallel |
+| `sequence([...])` | Run multiple animations one after another |
+| `keyframes([...])` | Define multi-step animations within a single animate() |
+
+### Timing Syntax
+
+```
+'200ms'                          — 200ms linear
+'200ms ease-out'                 — 200ms with easing
+'200ms 50ms ease-in'             — 200ms, delayed 50ms, with easing
+'200ms cubic-bezier(0.4,0,0.2,1)'  — custom cubic bezier
+```
+
+### Special Transition Aliases
+
+| Alias | Meaning |
+|---|---|
+| `:enter` | Element added to DOM (`void => *`) |
+| `:leave` | Element removed from DOM (`* => void`) |
+| `* <=> *` | Any state change in either direction |
+| `void => *` | Explicit enter (same as `:enter`) |
+| `* => void` | Explicit leave (same as `:leave`) |
+
+---
+
+## Section 3: Common Animations (Copy-Paste Ready)
+
+### Fade In/Out
+
+```typescript
+export const fadeInOut = trigger('fadeInOut', [
+  transition(':enter', [
+    style({ opacity: 0 }),
+    animate('200ms ease-in', style({ opacity: 1 })),
+  ]),
+  transition(':leave', [
+    animate('150ms ease-out', style({ opacity: 0 })),
+  ]),
+]);
+```
+
+### Slide In from Right
+
+```typescript
+export const slideInRight = trigger('slideInRight', [
+  transition(':enter', [
+    style({ transform: 'translateX(100%)', opacity: 0 }),
+    animate('250ms cubic-bezier(0.4, 0, 0.2, 1)', style({ transform: 'translateX(0)', opacity: 1 })),
+  ]),
+  transition(':leave', [
+    animate('200ms cubic-bezier(0.4, 0, 0.6, 1)', style({ transform: 'translateX(100%)', opacity: 0 })),
+  ]),
+]);
+```
+
+### Slide In from Bottom
+
+```typescript
+export const slideInBottom = trigger('slideInBottom', [
+  transition(':enter', [
+    style({ transform: 'translateY(24px)', opacity: 0 }),
+    animate('250ms cubic-bezier(0.4, 0, 0.2, 1)', style({ transform: 'translateY(0)', opacity: 1 })),
+  ]),
+  transition(':leave', [
+    animate('200ms cubic-bezier(0.4, 0, 0.6, 1)', style({ transform: 'translateY(24px)', opacity: 0 })),
+  ]),
+]);
+```
+
+### Expand/Collapse (Accordion)
+
+```typescript
+export const expandCollapse = trigger('expandCollapse', [
+  state('collapsed', style({ height: '0', overflow: 'hidden', opacity: 0 })),
+  state('expanded', style({ height: '*', overflow: 'hidden', opacity: 1 })),
+  transition('collapsed <=> expanded', animate('250ms cubic-bezier(0.4, 0, 0.2, 1)')),
+]);
+```
+
+Usage in template:
+```html
+<div [@expandCollapse]="isExpanded() ? 'expanded' : 'collapsed'">
+  <ng-content />
+</div>
+```
+
+### Scale In (for cards, modals, popovers)
+
+```typescript
+export const scaleIn = trigger('scaleIn', [
+  transition(':enter', [
+    style({ transform: 'scale(0.95)', opacity: 0 }),
+    animate('200ms cubic-bezier(0.4, 0, 0.2, 1)', style({ transform: 'scale(1)', opacity: 1 })),
+  ]),
+  transition(':leave', [
+    animate('150ms cubic-bezier(0.4, 0, 0.6, 1)', style({ transform: 'scale(0.95)', opacity: 0 })),
+  ]),
+]);
+```
+
+### List Stagger (animate items entering a list)
+
+```typescript
+export const listStagger = trigger('listStagger', [
+  transition('* => *', [
+    query(':enter', [
+      style({ opacity: 0, transform: 'translateY(-8px)' }),
+      stagger(60, [
+        animate('200ms ease-out', style({ opacity: 1, transform: 'translateY(0)' })),
+      ]),
+    ], { optional: true }),
+  ]),
+]);
+```
+
+Usage:
+```html
+<!-- Apply trigger to the container, not individual items -->
+<ul [@listStagger]="items().length">
+  @for (item of items(); track item.id) {
+    <li>{{ item.name }}</li>
+  }
+</ul>
+```
+
+### Route Transition
+
+```typescript
+export const routeTransition = trigger('routeTransition', [
+  transition('* <=> *', [
+    query(':enter', [style({ opacity: 0, transform: 'translateY(8px)' })], { optional: true }),
+    query(':leave', [animate('150ms ease-in', style({ opacity: 0 }))], { optional: true }),
+    query(':enter', [animate('200ms 50ms ease-out', style({ opacity: 1, transform: 'translateY(0)' }))], { optional: true }),
+  ]),
+]);
+```
+
+App component setup:
+```typescript
+// app.component.ts
+getRouteAnimationData(outlet: RouterOutlet) {
+  return outlet?.activatedRouteData?.['animation'];
+}
+```
+
+```html
+<!-- app.component.html -->
+<div [@routeTransition]="getRouteAnimationData(outlet)">
+  <router-outlet #outlet="outlet" />
+</div>
+```
+
+Route data:
+```typescript
+{ path: 'home', component: HomeComponent, data: { animation: 'home' } }
+```
+
+### Shake (validation error feedback)
+
+```typescript
+export const shake = trigger('shake', [
+  transition('* => shake', [
+    animate('400ms', keyframes([
+      style({ transform: 'translateX(0)',    offset: 0    }),
+      style({ transform: 'translateX(-8px)', offset: 0.2  }),
+      style({ transform: 'translateX(8px)',  offset: 0.4  }),
+      style({ transform: 'translateX(-6px)', offset: 0.6  }),
+      style({ transform: 'translateX(6px)',  offset: 0.8  }),
+      style({ transform: 'translateX(0)',    offset: 1    }),
+    ])),
+  ]),
+]);
+```
+
+Usage:
+```html
+<form [@shake]="shakeState()" (@shake.done)="shakeState.set('idle')">
+```
+
+---
+
+## Section 4: Applying Animations in Components
+
+```typescript
+@Component({
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  animations: [fadeInOut, listStagger, slideInRight, scaleIn],
+  template: `
+    @if (visible()) {
+      <div @fadeInOut class="panel">Content</div>
+    }
+
+    <ul [@listStagger]="items().length">
+      @for (item of items(); track item.id) {
+        <li>{{ item.name }}</li>
+      }
+    </ul>
+
+    @if (showPanel()) {
+      <aside @slideInRight class="side-panel">
+        Details...
+      </aside>
+    }
+  `,
+})
+export class MyComponent {
+  readonly visible = signal(true);
+  readonly showPanel = signal(false);
+  readonly items = signal<Item[]>([]);
+}
+```
+
+### Disabling Animations Programmatically
+
+```typescript
+// Useful for tests or reduced-motion
+@HostBinding('@.disabled')
+get animationsDisabled() {
+  return this.prefersReducedMotion;
+}
+```
+
+---
+
+## Section 5: Respecting `prefers-reduced-motion`
+
+### CSS Approach (Global — Recommended)
+
+```scss
+// styles.scss
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+### TypeScript Approach (Per Component)
+
+```typescript
+// Check preference at component level
+readonly prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+// React to OS setting changes at runtime
+private motionQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+readonly reducedMotion = signal(this.motionQuery.matches);
+
+constructor() {
+  this.motionQuery.addEventListener('change', e => {
+    this.reducedMotion.set(e.matches);
+  });
+}
+
+// Use in template
+animationDuration() {
+  return this.reducedMotion() ? '0ms' : '250ms';
+}
+```
+
+### Angular Animation with Reduced Motion Guard
+
+```typescript
+export const safeFadeIn = trigger('safeFadeIn', [
+  transition(':enter', [
+    style({ opacity: 0 }),
+    animate('{{ duration }}ms ease-in', style({ opacity: 1 })),
+  ], { params: { duration: 200 } }),
+]);
+```
+
+```html
+<div [@safeFadeIn]="{ value: '', params: { duration: reducedMotion() ? 0 : 200 } }">
+```
+
+---
+
+## Section 6: Motion Design Rules
+
+| Rule | Guideline |
+|---|---|
+| Duration: micro | 100–150ms — immediate feedback (tap, hover) |
+| Duration: standard | 200–300ms — most UI transitions |
+| Duration: complex | 300–500ms — route changes, modals, large reveals |
+| Never exceed | 500ms for UI transitions (feels sluggish) |
+| Easing: enter | `ease-out` — `cubic-bezier(0, 0, 0.2, 1)` — starts fast, decelerates |
+| Easing: exit | `ease-in` — `cubic-bezier(0.4, 0, 1, 1)` — starts slow, accelerates |
+| Easing: standard | `ease-in-out` — `cubic-bezier(0.4, 0, 0.2, 1)` — Material standard |
+| Spatial motion | Enter from direction of origin; exit toward destination |
+| Avoid | Simultaneous enter + leave in the same space (stagger them) |
+| Avoid | Animating `width`/`height` directly (causes layout thrash); use `transform` and `opacity` |
+| Prefer | `transform` and `opacity` — GPU-composited, no layout reflow |
+| Always | Test with `prefers-reduced-motion: reduce` |
+
+### Easing Cheat Sheet
+
+```
+ease-out (decelerate — for entering elements):
+  cubic-bezier(0, 0, 0.2, 1)
+
+ease-in (accelerate — for exiting elements):
+  cubic-bezier(0.4, 0, 1, 1)
+
+ease-in-out (standard — for elements changing state):
+  cubic-bezier(0.4, 0, 0.2, 1)
+
+spring-like (bouncy, expressive):
+  cubic-bezier(0.34, 1.56, 0.64, 1)
+```
+
+### Distance Guidelines
+
+| Element size | Recommended travel distance |
+|---|---|
+| Small (icon, chip) | 4–8px |
+| Medium (card, panel) | 8–16px |
+| Large (page, modal) | 16–32px or 100% (slide in from edge) |
+
+---
+
+## Section 7: Angular Material Built-in Animations
+
+Angular Material components already have animations baked in. Do not re-animate them.
+
+| Component | Built-in animation |
+|---|---|
+| `MatDialog` | Scale + fade on open/close |
+| `MatSnackBar` | Slide up from bottom |
+| `MatSidenav` | Slide in from side |
+| `MatExpansionPanel` | Height expand/collapse |
+| `MatTooltip` | Fade in/out |
+| `MatMenu` | Scale + fade |
+| `MatSelect` | Dropdown expand |
+| `MatProgressBar` | Indeterminate shimmer |
+| `MatChip` | Scale on add/remove |
+
+These all respect `provideAnimationsAsync()` and `prefers-reduced-motion` automatically via Angular Material's internal animation config.
+
+---
+
+## Section 8: Animation Testing
+
+### Disable in Unit Tests
+
+```typescript
+// In TestBed setup
+import { NoopAnimationsModule } from '@angular/platform-browser/animations';
+
+TestBed.configureTestingModule({
+  imports: [NoopAnimationsModule],  // replaces BrowserAnimationsModule
+});
+```
+
+### Flush Animations in Tests
+
+```typescript
+import { fakeAsync, tick } from '@angular/core/testing';
+
+it('should show element after animation', fakeAsync(() => {
+  component.visible.set(true);
+  fixture.detectChanges();
+  tick(200); // advance past animation duration
+  fixture.detectChanges();
+  expect(fixture.nativeElement.querySelector('.panel')).toBeTruthy();
+}));
+```
+
+---
+
+## Section 9: Reusable Animation File Pattern
+
+Centralize all animations to avoid duplication:
+
+```
+src/
+  app/
+    shared/
+      animations/
+        fade.animations.ts
+        slide.animations.ts
+        list.animations.ts
+        route.animations.ts
+        index.ts          ← barrel export
+```
+
+```typescript
+// shared/animations/index.ts
+export * from './fade.animations';
+export * from './slide.animations';
+export * from './list.animations';
+export * from './route.animations';
+```
+
+```typescript
+// In any component
+import { fadeInOut, slideInRight, listStagger } from '@shared/animations';
+
+@Component({
+  animations: [fadeInOut, slideInRight, listStagger],
+})
+```