docs: add more pages

Author: chrisbbreuer

docs/features/app-icons.md

@@ -0,0 +1,189 @@
+# App Icon Generation
+
+imgx provides powerful tools for generating app icons for iOS, macOS, and other platforms from a single source image.
+
+## Overview
+
+When developing applications, you need icons in various sizes for different platforms, devices, and contexts. Creating these manually is time-consuming and error-prone. imgx automates this process, generating all required icon sizes from a single high-resolution source image.
+
+## Supported Platforms
+
+- **iOS**: All icon sizes required for iPhone and iPad apps, including App Store icons
+- **macOS**: App icons for Mac applications, including the .icns format
+- **Web**: Favicon sets including various sizes and formats
+- **Android**: Coming soon (currently in beta)
+
+## Basic Usage
+
+### CLI
+
+```bash
+# Generate all app icons (iOS and macOS) from a single image
+imgx app-icon source-icon.png
+
+# Generate only iOS app icons
+imgx app-icon source-icon.png --platform ios
+
+# Generate only macOS app icons
+imgx app-icon source-icon.png --platform macos
+
+# Specify output directory
+imgx app-icon source-icon.png --output-dir ./assets/app-icons
+```
+
+### JavaScript/TypeScript API
+
+```ts
+import { createAppIcon } from '@stacksjs/imgx'
+
+// Generate all app icons
+const result = await createAppIcon('path/to/source-icon.png')
+
+// Generate only iOS icons
+const iosIcons = await createAppIcon('path/to/source-icon.png', {
+  platform: 'ios',
+  outputDir: './public/app-icons',
+})
+
+console.log(`Generated ${iosIcons.sizes.length} icons for ${iosIcons.platform}`)
+```
+
+## Source Image Requirements
+
+For best results, your source image should meet these requirements:
+
+- **Resolution**: At least 1024×1024 pixels (higher is better)
+- **Format**: PNG with transparency
+- **Content**: Place important content within the center 80% of the image (avoid corners)
+- **Style**: Follow platform-specific guidelines (i.e., rounded corners for iOS)
+- **Color**: Vibrant, distinctive and legible at small sizes
+
+## Generated Icons
+
+### iOS Icons
+
+imgx generates all iOS app icon sizes required by Apple, including:
+
+| Size | Purpose |
+|------|---------|
+| 20×20 pt @1x, @2x, @3x | Notification icon |
+| 29×29 pt @1x, @2x, @3x | Settings icon |
+| 40×40 pt @1x, @2x, @3x | Spotlight icon |
+| 60×60 pt @2x, @3x | iPhone app icon |
+| 76×76 pt @1x, @2x | iPad app icon |
+| 83.5×83.5 pt @2x | iPad Pro app icon |
+| 1024×1024 px | App Store icon |
+
+The output includes a properly formatted `Contents.json` file for use in Xcode projects.
+
+### macOS Icons
+
+For macOS applications, imgx generates:
+
+| Size | Purpose |
+|------|---------|
+| 16×16 pt @1x, @2x | Menu bar, Spotlight, Finder |
+| 32×32 pt @1x, @2x | Finder, Desktop |
+| 128×128 pt @1x, @2x | Finder, File Info |
+| 256×256 pt @1x, @2x | Finder, File Info |
+| 512×512 pt @1x, @2x | App Store |
+
+The output includes a `.icns` file that can be used directly in macOS applications.
+
+## Output Structure
+
+By default, imgx creates this directory structure:
+
+```
+output-dir/
+├── ios/
+│   ├── AppIcon.appiconset/
+│   │   ├── Contents.json
+│   │   ├── [email protected]
+│   │   ├── [email protected]
+│   │   ├── ... (all other iOS sizes)
+│   │   └── Icon-1024.png
+├── macos/
+│   ├── AppIcon.appiconset/
+│   │   ├── Contents.json
+│   │   ├── Icon-16.png
+│   │   ├── [email protected]
+│   │   ├── ... (all other macOS sizes)
+│   │   └── [email protected]
+│   └── AppIcon.icns
+```
+
+## Advanced Usage
+
+### Custom Background
+
+For platforms that don't support transparency (like iOS App Store), you can specify a background color:
+
+```bash
+imgx app-icon icon.png --background "#ffffff"
+```
+
+```ts
+await createAppIcon('icon.png', {
+  background: '#ffffff', // or 'rgba(255, 255, 255, 0.5)' for semi-transparent
+})
+```
+
+### Custom Filename Template
+
+You can customize the filename pattern:
+
+```bash
+imgx app-icon icon.png --filename-template "custom-[size]@[scale]x.[ext]"
+```
+
+```ts
+await createAppIcon('icon.png', {
+  filenameTemplate: 'custom-[size]@[scale]x.[ext]',
+})
+```
+
+Available placeholders:
+- `[size]`: Icon size (e.g., 20, 29, 40)
+- `[scale]`: Scale factor (1, 2, 3)
+- `[ext]`: File extension (png)
+- `[platform]`: Platform name (ios, macos)
+
+### Generating Specific Sizes
+
+You can generate only specific sizes if needed:
+
+```bash
+imgx app-icon icon.png --platform ios --sizes 20,29,40
+```
+
+```ts
+await createAppIcon('icon.png', {
+  platform: 'ios',
+  sizes: [20, 29, 40], // Only generate these sizes
+})
+```
+
+## Integration with Xcode
+
+The generated iOS and macOS AppIcon.appiconset directories can be directly used in Xcode:
+
+1. Generate the icons using imgx
+2. Drag the entire `.appiconset` folder into your Xcode project
+3. Select your target and set the AppIcon set as your app icon
+
+## Configuration
+
+You can set default app icon generation options in your imgx.config.ts file:
+
+```ts
+// imgx.config.ts
+export default {
+  appIcon: {
+    outputDir: 'assets/app-icons',
+    platform: 'all', // 'ios', 'macos', or 'all'
+    background: '#ffffff', // Background for non-transparent contexts
+    filenameTemplate: 'Icon-[size]@[scale]x.[ext]',
+  },
+}
+```