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

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

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:

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

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:

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

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:

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

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:

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:

## UI Analysis Results

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

### Issues by Severity

#### CRITICAL
{issues or "None found"}

#### HIGH
{issues or "None found"}

#### MEDIUM
{issues or "None found"}

#### LOW
{issues or "None found"}

### Strengths
{positive observations}

### Recommendations
{actionable improvements}

Integration with /dev:ui Command

The /dev:ui command uses this skill when:

1. User requests analysis only ("review", "audit", "check")
2. User provides image without implementation request
3. As first step before dev:ui-implement

Intent Triggers for Analysis

Primary triggers (route to ui-analyse):

• review, analyze, analyse, audit, check, evaluate, assess, score
• inspect, critique, rate, examine

Pattern triggers (route to ui-analyse):

• "what's wrong with", "problems with", "issues with"
• "accessibility", "usability", "wcag"

Workflow Integration

When used via /dev:ui:

1. Command detects analysis intent
2. Detects Gemini provider
3. Runs visual analysis with Gemini
4. Writes review to: ${SESSION_PATH}/reviews/design-review/gemini.md
5. Presents summary to user

Pattern 5: Fallback Mode (Text-Only)

If no Gemini provider is available:

1. Note in output: "Visual verification unavailable - manual review recommended"
2. Proceed with text-based analysis if component code is available
3. Use code analysis to infer potential issues
4. Recommend user provide API key for full visual analysis

Best Practices

DO

• Always validate image inputs exist before analysis
• Cite specific design principles for every issue
• Provide actionable, specific recommendations
• Prioritize by severity (CRITICAL first)
• Use Gemini for visual analysis (not guessing)

DON'T

• Make code changes (use dev:ui-implement for that)
• Give vague aesthetic opinions ("looks bad")
• Overwhelm with LOW severity items
• Forget accessibility considerations
• Skip the principle citation
• Assume implementation details without seeing