# Task: Revise Placeholder Images Guide

**Priority:** High  
**Type:** Content revision  
**Related:** Previous guide implementation needs text/UX improvements

---

## Context

Guide exists at `/docs/guides/placeholder-images/page.tsx`. Structure is OK, but texts need revision based on review session. This task covers text changes and minor UX improvements.

---

## SEO Keywords to Include Naturally

Target these in headings and body text:
- "placeholder image url" (390/mo, KD 21)
- "html placeholder image" (320/mo, KD 33)  
- "placeholder image generator" (480/mo, KD 32)
- "ai placeholder images" (from our research)

---

## Section-by-Section Changes

### Hero

**Current subtitle:** "Generate contextual images for development. Copy-paste ready examples with Tailwind CSS."

**New subtitle:** "Generate contextual images for development. The new era of AI placeholders."

Remove Tailwind mention from hero — it's implementation detail, not selling point.

---

### What This Guide Covers

**Current:**
- Live URLs — embed AI-generated images directly in HTML
- Ready-to-use snippets — copy into your project with Tailwind classes
- File download — save images locally via API

**New:**
- **Live URLs** — describe what you need right in `<img>` src URLs
- **API generation** — full control, permanent URLs, downloadable files

Remove "snippets" as separate point — that's expected from any guide.

---

### AI Generation Basics → Rename to "How to Create Placeholders"

**Current content:** Generic AI explanation (prompt → image, enhancement, etc.)

**New content:**

Focus on Banatie features, not AI basics:

**Templates**  
Choose a style, get quality results. Banatie enhances your simple prompt based on selected template.

Available templates:
- `photorealistic` — photo-quality images
- `digital-art` — stylized illustrations
- `3d-render` — 3D graphics

[Link to full templates documentation]

**Simple Prompts**  
Write minimal descriptions. Templates handle the rest.
- "office" → detailed modern office with proper lighting
- "headshot" → professional portrait with studio background

No need for complex prompts — this is for placeholders, not art.

**Remove:**
- "Prompt Enhancement" as separate concept (it's what templates do)
- "Caching" paragraph (belongs to Live URLs section, not here)

---

### Quick Start

**Add intro paragraph** explaining what Live URLs are and why they're perfect for placeholders:

> Live URLs let you generate images by describing what you need right in the URL. No API calls, no file management — just an `<img>` tag with your prompt. Each unique prompt is cached, so subsequent loads are instant via CDN.

**Change example URL** from `{org}/{project}` placeholder to real working URL:

```html
<img
  src="https://cdn.banatie.app/sys/demo/live/test?prompt=mountain+landscape"
  alt="Mountain landscape"
/>
```

**Add live result** — show the actual generated image right after the code snippet.

---

### Organizing Placeholders

**Current:** Dry list of scope examples

**New approach:**

Short explanation: "Organize images by sections of your site using scopes."

One example showing the pattern:
```
/live/avatars?prompt=...  → user photos
/live/hero?prompt=...     → hero backgrounds
/live/products?prompt=... → product catalog
```

Then link: "Learn more about scopes in [Live URLs documentation](/docs/live-urls/#scopes)."

Don't teach users how to name things — let them figure it out.

---

### Prompt Tips

**Current "Be specific"** — contradicts placeholder philosophy

**New "Write less, not more":**

> For placeholders, simple prompts work best. Templates add the details.
>
> - Want an office? Write "office"
> - Need something specific? Add only what matters: "office dark theme"
> - Templates handle lighting, composition, style

**Current "Dark mode"** → **"Colors and themes":**

> Control the mood with color hints:
> - `dark background` — dark theme
> - `blue and orange accents` — specific palette
> - `warm lighting` — cozy feel

Keep dark mode examples but expand to general color control.

**Remove "Consistent style"** — too vague. Consistency comes from templates + references (advanced topic).

**Change TipBox text:**
From: "All examples in this guide use prompt enhancement..."
To: "Templates automatically enhance your prompts. A simple description becomes a detailed generation instruction."

---

### Recipes Section

**Add section header:** Create a parent heading "Recipes" or "Common Use Cases" that groups all the examples (Avatar, Product, Hero, OG, Features).

---

### Recipe Cards: Code + Preview

**UX improvement:** Each recipe should have a tabbed component with "Preview" and "Code" tabs, not separate blocks.

If tabs are complex to implement, at minimum:
- Show live preview FIRST
- Code snippet below with clear label
- Remove redundant "Code Snippet" / "Live Example" headings — visual separation is enough

---

### Testimonial Card (Avatar section)

**Current design:** Basic dark card

**Improve design quality:**
- Add subtle border or gradient
- Better typography hierarchy
- Proper quote styling (quotation marks or left border)
- Make it look like something you'd actually ship

This is our showcase — it should look good.

---

### File-based Workflow

**Current intro:** "Sometimes you need image files in your repository instead of URLs."

**New intro:** "Need files in your repo? Here's how to download generated images."

Warmer, more direct.

**Remove "Static site generators" mention** — no SEO value, weak use case.

**Keep:**
- Next.js with imports (fix the pattern — show `import` from `src/assets`, not `/public`)
- Version-controlled images

**Simplify download example:**

Current code is mini-SDK territory. Simplify to:

```javascript
// 1. Generate image
const response = await fetch('https://api.banatie.app/v1/generations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.BANATIE_API_KEY,
  },
  body: JSON.stringify({ prompt: 'modern office' }),
});

const { image } = await response.json();
console.log(image.cdnUrl); // Download this URL via browser or curl
```

Remove the fs.writeFileSync part — that's SDK territory. User can download via browser.

---

### "When to Use Files" List

**Current:**
- Next.js projects with `/public` folder ❌
- Static site generators requiring local assets ❌
- Version-controlled images
- Offline development

**New:**
- Next.js/React projects with local image imports
- Version-controlled placeholder assets
- Offline or CI/CD environments

---

## Component Changes

### LivePreview wrapper

Current implementation is OK. No changes needed unless design quality is poor.

### Code/Preview tabs

If implementing tabs is too complex, skip for now. But note it as future improvement.

---

## Quality Checklist

After implementation:
- [ ] No mention of "Prompt Enhancement" as standalone feature
- [ ] Templates positioned as primary feature
- [ ] All example URLs use `sys/demo` (real project)
- [ ] Quick Start shows actual generated image
- [ ] File-based section uses import pattern, not /public
- [ ] No static site generators mentioned
- [ ] Testimonial card looks professional
- [ ] SEO keywords naturally integrated

---

## Files to Modify

```
apps/landing/src/app/(apps)/docs/guides/placeholder-images/page.tsx
```

No new files needed.