---
slug: "web-design-studio"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/xiaodong-wu/web-design-studio@main/README.md"
repo: "https://github.com/xiaodong-wu/web-design-studio"
source_file: "README.md"
branch: "main"
---
# Web Design Studio

> **Production-grade web design with AI-powered image generation and professional documentation**

A complete skill combining frontend design excellence, automated image generation, and professional design documentation to create stunning, production-ready web pages with all visual elements included.

## Overview

**Web Design Studio** is an all-in-one solution for creating complete web experiences. It integrates:

- **Frontend Design Excellence**: Following the design principles from `frontend-design` by Anthropic
- **AI Image Generation**: Using Google's Gemini 3 Pro Image API (via `nano-banana-pro`)
- **Professional Documentation**: Automatic generation of client-ready design specification documents
- **Quality Assurance**: Built-in image verification to ensure all assets are properly linked

## Features

- 🎨 **Distinctive Design**: Create memorable, production-grade interfaces with bold aesthetic choices
- 🖼️ **Auto-Generated Images**: Generate custom images that match your design aesthetic
- 📄 **Professional Documentation**: Generate comprehensive design specification documents with 6 major sections
- ✅ **Image Verification**: Automatically validate all image references before delivery
- 🚀 **Complete Output**: Get fully functional HTML/CSS/JS with all images included
- 📱 **Responsive**: Mobile-first, responsive designs out of the box
- ✨ **No Placeholders**: Real, finished work with actual images, not "image goes here"

## Installation

### Via skills.sh (Recommended)

```bash
npx skills add xiaodong-wu/web-design-studio
```

### Manual Installation

1. Clone this repository
2. Copy `skills/web-design-studio` to your Claude skills directory
3. Restart Claude

## Usage

When you need to create a web page with images, simply ask Claude to use this skill:

> "Create a landing page for a coffee shop"

The skill will:

1. **Design Phase**: Create a distinctive, production-grade interface with bold aesthetic choices
2. **Image Generation**: Identify all needed images (hero banners, product shots, backgrounds) and generate them
3. **Implementation**: Deliver complete HTML/CSS/JS with all images integrated
4. **Verification**: Validate all image references to ensure everything works
5. **Documentation**: Generate professional design specification document for client delivery

## Workflow

### Complete 5-Step Process

**Step 1: Frontend Design**
- Choose a bold aesthetic direction (minimalist, maximalist, retro-futuristic, organic, luxury, playful, brutalist, etc.)
- Define typography, color schemes, and visual hierarchy
- Plan the layout and component structure

**Step 2: Image Generation**
```bash
uv run ~/.claude/skills/web-design-studio/scripts/generate_image.py \
  --prompt "modern coffee shop interior with warm lighting" \
  --filename "2026-01-26-14-30-00-coffee-shop.png" \
  --resolution 2K
```

**Step 3: HTML Implementation**
- Create complete HTML/CSS/JS with `images/filename.png` references
- Ensure responsive design and accessibility

**Step 4: Image Verification (REQUIRED)**
```bash
python ~/.claude/skills/web-design-studio/scripts/verify_images.py
```

**Step 5: Design Documentation (REQUIRED)**
```bash
python ~/.claude/skills/web-design-studio/scripts/generate_design_doc.py \
  --project-name "Coffee Shop Landing Page" \
  --output "design-doc.html" \
  --html-file "index.html"
```

The script automatically extracts page structure, colors, images, and CTA counts from your HTML file!

## Requirements

### For Image Generation

- Python >= 3.9
- `uv` package manager
- Gemini API key (set as `GEMINI_API_KEY` environment variable)

### Install Dependencies

```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# The script will automatically install required Python dependencies:
# - google-genai>=1.0.0,<2.0.0
# - pillow>=10.0.0,<11.0.0
```

## Image Resolution Options

The skill supports three resolutions:

- **1K** (default) - ~1024px for small images, icons, thumbnails
- **2K** - ~2048px for standard images, product shots
- **4K** - ~4096px for hero banners, large backgrounds

**Filename Format:** `{timestamp}-{descriptive-name}.png`
- Timestamp: `yyyy-mm-dd-hh-mm-ss` (24-hour format)
- Name: lowercase descriptive text with hyphens

## Design Documentation

The skill generates professional 6-section design specification documents:

1. **Design Overview** - Core concept, design goals, target audience
2. **Visual Design Strategy** - Color system, typography, image strategy
3. **Page Structure Design** - Complete page layout and sections
4. **User Experience Design** - Interaction design, responsive design, performance
5. **Technical Implementation** - Tech stack, code features, browser compatibility
6. **Deliverables Checklist** - Deliverables, image inventory, future work

**Advanced Parameters:**
- `--primary-color`, `--secondary-color`, `--accent-color`, `--bg-color`
- `--page-sections` (comma-separated)
- `--image-list` (format: `filename|resolution|purpose`)
- `--cta-count`, `--author`, `--project-type`, `--version`

## Project Structure

```
web-design-studio/
├── README.md
├── CHANGELOG.md
├── LICENSE.txt
└── skills/web-design-studio/
    ├── SKILL.md
    ├── metadata.json
    ├── LICENSE.txt
    └── scripts/
        ├── generate_image.py       # Image generation
        ├── verify_images.py        # Image verification
        └── generate_design_doc.py  # Documentation generation
```

## What's New in v1.4.0

- 🤖 **HTML Auto-Extraction**: Automatically extract page structure, colors, images, and CTAs from HTML files
- 📄 **Professional Design Documentation**: 6-section format with advanced customization
- 🎨 **Enhanced Styling**: Sticky navigation, smooth scrolling, rich components
- 🔧 **20+ Customization Parameters**: Full control over generated documentation
- 🐛 **Python 3.9 Compatibility**: Works with Python 3.9+
- 🧹 **Cleaned Up**: Removed temporary test files

See [CHANGELOG.md](https://github.com/xiaodong-wu/web-design-studio/blob/HEAD/CHANGELOG.md) for full version history.

## Credits

This skill combines and extends work from:

- **frontend-design** by Anthropic - Frontend design principles and aesthetics
- **nano-banana-pro** - Image generation using Gemini 3 Pro Image API

## License

Apache 2.0 - See [LICENSE.txt](https://github.com/xiaodong-wu/web-design-studio/blob/HEAD/LICENSE.txt) for details

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Support

For questions or issues, please open an issue on GitHub.

- **Repository**: https://github.com/xiaodong-wu/web-design-studio
- **Issues**: https://github.com/xiaodong-wu/web-design-studio/issues