Design Feedback CLI

A powerful CLI tool that captures screenshots of websites and provides professional web design/UX feedback using AI vision analysis. Perfect for quickly identifying critical design issues, errors, and UX problems in web applications.

Features

• 🖼️ Automated website screenshot capture using @alexberriman/screenshotter
• 🤖 AI-powered design analysis using OpenAI's GPT vision models
• 📱 Support for multiple viewport sizes (mobile, tablet, desktop, custom)
• 🎨 Actionable feedback focused on critical issues and errors
• 📊 Multiple output formats (text and JSON)
• ⚡ Fast and efficient with TypeScript/Bun runtime
• 🔑 Secure API key management

Installation

Using npx (Recommended)

npx @alexberriman/openai-designer-feedback https://example.com

Using npm

npm install -g @alexberriman/openai-designer-feedback

Using Bun

bun install -g @alexberriman/openai-designer-feedback

From Source

# Clone the repository
git clone https://github.com/alexberriman/openai-designer-feedback.git
cd openai-designer-feedback

# Install dependencies
bun install

# Build and link globally
bun run build
bun link

Configuration

API Key Setup

The tool requires an OpenAI API key to analyze screenshots. Set it up in one of three ways:

1. Environment Variable (Recommended)

   export OPENAI_API_KEY="your-api-key-here"

2. Config File Create ~/.design-feedback/config.json:

   {
     "apiKey": "your-api-key-here"
   }

3. Command Line Option

   npx @alexberriman/openai-designer-feedback https://example.com --api-key "your-api-key-here"

If no API key is configured, the tool will prompt you to enter one interactively.

Usage

Basic Usage

npx @alexberriman/openai-designer-feedback https://example.com

Command Options

npx @alexberriman/design-feedback [options] <url>

Options:
  -v, --viewport <size>       Viewport size (mobile/tablet/desktop/WIDTHxHEIGHT) (default: "desktop")
  -o, --output <path>         Save screenshot to specified path
  -f, --format <format>       Output format (json/text) (default: "text")
  -s, --save <path>           Save analysis output to file instead of console
  -w, --wait <seconds>        Wait time before screenshot (seconds)
  --wait-for <selector>       Wait for specific CSS selector
  --full-page                 Capture full page (default: true)
  --no-full-page              Capture viewport only
  --quality <number>          JPEG quality (0-100) (default: 90)
  --api-key <key>             Override default OpenAI API key
  --verbose                   Enable debug logging
  -h, --help                  Display help for command

Usage Examples

Basic Website Analysis

npx @alexberriman/openai-designer-feedback https://example.com

Mobile Viewport Analysis

npx @alexberriman/openai-designer-feedback https://example.com --viewport mobile

Custom Viewport Size

npx @alexberriman/openai-designer-feedback https://example.com --viewport 1024x768

Save Screenshot with JSON Output

npx @alexberriman/openai-designer-feedback https://example.com --output screenshot.png --format json

Wait for Dynamic Content

npx @alexberriman/design-feedback https://spa-app.com --wait-for ".content-loaded" --wait 3

Save Analysis to File (Redirection)

npx @alexberriman/openai-designer-feedback https://example.com --format json > analysis.json

Save Analysis to File (Direct)

npx @alexberriman/openai-designer-feedback https://example.com --format json --save analysis.json

Output Formats

Text Format (Default)

The text format provides a human-readable analysis with color-coded output:

🔍 Design Feedback for https://example.com

📱 Viewport: desktop (1920x1080)
🕐 Analyzed at: 2024-01-15 10:30:00

Critical Issues:
• Navigation menu overlaps content on mobile devices
• Button text is not readable due to poor contrast ratio
• Form validation errors are not properly displayed
• Hero image takes too long to load (5.2s)

Accessibility Concerns:
• Missing alt text on several images
• Form inputs lack proper labels
• Color contrast fails WCAG AA standards

Performance Issues:
• Large unoptimized images (3.5MB total)
• No lazy loading implemented
• Missing viewport meta tag

JSON Format

The JSON format provides structured data for programmatic use:

{
  "url": "https://example.com",
  "viewport": "desktop",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "model": "gpt-4.1-2025-04-14",
  "analysisTime": 1500,
  "screenshotPath": "./screenshot.png",
  "pageDescription": "A modern e-commerce website with a clean layout featuring product categories, featured items, and a navigation menu.",
  "summary": "Several layout issues need to be addressed for optimal user experience.",
  "issues": [
    {
      "severity": "critical",
      "category": "Layout",
      "description": "Navigation menu overlaps content on mobile devices"
    },
    {
      "severity": "major",
      "category": "Responsiveness",
      "description": "Hero image does not resize properly on smaller screens"
    },
    {
      "severity": "minor",
      "category": "Content",
      "description": "Product card spacing is inconsistent"
    }
  ],
  "metadata": {
    "version": "0.1.0",
    "cli": "@alexberriman/openai-designer-feedback"
  }
}

Examples

Analyze a Production Website

npx @alexberriman/design-feedback https://mycompany.com --viewport mobile --format json > mobile-audit.json

Check Responsive Design

# Check mobile view
npx @alexberriman/design-feedback https://mysite.com --viewport mobile --output mobile.png

# Check tablet view
npx @alexberriman/design-feedback https://mysite.com --viewport tablet --output tablet.png

# Check desktop view
npx @alexberriman/design-feedback https://mysite.com --viewport desktop --output desktop.png

SPA with Dynamic Content

npx @alexberriman/design-feedback https://spa-app.com \
  --wait-for "[data-loaded='true']" \
  --wait 5 \
  --no-full-page

CI/CD Integration

# In your CI pipeline
npx @alexberriman/design-feedback $PREVIEW_URL --format json --save design-review.json

# Check for critical issues
if grep -q '"severity": "critical"' design-review.json; then
  echo "Critical design issues found!"
  exit 1
fi

Troubleshooting

Common Issues

1. "API key not found" error

   • Ensure your API key is properly configured
   • Check environment variables with echo $OPENAI_API_KEY
   • Verify config file exists at ~/.design-feedback/config.json

2. "Screenshot failed" error

   • Verify the URL is accessible
   • Check your internet connection
   • Try increasing wait time with --wait option

3. "Analysis timeout" error

   • OpenAI API might be slow; try again
   • Check your API key has sufficient credits
   • Use --verbose for detailed error logs

Debug Mode

Enable verbose logging for troubleshooting:

npx @alexberriman/openai-designer-feedback https://example.com --verbose

This will show:

• Screenshot capture progress
• API request details
• Error stack traces
• Performance timing

Contributing

We welcome contributions! Please see our Contributing Guide for details.

# Development setup
git clone https://github.com/alexberriman/openai-designer-feedback.git
cd openai-designer-feedback
bun install
bun test

For local testing during development:

# Run the local build directly
npm run build
./bin/design-feedback https://example.com

License

MIT © Alex Berriman

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Acknowledgments

Built with:

• Bun - Fast JavaScript runtime
• @alexberriman/screenshotter - Screenshot capture
• OpenAI - AI vision analysis
• Commander.js - CLI framework
• ts-results - Functional error handling