Image Placeholder Guide

Image Placeholder Guide - static.photos Service Documentation

Overview

The image-placeholder-guide skill provides complete documentation for the http://static.photos placeholder image service. This guide is injected into web-builder-initial and web-builder-update prompts so the AI knows how to generate proper placeholder image URLs.

Why Placeholder Images?

During web prototyping and POC development:

• No real images available yet: Project is in concept stage
• Need visual balance: Empty `` tags break layout
• Want themed content: Images should match the project theme (not random cats)
• Require consistency: Same seed → same image across page loads

static.photos Service

URL Format

http://static.photos/[category]/[dimensions]/[seed]

All parameters are optional:

• Omit category → random category
• Omit dimensions → default size (640x360)
• Omit seed → random image each time

Dimensions

Supported sizes (MUST use one of these):

| Dimension | Ratio | Use Case | |-----------|-------|----------| | 200x200 | 1:1 | Avatar, icon, small square | | 320x240 | 4:3 | Thumbnail, card image | | 640x360 | 16:9 | Blog post header, video thumbnail | | 1024x576 | 16:9 | Hero section, featured image | | 1200x630 | ~2:1 | Open Graph, social media preview |

⚠️ Invalid dimensions will fail - only use the 5 sizes above.

Seed Numbers

Purpose: Get consistent images across page loads

• Seed range: Any positive integer (1-999+)
• Same seed = same image: http://static.photos/nature/640x360/42 always returns the same nature image
• Different seed = different image: http://static.photos/nature/640x360/43 returns a different nature image
• Omit seed = random: http://static.photos/nature/640x360 returns random nature image each time

Best practice: Use sequential seeds for multiple images on same page (42, 43, 44...).

Categories

60+ categories available:

Nature & Outdoor

• nature - Natural landscapes, forests, mountains
• aerial - Aerial/drone views
• outdoor - Outdoor scenes
• season - Seasonal imagery (spring, fall, etc.)
• travel - Travel destinations

Professional & Work

• office - Office spaces, workstations
• workspace - Workspace setups
• people - People in various settings
• technology - Tech gadgets, devices
• industry - Industrial scenes

Style & Aesthetic

• minimal - Minimalist compositions
• abstract - Abstract patterns
• blurred - Blurred/out-of-focus
• bokeh - Bokeh effects
• gradient - Gradient backgrounds
• monochrome - Black and white
• vintage - Vintage/retro style

Color-Based

• white - White/light backgrounds
• black - Black/dark backgrounds
• blue - Blue tones
• red - Red tones
• green - Green tones
• yellow - Yellow tones

Urban & Architecture

• cityscape - City skylines, urban scenes
• indoor - Indoor spaces
• studio - Studio photography

Food & Dining

• food - Food photography
• restaurant - Restaurant scenes

Industry-Specific

• finance - Financial/business imagery
• medical - Medical/healthcare
• legal - Legal/professional
• estate - Real estate, property
• retail - Retail, shopping
• wellness - Wellness, spa, relaxation
• agriculture - Farming, agriculture
• construction - Construction, building
• craft - Handicrafts, artisanal
• cosmetic - Beauty, cosmetics
• automotive - Cars, vehicles
• gaming - Gaming, esports
• education - Education, learning

Events & Lifestyle

• holiday - Holidays, celebrations
• event - Events, gatherings
• sport - Sports, athletics

Other

• textures - Textural backgrounds
• science - Scientific imagery

Usage Examples

Example 1: Simple Image (No Parameters)

Result: Random category, default size (640x360), random image

Example 2: Specific Category

Result: Nature image, default size (640x360), random each time

Example 3: Category + Dimensions

Result: Office image, 320×240px, random each time

Example 4: Full URL with Seed

Result: Technology image, 1200×630px, always the same image (seed 42)

Example 5: Multiple Consistent Images

Result: 4 different nature images, all consistent across page loads

Category Selection Guide

For Portfolio Websites

For E-commerce Sites

For Restaurant Websites

For SaaS Landing Pages

For Blog/Content Sites

For Real Estate Sites

For Health/Fitness Sites

Best Practices

1. Consistent Theme

Use the same category for related images to maintain visual coherence:

✅ Good:

❌ Bad (mixed themes):

2. Use Seeds for Consistency

Always use seed numbers for production-like POCs:

✅ Good (with seeds):

❌ Bad (no seed):

3. Match Dimensions to Use Case

Choose appropriate sizes for each element:

| Element | Recommended Size | Example | |---------|------------------|---------| | Avatar | 200x200 | Profile pictures | | Card image | 320x240 | Product cards, blog thumbnails | | Blog post header | 640x360 | Article headers | | Hero section | 1024x576 | Landing page hero | | Open Graph | 1200x630 | Social media previews |

4. Sequential Seeds for Sets

Use consecutive seeds for image sets:

5. Category Fallbacks

If unsure about category, use safe defaults:

• General purpose: minimal, abstract, white
• Professional: office, workspace, technology
• Creative: nature, gradient, bokeh
• Commercial: retail, white, studio

Common Mistakes

Mistake 1: Invalid Dimensions

❌ Wrong:

✅ Correct:

Mistake 2: Typo in Category

❌ Wrong:

✅ Correct:

Mistake 3: Missing Alt Text

❌ Wrong:

✅ Correct:

Mistake 4: No Seed for Important Images

❌ Wrong:

✅ Correct:

Prompt Injection Template

This section shows how to inject the image placeholder guide into web-builder prompts.

For web-builder-initial

Add this to the system prompt:

If you want to use image placeholder, http://static.photos Usage:

Format: http://static.photos/[category]/[dimensions]/[seed]

where:
- dimensions must be one of: 200x200, 320x240, 640x360, 1024x576, or 1200x630
- seed can be any number (1-999+) for consistent images or omit for random
- categories include: nature, office, people, technology, minimal, abstract, aerial,
  blurred, bokeh, gradient, monochrome, vintage, white, black, blue, red, green,
  yellow, cityscape, workspace, food, travel, textures, industry, indoor, outdoor,
  studio, finance, medical, season, holiday, event, sport, science, legal, estate,
  restaurant, retail, wellness, agriculture, construction, craft, cosmetic,
  automotive, gaming, education

Examples:
- http://static.photos/red/320x240/133 (red-themed with seed 133)
- http://static.photos/640x360 (random category and image)
- http://static.photos/nature/1200x630/42 (nature-themed with seed 42)

IMPORTANT: Always use seeds for consistent placeholder images. Choose categories that
match your project theme (e.g., 'food' for restaurant sites, 'office' for SaaS).

For web-builder-update

Same injection, but add a note about consistency:

[Same content as above]

IMPORTANT: When adding new images to existing project, maintain consistency:
- Use the same category as existing images
- Use sequential seed numbers (if existing images use seeds 1-5, use 6-10 for new images)
- Match dimensions to similar elements

Integration with web-builder Skills

In web-builder-initial SKILL.md

Add to System Prompt section:

## System Prompt (with Image Placeholder Guide)

When calling the LLM, inject the image placeholder guide into the prompt:

```python
INITIAL_PROMPT = f"""
{INITIAL_SYSTEM_PROMPT}

{IMAGE_PLACEHOLDER_GUIDE}

User Request: {user_request}
"""

Where IMAGE_PLACEHOLDER_GUIDE is the content from this skill.

### In web-builder-update SKILL.md

Similar injection pattern:

```markdown
## System Prompt (with Image Placeholder Guide)

```python
UPDATE_PROMPT = f"""
{FOLLOW_UP_SYSTEM_PROMPT}

{IMAGE_PLACEHOLDER_GUIDE}

Current Files:
{current_files}

User Request: {user_request}
"""

## Testing

### Test Case 1: Verify URL Format

```python
def test_placeholder_url():
    url = "http://static.photos/nature/640x360/42"

    # Test URL is accessible
    import requests
    response = requests.get(url)

    assert response.status_code == 200
    assert response.headers['Content-Type'].startswith('image/')
    print("✅ URL format valid")

Test Case 2: Verify Consistency

def test_seed_consistency():
    import requests
    import hashlib

    url = "http://static.photos/nature/640x360/42"

    # Fetch same URL twice
    response1 = requests.get(url)
    response2 = requests.get(url)

    # Compare content hashes
    hash1 = hashlib.md5(response1.content).hexdigest()
    hash2 = hashlib.md5(response2.content).hexdigest()

    assert hash1 == hash2, "Same seed should return same image"
    print("✅ Seed consistency verified")

Test Case 3: Verify Dimensions

def test_dimensions():
    from PIL import Image
    from io import BytesIO
    import requests

    url = "http://static.photos/nature/640x360/42"
    response = requests.get(url)

    img = Image.open(BytesIO(response.content))
    assert img.size == (640, 360), f"Expected 640x360, got {img.size}"
    print("✅ Dimensions correct")

Bilingual Version (Chinese)

中文版本

如果你想使用图片占位符,可以使用 http://static.photos 服务:

格式: http://static.photos/[分类]/[尺寸]/[种子]

其中:
- 尺寸必须是以下之一: 200x200, 320x240, 640x360, 1024x576, 或 1200x630
- 种子可以是任意数字 (1-999+) 用于获取一致的图片,或省略以获取随机图片
- 分类包括: nature(自然), office(办公), people(人物), technology(科技), minimal(极简),
  abstract(抽象), aerial(航拍), blurred(模糊), bokeh(景深), gradient(渐变),
  monochrome(单色), vintage(复古), white(白色), black(黑色), blue(蓝色), red(红色),
  green(绿色), yellow(黄色), cityscape(城市), workspace(工作空间), food(美食),
  travel(旅行), textures(纹理), industry(工业), indoor(室内), outdoor(户外),
  studio(工作室), finance(金融), medical(医疗), season(季节), holiday(节日),
  event(活动), sport(体育), science(科学), legal(法律), estate(房地产),
  restaurant(餐厅), retail(零售), wellness(健康), agriculture(农业),
  construction(建筑), craft(手工艺), cosmetic(美容), automotive(汽车),
  gaming(游戏), education(教育)

示例:
- http://static.photos/red/320x240/133 (红色主题,种子133)
- http://static.photos/640x360 (随机分类和图片)
- http://static.photos/nature/1200x630/42 (自然主题,种子42)

重要: 始终使用种子以获得一致的占位图片。选择与项目主题匹配的分类
(例如,餐厅网站使用 'food',SaaS 使用 'office')。

Summary

This guide ensures that:

1. ✅ AI knows how to use static.photos correctly
2. ✅ Generated code uses valid dimensions (5 supported sizes only)
3. ✅ Images have consistent seeds for production-like POCs
4. ✅ Categories match project themes
5. ✅ Alt text is always included for accessibility
6. ✅ Image URLs follow best practices

When injected into web-builder prompts, this guide eliminates common placeholder image errors and produces professional-looking POC websites with themed, consistent placeholder images.

---

Implementation Status: ✅ Complete - Ready for injection BuildFlow Source: /mnt/oldroot/home/bird/buildflow/lib/prompts.ts line 13, 403-405 Dependencies: None (documentation only) Used By: web-builder-initial, web-builder-update (as prompt context) Last Updated: 2026-03-30

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: youyouhe
• Source: youyouhe/bidsmart-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.