ui-analyse

# UI Analysis Skill

## Overview

This skill provides patterns for analyzing UI designs visually using Gemini 3 Pro Preview. It is **analysis-only** - for implementing improvements, use `dev:ui-implement`.

## Relationship to Other Skills

| Skill | Purpose | Modifies Code? |
|-------|---------|----------------|
| dev:ui-analyse | Visual analysis, issue detection | No |
| dev:ui-implement | Apply improvements from analysis | Yes |
| dev:ui-style-format | Style file specification | No |
| dev:design-references | Reference image management | No |

## Provider Selection

### Detection Logic

```bash
detect_gemini_provider() {
  # Priority 1: Gemini Direct API (lowest latency)
  if [[ -n "$GEMINI_API_KEY" ]]; then
    echo "g/gemini-3-pro-preview"
    return 0
  fi

  # Priority 2: OpenRouter (requires or/ prefix)
  if [[ -n "$OPENROUTER_API_KEY" ]]; then
    echo "or/google/gemini-3-pro-preview"
    return 0
  fi

  # Priority 3: Vertex AI
  if [[ -n "$GOOGLE_APPLICATION_CREDENTIALS" ]]; then
    echo "vertex/gemini-3-pro-preview"
    return 0
  fi

  # Priority 4: Gemini OAuth (check claudish)
  if npx claudish --list-accounts 2>/dev/null | grep -q "gemini"; then
    echo "g/gemini-3-pro-preview"
    return 0
  fi

  # No provider
  return 1
}
```

### Model Prefix Reference

| Prefix | Provider | Env Var | Notes |
|--------|----------|---------|-------|
| `g/` | Gemini Direct | GEMINI_API_KEY | Lowest latency |
| `or/` | OpenRouter | OPENROUTER_API_KEY | Avoids google/ collision |
| `vertex/` | Vertex AI | GOOGLE_APPLICATION_CREDENTIALS | Enterprise |

### Error Messages by Provider

| Provider | Missing | Error Message | Setup Instructions |
|----------|---------|---------------|-------------------|
| gemini_direct | GEMINI_API_KEY | "Gemini API key not found" | `export GEMINI_API_KEY="your-key"` from aistudio.google.com |
| openrouter | OPENROUTER_API_KEY | "OpenRouter API key not found" | `export OPENROUTER_API_KEY="your-key"` from openrouter.ai |
| vertex_ai | GOOGLE_APPLICATION_CREDENTIALS | "Google Cloud credentials not configured" | `gcloud auth application-default login` |
| gemini_oauth | OAuth session | "No Gemini OAuth session" | `claudish auth gemini` |

## Analysis Patterns

### Pattern 1: Quick Usability Scan

```markdown
Analyze this UI screenshot for usability issues.

**Focus Areas**:
1. Visual hierarchy - Is the most important content prominent?
2. Affordances - Do interactive elements look clickable?
3. Consistency - Do similar elements behave similarly?

**Output**: Top 5 issues with severity and location.
```

**Usage**:
```bash
npx claudish --model "$GEMINI_MODEL" --image "$SCREENSHOT_PATH" --quiet --auto-approve <<< "
Analyze this UI screenshot for usability issues.

Focus Areas:
1. Visual hierarchy - Is the most important content prominent?
2. Affordances - Do interactive elements look clickable?
3. Consistency - Do similar elements behave similarly?

Output: Top 5 issues with severity and location."
```

### Pattern 2: Accessibility Audit

```markdown
Audit this UI for WCAG 2.1 AA compliance.

**Checklist**:
- [ ] Text contrast >= 4.5:1 (WCAG 1.4.3)
- [ ] Non-text contrast >= 3:1 (WCAG 1.4.11)
- [ ] Touch targets >= 44x44px (WCAG 2.5.5)
- [ ] Focus visible (WCAG 2.4.7)

**Output**: Pass/Fail per criterion with evidence.
```

**Usage**:
```bash
npx claudish --model "$GEMINI_MODEL" --image "$SCREENSHOT_PATH" --quiet --auto-approve <<< "
Audit this UI for WCAG 2.1 AA compliance.

Checklist:
- Text contrast >= 4.5:1 (WCAG 1.4.3)
- Non-text contrast >= 3:1 (WCAG 1.4.11)
- Touch targets >= 44x44px (WCAG 2.5.5)
- Focus visible (WCAG 2.4.7)

Output as: Pass/Fail per criterion with visual evidence."
```

### Pattern 3: Anti-AI Design Audit

```markdown
Analyze this UI for "AI-generated" patterns that should be avoided.

**Check for**:
1. Rigid symmetric grids (should be asymmetric)
2. Flat solid colors (should have gradients/texture)
3. Generic typography (should have dramatic hierarchy)
4. Static elements (should have micro-interactions)
5. Default Tailwind colors (should be bespoke palette)

**Output**: List violations with specific recommendations.
```

**Usage**:
```bash
npx claudish --model "$GEMINI_MODEL" --image "$SCREENSHOT_PATH" --quiet --auto-approve <<< "
Analyze this UI for AI-generated patterns that should be avoided.

Check for:
1. Rigid symmetric grids (should be asymmetric)
2. Flat solid colors (should have gradients/texture)
3. Generic typography (should have dramatic hierarchy)
4. Static elements (should have micro-interactions)
5. Default Tailwind colors (should be bespoke palette)

List each violation found with specific recommendations for improvement."
```

### Pattern 4: Comparative Analysis

```markdown
Compare these two images:
- Image 1: Design reference
- Image 2: Implementation

**Validate**:
1. Layout accuracy
2. Color fidelity
3. Typography matching
4. Spacing precision
5. Component rendering

**Output**: Match score (1-10) and deviation list.
```

**Usage**:
```bash
npx claudish --model "$GEMINI_MODEL" \
  --image "$REFERENCE_PATH" \
  --image "$IMPLEMENTATION_PATH" \
  --quiet --auto-approve <<< "
Compare these two images:
- Image 1: Design reference (target)
- Image 2: Current implementation

Validate:
1. Layout accuracy
2. Color fidelity
3. Typography matching
4. Spacing precision
5. Component rendering

Output: Match score (1-10) and list of specific deviations."
```

## Severity Guidelines

| Severity | Impact | Examples | Action |
|----------|--------|----------|--------|
| CRITICAL | Blocks task | Invisible button, broken flow | Fix immediately |
| HIGH | Major barrier | WCAG fail, confusing nav | Fix before release |
| MEDIUM | Friction | Inconsistent spacing | Next sprint |
| LOW | Polish | Minor alignment | Backlog |

## Output Format

Analysis results should follow this structure:

```markdown
## UI Analysis Results

**Target**: {image_path}
**Provider**: {gemini_model}
**Date**: {timestamp}
**Score**: {X}/10

### Issues by Severi