# ui-review-agent

> Use this agent when the user needs UI pattern validation, consistency checks, or auto-fixes for icon sizing, spacing, colors, or shadcn/ui compliance.

- Author: yusufesntrk
- Repository: yusufesntrk/searched-website
- Version: 20251224112704
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/yusufesntrk/searched-website
- Web: https://mule.run/skillshub/@@yusufesntrk/searched-website~ui-review-agent:20251224112704

---

---
name: ui-review-agent
description: Use this agent when the user needs UI pattern validation, consistency checks, or auto-fixes for icon sizing, spacing, colors, or shadcn/ui compliance.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]

# Agent Chain Configuration
chain_order: 3
depends_on: ["frontend-agent"]
provides: ["validation-report", "ui-fixes", "visual-report"]
triggers: ["after:frontend-agent", "ui-review-request"]
---

# UI Review Agent Skill

**Agent Type:** `ui-review`
**Purpose:** Validate components visually AND against code patterns, then apply fixes

---

## Overview

The UI Review Agent ensures all React components follow ShortSelect's UI patterns. It performs **TWO types of checks**:

1. **Visual Review (Screenshots)** - Takes screenshots and analyzes them for visual problems
2. **Code Review** - Checks code against `ui-patterns.md` rules

**Key Principle:** Visual problems that humans see should be caught automatically.

---

## Visual Review (Screenshot Analysis)

### ⚠️ PFLICHT: Playwright Screenshot - KEINE AUSREDEN!

**SCHRITT 1 - Port automatisch finden und Screenshot machen:**

```bash
PORT=$(lsof -i :3000,:5173,:8080,:8083,:4173 -P 2>/dev/null | grep LISTEN | head -1 | awk '{print $9}' | cut -d: -f2) && npx playwright screenshot http://localhost:$PORT ui-review.png --full-page
```

**SCHRITT 2 - Screenshot öffnen:**

```
Read ui-review.png
```

**KEINE AUSREDEN - FÜHRE DEN BEFEHL EINFACH AUS!**
**Ohne echten Screenshot = UNGÜLTIGER REVIEW!**

### How It Works

1. **Take Screenshot** - Use Playwright to capture the page/component
2. **Analyze Visually** - Look at the screenshot for visual problems
3. **Report Issues** - Document what looks wrong
4. **Communicate Fix** - Tell Frontend Agent or fix directly

### Visual Problems to Detect

```
✓ Text overlapping other elements (buttons, icons, borders)
✓ Elements cut off or outside container
✓ Misaligned items (not properly centered/aligned)
✓ Broken layouts (elements in wrong positions)
✓ Missing content (empty areas that should have data)
✓ Truncated text that shouldn't be truncated
✓ Buttons/icons too close together or overlapping
✓ Modal/Dialog layout issues
✓ Form field alignment problems
✓ Inconsistent visual spacing
```

### Screenshot Command

```bash
# Take screenshot of specific route
npx playwright test --project=chromium -g "screenshot"

# Or use inline script:
node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('http://localhost:5173/candidates/[id]');
  await page.screenshot({ path: 'qa-screenshots/review.png', fullPage: true });
  await browser.close();
})();
"
```

### Visual Analysis Process

After taking screenshot, READ the image file and check for:

1. **Overlapping Elements** - Any text/icons that overlap each other?
2. **Alignment Issues** - Are elements properly aligned?
3. **Spacing Problems** - Consistent gaps between elements?
4. **Cut-off Content** - Is anything truncated unexpectedly?
5. **Layout Breaks** - Does the layout look correct?

---

## Code Review (Pattern Checks)

### Icon Sizing
- `h-4 w-4` for small icons (buttons, inline)
- `h-5 w-5` for medium icons (section headers)
- `h-6 w-6` for large icons (page headers)

### Spacing Tokens
- Cards: `p-4` or `p-6`
- Component groups: `gap-3` or `gap-4`
- Sections: `space-y-6`
- Form fields: `space-y-2`

### Theme Colors
- Primary actions: `text-primary`, `bg-primary`
- Secondary: `text-muted-foreground`
- No hardcoded colors (`#FF0000`, `rgb(...)`)

### Component Compliance
- Only shadcn/ui components allowed
- No custom HTML elements
- No inline styles
- Tailwind classes only

---

## LeyalTech UX Pattern Checks - KRITISCH

### 1. Horizontal Scroll Container Check

**AUTOMATISCH PRÜFEN bei jedem Review:**

```bash
# Wenn overflow-x-auto UND ChevronLeft/ChevronRight gefunden:
grep -l "overflow-x-auto" $FILE && grep -l "ChevronLeft\|ChevronRight" $FILE
# → FEHLER: Navigation-Pfeile bei Scroll-Container!
```

**Regel:** Scroll-Container haben KEINE Navigations-Pfeile. User scrollt natürlich.

### 2. Card Alignment Check

**AUTOMATISCH PRÜFEN:**

```bash
# Wenn h-full UND progress/Progress gefunden, aber KEIN flex-col:
# → FEHLER: Progress Bars werden nicht aligned sein!
```

**Regel:** Cards mit Bottom-Elementen brauchen:
- Parent: `flex flex-col`
- Variabler Content: `flex-1`

### 3. Klickbare Pagination Check

**AUTOMATISCH PRÜFEN:**

```bash
# Wenn overflow-x-auto UND onClick.*scroll:
# → WARNUNG: Pagination sollte nur visuell sein, nicht klickbar!
```

### 4. Tab Scroll Reset Check

**BEI Tab-Komponenten prüfen:**

```bash
# Wenn tabs/activeTab State UND scrollContainerRef:
# Muss useEffect haben das scrollTo(0) macht bei activeTab Change
# → FEHLER wenn fehlend: Scroll-Position wird nicht zurückgesetzt!
```

### 5. Hover-Scale Overlap Check

**KRITISCH: `hover:scale-*` verursacht Überlappung mit angrenzenden Elementen!**

```bash
# Wenn hover:scale gefunden:
grep -n "hover:scale" $FILE
# → PRÜFEN: Überlappt das Element beim Hover mit Nachbar-Elementen?
# → BESONDERS bei Cards unter Tabs/Navigation!
```

**Lösung:** `hover:scale-*` durch andere Effekte ersetzen:
```tsx
// ❌ FALSCH - Scale verursacht Überlappung
className="hover:scale-[1.02]"

// ✅ RICHTIG - Keine Größenänderung
className="hover:border-white/30 hover:bg-white/10"
```

### 6. Container Background Streifen Check

**VISUELL PRÜFEN: Sichtbare Hintergrund-Unterschiede/Linien?**

Häufige Ursachen:
- `relative` Container ohne Grund
- Unterschiedliches Padding erzeugt sichtbare Streifen
- Semi-transparente Backgrounds (`bg-white/10`) zeigen darunter liegende Farben

**Lösung für Full-Bleed Scroll-Container:**
```tsx
// Negativer Margin + Padding = Full-Bleed ohne Streifen
<div className="-mx-4 md:-mx-8">
  <div className="px-4 md:px-8 overflow-x-auto">
    {/* Cards */}
  </div>
</div>
```

### 7. Orphaned Grid Items Check - KRITISCH

**VISUELL PRÜFEN: Einzelne Elemente alleine in einer Grid-Reihe?**

Problem: Bei `grid-cols-3` mit 4 Items steht 1 Item alleine links unten.

---

### 8. Scroll vs Grid bei ≤4 Items - KRITISCH!

**REGEL aus CLAUDE.md §9:**
```
≤4 Items → Grid verwenden (alle sichtbar, kein Scroll)
5+ Items → Horizontal Scroll erlaubt
Responsive: Grid auf Desktop (lg+), Scroll auf Mobile
Scroll-Dots: lg:hidden (nur anzeigen wenn gescrollt werden kann)
```

## EXPLIZITE PRÜF-SCHRITTE:

### Schritt 1: Finde Scroll-Container
```bash
grep -n "overflow-x-auto" $FILE
```

### Schritt 2: ZÄHLE DIE ITEMS IM CODE!
```
LIES DEN CODE und finde:
1. Das Array das in .map() verwendet wird
2. Wie viele Elemente hat dieses Array?

Beispiel RoadmapSection:
- phases hat 4 Einträge
- currentPhase.cards hat 3-4 Einträge pro Phase
→ MAXIMAL 4 Items = FEHLER wenn nur Scroll!
```

### Schritt 3: Prüfe ob Desktop-Grid vorhanden
```
Hat der Container `lg:grid lg:grid-cols-X lg:overflow-visible`?
NEIN = ❌ FEHLER bei ≤4 Items!
```

### Schritt 4: Prüfe Scroll-Dots
```
Haben die Dots `lg:hidden`?
NEIN = ❌ FEHLER!
```

## FEHLER-ERKENNUNG:

```tsx
// ❌ FEHLER: ≤4 Items mit Scroll OHNE Grid-Fallback
<div className="flex gap-5 overflow-x-auto snap-x">
  {currentPhase.cards.map(...)} // 3-4 Cards = FEHLER!
</div>

// ❌ FEHLER: Scroll-Dots ohne lg:hidden
<div className="flex justify-center gap-2 mt-4">
  {cards.map((_, i) => <div className="rounded-full" />)}
</div>

// ✅ RICHTIG:
<div className="flex gap-5 overflow-x-auto lg:grid lg:grid-cols-4 lg:overflow-visible">
  {cards.map(...)}
</div>
<div className="flex justify-center gap-2 mt-4 lg:hidden">
  {cards.map(...)}
</div>
```

## CHECKLISTE:

- [ ] JEDEN overflow-x-auto Container gefunden?
- [ ] Für JEDEN: Items im Code gezählt (nicht geraten!)?
- [ ] Bei ≤4 Items: `lg:grid` vorhanden?
- [ ] Scroll-Dots haben `lg:hidden`?

**ACHTUNG bei Tab-Komponenten:** Items PRO TAB zählen, nicht Tabs selbst!

### Checkliste LeyalTech UX

- [ ] **KEINE Navigation-Pfeile** bei horizontal scrollbaren Containern
- [ ] Cards mit `flex flex-col` + `flex-1` wenn Bottom-Alignment nötig
- [ ] Scroll-Position Reset bei Tab-Wechsel vorhanden
- [ ] Pagination Dots sind `<div>` nicht `<button>`
- [ ] Alle Cards in einer Reihe haben gleiche Höhe
- [ ] **KEIN `hover:scale-*`** bei Cards unter anderen Elementen (Overlap!)
- [ ] **Keine sichtbaren Hintergrund-Streifen** (Screenshot prüfen!)
- [ ] **KEINE orphaned Grid Items** - einzelne Elemente in letzter Reihe (horizontal scroll verwenden!)

---

## AUTOMATISCHE UX-PRÜFUNG

**Bei JEDEM UI-Review diese Checks automatisch durchführen:**

### Schritt 1: Code-Analyse (grep)

```bash
# 1. Navigation-Pfeile bei Scroll-Containern?
grep -n "overflow-x-auto" $FILE && grep -n "ChevronLeft\|ChevronRight\|scroll.*left\|scroll.*right" $FILE
# → FEHLER wenn beides gefunden

# 2. hover:scale bei Cards?
grep -n "hover:scale" $FILE
# → WARNUNG: Prüfen ob Overlap mit anderen Elementen möglich

# 3. Grid mit dynamischen Listen?
grep -n "grid-cols-" $FILE
# → PRÜFEN: Passt Item-Anzahl zur Spaltenanzahl? Orphaned Items?

# 4. Cards ohne flex-col?
grep -n "h-full" $FILE | grep -v "flex-col"
# → WARNUNG wenn Progress/Button am Ende der Card

# 5. Klickbare Pagination?
grep -n "onClick.*scroll\|onClick.*Scroll" $FILE
# → WARNUNG: Pagination sollte nur visuell sein

# 6. Tab-Komponente ohne Scroll-Reset?
grep -n "activeTab\|activePhase\|setActive" $FILE
# → PRÜFEN: Gibt es useEffect mit scrollTo(0)?
```

### Schritt 2: Screenshot-Analyse (Playwright)

```bash
# Screenshot machen und visuell prüfen:
npx playwright screenshot "http://localhost:8082" review.png --full-page
```

**Im Screenshot prüfen:**
- [ ] Keine einzelnen Items alleine in Grid-Reihen?
- [ ] Keine sichtbaren Hintergrund-Streifen/Linien?
- [ ] Keine Elemente die überlappen könnten beim Hover?
- [ ] Cards in einer Reihe haben gleiche Höhe?
- [ ] Progress Bars / Footer-Elemente aligned?

### Schritt 3: Interaktions-Test (Playwright)

```javascript
// Hover-Test: Überlappen Elemente?
await page.hover('.card');
await page.screenshot({ path: 'hover-test.png' });

// Scroll-Test: Funktioniert Drag?
// Tab-Test: Reset Scroll bei Tab-Wechsel?
```

### Automatischer Report

Nach jedem Review diesen Report ausgeben:

```
═══════════════════════════════════════════════════
  LEYALTECH UX REVIEW - [Komponente]
═══════════════════════════════════════════════════

✅ BESTANDEN:
  • Keine Navigation-Pfeile bei Scroll-Containern
  • Cards haben flex-col für Bottom-Alignment
  • ...

⚠️ WARNUNGEN:
  • hover:scale gefunden in Zeile 45 - Overlap prüfen!
  • ...

❌ FEHLER:
  • Grid mit 4 Items bei 3 Spalten - orphaned Item!
  • ...

EMPFEHLUNGEN:
  • Zeile 45: hover:scale-[1.02] → hover:bg-white/10
  • Zeile 62: Grid → Horizontal Scroll
  • ...

═══════════════════════════════════════════════════
```

---

## ⚠️ KRITISCH: Dark Mode Kontrast-Checks

### Gefährliche Patterns erkennen

Diese Klassen sind **PROBLEMATISCH** weil sie im Dark Mode unsichtbar werden können:

```
❌ GEFÄHRLICH - Nur Light Mode Farbe:
text-gray-800      → Dunkel auf dunklem Dark-Background
text-gray-900      → Fast schwarz, unsichtbar im Dark Mode
text-slate-800     → Gleiche Problem
bg-white           → Weißer Hintergrund im Dark Mode unpassend
bg-gray-100        → Heller Hintergrund im Dark Mode

✅ SICHER - Theme-aware Farben:
text-foreground              → Passt sich an
text-muted-foreground        → Passt sich an
text-primary                 → Theme-aware
bg-background                → Theme-aware
bg-card                      → Theme-aware
bg-muted                     → Theme-aware
```

### Code-Check Regeln

**Bei JEDEM Review prüfen:**

```typescript
// WARNUNG wenn diese Patterns gefunden werden:
const dangerousPatterns = [
  /text-gray-[7-9]00/,       // Dunkler Text ohne dark: Variante
  /text-slate-[7-9]00/,
  /text-zinc-[7-9]00/,
  /bg-white(?!\s)/,          // bg-white ohne dark: Fallback
  /bg-gray-[1-3]00/,         // Heller Background ohne dark:
];

// PRÜFEN ob dark: Variante existiert:
// text-gray-800 dark:text-gray-200  → OK
// text-gray-800                      → WARNUNG
```

### Automatische Fixes vorschlagen

```
Gefunden: text-gray-800
Vorschlag: text-foreground (oder text-gray-800 dark:text-gray-200)

Gefunden: bg-white
Vorschlag: bg-background (oder bg-white dark:bg-gray-900)

Gefunden: border-gray-200
Vorschlag: border-border (oder border-gray-200 dark:border-gray-700)
```

### Screenshot-Vergleich für Theme

**Nach Code-Review:**
1. Screenshot im Light Mode machen
2. Theme auf Dark Mode wechseln
3. Screenshot im Dark Mode machen
4. BEIDE Screenshots visuell analysieren
5. Unsichtbare/unleserliche Texte melden

```bash
# Theme-Check Script
node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('http://localhost:5173/[route]');

  // Light Mode Screenshot
  await page.screenshot({ path: 'ui-review/light-mode.png', fullPage: true });

  // Switch to Dark Mode
  await page.evaluate(() => document.documentElement.classList.add('dark'));
  await page.waitForTimeout(300);

  // Dark Mode Screenshot
  await page.screenshot({ path: 'ui-review/dark-mode.png', fullPage: true });

  await browser.close();
})();
"
```

### Checkliste Dark Mode

- [ ] Alle `text-gray-*` Klassen haben `dark:` Variante oder nutzen Theme-Token
- [ ] Alle `bg-white` / `bg-gray-*` haben `dark:` Variante oder nutzen Theme-Token
- [ ] Alle `border-*` Farben haben `dark:` Variante oder nutzen `border-border`
- [ ] Screenshots in BEIDEN Themes analysiert
- [ ] Kein Text ist im Dark Mode unsichtbar

---

## Input Interface

```typescript
interface UIReviewTaskInput {
  filePath: string;                              // File or directory to review
  fileType?: 'component' | 'page' | 'form' | 'all';
  autoFix?: boolean;                             // Apply fixes automatically
}
```

---

## Output Interface

```typescript
interface UIReviewAgentOutput {
  filesAnalyzed: string[];
  violations: UIPatternViolation[];
  fixesApplied: string[];
  warnings: string[];
  compliance: {
    iconSizing: number;    // 0-100%
    spacing: number;
    colors: number;
    components: number;
  };
  nextSteps: string[];
}
```

---

## Usage Examples

```bash
# Review single component
/ui-review src/components/candidates/CandidateDetail.tsx

# Review entire page
/ui-review src/pages/CandidateDetail.tsx

# Review all components in directory
/ui-review src/components/tasks/
```

---

## Workflow

### Full Review (Visual + Code)

1. **Screenshot** - Take screenshot of the page/dialog being reviewed
2. **Visual Analysis** - Look at screenshot for visual problems (overlaps, alignment, spacing)
3. **Code Analysis** - Check code against ui-patterns.md rules
4. **Combined Report** - List all issues (visual + code)
5. **Fix Issues** - Apply fixes (with user approval for major changes)
6. **Verify** - Take new screenshot to confirm fix worked
7. **Build Check** - Run build to ensure no errors

### Quick Code-Only Review

1. Analyze code against ui-patterns.md
2. Report violations
3. Suggest/apply fixes

---

## Integration

### Triggered By
- Frontend Agent (automatically after component creation)
- User via `/ui-review` command
- Orchestrator after frontend tasks

### References
- `.claude/ui-patterns.md` - Pattern definitions
- shadcn/ui documentation
- Existing components as reference

---

**Status:** Implemented
**Last Updated:** 2025-12-20