UI Improvement Workflow

Overview

Systematic workflow for UI/UX improvements with visual validation. Takes screenshots before and after changes, generates visual comparisons, and creates comprehensive testing documentation following project standards.

Prerequisites

• Android device or emulator connected via ADB
• Project with Jetpack Compose UI
• Git repository for version control
• MCP servers: ADB, serena, git

What This Skill Does

1. Analysis Mode: Analyze UI without making changes (screenshots + recommendations)
2. Implementation Mode: Implement specific changes with before/after visual proof
3. Batch Mode: Process multiple recommendations systematically
4. Documentation: Auto-generate testing instructions per project standards

---

Quick Start

Analysis Only (No Changes)

# Analyze entire app
/ui-analyze

# Analyze specific screen
/ui-analyze HomeScreen

# Analyze specific component
/ui-analyze GiftCard

Implement Single Change

# Implement specific recommendation
/ui-implement "Fix TopAppBar colors"

# Or reference from analysis
/ui-implement recommendation-2

Batch Implementation

# Implement all high-priority items
/ui-implement-batch high-priority

# Implement all recommendations
/ui-implement-batch all

---

Two-Phase Workflow

Phase 1: Analysis (Read-Only)

Purpose: Understand current UI state and generate recommendations without making changes.

Workflow:

1. Check ADB device connection
2. Take screenshots of current UI state
3. Analyze code with serena MCP (theme, components, screens)
4. Use ui-designer agent for design evaluation
5. Generate prioritized recommendations (high/medium/low)
6. Save analysis to docs/ui-analysis/YYYY-MM-DD-analysis.md
7. NO CODE CHANGES - just recommendations

Output:

• Screenshots: docs/ui-screenshots/YYYY-MM-DD/analysis/
• Analysis report: docs/ui-analysis/YYYY-MM-DD-analysis.md
• Recommendations list with impact/effort ratings

Phase 2: Implementation (Makes Changes)

Purpose: Implement specific UI changes with visual validation.

Workflow:

1. Take baseline screenshots (before state)
2. Implement specific change via serena MCP
3. Run build validation (./gradlew assembleDebug)
4. Take updated screenshots (after state)
5. Generate side-by-side visual comparison
6. Create commit with visual proof
7. Update TODO documentation with testing instructions
8. Push changes to feature branch

Output:

• Before/after screenshots with comparison
• Git commit with visual evidence
• Testing instructions in TODO file
• Build validation confirmation

---

Analysis Mode

Command Format

/ui-analyze [target] [--depth quick|medium|thorough]

Parameters:

• target (optional): "all" | "ScreenName" | "ComponentName" | screen path
• --depth (optional): Analysis thoroughness
  • quick: Key screens only (~5 min)
  • medium: All screens + main components (~15 min)
  • thorough: Complete app analysis (~30 min)

Analysis Process

Step 1: Screenshot Capture

strategy:
  home_screen: Always capture
  key_flows: Capture user journeys
  components: Capture in isolation if possible
  edge_cases: Empty states, errors, loading

storage:
  path: docs/ui-screenshots/YYYY-MM-DD/analysis/
  format: PNG
  naming: [screen-name]-[state].png

Step 2: Code Analysis (serena MCP)

targets:
  theme: Theme.kt, Color.kt, Type.kt, Shape.kt
  screens: All @Composable screen functions
  components: Reusable UI components
  patterns: Common layout patterns

focus:
  - Material Design 3 compliance
  - Typography system completeness
  - Color usage consistency
  - Spacing patterns
  - Component reusability

Step 3: Design Evaluation (ui-designer agent)

evaluate:
  visual_hierarchy: Typography scale, spacing, emphasis
  color_scheme: Theme consistency, contrast ratios, accessibility
  component_design: Card styles, buttons, inputs
  layout_patterns: Grids, lists, responsive design
  interaction_patterns: Navigation, feedback, animations

output:
  format: Markdown report
  structure: Current state → Issues → Recommendations → Action plan
  priority: HIGH/MEDIUM/LOW with impact/effort ratings

Step 4: Generate Report

Report Structure:

# UI/UX Analysis Report - YYYY-MM-DD

## Executive Summary
- Overall grade (A-F)
- Top 3 issues
- Quick wins identified

## Current State Analysis
### What's Working Well
[Strengths]

### Areas for Improvement
[Issues by category]

## Recommendations

### HIGH PRIORITY (High Impact, Low Effort)
1. **Recommendation Title**
   - **Impact**: HIGH | **Effort**: LOW | **Timeline**: X hours
   - **Problem**: Current issue description
   - **Solution**: Code example with before/after
   - **Benefits**: Expected improvements

### MEDIUM PRIORITY
[Similar structure]

### LOW PRIORITY
[Similar structure]

## Prioritized Action Plan
- Phase 1 (Week 1): HIGH priority items
- Phase 2 (Week 2): MEDIUM priority items
- Phase 3 (Future): LOW priority items

## Visual Evidence
[Screenshot references with annotations]

Save Location: docs/ui-analysis/YYYY-MM-DD-[target]-analysis.md

---

Implementation Mode

Command Format

/ui-implement "recommendation description"
/ui-implement recommendation-N
/ui-implement --from-file docs/ui-analysis/2025-11-05-analysis.md --recommendation 3

Implementation Process

Step 1: Pre-Implementation Validation

checks:
  adb_connection: Device/emulator connected
  git_status: Clean working directory or stashable changes
  build_baseline: Current code builds successfully
  screenshots: Device ready for screenshot capture

Step 2: Baseline Capture

screenshots:
  location: docs/ui-screenshots/YYYY-MM-DD/[recommendation-id]/before/
  capture:
    - All affected screens
    - Related navigation flows
    - Component in various states
  metadata:
    - Timestamp
    - Device info
    - Build variant

Step 3: Implementation (serena MCP)

approach:
  read_current: Use serena to read affected files
  understand_patterns: Analyze existing code patterns
  implement: Make surgical changes via serena tools
  verify_syntax: Ensure no syntax errors

tools:
  - mcp__serena__find_symbol
  - mcp__serena__replace_symbol_body
  - mcp__serena__insert_after_symbol
  - mcp__serena__insert_before_symbol

Step 4: Build Validation

# Run build to verify changes
./gradlew assembleDebug

# Expected: BUILD SUCCESSFUL
# If fails: Review errors, fix, retry

Step 5: After Capture

screenshots:
  location: docs/ui-screenshots/YYYY-MM-DD/[recommendation-id]/after/
  capture: Same screens/flows as baseline
  naming: Match before/ naming for comparison

Step 6: Visual Comparison

generation:
  format: Markdown table with side-by-side images
  template: |
    ## Visual Comparison

    | Before | After |
    |--------|-------|
    | ![Before](before/home-screen.png) | ![After](after/home-screen.png) |
    | Old state description | New state description |

  annotations:
    - Highlight changed areas
    - Note color/spacing differences
    - Mark new/removed elements

Step 7: Documentation (Project Standards)

Add to TODO file (docs/todo/[task-id]-[name].md):

---

## Implementation Summary

**Status**: ✅ Completed
**Branch**: `ui/[recommendation-id]--YYYY-MM-DD`
**Completed**: YYYY-MM-DD

### What Changed

**Files Modified:**
1. **path/to/File.kt** (lines X-Y) - Brief description

**Changes Made**:

**File**: `path/to/File.kt`

1. **Change description** (lines X-Y):
   - Detailed explanation

**Before**:
```kotlin
// Old code

After:

// New code

Rationale: Why this approach was chosen

Visual Comparison

Before	After
Old visual state	New visual state

Testing Instructions

Build Status: ✅ Verified - ./gradlew assembleDebug

Manual Testing Steps:

1. Test Scenario: Primary Change Verification

   • Open the app
   • Navigate to [affected screen]
   • Expected: [Specific visual change]
   • Verify: ✅ [Checkpoint 1], ✅ [Checkpoint 2]

2. Test Scenario: Regression Check

   • Navigate through related screens
   • Expected: No unintended changes
   • Verify: ✅ Other screens unchanged

What to Verify:

• ✅ Visual change matches screenshots
• ✅ No layout breakage
• ✅ Theme consistency maintained
• ✅ No new accessibility issues

Edge Cases to Test:

• Different screen sizes
• Light/dark theme (if applicable)
• Landscape orientation

#### Step 8: Git Commit (git-workflow agent)

**Commit Message Format**:
```bash
refactor(ui): [concise description]

[Detailed explanation of visual change]
[Why this improves UX]

Visual evidence: docs/ui-screenshots/YYYY-MM-DD/rec-1/

Critical: NEVER reference "Claude", "AI", or "assistant" in commit messages.

Step 9: Quality Gates

Must Pass Before Complete:

• ✅ Build succeeds (./gradlew assembleDebug)
• ✅ Before/after screenshots captured
• ✅ Visual comparison generated
• ✅ Testing instructions added to TODO
• ✅ Commit follows project standards
• ✅ Changes are independently testable

---

Batch Implementation Mode

Command Format

/ui-implement-batch [priority|all]
/ui-implement-batch high-priority
/ui-implement-batch medium-priority
/ui-implement-batch all

Batch Process

For each recommendation in priority order:

1. Execute full implementation workflow (Steps 1-9)
2. Verify build success before proceeding to next
3. Commit each change independently
4. Generate batch summary report

Batch Summary:

# Batch Implementation Summary - YYYY-MM-DD

## Completed Recommendations
1. ✅ Recommendation 1: [Title] - [Impact]
2. ✅ Recommendation 2: [Title] - [Impact]
3. ✅ Recommendation 3: [Title] - [Impact]

## Build Status
- All changes compiled successfully
- No new lint warnings
- Total commits: 3

## Visual Changes
- Screenshots: docs/ui-screenshots/YYYY-MM-DD/batch-summary/
- Total screens affected: X
- Total files modified: Y

## Testing Required
- [ ] Test scenario 1 from recommendation 1
- [ ] Test scenario 2 from recommendation 2
- [ ] Comprehensive regression testing

## Next Steps
- Manual testing of all changes
- Verify visual consistency across all screens
- Consider Phase 2 (medium priority) recommendations

---

Screenshot Management

Directory Structure

docs/ui-screenshots/
└── YYYY-MM-DD/                      # Date-based organization
    ├── analysis/                     # Analysis mode screenshots
    │   ├── home-screen.png
    │   ├── gift-list.png
    │   └── add-gift-screen.png
    ├── rec-1/                        # Implementation mode (per recommendation)
    │   ├── before/
    │   │   ├── home-screen.png
    │   │   └── gift-card.png
    │   └── after/
    │       ├── home-screen.png
    │       └── gift-card.png
    ├── rec-2/
    │   ├── before/
    │   └── after/
    └── batch-summary/                # Batch mode summary
        └── comparison-grid.png

Screenshot Capture Strategy

Via ADB MCP:

capture_command: mcp__adb__dump_image
parameters:
  asBase64: false  # Save as file
  device: [auto-detect or specific device]

naming_convention:
  format: [screen-name]-[state]-[variant].png
  examples:
    - home-screen-default.png
    - gift-card-empty-state.png
    - add-gift-validation-error.png

capture_states:
  default: Normal state
  empty: Empty data state
  loading: Loading state
  error: Error state
  interaction: During interaction (e.g., dialog open)

Visual Comparison Generation

Markdown Table Format:

## Visual Comparison: [Change Description]

| Before | After |
|--------|-------|
| ![Before](path/to/before/screen.png) | ![After](path/to/after/screen.png) |
| **Old State** | **New State** |
| - Old spacing: 12dp | - New spacing: 16dp |
| - Hardcoded color | - Theme color |
| - No visual hierarchy | - Clear hierarchy |

**Key Changes**:
- ✨ Improved spacing consistency
- 🎨 Theme color integration
- 📐 Better visual hierarchy

Annotated Screenshots (optional):

• Use image editing to highlight changed areas
• Add arrows or boxes to emphasize differences
• Include measurements (spacing, sizes)

---

Quality Gates

Pre-Implementation

• ✅ ADB device connected
• ✅ Git working directory clean
• ✅ Current code builds successfully
• ✅ Recommendation clearly understood

During Implementation

• ✅ Code changes follow project standards
• ✅ Build succeeds after changes
• ✅ No new lint warnings introduced
• ✅ Screenshots captured successfully

Post-Implementation

• ✅ Before/after visual comparison generated
• ✅ Testing instructions comprehensive
• ✅ Commit message follows standards
• ✅ Changes independently testable
• ✅ TODO documentation updated

Batch Mode Additional Gates

• ✅ Each recommendation completes before next
• ✅ Build succeeds after each change
• ✅ No accumulated errors or warnings
• ✅ Batch summary report generated

---

Integration with Project Standards

File Structure Compliance

analysis_reports: docs/ui-analysis/
screenshots: docs/ui-screenshots/
todo_files: docs/todo/
testing_docs: Inline in TODO files (project standard)

Documentation Standards

• Follow CLAUDE.md TODO documentation format
• Include Implementation Summary section
• Add comprehensive Testing Instructions
• Use "Expected" and "Verify" keywords
• Provide specific line numbers and file paths

Commit Standards

• Use git-workflow agent for all commits
• Follow conventional commit format
• NEVER reference AI/Claude/assistant
• Include visual evidence path in commit message

Quality Standards

• Follow claude-rules/coding-standards-ai.md
• Use patterns from claude-rules/architecture-ai.md
• Maintain MVVM separation
• Use theme colors and typography scales

---

Troubleshooting

Issue: ADB Device Not Connected

Symptoms: Screenshot capture fails Solution:

# Check device connection
adb devices

# If no devices, reconnect device/emulator
# Start emulator or reconnect USB device

# Verify connection
adb shell echo "Connected"

Issue: Build Fails After Changes

Symptoms: ./gradlew assembleDebug fails Solution:

1. Review error messages carefully
2. Check imports and syntax
3. Verify theme references exist
4. Use serena MCP to inspect code
5. Rollback if needed: git checkout -- .

Issue: Screenshots Don't Show Changes

Symptoms: Before/after screenshots look identical Solution:

• Verify changes were actually made (check git diff)
• Rebuild app before taking after screenshots
• Ensure correct screen is displayed
• Check if change requires app restart

Issue: Documentation Generation Fails

Symptoms: Testing instructions not created Solution:

• Verify TODO file exists at expected path
• Check file permissions
• Review template format
• Generate manually if needed

---

Advanced Usage

Custom Analysis Targets

# Analyze specific file path
/ui-analyze app/src/main/java/com/example/ui/HomeScreen.kt

# Analyze component pattern
/ui-analyze "all Card components"

# Analyze theme files only
/ui-analyze theme

Implementation Variations

# Implement with custom branch name
/ui-implement "Fix spacing" --branch ui/spacing-fix

# Implement without screenshots (quick iteration)
/ui-implement "Quick fix" --no-screenshots

# Implement with specific device
/ui-implement "Test on tablet" --device emulator-5554

Batch Filtering

# Batch by category
/ui-implement-batch typography
/ui-implement-batch colors
/ui-implement-batch spacing

# Batch by effort
/ui-implement-batch quick-wins  # Low effort items

---

Related Skills

• batch-task-workflow: For structured task implementation
• todo-driven-development: For TODO file management (deprecated, use batch-task-workflow)

---

Resources

Project Documentation

• CLAUDE.md - Project-specific instructions
• claude-rules/architecture-ai.md - Architecture patterns
• claude-rules/coding-standards-ai.md - Code standards
• docs/TODO.md - Task tracking

MCP Servers Used

• ADB MCP: Screenshot capture, device interaction
• serena MCP: Code analysis and modification
• git MCP: Version control operations

External Resources

• Material Design 3 Guidelines
• Jetpack Compose Documentation
• Android Accessibility

---

Created: 2025-11-05 Category: UI/UX Development Difficulty: Intermediate Estimated Time: 15 minutes per recommendation Requires: ADB MCP, serena MCP, git-workflow agent, ui-designer agent