madappgang/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:frontend-implement.

Relationship to Other Skills

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

Model Selection

Read shared/model-aliases.json → roles.designer_review.modelId for the design review model. If the file doesn't exist, tell the user to run /update-models.

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 /designer:ui Command

The /designer: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:frontend-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 /designer:ui:

1. Command detects analysis intent
2. Reads model from shared/model-aliases.json → roles.designer_review.modelId
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 run /update-models and configure model aliases 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:frontend-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