Web Asset Generator

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Type: Claude Skill

This is a **Claude Skill** project. Skills are model-invoked capabilities that Claude automatically triggers based on the description in SKILL.md frontmatter.

### How This Skill Works

- **Entry point**: `SKILL.md` with YAML frontmatter (name + description)
- **Trigger**: Claude reads the description at startup and invokes this skill when users request favicons, app icons, or social media images
- **Execution**: Claude reads SKILL.md instructions and runs the Python scripts in `scripts/`
- **Output**: Generated image assets + HTML meta tags

### Skill Structure

```
web-asset-generator/
├── SKILL.md              # Entry point (name, description, workflows)
├── scripts/
│   ├── generate_favicons.py    # Favicon/app icon generator
│   ├── generate_og_images.py   # Open Graph image generator
│   ├── emoji_utils.py          # Emoji suggestion and rendering
│   └── lib/
│       ├── __init__.py
│       └── validators.py       # Validation utilities (NEW)
└── references/
    └── specifications.md   # Platform specs (FB, Twitter, etc.)
```

## Core Commands

### Generate Favicons/App Icons

**From Image:**
```bash
python scripts/generate_favicons.py <source_image> <output_dir> [icon_type]
# icon_type: 'favicon', 'app', or 'all' (default)
```

**From Emoji (NEW):**
```bash
# Get emoji suggestions
python scripts/generate_favicons.py --suggest "project description" <output_dir> [icon_type]

# Generate from emoji
python scripts/generate_favicons.py --emoji "🚀" <output_dir> [icon_type] [--emoji-bg COLOR]
```

### Generate Social Media Images

**From logo:**
```bash
python scripts/generate_og_images.py <output_dir> --image <source_image>
```

**From text:**
```bash
python scripts/generate_og_images.py <output_dir> --text "Your text" [--logo path] [--bg-color '#4F46E5']
```

### Validation (NEW)

Both scripts support `--validate` flag to check file sizes, dimensions, formats, and accessibility:

```bash
# Validate OG images
python scripts/generate_og_images.py output/ --text "My Site" --validate

# Validate favicons
python scripts/generate_favicons.py logo.png output/ all --validate
```

**What gets validated:**
- **File sizes**: Checks against platform limits (FB <8MB, Twitter <5MB, favicons <100KB)
- **Dimensions**: Verifies sizes match platform specs and aspect ratios
- **Format**: Ensures PNG/JPG/JPEG compatibility
- **Contrast (OG only)**: WCAG AA/AAA compliance for text-based images

## Dependencies

- Python 3.6+
- Pillow: `pip install Pillow --break-system-packages`
- Font path: `/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf` (falls back to default)
- **Pilmoji** (for emoji rendering): `pip install pilmoji` (optional)
- **emoji** (for emoji suggestions): `pip install 'emoji<2.0.0'` (optional, **must use version <2.0.0 for pilmoji compatibility**)

## Implementation Architecture

### generate_favicons.py
- **Image mode**: Converts source to RGBA for transparency, LANCZOS resampling
- **Emoji mode** (NEW): Renders emoji using Pilmoji library, auto-scales to fit icon sizes
- Outputs: favicon.ico (multi-res) + PNGs at 16x16, 32x32, 96x96, 180x180, 192x192, 512x512
- Returns HTML `<link>` tags
- Background: Transparent for favicons, solid (white default) for app icons when using emoji

### emoji_utils.py (NEW)
- **`suggest_emojis(description, count=4)`**: Returns 4 emoji suggestions based on keyword matching
- **`generate_emoji_icon(emoji, size, bg_color)`**: Renders emoji to PIL Image using Pilmoji
- **Emoji database**: 60+ curated emojis with keywords across 10 categories (tech, business, food, health, etc.)
- **Scoring algorithm**: Keyword matching with category diversity for better suggestions

### generate_og_images.py
- **Two modes**: text-based (creates images) or image-based (resizes existing)
- **Outputs**: og-image.png (1200x630), twitter-image.png (1200x675), og-square.png