tomevault-io 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:
- User requests analysis only ("review", "audit", "check")
- User provides image without implementation request
- 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:
- Command detects analysis intent
- Detects Gemini provider
- Runs visual analysis with Gemini
- Writes review to:
${SESSION_PATH}/reviews/design-review/gemini.md - Presents summary to user
Pattern 5: Fallback Mode (Text-Only)
If no Gemini provider is available:
- Note in output: "Visual verification unavailable - manual review recommended"
- Proceed with text-based analysis if component code is available
- Use code analysis to infer potential issues
- 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.