@open-assets/open-assets 0.1.10 → 0.1.12

package/README.md

@@ -1,15 +1,34 @@
-# open-assets
+<p align="center">
+  <img src="public/img/banner/1280/banner.png" alt="Open Assets" width="100%" />
+</p>
+
+# Open Assets
+
+The LLM first way to do graphics all from your git repo. 
 
 Dev server and export tool for app marketing assets. Like Storybook, but for marketing assets.
 
 Design your App Store screenshots, app icons, logos, OG images, favicons, and more in HTML/CSS/SVG, preview them live in the browser, and export pixel-perfect PNGs at any size — including directly into your Xcode project.
 
-## Quick Start
+## Installation
 
 ```bash
-# Install
-npm install --save-dev open-assets
+# npm
+npm install --save-dev @open-assets/open-assets
+
+# yarn
+yarn add --dev @open-assets/open-assets
+
+# pnpm
+pnpm add --save-dev @open-assets/open-assets
+
+# bun
+bun add --dev @open-assets/open-assets
+```
+
+## Quick Start
 
+```bash
 # Scaffold a new project
 npx open-assets init
 
@@ -17,6 +36,22 @@ npx open-assets init
 npx open-assets dev
 ```
 
+## Shell Alias
+
+Add an alias to your shell profile for a shorter command:
+
+```bash
+echo 'alias oa="npx open-assets"' >> ~/.zshrc && source ~/.zshrc
+```
+
+Then use `oa` anywhere:
+
+```bash
+oa dev
+oa render --all
+oa init
+```
+
 ## Concepts
 
 open-assets uses a simple, unified data model. Every asset type follows the same structure: **N templates × M export sizes**.
@@ -26,7 +61,6 @@ open-assets uses a simple, unified data model. Every asset type follows the same
 | **Collection** | A named group of related assets sharing the same source size and export sizes. One tab in the dev UI. |
 | **Template** | A single source file (HTML or SVG) that produces one image per export size. |
 | **Export Size** | A named output dimension that templates are rendered at (e.g., "iPhone 6.9" → 1320×2868). |
-| **Platform** | Optional grouping label for related export sizes (e.g., "App Store", "Play Store"). |
 | **Source Size** | The dimensions the HTML template is authored at. Puppeteer scales from source → export size. |
 | **Output** | An optional post-render action (e.g., write to Xcode `.appiconset`, copy SVG source). |
 
@@ -38,21 +72,30 @@ open-assets uses a simple, unified data model. Every asset type follows the same
 npx open-assets init
 ```
 
-Creates a `manifest.json`, sample HTML templates, and a `public/` directory for shared assets.
+Creates a `assets.json`, sample HTML templates, and a `public/` directory for shared assets.
 
 ### 2. Design with Claude Code
 
-Install the open-assets Claude skill, then prompt:
+Install the open-assets Claude Code skill into your project:
+
+```bash
+# Using the built-in command
+npx open-assets skills
+
+# Or using the Skills CLI
+npx skills add https://github.com/Parra-Inc/open-assets --skill open-assets
+```
+
+This copies the skill into `.claude/skills/open-assets/` so Claude Code can use it. Then prompt:
 
 ```
-Now we want to make beautiful screenshots for this app. Install the open-assets
-skill from https://github.com/parra-inc/open-assets. Look at the marketing
+Now we want to make beautiful screenshots for this app. Look at the marketing
 doc and demographics. Design 8 high-converting App Store screenshots that catch
 your eye as you scroll. Use bold headlines with highlighted keywords, phone
 mockups with real app screenshots, and close with reviews + a CTA.
 ```
 
-Claude reads your `manifest.json` and `publicDir` to understand the project structure, then creates screenshot HTML files using the design patterns in the skill.
+Claude reads your `assets.json` and `publicDir` to understand the project structure, then creates screenshot HTML files using the design patterns in the skill.
 
 ### 3. Preview
 
@@ -95,7 +138,7 @@ Reference captured screenshots in your HTML templates:
 <img src="../../public/screenshots/01-home.png" style="width: 100%; height: 100%; object-fit: cover;" />
 ```
 
-The `manifest.json` `command` field stores the export command so automation tools know what to run:
+The `assets.json` `command` field stores the export command so automation tools know what to run:
 ```json
 {
   "command": "npx open-assets render --all"
@@ -117,7 +160,7 @@ open-assets dev --no-open              # Don't auto-open browser
 open-assets dev --quiet                # Suppress server logs
 open-assets dev --ci                   # CI mode (quiet + no browser)
 open-assets dev --static-dir ./shared  # Serve additional static directories
-open-assets dev --manifest config.json # Use a custom manifest filename
+open-assets dev --config config.json # Use a custom config filename
 ```
 
 Options:
@@ -128,7 +171,7 @@ Options:
 | `--no-open` | `OPEN_ASSETS_NO_OPEN` | — | Don't auto-open the browser |
 | `-q, --quiet` | `OPEN_ASSETS_QUIET` | `false` | Suppress server logs |
 | `--ci` | `CI` | `false` | CI mode: quiet + no browser |
-| `--manifest <path>` | `OPEN_ASSETS_MANIFEST` | `manifest.json` | Path to manifest file |
+| `--config <path>` | `OPEN_ASSETS_CONFIG` | `assets.json` | Path to config file |
 | `--static-dir <dirs...>` | — | — | Additional static directories to serve |
 | `--render-timeout <ms>` | `OPEN_ASSETS_RENDER_TIMEOUT` | `30000` | Puppeteer render timeout |
 
@@ -142,7 +185,6 @@ open-assets render --all                        # Export at EVERY configured siz
 open-assets render --collection screenshots     # Render a specific collection
 open-assets render --template 01-hero           # Render a single template
 open-assets render --size iphone-6.9            # Use a named export size
-open-assets render --platform "App Store"       # Render all sizes for a platform
 open-assets render --width 1320 --height 2868   # Custom size
 open-assets render --force                      # Re-render everything, ignore cache
 open-assets render -o ./build                   # Custom output directory
@@ -155,14 +197,13 @@ Options:
 |------|---------|---------|-------------|
 | `--collection <id>` | — | all | Render only the collection with this ID |
 | `--template <name>` | — | all | Render only the template with this name |
-| `--size <name>` | — | — | Use a named export size from manifest |
-| `--platform <name>` | — | — | Render only sizes for this platform |
+| `--size <name>` | — | — | Use a named export size from config |
 | `--width <px>` | — | — | Custom output width |
 | `--height <px>` | — | — | Custom output height |
-| `--all` | — | — | Export at every size defined in the manifest |
+| `--all` | — | — | Export at every size defined in the config |
 | `--force` | — | — | Re-render all assets even if unchanged |
 | `-o, --output <dir>` | `OPEN_ASSETS_OUTPUT` | `./exports` | Output directory |
-| `--manifest <path>` | `OPEN_ASSETS_MANIFEST` | `manifest.json` | Path to manifest file |
+| `--config <path>` | `OPEN_ASSETS_CONFIG` | `assets.json` | Path to config file |
 | `--parallel <count>` | `OPEN_ASSETS_PARALLEL` | `1` | Number of parallel renders |
 | `--render-timeout <ms>` | `OPEN_ASSETS_RENDER_TIMEOUT` | `30000` | Puppeteer render timeout |
 | `--json` | — | — | Output results as JSON |
@@ -178,9 +219,6 @@ open-assets render --collection screenshots --template 01-hero --all
 
 # All templates at one device size
 open-assets render --collection screenshots --size iphone-6.9
-
-# All templates for a specific platform
-open-assets render --collection screenshots --platform "App Store"
 ```
 
 **Output structure**: `exports/{collection}/{size}/{template}.png`
@@ -209,7 +247,7 @@ exports/
 
 ### `open-assets list [dir]`
 
-List all collections and templates defined in the manifest.
+List all collections and templates defined in the config.
 
 ```bash
 open-assets list              # Pretty-print asset tree
@@ -218,7 +256,7 @@ open-assets list --json       # Output as JSON
 
 ### `open-assets validate [dir]`
 
-Validate the manifest and check that all referenced source files exist.
+Validate the config and check that all referenced source files exist.
 
 ```bash
 open-assets validate          # Check current directory
@@ -227,9 +265,21 @@ open-assets validate ./assets # Check specific directory
 
 Returns exit code 1 if any errors are found — useful in CI pipelines.
 
+### `open-assets skills [dir]`
+
+Install Claude Code skills into your project. Copies skill files to `.claude/skills/` so Claude Code can generate and manage marketing assets.
+
+```bash
+open-assets skills            # Install to current project
+open-assets skills ./my-app   # Install to a specific project
+
+# Or using the Skills CLI
+npx skills add https://github.com/Parra-Inc/open-assets --skill open-assets
+```
+
 ### `open-assets init [dir]`
 
-Scaffold a new project with a `manifest.json`, sample HTML templates, and a `public/` directory.
+Scaffold a new project with a `assets.json`, sample HTML templates, and a `public/` directory.
 
 ```bash
 open-assets init              # Current directory
@@ -238,7 +288,7 @@ open-assets init ./my-assets  # Specific directory
 
 ## Manifest Format
 
-Your project needs a `manifest.json` at its root. This file defines the collections shown in the viewer and all export options.
+Your project needs a `assets.json` at its root. This file defines the collections shown in the viewer and all export options.
 
 ```json
 {
@@ -274,14 +324,9 @@ All collections follow the same structure. No `type` field needed.
     { "src": "src/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
     { "src": "src/screenshots/02-features.html", "name": "02-features", "label": "Features" }
   ],
-  "exportSizes": [
-    {
-      "platform": "App Store",
-      "sizes": [
-        { "name": "iphone-6.9", "label": "iPhone 6.9\"", "width": 1320, "height": 2868 },
-        { "name": "iphone-6.7", "label": "iPhone 6.7\"", "width": 1290, "height": 2796 }
-      ]
-    }
+  "export": [
+    { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } },
+    { "name": "iphone-6.7", "label": "iPhone 6.7\"", "size": { "width": 1290, "height": 2796 } }
   ],
   "outputs": [
     { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
@@ -299,9 +344,11 @@ All collections follow the same structure. No `type` field needed.
 | `templates[].src` | string | Path to HTML/SVG file (relative to project root) |
 | `templates[].name` | string | Filename for exports (used by `--template` flag) |
 | `templates[].label` | string | Display label |
-| `exportSizes` | array | Grouped export size definitions |
-| `exportSizes[].platform` | string | Optional grouping label |
-| `exportSizes[].sizes[]` | object | `{ name, label, width, height }` |
+| `export` | array | Flat array of export size definitions |
+| `export[].name` | string | Size identifier (used by `--size` flag) |
+| `export[].label` | string | Display label |
+| `export[].size` | object | `{ width, height }` — output dimensions in pixels |
+| `export[].outFile` | string | Optional output path for this size (supports .png, .jpg) |
 | `outputs` | array | Optional post-render actions |
 | `customExport` | object | Optional `{ defaultWidth, defaultHeight }` for custom size UI |
 
@@ -325,16 +372,11 @@ All collections follow the same structure. No `type` field needed.
     { "src": "src/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
     { "src": "src/screenshots/02-import.html", "name": "02-import", "label": "Import" }
   ],
-  "exportSizes": [
-    {
-      "platform": "App Store",
-      "sizes": [
-        { "name": "iphone-6.9", "label": "iPhone 6.9\"", "width": 1320, "height": 2868 },
-        { "name": "iphone-6.7", "label": "iPhone 6.7\"", "width": 1290, "height": 2796 },
-        { "name": "iphone-6.5", "label": "iPhone 6.5\"", "width": 1284, "height": 2778 },
-        { "name": "iphone-6.1", "label": "iPhone 6.1\"", "width": 1179, "height": 2556 }
-      ]
-    }
+  "export": [
+    { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } },
+    { "name": "iphone-6.7", "label": "iPhone 6.7\"", "size": { "width": 1290, "height": 2796 } },
+    { "name": "iphone-6.5", "label": "iPhone 6.5\"", "size": { "width": 1284, "height": 2778 } },
+    { "name": "iphone-6.1", "label": "iPhone 6.1\"", "size": { "width": 1179, "height": 2556 } }
   ]
 }
 ```
@@ -349,15 +391,10 @@ All collections follow the same structure. No `type` field needed.
   "templates": [
     { "src": "src/icon.html", "name": "icon", "label": "App Icon" }
   ],
-  "exportSizes": [
-    {
-      "platform": "Apple",
-      "sizes": [
-        { "name": "1024", "label": "1024px", "width": 1024, "height": 1024 },
-        { "name": "180", "label": "180px", "width": 180, "height": 180 },
-        { "name": "120", "label": "120px", "width": 120, "height": 120 }
-      ]
-    }
+  "export": [
+    { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
+    { "name": "180", "label": "180px", "size": { "width": 180, "height": 180 } },
+    { "name": "120", "label": "120px", "size": { "width": 120, "height": 120 } }
   ],
   "outputs": [
     { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
@@ -377,13 +414,9 @@ All collections follow the same structure. No `type` field needed.
     { "src": "src/icons/concept-b.html", "name": "concept-b", "label": "Concept B" },
     { "src": "src/icons/seasonal-winter.html", "name": "seasonal-winter", "label": "Winter" }
   ],
-  "exportSizes": [
-    {
-      "sizes": [
-        { "name": "1024", "label": "1024px", "width": 1024, "height": 1024 },
-        { "name": "512", "label": "512px", "width": 512, "height": 512 }
-      ]
-    }
+  "export": [
+    { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
+    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } }
   ]
 }
 ```
@@ -399,14 +432,10 @@ All collections follow the same structure. No `type` field needed.
     { "src": "src/logo-dark.svg", "name": "logo-dark", "label": "Dark" },
     { "src": "src/wordmark.svg", "name": "wordmark", "label": "Wordmark" }
   ],
-  "exportSizes": [
-    {
-      "sizes": [
-        { "name": "2048", "label": "2048px", "width": 2048, "height": 2048 },
-        { "name": "1024", "label": "1024px", "width": 1024, "height": 1024 },
-        { "name": "512", "label": "512px", "width": 512, "height": 512 }
-      ]
-    }
+  "export": [
+    { "name": "2048", "label": "2048px", "size": { "width": 2048, "height": 2048 } },
+    { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
+    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } }
   ],
   "outputs": [
     { "type": "copy-source", "format": "svg" }
@@ -423,8 +452,8 @@ All collections follow the same structure. No `type` field needed.
   "templates": [
     { "src": "src/og/default.html", "name": "default", "label": "Default OG" }
   ],
-  "exportSizes": [
-    { "sizes": [{ "name": "og", "label": "OG Image", "width": 1200, "height": 630 }] }
+  "export": [
+    { "name": "og", "label": "OG Image", "size": { "width": 1200, "height": 630 } }
   ]
 }
 ```
@@ -438,29 +467,19 @@ All collections follow the same structure. No `type` field needed.
   "templates": [
     { "src": "src/favicon.html", "name": "favicon", "label": "Favicon" }
   ],
-  "exportSizes": [
-    {
-      "platform": "Web",
-      "sizes": [
-        { "name": "512", "label": "512px", "width": 512, "height": 512 },
-        { "name": "192", "label": "192px", "width": 192, "height": 192 },
-        { "name": "32", "label": "32px", "width": 32, "height": 32 },
-        { "name": "16", "label": "16px", "width": 16, "height": 16 }
-      ]
-    },
-    {
-      "platform": "Apple",
-      "sizes": [
-        { "name": "apple-touch", "label": "Apple Touch Icon", "width": 180, "height": 180 }
-      ]
-    }
+  "export": [
+    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } },
+    { "name": "192", "label": "192px", "size": { "width": 192, "height": 192 } },
+    { "name": "32", "label": "32px", "size": { "width": 32, "height": 32 }, "outFile": "public/favicon.png" },
+    { "name": "16", "label": "16px", "size": { "width": 16, "height": 16 } },
+    { "name": "apple-touch", "label": "Apple Touch Icon", "size": { "width": 180, "height": 180 }, "outFile": "public/apple-touch-icon.png" }
   ]
 }
 ```
 
-## Incremental Builds with manifest.lock
+## Incremental Builds with assets.lock
 
-The `render` command maintains a `manifest.lock` file that stores SHA256 checksums of each source HTML/SVG file. On subsequent renders, unchanged assets are skipped automatically:
+The `render` command maintains a `assets.lock` file that stores SHA256 checksums of each source HTML/SVG file. On subsequent renders, unchanged assets are skipped automatically:
 
 ```
 $ open-assets render --all
@@ -475,7 +494,7 @@ Use `--force` to re-render everything regardless of the cache.
 
 **Limitation**: Only source HTML/SVG files are checksummed. Changes to referenced assets (images in `publicDir`, compiled Tailwind CSS) won't trigger re-renders — use `--force` when those change.
 
-Add `manifest.lock` to your `.gitignore` (done automatically by `open-assets init`).
+Add `assets.lock` to your `.gitignore` (done automatically by `open-assets init`).
 
 ## CI/CD with GitHub Actions
 
@@ -487,7 +506,7 @@ on:
   push:
     paths:
       - 'marketing/screenshots/**'
-      - 'marketing/screenshots/manifest.json'
+      - 'marketing/screenshots/assets.json'
 jobs:
   export:
     runs-on: ubuntu-latest
@@ -524,8 +543,8 @@ jobs:
 
 ```
 project/
-  manifest.json
-  manifest.lock              # Auto-generated cache (gitignored)
+  assets.json
+  assets.lock              # Auto-generated cache (gitignored)
   public/                    # Shared assets (configured via publicDir)
     logo-round.png
     social/