@alexberriman/openai-designer-feedback
Version:
CLI tool that captures website screenshots using @alexberriman/screenshotter and provides professional web design/UX feedback via OpenAI's gpt-image-1 vision model. Focus on identifying critical issues and design errors.
318 lines (244 loc) ā¢ 8.73 kB
Markdown
# Design Feedback CLI
[](https://github.com/alexberriman/openai-designer-feedback/actions/workflows/ci.yml)
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](https://github.com/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)
```bash
npx @alexberriman/openai-designer-feedback https://example.com
```
### Using npm
```bash
npm install -g @alexberriman/openai-designer-feedback
```
### Using Bun
```bash
bun install -g @alexberriman/openai-designer-feedback
```
### From Source
```bash
# 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)
```bash
export OPENAI_API_KEY="your-api-key-here"
```
2. **Config File**
Create `~/.design-feedback/config.json`:
```json
{
"apiKey": "your-api-key-here"
}
```
3. **Command Line Option**
```bash
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
```bash
npx @alexberriman/openai-designer-feedback https://example.com
```
### Command Options
```bash
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
```bash
npx @alexberriman/openai-designer-feedback https://example.com
```
#### Mobile Viewport Analysis
```bash
npx @alexberriman/openai-designer-feedback https://example.com --viewport mobile
```
#### Custom Viewport Size
```bash
npx @alexberriman/openai-designer-feedback https://example.com --viewport 1024x768
```
#### Save Screenshot with JSON Output
```bash
npx @alexberriman/openai-designer-feedback https://example.com --output screenshot.png --format json
```
#### Wait for Dynamic Content
```bash
npx @alexberriman/design-feedback https://spa-app.com --wait-for ".content-loaded" --wait 3
```
#### Save Analysis to File (Redirection)
```bash
npx @alexberriman/openai-designer-feedback https://example.com --format json > analysis.json
```
#### Save Analysis to File (Direct)
```bash
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:
```json
{
"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
```bash
npx @alexberriman/design-feedback https://mycompany.com --viewport mobile --format json > mobile-audit.json
```
### Check Responsive Design
```bash
# 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
```bash
npx @alexberriman/design-feedback https://spa-app.com \
--wait-for "[data-loaded='true']" \
--wait 5 \
--no-full-page
```
### CI/CD Integration
```bash
# 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:
```bash
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](CONTRIBUTING.md) for details.
```bash
# 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:
```bash
# Run the local build directly
npm run build
./bin/design-feedback https://example.com
```
## License
MIT Ā© [Alex Berriman](https://github.com/alexberriman)
## Support
- š§ Email: alex@berriman.dev
- š Issues: [GitHub Issues](https://github.com/alexberriman/openai-designer-feedback/issues)
- š¬ Discussions: [GitHub Discussions](https://github.com/alexberriman/openai-designer-feedback/discussions)
## Acknowledgments
Built with:
- [Bun](https://bun.sh/) - Fast JavaScript runtime
- [@alexberriman/screenshotter](https://github.com/alexberriman/screenshotter) - Screenshot capture
- [OpenAI](https://openai.com/) - AI vision analysis
- [Commander.js](https://github.com/tj/commander.js/) - CLI framework
- [ts-results](https://github.com/vultix/ts-results) - Functional error handling