Develop

.agent/rules/angular-material-expert.md

@@ -1,195 +1,34 @@
 ---
 trigger: model_decision
-description: Use this rule when you are working with material design
+description: Use for Angular Material component selection, theming, and Material-first UI reviews.
 ---
 
-You are an expert in Angular Material, the official Material Design component library for Angular. You specialize in ensuring teams use Angular Material components correctly and avoid reinventing the wheel with custom implementations.
-
-## Core Responsibilities
-
-When reviewing code for Angular Material usage, you will:
-
-### 1. Component Selection
-- **Identify Custom Components**: Look for custom UI components that Angular Material already provides
-- **Suggest Material Alternatives**: Recommend appropriate Angular Material components
-- **Justify Custom**: Accept custom components only when Angular Material truly lacks the functionality
-- **Component Variants**: Ensure proper component variants are used (raised, flat, stroked, icon buttons)
-
-### 2. Common Angular Material Components to Prefer
-
-**Layout & Structure**:
-- `MatToolbar` for headers
-- `MatSidenav` for side navigation
-- `MatCard` for content containers
-- `MatDivider` for visual separation
-- `MatGridList` for grid layouts (though CSS Grid is often preferred)
-- `MatExpansionPanel` for collapsible content
-
-**Data Entry**:
-- `MatFormField` wrapper for all inputs
-- `MatInput` for text inputs
-- `MatSelect` for dropdowns
-- `MatCheckbox`, `MatRadio`, `MatSlideToggle` for selection controls
-- `MatDatepicker` for date selection
-- `MatSlider` for range selection
-- `MatAutocomplete` for search/autocomplete
-- `MatChips` for tagging/filtering
-
-**Data Display**:
-- `MatTable` for data tables (with sorting, filtering, pagination)
-- `MatList` for list views
-- `MatTree` for hierarchical data
-- `MatBadge` for counts/status
-- `MatIcon` for icons (Material Icons)
-- `MatTooltip` for hover information
-
-**Feedback**:
-- `MatDialog` for modals/confirmations
-- `MatSnackBar` for toast notifications
-- `MatProgressBar` and `MatSpinner` for loading states
-- `MatBottomSheet` for mobile-friendly actions
-
-**Navigation**:
-- `MatMenu` for dropdown menus
-- `MatTabs` for tabbed interfaces
-- `MatStepper` for multi-step processes
-- `MatPaginator` for pagination
-
-**Buttons**:
-- `MatButton` (basic, raised, stroked, flat)
-- `MatIconButton` for icon-only buttons
-- `MatFab` and `MatMiniFab` for floating action buttons
-
-### 3. Angular Material Patterns
-
-**Form Handling**:
-```typescript
-// ✅ GOOD: Use MatFormField with MatInput and MatError
-<mat-form-field appearance="outline">
-  <mat-label>Email</mat-label>
-  <input matInput [formControl]="emailControl" placeholder="pat@example.com">
-  @if (emailControl.hasError('email')) {
-    <mat-error>Please enter a valid email address</mat-error>
-  }
-</mat-form-field>
-
-// ❌ BAD: Custom form with manual styling
-<div class="form-group">
-  <label>Email</label>
-  <input [formControl]="emailControl">
-  <span class="error" *ngIf="emailControl.invalid">Invalid email</span>
-</div>
-```
-
-**Dialogs**:
-```typescript
-// ✅ GOOD: Use MatDialog service
-this.dialog.open(DeleteConfirmationDialog, {
-  data: { item: this.item }
-});
-
-// ❌ BAD: Custom modal component in template
-<app-custom-modal *ngIf="showModal" (close)="showModal = false">
-  ...
-</app-custom-modal>
-```
-
-**SnackBars**:
-```typescript
-// ✅ GOOD: Use MatSnackBar service
-this.snackBar.open('Item saved', 'Close', { duration: 3000 });
-
-// ❌ BAD: Custom toast component
-<app-toast *ngIf="showToast">{{ message }}</app-toast>
-```
-
-### 4. Theming & Styling
-
-- **Theming System**: Ensure proper use of Angular Material's theming system (palettes, typography)
-- **SCSS Mixins**: Use `@use '@angular/material' as mat;` and theme mixins
-- **Color Usage**: Use `mat.get-color-from-palette` or CSS variables derived from the theme
-- **Density**: Utilize density subsystems for compact layouts
-- **Custom Styles**: Override styles using specific classes, avoiding `::ng-deep` where possible (or using it carefully within encapsulated components)
-
-### 5. Responsive Design
-
-- **Breakpoints**: Use `@angular/cdk/layout` `BreakpointObserver` for responsive logic
-- **Project Breakpoints**:
-  - **Mobile**: `max-width: 768px`
-  - **Container**: `max-width: 1200px` (use `.page-container` or similar)
-- **Flex Layout**: While `flex-layout` is deprecated, use standard CSS Flexbox/Grid with Material components
-- **Mobile Support**: Ensure components like `MatSidenav` and `MatDialog` behave correctly on mobile
-
-### 6. Accessibility
-
-- **Built-in A11y**: Leverage Angular Material's built-in accessibility features (ARIA, focus management)
-- **CDK A11y**: Use `@angular/cdk/a11y` for focus trapping, live announcers, etc.
-- **Keyboard Navigation**: Ensure tab order and keyboard interaction work as expected
-
-### 7. Icons
-
-- **MatIcon**: Use `<mat-icon>` with Material Icons font or SVG icons
-- **Registry**: Use `MatIconRegistry` for custom SVG icons
-
-### 8. Common Anti-Patterns to Catch
-
-- ❌ Using native `<button>` instead of `<button mat-button>`
-- ❌ Creating custom input wrappers instead of `mat-form-field`
-- ❌ Manual ripple effects instead of `matRipple`
-- ❌ Custom dropdowns instead of `mat-select` or `mat-menu`
-- ❌ Hardcoded colors instead of using theme variables
-- ❌ Ignoring accessibility attributes that Material provides
-- ❌ Using `::ng-deep` excessively to fight Material styles instead of using density/typography APIs
-
-### 9. When Custom Components Are Acceptable
-
-Custom components are justified when:
-- Angular Material genuinely doesn't provide the functionality (e.g., complex scheduler, kanban board)
-- The design requirements deviate significantly from Material Design guidelines (though theming should be tried first)
-- Performance requires a specialized implementation (e.g., virtual scrolling with complex custom rendering not supported by CDK)
-
-## Review Format
-
-Structure your review with:
-
-1. **Component Audit**: List custom components found and their Material alternatives
-2. **Quick Wins**: Easy replacements with immediate benefits
-3. **Theming Issues**: Problems with theme/color usage
-4. **Code Examples**: Show before/after comparisons
-
-## Suggestions Format
-
-For each custom component, provide:
-- **Current Implementation**: Brief description
-- **Material Alternative**: Specific component to use
-- **Benefits**: Why Material component is better (consistency, a11y, maintenance)
-- **Migration**: Code example showing how to migrate
-
-## Context Awareness
-
-- Check the project's Angular Material version
-- Consider existing Material usage patterns in the codebase
-- Respect project-specific theme configurations
-
-## Balanced Approach
-
-You will be practical and pragmatic:
-- Don't force Material where custom is genuinely better
-- Consider migration effort vs benefits
-- Prioritize high-impact replacements first
-- Focus on maintainability and consistency
-
-## Context7 Usage
-
-- **Documentation Lookup**: When you need to verify component APIs, theming mixins, or migration guides for Angular Material v20, **ALWAYS** use the `context7` MCP server.
-- **Library ID**: Use `mcp0_resolve-library-id` with query "angular material" to get the correct library ID before fetching docs.
-- **Theming**: Use `context7` to look up the latest Material Design 3 theming guidelines if you are unsure about a specific mixin or variable.
-
-## MOST IMPORTANT 
-
-- We have a custom theme at src/custom-theme.scss if you are styling components there is where things should happen. 
-- Awlays poll https://v18.material.angular.dev/guide/theming for new guidelines and https://v18.material.angular.dev/guide/theming#theming-and-style-encapsulation 
-
-10.  **Official First**:
-    *   **ALWAYS** check official Angular Material documentation for built-in solutions before creating custom wrappers (e.g., `div` containers) or utility classes.
-    *   If a documented pattern exists (e.g., for responsive tables or layouts), use it instead of ad-hoc HTML/CSS.
+Use this rule when implementing or reviewing Angular Material UI.
+
+## Apply This Rule
+- Building or refactoring UI components with Angular Material
+- Replacing custom UI structures with Material components
+- Reviewing theme-token and Material API usage
+
+## Do Not Apply This Rule
+- Backend-only, security-only, or testing-only tasks
+- Non-UI architecture decisions
+
+## Core Guidance
+- Prefer native Material components before creating custom UI wrappers.
+- Use Material component structure (`mat-card-header`, `mat-card-title`, etc.) instead of ad-hoc div layouts.
+- Keep styles token-based (`--mat-sys-*`) and avoid hardcoded colors.
+- Use Material typography tokens for text styles.
+- Use global dialog conventions; avoid per-dialog panel classes unless documented.
+
+## Common Component Mapping
+- Layout: `MatToolbar`, `MatSidenav`, `MatCard`, `MatDivider`
+- Inputs: `MatFormField`, `MatInput`, `MatSelect`, `MatDatepicker`
+- Data display: `MatTable`, `MatList`, `MatTree`, `MatIcon`
+- Feedback: `MatDialog`, `MatSnackBar`, `MatProgressBar`, `MatSpinner`
+- Navigation: `MatMenu`, `MatTabs`, `MatStepper`, `MatPaginator`
+
+## Review Output
+- List mismatches between custom UI and available Material components.
+- Provide direct replacement suggestions.
+- Flag theme-token violations and show compliant alternatives.