usulpro
/
banatie-service
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
banatie-service/inbox/task-placeholder-guide-revi...

7.3 KiB
Raw Permalink Blame History

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:

<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."

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:

// 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.