# PWA Icons - Usage Guide

Complete PWA icon converter toolkit located at `ADP/pwa-icons/`

## 📁 Structure

```
ADP/pwa-icons/
├── README.md                    ← Overview & quick start
├── USAGE.md                     ← This file
├── src/                         ← Conversion scripts
│   ├── convert-apple-icon.js    ← Node.js (recommended)
│   ├── convert_apple.py         ← Python alternative
│   └── generate_icons.sh        ← Bash alternative
├── public/                      ← Generated assets & web app
│   ├── converter.html           ← Browser-based converter
│   ├── manifest.json            ← Sample manifest
│   └── html-head-snippet.html   ← HTML snippets
├── docs/                        ← Documentation
│   ├── QUICK_START.md           ← Quick reference
│   ├── PWA_ICON_GUIDE.md        ← Full guide
│   └── APPLE_CONVERTER_README.txt
└── package-icon-converter.json  ← NPM dependencies
```

## 🚀 Quick Start

### Method 1: Browser Converter (Easiest)

```bash
# Open in your browser
open ADP/pwa-icons/public/converter.html
# or
file:///var/www/vhosts/adp.dev.portalpeople.co.uk/dev/ADP/pwa-icons/public/converter.html

# Then:
# 1. Drag & drop your apple.jpg
# 2. Click "Generate All Sizes"
# 3. Right-click to download each PNG
```

### Method 2: Node.js (Fastest)

```bash
cd ADP/pwa-icons

# Install dependencies (first time only)
npm install

# Run converter
node src/convert-apple-icon.js apple.jpg public
```

### Method 3: Python

```bash
cd ADP/pwa-icons

# Install dependencies (first time only)
pip install Pillow

# Run converter
python3 src/convert_apple.py apple.jpg
```

### Method 4: Bash Script

```bash
cd ADP/pwa-icons

# Run script
bash src/generate_icons.sh apple.jpg
```

## 📦 Output Files

All methods generate 11 PNG files:

```
apple-512.png (512×512)
apple-384.png (384×384)
apple-256.png (256×256)
apple-192.png (192×192)
apple-touch-icon-180.png (180×180)
apple-touch-icon-167.png (167×167)
apple-touch-icon-152.png (152×152)
apple-touch-icon-120.png (120×120)
apple-96.png (96×96)
apple-64.png (64×64)
apple-32.png (32×32)
```

Plus:
- `manifest.json` - Sample PWA manifest
- `html-head-snippet.html` - HTML integration code

## 🔌 Integration Steps

1. **Convert your image** using any method above

2. **Copy icons to your project:**
   ```bash
   cp ADP/pwa-icons/public/apple-*.png your-app/public/icons/
   ```

3. **Add HTML tags** from `public/html-head-snippet.html`:
   ```html
   <link rel="apple-touch-icon" href="/icons/apple-touch-icon-180.png">
   <link rel="apple-touch-icon" href="/icons/apple-touch-icon-167.png" sizes="167x167">
   <link rel="apple-touch-icon" href="/icons/apple-touch-icon-152.png" sizes="152x152">
   <link rel="icon" type="image/png" href="/icons/apple-192.png">
   ```

4. **Update manifest.json:**
   ```json
   "icons": [
     {"src": "/icons/apple-192.png", "sizes": "192x192", "type": "image/png"},
     {"src": "/icons/apple-512.png", "sizes": "512x512", "type": "image/png"}
   ]
   ```

## 📚 Documentation

- **README.md** - Overview & features
- **QUICK_START.md** - Quick reference guide
- **PWA_ICON_GUIDE.md** - Complete specifications
- **APPLE_CONVERTER_README.txt** - Detailed setup guide

See `docs/` folder for full documentation.

## ✅ Testing

### iOS
1. Safari → Website → Share → Add to Home Screen
2. Your icon appears on home screen

### Android
1. Chrome → Website → Menu → Install app
2. Your icon appears

### Desktop
1. Chrome/Edge → Website → Install icon
2. Your icon appears in taskbar

## 🛠 Troubleshooting

**Browser converter doesn't work?**
- Try a different browser (Chrome, Edge, Safari)
- Check browser console for errors

**Node.js converter fails?**
- Run: `npm install` in `ADP/pwa-icons/`
- Ensure Node.js v14+ is installed

**Python converter fails?**
- Run: `pip install Pillow`
- Ensure Python 3 is installed

**Bash script not working?**
- ImageMagick is installed ✅ (v6.9.11)
- Run: `bash src/generate_icons.sh apple.jpg`
- Make sure source image exists in current directory
- Clear Safari cache
- Wait a few minutes for cache refresh
- Test with incognito/private browsing

**Icon looks blurry?**
- Use larger source image (1024×1024+)
- Use PNG format for best quality

## 📍 Location Reference

Current working directory: `/var/www/vhosts/adp.dev.portalpeople.co.uk/dev/`

Files are located at:
- Scripts: `./ADP/pwa-icons/src/`
- Generated: `./ADP/pwa-icons/public/`
- Docs: `./ADP/pwa-icons/docs/`

## 🔗 Resources

- [Web App Manifest Spec](https://www.w3.org/TR/appmanifest/)
- [Apple Startup Image Guide](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/)
- [Android App Requirements](https://support.google.com/googleplay/android-developer/answer/1078870)
- [PWA Builder](https://www.pwabuilder.com/)

---

**Location:** `ADP/pwa-icons/`  
**Ready to use!** 🚀
