README.md

metadata

title: UX Analyst AI
emoji: 🧐
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860
pinned: false

UX Analyst AI

An AI-powered UX analysis tool that provides comprehensive website analysis with actionable recommendations and implementation code generation.

Features

🎯 Comprehensive UX Analysis

• Multi-viewport screenshot capture (desktop, tablet, mobile)
• Visual design analysis with color, layout, and typography insights
• AI-powered UX critique with actionable recommendations
• Accessibility compliance checking
• Performance and usability scoring

💻 Implementation Ready

• Generates HTML, CSS, JavaScript code for recommended improvements
• Step-by-step implementation guides
• Copy-paste ready code snippets
• Framework-agnostic solutions

🚀 Multiple Interfaces

• Web Interface: Full-featured dashboard with real-time progress
• Command Line Tool: Perfect for CI/CD integration and automation
• MCP Server: Natural language UX analysis with Claude and other LLMs
• Programmatic API: Integrate into your own tools and workflows

⚙️ Developer Friendly

• Circuit breaker pattern for fault tolerance
• Browser pool management for resource efficiency
• Dependency injection architecture
• Comprehensive error handling and logging

Tech Stack

Backend

• Node.js with Express
• Puppeteer for screenshot capture
• @axe-core/puppeteer for accessibility scanning
• Google Gemini AI for UX critique generation with vision analysis
• SQLite for data storage

Frontend

• React with Vite
• Tailwind CSS for styling
• React Query for state management
• React Router for navigation

Quick Start

Prerequisites

1. Node.js 18+ and npm
2. Google Gemini API Key - Get one from Google AI Studio

Installation & Setup

# Clone the repository
git clone https://github.com/grzetich/eyeson.git
cd eyeson/ux-analyst-ai

# Install dependencies for all components
npm run install:all

# Set up your API key
export GEMINI_API_KEY="your-api-key-here"
# Or create a .env file in the backend directory
echo "GEMINI_API_KEY=your-api-key-here" > backend/.env

Usage Options

1. Command Line Interface (Recommended for CI/CD)

# Install CLI globally
cd cli && npm link

# Basic analysis
ux-analyze https://example.com

# Quick analysis with code generation
ux-analyze https://example.com --quick --code --accessibility

# Interactive mode with guided prompts
ux-analyze interactive

# Custom output format and location
ux-analyze https://example.com --format html --output ./my-analysis

# CI/CD friendly JSON output
ux-analyze https://example.com --format json --quick

CLI Options

• -o, --output <dir> - Output directory (default: ./ux-analysis)
• -f, --format <format> - Output format: json, html, markdown (default: json)
• -v, --viewports <list> - Comma-separated viewports (default: desktop,tablet,mobile)
• --quick - Run quick analysis (faster, less detailed)
• --code - Generate implementation code
• --accessibility - Include accessibility analysis
• --api-key <key> - Gemini API key (or set GEMINI_API_KEY env var)

2. Web Interface

# Start the backend server
cd backend && npm run dev

# Start the frontend (in another terminal)
cd frontend && npm run dev

# Open http://localhost:3000 in your browser

3. Programmatic Usage

const { UXAnalyzer } = require('./cli/lib/UXAnalyzer');

const analyzer = new UXAnalyzer({
  ai: { geminiApiKey: process.env.GEMINI_API_KEY }
});

const result = await analyzer.analyze('https://example.com', {
  viewports: ['desktop', 'mobile'],
  includeCodeGeneration: true,
  includeAccessibility: true
});

console.log('UX Score:', result.report.summary.uxScore);
console.log('Implementation Code:', result.implementationCode);

4. MCP Server (Natural Language Interface)

The MCP server allows you to use natural language with Claude and other LLMs to analyze websites.

Setup

# Configure Claude Desktop
# Add to ~/.config/claude/claude_desktop_config.json (Linux/Mac)
# or %APPDATA%/Claude/claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "ux-analyst": {
      "command": "node",
      "args": ["/path/to/ux-analyst-ai/mcp-server/index.js"],
      "env": {
        "UX_BACKEND_URL": "http://localhost:3005"
      }
    }
  }
}

Usage

Just ask Claude naturally:

"Please analyze the UX of https://example.com"

"Can you do a comprehensive UX analysis including accessibility?"

"Show me the screenshots from the mobile viewport"

"What implementation code do you recommend for the UX issues?"

Benefits

• Natural conversation: No command syntax to remember
• Progressive updates: Claude monitors progress and explains what's happening
• Visual analysis: Claude can see and discuss the actual screenshots
• Intelligent presentation: Results formatted based on your specific questions
• Code explanations: Claude explains generated code and why it works

Integration Examples

NPM Scripts

Add to your package.json:

{
  "scripts": {
    "ux:check": "ux-analyze http://localhost:3000 --quick",
    "ux:full": "ux-analyze http://localhost:3000 --code --accessibility --format html",
    "ux:mobile": "ux-analyze http://localhost:3000 --viewports mobile --quick",
    "ux:ci": "ux-analyze $UX_TARGET_URL --format json --quick --output ./ux-reports"
  }
}

GitHub Actions CI/CD

name: UX Analysis

on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]

jobs:
  ux-analysis:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3

    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'

    - name: Install UX Analyzer
      run: |
        cd ux-analyst-ai/cli
        npm install
        npm link

    - name: Run UX Analysis
      env:
        GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
      run: |
        ux-analyze https://your-staging-site.com \
          --format json \
          --output ./ux-reports \
          --quick \
          --accessibility

    - name: Upload UX Reports
      uses: actions/upload-artifact@v3
      with:
        name: ux-analysis-reports
        path: ./ux-reports/

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Running UX analysis..."
npm run ux:check

if [ $? -ne 0 ]; then
  echo "❌ UX analysis failed. Please review and fix issues before committing."
  exit 1
fi

echo "✅ UX analysis passed!"

Architecture

Backend Services

• AnalysisService: Core analysis orchestration
• ScreenshotService: Multi-viewport screenshot capture with browser pooling
• AICritiqueService: AI-powered UX evaluation using Google Gemini
• VisualDesignAnalyzer: Color, layout, and typography analysis
• CodeGenerationService: AI-powered implementation code generation

Frontend Components

• React Dashboard: Real-time analysis progress and results
• AnalysisForm: URL input and configuration
• ProgressTracker: Live analysis status updates
• ResultsViewer: Interactive report display
• CodeImplementationSection: Generated code display with copy/download

CLI Tool

• Commander.js: Robust CLI argument parsing
• Interactive Mode: Guided prompts with inquirer
• Progress Tracking: Real-time spinners and status updates
• Multiple Output Formats: JSON, HTML, Markdown support

MCP Server

• Model Context Protocol: Standard interface for LLM tool integration
• Natural Language Interface: Conversational UX analysis with Claude
• Progressive Updates: Real-time progress monitoring and explanations
• Visual Content Support: Screenshots and images for LLM analysis

Configuration

Environment Variables

# Required
GEMINI_API_KEY="your-gemini-api-key"

# Optional
PORT=3000
NODE_ENV=development

Configuration File

Create ux-config.json:

{
  "ai": {
    "geminiApiKey": "your-api-key"
  },
  "defaults": {
    "viewports": ["desktop", "tablet", "mobile"],
    "outputFormat": "html",
    "includeCode": true,
    "includeAccessibility": true
  },
  "analysis": {
    "timeoutMs": 300000,
    "maxConcurrentAnalyses": 3
  }
}

Use with: ux-analyze https://example.com --config ux-config.json

Output Formats

JSON (Machine-readable)

• Raw analysis data perfect for CI/CD integration
• Parseable by other tools and scripts
• Contains all metrics, scores, and recommendations

HTML (Human-readable)

• Beautiful visual reports with embedded screenshots
• Implementation code included with syntax highlighting
• Shareable analysis results

Markdown (Documentation-friendly)

• README-compatible format for documentation
• Version control friendly
• Great for team collaboration

API Documentation

Start Analysis

POST /api/analyze
Content-Type: application/json

{
  "url": "https://example.com",
  "options": {
    "viewports": ["desktop", "tablet", "mobile"],
    "includeAccessibility": true,
    "analysisType": "comprehensive"
  }
}

Get Analysis Result

GET /api/analyze/{analysisId}

Get HTML Report

GET /api/analyze/{analysisId}/report

Health Check

GET /api/health

Development

Project Structure

ux-analyst-ai/
├── backend/                 # Express API server
│   ├── services/           # Core business logic
│   ├── routes/             # API routes
│   ├── database/           # Database setup
│   └── server.js           # Entry point
├── frontend/               # React application
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── pages/          # Page components
│   │   └── api/            # API client
│   └── dist/               # Built assets
├── data/                   # Runtime data (screenshots, DB)
└── docker-compose.yml      # Production deployment

Available Scripts

# Development
npm run dev                 # Start both backend and frontend
npm run dev:backend         # Start only backend
npm run dev:frontend        # Start only frontend

# Building
npm run build              # Build frontend
npm run install:all        # Install all dependencies

# Testing
npm test                   # Run backend tests

Adding New Features

1. Backend Services: Add to backend/services/
2. API Routes: Add to backend/routes/
3. Frontend Components: Add to frontend/src/components/
4. Database Changes: Modify backend/database/init.js

Troubleshooting

Common Issues

1. Puppeteer Chrome Issues

   # Linux: Install dependencies
   sudo apt-get install -y gconf-service libasound2 libatk1.0-0 libc6 libcairo2
   
   # Docker: Already included in Dockerfile
   

2. Gemini API Errors

   • Verify API key is set correctly
   • Check API usage limits and quotas
   • Ensure Gemini API access is enabled

3. Out of Memory

   # Increase Node.js memory limit
   export NODE_OPTIONS="--max-old-space-size=4096"
   

4. Screenshots Not Loading

   • Check file permissions in data/screenshots/
   • Verify SCREENSHOT_STORAGE_PATH is correct
   • Ensure sufficient disk space

Performance Optimization

• Reduce Concurrent Analyses: Lower MAX_CONCURRENT_ANALYSES
• Optimize Screenshots: Reduce viewport sizes or skip viewports
• Database: Consider PostgreSQL for production
• Caching: Add Redis for session caching

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check this README and troubleshooting section
2. Review the docs for architecture details
3. Open an issue with reproduction steps

---

Note: This is an MVP implementation. See the roadmap in the docs for planned enhancements including Figma integration, team collaboration, and enterprise features.