MohamedAbdallah-14/prompt-to-asset

# App icon generation

## Platform requirements (non-negotiable)

| Platform | Size/format | Transparency | Safe zone |
|---|---|---|---|
| **iOS App Store** | 1024×1024 PNG, **no alpha** | **opaque** | squircle mask applied by OS; keep subject in 824px center |
| iOS device | 180, 167, 152, 120, 87, 80, 76, 60, 58, 40, 29, 20 (@1x, @2x, @3x) | opaque | same |
| iOS 18 dark / tinted | Icon Composer layered source | per-layer | same |
| **Android adaptive** | 108 dp foreground + 108 dp background; 72 dp visible safe zone | FG yes / BG no | 72 dp of 108 dp |
| Android 13 monochrome | themed drawable | yes | same |
| Google Play | 512×512 PNG, no alpha | opaque | — |
| **PWA** | 192, 512 `any`; 512 `maskable` | `maskable`: opaque + 80% safe zone | 80% of 512 for maskable |
| **visionOS** | 3× 1024² PNGs (parallax layers) | per-layer | — |

# asset-enhancer skill

Comprehensive behavior spec for producing production-grade software-development assets. Drives every `asset_*` MCP tool.

## Cardinal rules

> 1. Producing production-grade software assets is a **routing + post-processing** problem, not a prompt-engineering problem.
> 2. The user may not have an image-model API key. The plugin must work anyway.
> 3. There are real zero-key and free-token paths — always surface them first before asking the user to pay for anything. The `free_api.routes` block in `asset_capabilities()` enumerates the ranked free programmatic routes: Cloudflare Workers AI (Flux-1-Schnell + SDXL, 10k neurons/day), NVIDIA NIM (Flux / SDXL / SANA, 1k requests/month with `NVIDIA_API_KEY`, no card), HF Inference (free `HF_TOKEN`), Stable Horde (anonymous queue), Pollinations (zero-signup HTTP, last resort), and local ComfyUI. **Google's Gemini / Imagen image API is paid for programmatic image output** — unbilled `GEMINI_API_KEY` → HTTP 429, `limit: 0`. The AI Studio **web UI** at https://aistudio.google.com is still free for interactive generation — treat it as a paste-only flow (`external_prompt_only` → `asset_ingest_external`).

See `rules/asset-enhancer-activate.md` for the condensed always-on version. This file is the long-form spec.

## Three execution modes

# Asset validation + repair

Triggered when `asset_validate()`, `asset_generate_*`, or `asset_save_inline_svg` returns warnings or errors. Do NOT loop on the same failure; follow the tree and respect the retry budget.

## Failure code → repair table

| Code | Origin | Repair primitive | Retry budget |
|---|---|---|---|
| `T0_CHECKERBOARD` | Imagen/Gemini rendering fake transparency | **Route change** → `gpt-image-1` (`background:"transparent"`), Ideogram v3 (`style:"transparent"`), Recraft V3 | 2 |
| `T0_ALPHA_MISSING` | RGB-only output on transparency-required asset | **Matte** via `asset_remove_background` (BiRefNet preferred, RMBG fallback) | 1 |
| `T0_DIMENSIONS` | wrong `width`/`height` API params | Fix params, regenerate | 1 |
| `T0_SAFE_ZONE` | subject bleeds outside platform center | Regenerate with explicit `"centered with 20% padding on all sides"` | 1 |
| `T0_FILE_SIZE` (SVG) | path count blows budget | `asset_save_inline_svg` → SVGO → K-means color reduction → vtracer | 1 |
| `T0_DCT_ENTROPY` | solid-color / NSFW-filter hit | Regenerate same params once; if repeats, change prompt | 1 |

# Brand consistency

Engaged when a user is generating more than one asset for the same brand, or when an existing `brand.json` / `brand.md` is in play. Wraps `asset_brand_bundle_parse`, `asset_generate_*`, and validation.

## BrandBundle shape

```yaml
palette:
  - { name: primary,   hex: "#0A1F44", usage: mark }
  - { name: accent,    hex: "#FF6B6B", usage: highlight }
  - { name: neutral,   hex: "#FAFAFA", usage: background }
typography:
  primary:   { family: "Geist Sans", fallback: "geometric sans-serif, bold" }
  secondary: { family: "Geist Mono", fallback: "monospace" }

# Favicon generation

## What modern browsers actually want (see research 11)

```html
<link rel="icon" href="/favicon.ico" sizes="any">
<link rel="icon" type="image/svg+xml" href="/icon.svg">
<link rel="icon" type="image/svg+xml" href="/icon-dark.svg" media="(prefers-color-scheme: dark)">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">
<link rel="manifest" href="/manifest.webmanifest">
```

| File | Size | Alpha | Notes |
|---|---|---|---|

# Illustration generation

## The consistency problem

A single illustration is easy. **A set of twelve in the same style** is the hard problem. Research 10 + 15: prompt words drift; reference images do not. Any illustration skill must inject a brand style reference at every call.

## Routing

| Model | Brand lock mechanism | Best for |
|---|---|---|
| **Flux Pro / Flux.2** | `reference_images[]` (up to 8 in Flux.2) + brand LoRA | Photoreal, stylized 3D, brand illustration sets |
| **SDXL + brand LoRA** | trained LoRA (6d recipe, ~5k steps on 20 images) | Bespoke brand style, open-weight |
| **Recraft V3** | `style_id` (brand magic) | Flat vector, editorial illustration |
| **Ideogram 3** | style codes | Loose "same vibe" — not strict lock |

# Logo generation

## Spec
- **Master:** 1024×1024 RGBA PNG, transparent background, subject centered in 80% safe zone
- **Vector:** SVG, ≤200 paths, fixed viewBox, SVGO optimized
- **Monochrome:** 1-color mono variant (auto-derived via luminance threshold or separate generation)
- **Wordmark routing — model-specific, not blanket:**
  - **Paragraph-length OK:** `gpt-image-2`, `gemini-3-pro-image-preview` (Nano Banana Pro), `gpt-image-1.5`. Include the wordmark in the prompt; composite stays safer for pixel-exact UI copy.
  - **3–10 words reliable:** `ideogram-3` / `ideogram-3-turbo`, `gemini-3.1-flash-image-preview` (Nano Banana 2), `gpt-image-1`, `flux-2` family.
  - **≤3 words / ≤25 chars:** Imagen 4 family, Recraft V4.
  - **Composite always:** Flux 1.x, Flux Schnell, SDXL, SD 1.5, Mystic, Pollinations, original Nano Banana 1.

## Routing by intent
| text in mark? | vector needed? | primary | fallback |

# OG image generation

## Spec

- **Dimensions:** 1200×630 (OG 1.91:1) primary. Optional: 1080×1080 square (Instagram), 2:1 Twitter Card `summary_large_image`.
- **Format:** PNG or JPEG, <5MB, served over absolute HTTPS URL, no auth headers.
- **Text:** Deterministic — use Satori + real fonts. **Never sample typography from a diffusion model** for OG cards; headlines get garbled (see logo skill § 3-word rule).
- **Headline:** ≤8 words, 64–96pt. Subheadline: ≤15 words, 28–36pt.
- **Contrast:** WCAG AA min 4.5:1 (Slack/Discord render inside their own color backgrounds).

## Architecture

**Default: template-based, no diffusion.** The OG engine is:

# SVG authoring (inline_svg mode)

Engaged when `asset_generate_*` returns an `InlineSvgPlan`. Read `svg_brief` (viewBox, palette, path_budget, require[], do_not[], skeleton) and emit one `<svg>…</svg>` code block that honors every constraint. Then call `asset_save_inline_svg({ svg, asset_type })` so the file lands on disk.

## Hard constraints (non-negotiable)

| Asset type | viewBox | Path budget | Colors | Safe-zone | Notes |
|---|---|---|---|---|---|
| `logo` | `0 0 120 120` (or brief-specified) | ≤40 | 2–4 hex | subject fits inside 80% center box | Flat, geometric, closed shapes |
| `favicon` (master SVG) | `0 0 64 64` | ≤30 | 2–3 hex | legible at 16×16 after downsampling | ≥2px stroke equivalent at 16² |
| `icon_pack` (per icon) | `0 0 24 24` | ≤8 | monocolor (`currentColor`) OR 2 tones | 2px grid, 1.5–2px strokes | All icons share grid + stroke weight |
| `sticker` | `0 0 240 240` | ≤60 | up to 6 hex | bleed allowed; no hard edge requirement | Chunkier line weights OK |
| `transparent_mark` | `0 0 200 200` | ≤40 | 2–3 hex | 80% center | Never emit `<rect fill="white">` as "background" |
| `app_icon` master | `0 0 1024 1024` | ≤60 | 3–5 hex | iOS HIG 824² center | Opaque bg allowed; no alpha needed on this one |

# T2I prompt dialect

Runs between `asset_enhance_prompt()` and `asset_generate_*()`. Takes a normalized brief plus a target model and emits a prompt that honors that model's syntax, token budget, and quirks.

## Per-model rules (quick card, verified Apr 2026)

| Model | Grammar | Token / char ceiling | Negative prompt | Transparency | Text ceiling |
|---|---|---|---|---|---|
| `gpt-image-2` | Prose | ~100 words | silently ignored | **NOT supported — `background:"transparent"` 400s** (regression vs 1.5) — route transparent jobs to gpt-image-1.5 instead | ~80 chars / paragraph (~99% accuracy per third-party tests) |
| `gpt-image-1.5` | Prose | ~100 words | silently ignored | API param `background: "transparent"` | dense text ~60 chars (LM Arena #1) |
| `gpt-image-1` | Prose | ~100 words | silently ignored | API param `background: "transparent"` | ~50 chars / ≤5 words |
| Imagen 4 (Fast/Standard/Ultra) | Narrative prose, ≥30 words suppresses auto-rewriter | unbounded | **`negativePrompt` accepted on Vertex AI; ignored on Gemini API** | never request in prompt (renders checkerboard as RGB) | ≤25 chars per Google's own guidance |
| Gemini 3.1 Flash Image (Nano Banana 2) | Prose | unbounded | ignored | renders checkerboard | ~50 chars / ~90% accuracy (#1 Image Arena at launch — strong-text, not weak) |
| Gemini 3 Pro Image (Nano Banana Pro) | Prose | unbounded | ignored | renders checkerboard | paragraph-length reliable (~94-96% accuracy) |

# Transparent background

## The problem (see research 13 + 04)

Almost every modern T2I VAE is **RGB-only**. Asking Imagen 3/4 or Gemini 2.5/3 Flash Image for a "transparent logo" triggers one of two failures:

1. **Flat background** — DALL·E 3, Stable Diffusion families render a white/gray background that must be matted.
2. **Checkerboard as RGB pixels** — Gemini/Imagen literally render the gray-and-white 8×8 tile pattern (because Photoshop screenshots in their training data show transparency that way). This is the "weird boxes" users report. **It cannot be fixed by prompting.**

## Fix hierarchy (apply first that fits)

### 1. Route to a native-RGBA provider

| Provider | Mechanism |

# ui-mockup-prompt

This skill turns a UI brief into a single paste-ready prompt for a strong-text image model (gpt-image-2, Nano Banana Pro, Ideogram 3 Turbo, Flux 2 Pro, Midjourney v7) that produces designer-quality mockups for **inspiration**, not pixel-exact production UI.

The output is for a working designer to riff on. They will redo the spacing, the radius, the font, the exact palette. What they need from the image is a **visual direction with soul** — one that isn't AI-default purple-gradient-on-white-Inter-rounded-card slop.

## Four things this skill must do, in order

1. **Identify the surface and its job.** A pricing page, a dashboard, a settings screen, an onboarding flow — each has a different job. Aesthetic commitment is constrained by what the surface must *do*, not chosen freely. Look the surface up in `references/surface-patterns.md`.
2. **Pick the right model.** Text density, transparency need, available references, and budget all flow into a routing decision the calling agent should not have to think about.
3. **Compose a slot-labeled prompt** in that model's specific dialect, with the universal anti-slop rules, craft-grounded design intelligence, and the surface's UX-pattern requirements baked in.
4. **Return the bundle:** chosen model + reasoning + paste-ready prompt + multi-ref recipe (if the user has refs) + validation reminder (with surface-specific UX checks).

The prompt should resist AI defaults *by construction*. The model still has freedom — the skill commits to one bold aesthetic direction *constrained by the surface's job* and writes the prompt around it, instead of letting the model fall back to indigo + Inter + rounded cards OR to editorially-polished output that violates the page's UX fundamentals.

# Vectorize

## Three paths

### 1. Recraft `/vectorize` (hosted, highest quality)

Input: any raster. Output: clean SVG, typically 20–100 paths for a mark, 200–500 for an illustration. Commercial tier only.

```ts
const svg = await recraft.vectorize({ image: pngBuffer });
```

### 2. `vtracer` (local, multi-color polygon)

# App icon generation

## Platform requirements (non-negotiable)

| Platform | Size/format | Transparency | Safe zone |
|---|---|---|---|
| **iOS App Store** | 1024×1024 PNG, **no alpha** | **opaque** | squircle mask applied by OS; keep subject in 824px center |
| iOS device | 180, 167, 152, 120, 87, 80, 76, 60, 58, 40, 29, 20 (@1x, @2x, @3x) | opaque | same |
| iOS 18 dark / tinted | Icon Composer layered source | per-layer | same |
| **Android adaptive** | 108 dp foreground + 108 dp background; 72 dp visible safe zone | FG yes / BG no | 72 dp of 108 dp |
| Android 13 monochrome | themed drawable | yes | same |
| Google Play | 512×512 PNG, no alpha | opaque | — |
| **PWA** | 192, 512 `any`; 512 `maskable` | `maskable`: opaque + 80% safe zone | 80% of 512 for maskable |
| **visionOS** | 3× 1024² PNGs (parallax layers) | per-layer | — |

# asset-enhancer skill

Comprehensive behavior spec for producing production-grade software-development assets. Drives every `asset_*` MCP tool.

## Cardinal rules

> 1. Producing production-grade software assets is a **routing + post-processing** problem, not a prompt-engineering problem.
> 2. The user may not have an image-model API key. The plugin must work anyway.
> 3. There are real zero-key and free-token paths — always surface them first before asking the user to pay for anything. The `free_api.routes` block in `asset_capabilities()` enumerates the ranked free programmatic routes: Cloudflare Workers AI (Flux-1-Schnell + SDXL, 10k neurons/day), NVIDIA NIM (Flux / SDXL / SANA, 1k requests/month with `NVIDIA_API_KEY`, no card), HF Inference (free `HF_TOKEN`), Stable Horde (anonymous queue), Pollinations (zero-signup HTTP, last resort), and local ComfyUI. **Google's Gemini / Imagen image API is paid for programmatic image output** — unbilled `GEMINI_API_KEY` → HTTP 429, `limit: 0`. The AI Studio **web UI** at https://aistudio.google.com is still free for interactive generation — treat it as a paste-only flow (`external_prompt_only` → `asset_ingest_external`).

See `rules/asset-enhancer-activate.md` for the condensed always-on version. This file is the long-form spec.

## Three execution modes

# Asset validation + repair

Triggered when `asset_validate()`, `asset_generate_*`, or `asset_save_inline_svg` returns warnings or errors. Do NOT loop on the same failure; follow the tree and respect the retry budget.

## Failure code → repair table

| Code | Origin | Repair primitive | Retry budget |
|---|---|---|---|
| `T0_CHECKERBOARD` | Imagen/Gemini rendering fake transparency | **Route change** → `gpt-image-1` (`background:"transparent"`), Ideogram v3 (`style:"transparent"`), Recraft V3 | 2 |
| `T0_ALPHA_MISSING` | RGB-only output on transparency-required asset | **Matte** via `asset_remove_background` (BiRefNet preferred, RMBG fallback) | 1 |
| `T0_DIMENSIONS` | wrong `width`/`height` API params | Fix params, regenerate | 1 |
| `T0_SAFE_ZONE` | subject bleeds outside platform center | Regenerate with explicit `"centered with 20% padding on all sides"` | 1 |
| `T0_FILE_SIZE` (SVG) | path count blows budget | `asset_save_inline_svg` → SVGO → K-means color reduction → vtracer | 1 |
| `T0_DCT_ENTROPY` | solid-color / NSFW-filter hit | Regenerate same params once; if repeats, change prompt | 1 |

# Brand consistency

Engaged when a user is generating more than one asset for the same brand, or when an existing `brand.json` / `brand.md` is in play. Wraps `asset_brand_bundle_parse`, `asset_generate_*`, and validation.

## BrandBundle shape

```yaml
palette:
  - { name: primary,   hex: "#0A1F44", usage: mark }
  - { name: accent,    hex: "#FF6B6B", usage: highlight }
  - { name: neutral,   hex: "#FAFAFA", usage: background }
typography:
  primary:   { family: "Geist Sans", fallback: "geometric sans-serif, bold" }
  secondary: { family: "Geist Mono", fallback: "monospace" }

# Favicon generation

## What modern browsers actually want (see research 11)

```html
<link rel="icon" href="/favicon.ico" sizes="any">
<link rel="icon" type="image/svg+xml" href="/icon.svg">
<link rel="icon" type="image/svg+xml" href="/icon-dark.svg" media="(prefers-color-scheme: dark)">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">
<link rel="manifest" href="/manifest.webmanifest">
```

| File | Size | Alpha | Notes |
|---|---|---|---|

# Illustration generation

## The consistency problem

A single illustration is easy. **A set of twelve in the same style** is the hard problem. Research 10 + 15: prompt words drift; reference images do not. Any illustration skill must inject a brand style reference at every call.

## Routing

| Model | Brand lock mechanism | Best for |
|---|---|---|
| **Flux Pro / Flux.2** | `reference_images[]` (up to 8 in Flux.2) + brand LoRA | Photoreal, stylized 3D, brand illustration sets |
| **SDXL + brand LoRA** | trained LoRA (6d recipe, ~5k steps on 20 images) | Bespoke brand style, open-weight |
| **Recraft V3** | `style_id` (brand magic) | Flat vector, editorial illustration |
| **Ideogram 3** | style codes | Loose "same vibe" — not strict lock |

# Logo generation

## Spec
- **Master:** 1024×1024 RGBA PNG, transparent background, subject centered in 80% safe zone
- **Vector:** SVG, ≤200 paths, fixed viewBox, SVGO optimized
- **Monochrome:** 1-color mono variant (auto-derived via luminance threshold or separate generation)
- **Wordmark routing — model-specific, not blanket:**
  - **Paragraph-length OK:** `gpt-image-2`, `gemini-3-pro-image-preview` (Nano Banana Pro), `gpt-image-1.5`. Include the wordmark in the prompt; composite stays safer for pixel-exact UI copy.
  - **3–10 words reliable:** `ideogram-3` / `ideogram-3-turbo`, `gemini-3.1-flash-image-preview` (Nano Banana 2), `gpt-image-1`, `flux-2` family.
  - **≤3 words / ≤25 chars:** Imagen 4 family, Recraft V4.
  - **Composite always:** Flux 1.x, Flux Schnell, SDXL, SD 1.5, Mystic, Pollinations, original Nano Banana 1.

## Routing by intent
| text in mark? | vector needed? | primary | fallback |

# OG image generation

## Spec

- **Dimensions:** 1200×630 (OG 1.91:1) primary. Optional: 1080×1080 square (Instagram), 2:1 Twitter Card `summary_large_image`.
- **Format:** PNG or JPEG, <5MB, served over absolute HTTPS URL, no auth headers.
- **Text:** Deterministic — use Satori + real fonts. **Never sample typography from a diffusion model** for OG cards; headlines get garbled (see logo skill § 3-word rule).
- **Headline:** ≤8 words, 64–96pt. Subheadline: ≤15 words, 28–36pt.
- **Contrast:** WCAG AA min 4.5:1 (Slack/Discord render inside their own color backgrounds).

## Architecture

**Default: template-based, no diffusion.** The OG engine is:

# SVG authoring (inline_svg mode)

Engaged when `asset_generate_*` returns an `InlineSvgPlan`. Read `svg_brief` (viewBox, palette, path_budget, require[], do_not[], skeleton) and emit one `<svg>…</svg>` code block that honors every constraint. Then call `asset_save_inline_svg({ svg, asset_type })` so the file lands on disk.

## Hard constraints (non-negotiable)

| Asset type | viewBox | Path budget | Colors | Safe-zone | Notes |
|---|---|---|---|---|---|
| `logo` | `0 0 120 120` (or brief-specified) | ≤40 | 2–4 hex | subject fits inside 80% center box | Flat, geometric, closed shapes |
| `favicon` (master SVG) | `0 0 64 64` | ≤30 | 2–3 hex | legible at 16×16 after downsampling | ≥2px stroke equivalent at 16² |
| `icon_pack` (per icon) | `0 0 24 24` | ≤8 | monocolor (`currentColor`) OR 2 tones | 2px grid, 1.5–2px strokes | All icons share grid + stroke weight |
| `sticker` | `0 0 240 240` | ≤60 | up to 6 hex | bleed allowed; no hard edge requirement | Chunkier line weights OK |
| `transparent_mark` | `0 0 200 200` | ≤40 | 2–3 hex | 80% center | Never emit `<rect fill="white">` as "background" |
| `app_icon` master | `0 0 1024 1024` | ≤60 | 3–5 hex | iOS HIG 824² center | Opaque bg allowed; no alpha needed on this one |

# T2I prompt dialect

Runs between `asset_enhance_prompt()` and `asset_generate_*()`. Takes a normalized brief plus a target model and emits a prompt that honors that model's syntax, token budget, and quirks.

## Per-model rules (quick card, verified Apr 2026)

| Model | Grammar | Token / char ceiling | Negative prompt | Transparency | Text ceiling |
|---|---|---|---|---|---|
| `gpt-image-2` | Prose | ~100 words | silently ignored | **NOT supported — `background:"transparent"` 400s** (regression vs 1.5) — route transparent jobs to gpt-image-1.5 instead | ~80 chars / paragraph (~99% accuracy per third-party tests) |
| `gpt-image-1.5` | Prose | ~100 words | silently ignored | API param `background: "transparent"` | dense text ~60 chars (LM Arena #1) |
| `gpt-image-1` | Prose | ~100 words | silently ignored | API param `background: "transparent"` | ~50 chars / ≤5 words |
| Imagen 4 (Fast/Standard/Ultra) | Narrative prose, ≥30 words suppresses auto-rewriter | unbounded | **`negativePrompt` accepted on Vertex AI; ignored on Gemini API** | never request in prompt (renders checkerboard as RGB) | ≤25 chars per Google's own guidance |
| Gemini 3.1 Flash Image (Nano Banana 2) | Prose | unbounded | ignored | renders checkerboard | ~50 chars / ~90% accuracy (#1 Image Arena at launch — strong-text, not weak) |
| Gemini 3 Pro Image (Nano Banana Pro) | Prose | unbounded | ignored | renders checkerboard | paragraph-length reliable (~94-96% accuracy) |

# Transparent background

## The problem (see research 13 + 04)

Almost every modern T2I VAE is **RGB-only**. Asking Imagen 3/4 or Gemini 2.5/3 Flash Image for a "transparent logo" triggers one of two failures:

1. **Flat background** — DALL·E 3, Stable Diffusion families render a white/gray background that must be matted.
2. **Checkerboard as RGB pixels** — Gemini/Imagen literally render the gray-and-white 8×8 tile pattern (because Photoshop screenshots in their training data show transparency that way). This is the "weird boxes" users report. **It cannot be fixed by prompting.**

## Fix hierarchy (apply first that fits)

### 1. Route to a native-RGBA provider

| Provider | Mechanism |

# ui-mockup-prompt

This skill turns a UI brief into a single paste-ready prompt for a strong-text image model (gpt-image-2, Nano Banana Pro, Ideogram 3 Turbo, Flux 2 Pro, Midjourney v7) that produces designer-quality mockups for **inspiration**, not pixel-exact production UI.

The output is for a working designer to riff on. They will redo the spacing, the radius, the font, the exact palette. What they need from the image is a **visual direction with soul** — one that isn't AI-default purple-gradient-on-white-Inter-rounded-card slop.

## Four things this skill must do, in order

1. **Identify the surface and its job.** A pricing page, a dashboard, a settings screen, an onboarding flow — each has a different job. Aesthetic commitment is constrained by what the surface must *do*, not chosen freely. Look the surface up in `references/surface-patterns.md`.
2. **Pick the right model.** Text density, transparency need, available references, and budget all flow into a routing decision the calling agent should not have to think about.
3. **Compose a slot-labeled prompt** in that model's specific dialect, with the universal anti-slop rules, craft-grounded design intelligence, and the surface's UX-pattern requirements baked in.
4. **Return the bundle:** chosen model + reasoning + paste-ready prompt + multi-ref recipe (if the user has refs) + validation reminder (with surface-specific UX checks).

The prompt should resist AI defaults *by construction*. The model still has freedom — the skill commits to one bold aesthetic direction *constrained by the surface's job* and writes the prompt around it, instead of letting the model fall back to indigo + Inter + rounded cards OR to editorially-polished output that violates the page's UX fundamentals.

# Vectorize

## Three paths

### 1. Recraft `/vectorize` (hosted, highest quality)

Input: any raster. Output: clean SVG, typically 20–100 paths for a mark, 200–500 for an illustration. Commercial tier only.

```ts
const svg = await recraft.vectorize({ image: pngBuffer });
```

### 2. `vtracer` (local, multi-color polygon)

# App icon generation

## Platform requirements (non-negotiable)

| Platform | Size/format | Transparency | Safe zone |
|---|---|---|---|
| **iOS App Store** | 1024×1024 PNG, **no alpha** | **opaque** | squircle mask applied by OS; keep subject in 824px center |
| iOS device | 180, 167, 152, 120, 87, 80, 76, 60, 58, 40, 29, 20 (@1x, @2x, @3x) | opaque | same |
| iOS 18 dark / tinted | Icon Composer layered source | per-layer | same |
| **Android adaptive** | 108 dp foreground + 108 dp background; 72 dp visible safe zone | FG yes / BG no | 72 dp of 108 dp |
| Android 13 monochrome | themed drawable | yes | same |
| Google Play | 512×512 PNG, no alpha | opaque | — |
| **PWA** | 192, 512 `any`; 512 `maskable` | `maskable`: opaque + 80% safe zone | 80% of 512 for maskable |
| **visionOS** | 3× 1024² PNGs (parallax layers) | per-layer | — |

# asset-enhancer skill

Comprehensive behavior spec for producing production-grade software-development assets. Drives every `asset_*` MCP tool.

## Cardinal rules

> 1. Producing production-grade software assets is a **routing + post-processing** problem, not a prompt-engineering problem.
> 2. The user may not have an image-model API key. The plugin must work anyway.
> 3. There are real zero-key and free-token paths — always surface them first before asking the user to pay for anything. The `free_api.routes` block in `asset_capabilities()` enumerates the ranked free programmatic routes: Cloudflare Workers AI (Flux-1-Schnell + SDXL, 10k neurons/day), NVIDIA NIM (Flux / SDXL / SANA, 1k requests/month with `NVIDIA_API_KEY`, no card), HF Inference (free `HF_TOKEN`), Stable Horde (anonymous queue), Pollinations (zero-signup HTTP, last resort), and local ComfyUI. **Google's Gemini / Imagen image API is paid for programmatic image output** — unbilled `GEMINI_API_KEY` → HTTP 429, `limit: 0`. The AI Studio **web UI** at https://aistudio.google.com is still free for interactive generation — treat it as a paste-only flow (`external_prompt_only` → `asset_ingest_external`).

See `rules/asset-enhancer-activate.md` for the condensed always-on version. This file is the long-form spec.

## Three execution modes

# Asset validation + repair

Triggered when `asset_validate()`, `asset_generate_*`, or `asset_save_inline_svg` returns warnings or errors. Do NOT loop on the same failure; follow the tree and respect the retry budget.

## Failure code → repair table

| Code | Origin | Repair primitive | Retry budget |
|---|---|---|---|
| `T0_CHECKERBOARD` | Imagen/Gemini rendering fake transparency | **Route change** → `gpt-image-1` (`background:"transparent"`), Ideogram v3 (`style:"transparent"`), Recraft V3 | 2 |
| `T0_ALPHA_MISSING` | RGB-only output on transparency-required asset | **Matte** via `asset_remove_background` (BiRefNet preferred, RMBG fallback) | 1 |
| `T0_DIMENSIONS` | wrong `width`/`height` API params | Fix params, regenerate | 1 |
| `T0_SAFE_ZONE` | subject bleeds outside platform center | Regenerate with explicit `"centered with 20% padding on all sides"` | 1 |
| `T0_FILE_SIZE` (SVG) | path count blows budget | `asset_save_inline_svg` → SVGO → K-means color reduction → vtracer | 1 |
| `T0_DCT_ENTROPY` | solid-color / NSFW-filter hit | Regenerate same params once; if repeats, change prompt | 1 |

# Brand consistency

Engaged when a user is generating more than one asset for the same brand, or when an existing `brand.json` / `brand.md` is in play. Wraps `asset_brand_bundle_parse`, `asset_generate_*`, and validation.

## BrandBundle shape

```yaml
palette:
  - { name: primary,   hex: "#0A1F44", usage: mark }
  - { name: accent,    hex: "#FF6B6B", usage: highlight }
  - { name: neutral,   hex: "#FAFAFA", usage: background }
typography:
  primary:   { family: "Geist Sans", fallback: "geometric sans-serif, bold" }
  secondary: { family: "Geist Mono", fallback: "monospace" }

# Favicon generation

## What modern browsers actually want (see research 11)

```html
<link rel="icon" href="/favicon.ico" sizes="any">
<link rel="icon" type="image/svg+xml" href="/icon.svg">
<link rel="icon" type="image/svg+xml" href="/icon-dark.svg" media="(prefers-color-scheme: dark)">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">
<link rel="manifest" href="/manifest.webmanifest">
```

| File | Size | Alpha | Notes |
|---|---|---|---|

# Illustration generation

## The consistency problem

A single illustration is easy. **A set of twelve in the same style** is the hard problem. Research 10 + 15: prompt words drift; reference images do not. Any illustration skill must inject a brand style reference at every call.

## Routing

| Model | Brand lock mechanism | Best for |
|---|---|---|
| **Flux Pro / Flux.2** | `reference_images[]` (up to 8 in Flux.2) + brand LoRA | Photoreal, stylized 3D, brand illustration sets |
| **SDXL + brand LoRA** | trained LoRA (6d recipe, ~5k steps on 20 images) | Bespoke brand style, open-weight |
| **Recraft V3** | `style_id` (brand magic) | Flat vector, editorial illustration |
| **Ideogram 3** | style codes | Loose "same vibe" — not strict lock |

# Logo generation

## Spec
- **Master:** 1024×1024 RGBA PNG, transparent background, subject centered in 80% safe zone
- **Vector:** SVG, ≤200 paths, fixed viewBox, SVGO optimized
- **Monochrome:** 1-color mono variant (auto-derived via luminance threshold or separate generation)
- **Wordmark routing — model-specific, not blanket:**
  - **Paragraph-length OK:** `gpt-image-2`, `gemini-3-pro-image-preview` (Nano Banana Pro), `gpt-image-1.5`. Include the wordmark in the prompt; composite stays safer for pixel-exact UI copy.
  - **3–10 words reliable:** `ideogram-3` / `ideogram-3-turbo`, `gemini-3.1-flash-image-preview` (Nano Banana 2), `gpt-image-1`, `flux-2` family.
  - **≤3 words / ≤25 chars:** Imagen 4 family, Recraft V4.
  - **Composite always:** Flux 1.x, Flux Schnell, SDXL, SD 1.5, Mystic, Pollinations, original Nano Banana 1.

## Routing by intent
| text in mark? | vector needed? | primary | fallback |

# OG image generation

## Spec

- **Dimensions:** 1200×630 (OG 1.91:1) primary. Optional: 1080×1080 square (Instagram), 2:1 Twitter Card `summary_large_image`.
- **Format:** PNG or JPEG, <5MB, served over absolute HTTPS URL, no auth headers.
- **Text:** Deterministic — use Satori + real fonts. **Never sample typography from a diffusion model** for OG cards; headlines get garbled (see logo skill § 3-word rule).
- **Headline:** ≤8 words, 64–96pt. Subheadline: ≤15 words, 28–36pt.
- **Contrast:** WCAG AA min 4.5:1 (Slack/Discord render inside their own color backgrounds).

## Architecture

**Default: template-based, no diffusion.** The OG engine is:

# SVG authoring (inline_svg mode)

Engaged when `asset_generate_*` returns an `InlineSvgPlan`. Read `svg_brief` (viewBox, palette, path_budget, require[], do_not[], skeleton) and emit one `<svg>…</svg>` code block that honors every constraint. Then call `asset_save_inline_svg({ svg, asset_type })` so the file lands on disk.

## Hard constraints (non-negotiable)

| Asset type | viewBox | Path budget | Colors | Safe-zone | Notes |
|---|---|---|---|---|---|
| `logo` | `0 0 120 120` (or brief-specified) | ≤40 | 2–4 hex | subject fits inside 80% center box | Flat, geometric, closed shapes |
| `favicon` (master SVG) | `0 0 64 64` | ≤30 | 2–3 hex | legible at 16×16 after downsampling | ≥2px stroke equivalent at 16² |
| `icon_pack` (per icon) | `0 0 24 24` | ≤8 | monocolor (`currentColor`) OR 2 tones | 2px grid, 1.5–2px strokes | All icons share grid + stroke weight |
| `sticker` | `0 0 240 240` | ≤60 | up to 6 hex | bleed allowed; no hard edge requirement | Chunkier line weights OK |
| `transparent_mark` | `0 0 200 200` | ≤40 | 2–3 hex | 80% center | Never emit `<rect fill="white">` as "background" |
| `app_icon` master | `0 0 1024 1024` | ≤60 | 3–5 hex | iOS HIG 824² center | Opaque bg allowed; no alpha needed on this one |

# T2I prompt dialect

Runs between `asset_enhance_prompt()` and `asset_generate_*()`. Takes a normalized brief plus a target model and emits a prompt that honors that model's syntax, token budget, and quirks.

## Per-model rules (quick card, verified Apr 2026)

| Model | Grammar | Token / char ceiling | Negative prompt | Transparency | Text ceiling |
|---|---|---|---|---|---|
| `gpt-image-2` | Prose | ~100 words | silently ignored | **NOT supported — `background:"transparent"` 400s** (regression vs 1.5) — route transparent jobs to gpt-image-1.5 instead | ~80 chars / paragraph (~99% accuracy per third-party tests) |
| `gpt-image-1.5` | Prose | ~100 words | silently ignored | API param `background: "transparent"` | dense text ~60 chars (LM Arena #1) |
| `gpt-image-1` | Prose | ~100 words | silently ignored | API param `background: "transparent"` | ~50 chars / ≤5 words |
| Imagen 4 (Fast/Standard/Ultra) | Narrative prose, ≥30 words suppresses auto-rewriter | unbounded | **`negativePrompt` accepted on Vertex AI; ignored on Gemini API** | never request in prompt (renders checkerboard as RGB) | ≤25 chars per Google's own guidance |
| Gemini 3.1 Flash Image (Nano Banana 2) | Prose | unbounded | ignored | renders checkerboard | ~50 chars / ~90% accuracy (#1 Image Arena at launch — strong-text, not weak) |
| Gemini 3 Pro Image (Nano Banana Pro) | Prose | unbounded | ignored | renders checkerboard | paragraph-length reliable (~94-96% accuracy) |

# Transparent background

## The problem (see research 13 + 04)

Almost every modern T2I VAE is **RGB-only**. Asking Imagen 3/4 or Gemini 2.5/3 Flash Image for a "transparent logo" triggers one of two failures:

1. **Flat background** — DALL·E 3, Stable Diffusion families render a white/gray background that must be matted.
2. **Checkerboard as RGB pixels** — Gemini/Imagen literally render the gray-and-white 8×8 tile pattern (because Photoshop screenshots in their training data show transparency that way). This is the "weird boxes" users report. **It cannot be fixed by prompting.**

## Fix hierarchy (apply first that fits)

### 1. Route to a native-RGBA provider

| Provider | Mechanism |

# ui-mockup-prompt

This skill turns a UI brief into a single paste-ready prompt for a strong-text image model (gpt-image-2, Nano Banana Pro, Ideogram 3 Turbo, Flux 2 Pro, Midjourney v7) that produces designer-quality mockups for **inspiration**, not pixel-exact production UI.

The output is for a working designer to riff on. They will redo the spacing, the radius, the font, the exact palette. What they need from the image is a **visual direction with soul** — one that isn't AI-default purple-gradient-on-white-Inter-rounded-card slop.

## Four things this skill must do, in order

1. **Identify the surface and its job.** A pricing page, a dashboard, a settings screen, an onboarding flow — each has a different job. Aesthetic commitment is constrained by what the surface must *do*, not chosen freely. Look the surface up in `references/surface-patterns.md`.
2. **Pick the right model.** Text density, transparency need, available references, and budget all flow into a routing decision the calling agent should not have to think about.
3. **Compose a slot-labeled prompt** in that model's specific dialect, with the universal anti-slop rules, craft-grounded design intelligence, and the surface's UX-pattern requirements baked in.
4. **Return the bundle:** chosen model + reasoning + paste-ready prompt + multi-ref recipe (if the user has refs) + validation reminder (with surface-specific UX checks).

The prompt should resist AI defaults *by construction*. The model still has freedom — the skill commits to one bold aesthetic direction *constrained by the surface's job* and writes the prompt around it, instead of letting the model fall back to indigo + Inter + rounded cards OR to editorially-polished output that violates the page's UX fundamentals.

# Vectorize

## Three paths

### 1. Recraft `/vectorize` (hosted, highest quality)

Input: any raster. Output: clean SVG, typically 20–100 paths for a mark, 200–500 for an illustration. Commercial tier only.

```ts
const svg = await recraft.vectorize({ image: pngBuffer });
```

### 2. `vtracer` (local, multi-color polygon)