/design-review

Design Review

Review existing Angular Material UI code for Fastlane design issues, usability problems, and improvement opportunities. Provides actionable recommendations aligned with Pangea design tokens and Angular Material 19 patterns.

Pre-flight Checks

1. Check if .ui-design/ directory exists:

   • If not: Create .ui-design/ directory
   • Create .ui-design/reviews/ subdirectory for storing review results

2. Load project context if available:

   • Check for DESIGN.md for Fastlane app conventions
   • Check for apps/web/src/styles.scss for Pangea token definitions
   • Check for .ui-design/design-system.json for design tokens

Target Identification

If argument provided:

• If file path: Validate file exists, read the file
• If component name: Search codebase for matching component files
• If not found: Display error with suggestions

If no argument:

Ask user to specify target:

What would you like me to review?

1. A specific component (provide name or path)
2. A page/route (provide path)
3. The entire UI directory
4. Recent changes (last commit)

Enter number or provide a file path:

Interactive Review Configuration

CRITICAL RULES:

• Ask ONE question per turn
• Wait for user response before proceeding
• Gather context to provide relevant feedback

Q1: Review Focus

What aspects should I focus on?

1. Visual design (spacing, alignment, typography, colors, tokens)
2. Usability (interaction patterns, accessibility basics)
3. Code quality (patterns, maintainability, reusability)
4. Performance (render optimization, change detection)
5. Comprehensive (all of the above)

Enter number:

Q2: Design Context (if visual/usability selected)

What is this UI's primary purpose?

1. Data display (dashboards, tables, reports)
2. Data entry (forms, wizards, editors)
3. Navigation (menus, sidebars, breadcrumbs)
4. Content consumption (articles, media, feeds)
5. Other (describe)

Enter number or description:

Q3: Pangea Surface Question (NEW — after Q2)

Is this view using the standard cool-neutral surface (--surface) or the warm-neutral secondary surface (--surface-alt)?

1. Standard cool-neutral (--surface) — default
2. Warm-neutral secondary (--surface-alt) — documents/records feel

Enter number:

State Management

Create/update .ui-design/reviews/review_state.json:

{
  "review_id": "{target}_{YYYYMMDD_HHMMSS}",
  "target": "{file_path_or_component}",
  "focus_areas": ["visual", "usability", "code", "performance"],
  "context": "{purpose}",
  "surface": "standard|secondary",
  "status": "in_progress",
  "started_at": "ISO_TIMESTAMP",
  "issues_found": 0,
  "severity_counts": {
    "critical": 0,
    "major": 0,
    "minor": 0,
    "suggestion": 0
  }
}

Review Execution

1. Code Analysis

Read and analyze the target files (.ts, .html, .scss only):

• Parse Angular component structure
• Detect Angular Material version and imports
• Note Pangea token usage vs. hardcoded hex values
• Check form field patterns, button color semantics

2. Static Analysis — Anti-pattern Checklist (Fastlane-specific)

When performing static analysis, check these Angular/Pangea-specific issues:

Hex Literals:

• Flag any hex color #XXXXXX or rgb() in .scss files or inline template [style] bindings
• Issue: "Pangea drift — use var(--*) token instead" (known ~232-hex drift)
• Link to: apps/web/src/styles.scss for available tokens

Button Color Semantics:

• color="primary" on success/confirmation states (e.g., "Save", "Submit") → Should be color="accent"
• color="primary" on destructive actions (e.g., "Delete", "Remove") → Should be color="danger"
• color="warn" used decoratively (not actual warning state) → Flag as misuse

Modal Anti-patterns:

• Multi-column form layouts inside <mat-dialog-content> (modals should be single-column)
• Non-scrollable content forcing the whole dialog to overflow

Card Nesting:

• Nested <mat-card> inside another <mat-card> → Recommend structural refactor

Redundant Status Indicators:

• Count/badge duplicating data already shown in table (e.g., "5 items" badge above a 5-row table)
• Decorative number tiles (summaries above tables that don't change a user decision)

Input Field Issues:

• <input> elements outside <mat-form-field> → Required wrapper for Material forms
• <mat-error> outside <mat-form-field> → Must be nested for proper association with input

Icon Button Missing Labels:

• <button mat-icon-button> without aria-label → Icon-only buttons need accessible names

3. Visual Design Review

Check for:

Spacing & Layout:

• Consistent use of Pangea spacing tokens (var(--spacing-*))
• Alignment with Material grid system (4px baseline)
• Unbalanced whitespace
• Magic numbers vs. design tokens

Typography:

• Consistent heading styles (use Material typography scale)
• Font size/weight consistency
• Appropriate line heights
• Text contrast ratios meet WCAG AA (4.5:1 normal, 3:1 large)

Colors & Tokens:

• All text colors use var(--on-surface) or var(--pangea-text-secondary)
• Surface colors use var(--surface) or var(--surface-alt) (not hardcoded)
• Semantic colors: var(--success), var(--error), var(--warning), var(--info)
• Consistent color usage across components
• Dark mode support (:host-context(body.dark-theme) & overrides)

Visual Hierarchy:

• Clear primary actions (raised, accent color)
• Appropriate emphasis and contrast
• Scannable content structure

4. Code Quality Review

Check for:

Angular Patterns:

• Single responsibility per component
• Proper use of input/output signals (Angular 19+)
• ChangeDetectionStrategy.OnPush on all components
• No prop drilling; state lifted appropriately
• Standalone components used correctly

Styling Patterns:

• No inline styles — use .scss files
• Consistent SCSS nesting (no excessive nesting depth)
• Reusable mixins/variables for Pangea tokens
• No CSS-in-JS or inline [style] bindings (except for computed vars)

Maintainability:

• Clear component boundaries
• Descriptive selector names (app-component-name)
• Comments for complex logic
• Accessibility attributes (aria-label, role, etc.)

5. Performance Review

Check for:

Change Detection:

• All components use ChangeDetectionStrategy.OnPush
• No unnecessary @Input() mutations
• Signals used for reactive state (not BehaviorSubject)

Template Optimization:

• @if / @for used over *ngIf / *ngFor (Angular 17+ syntax)
• No expensive computations in templates
• Proper use of trackBy in @for loops

Asset Optimization:

• Image sizes appropriate (no fullsize photos)
• Icons use Material icons, not image files
• No duplicate asset loads

Live Browser Check (optional)

If dev server is running at http://localhost:4200, offer optional live checks:

1. Navigate and Screenshot

Would you like to perform a live browser check? (requires dev server at http://localhost:4200)

1. Yes, perform live checks
2. No, static analysis only

If yes:

• mcp__chrome-devtools__new_page + mcp__chrome-devtools__navigate_page to the component's route
• mcp__chrome-devtools__take_screenshot → save as .ui-design/reviews/{review_id}/light.png
• mcp__chrome-devtools__evaluate_script with document.body.classList.add('dark-theme') → take_screenshot → save as dark.png

2. Lighthouse Audit

• mcp__chrome-devtools__lighthouse_audit → save JSON to .ui-design/reviews/{review_id}/lighthouse.json
• Flag accessibility score < 100 as a blocker; performance < 90 as a warning

3. Runtime Axe Scan

• mcp__chrome-devtools__evaluate_script to inject axe-core from CDN and run axe.run()
• Classify violations by impact; mark as "runtime" in the report (vs "static")

Output Format

Generate review report in .ui-design/reviews/{review_id}/review.md:

# Design Review: {Component/File Name}

**Review ID:** {review_id}
**Reviewed:** {YYYY-MM-DD HH:MM}
**Target:** {file_path}
**Focus:** {focus_areas}
**Surface:** {standard | secondary}

## Summary

{2-3 sentence overview of findings}

**Issues Found:** {total_count}

- Critical: {count}
- Major: {count}
- Minor: {count}
- Suggestions: {count}

**Reference Context:**
- Pangea tokens: `apps/web/src/styles.scss`
- Fastlane conventions: `DESIGN.md`

## Static Analysis Issues

### Issue 1: {Title}

**Severity:** Critical
**Location:** {file}:{line}
**Category:** {Visual|Usability|Code|Performance}

**Problem:**
{Description of the issue}

**Impact:**
{Why this matters for users/maintainability}

**Recommendation:**
{Specific fix suggestion}

**Code Example:**

```{language}
// Before
{current_code}

// After
{suggested_code}
```

---

### Issue 2: ...

## Runtime Issues (if browser check performed)

### Screenshot: Light Mode

[light.png]

### Screenshot: Dark Mode

[dark.png]

### Lighthouse Results

- Accessibility: {score}/100
- Performance: {score}/100

### Runtime Accessibility Violations

{List of axe violations found at runtime}

---

## Positive Observations

{List things done well to reinforce good patterns}

- {Positive observation 1}
- {Positive observation 2}

## Next Steps

1. {Prioritized action 1}
2. {Prioritized action 2}
3. {Prioritized action 3}

---

_Generated by UI Design Review. Run `/ui-design:design-review` again after fixes._

Completion

After generating report:

1. Update review_state.json:

   • Set status: "complete"
   • Update issue counts

2. Display summary:

Design Review Complete!

Target: {component/file}
Issues Found: {total}

- {critical} Critical
- {major} Major
- {minor} Minor
- {suggestions} Suggestions

Full report: .ui-design/reviews/{review_id}/review.md

Follow-up Actions

If user selects "Start implementing fixes":

Which issues would you like to address?

1. All critical issues first
2. All issues in current file
3. Specific issue (enter number)
4. Generate a fix plan for all issues

Enter choice:

Guide user through fixes one at a time, updating the review report as issues are resolved.

Error Handling

• If target file not found: Suggest similar files, offer to search
• If file is not UI code: Explain and ask for correct target
• If review fails mid-way: Save partial results, offer to resume