🎯 Koubou (工房) - The Artisan Workshop for App Store Screenshots

Koubou (工房) transforms YAML into handcrafted App Store screenshots with artisan quality.

工房 (koubou) means "artisan's workshop" in Japanese - where masters create their finest work. Every screenshot is carefully crafted with professional precision using device frames, rich backgrounds, and elegant typography.

✨ Features

• 🔄 Live Editing - Real-time screenshot regeneration when config or assets change
• 🖥️ Live Preview Dashboard - Auto-open a local dashboard for screenshot previews with hot reload
• 🧩 HTML/CSS Templates - Render polished marketing layouts with Chrome or Playwright Chromium
• 🌍 Multi-Language Localization - Generate localized screenshots using familiar xcstrings format from Xcode
• 🖼️ Localized Assets - Automatic language-specific asset resolution with convention-based and explicit mapping
• 🎨 100+ Device Frames - iPhone 16 Pro, iPad Air M2, MacBook Pro, Apple Watch Ultra, and more
• 🌈 Professional Backgrounds - Linear, radial, conic gradients with precise color control
• ✨ Rich Typography - Advanced text overlays with stroke, alignment, wrapping, and custom fonts
• 🌈 Gradient Typography - Linear, radial, and conic gradients for text with custom color stops
• 📱 YAML-First Configuration - Elegant, declarative screenshot definitions
• 🚀 Batch Processing - Generate multiple screenshots efficiently from a single config
• 🔦 Highlight Annotations - Circle, rounded rect, and rect shapes with spotlight dimming and background blur
• 🔍 Zoom Callouts - Magnified callout bubbles with source indicators, advanced connectors (straight/curved/facing), and drop shadows
• ✨ Anti-Aliased Rendering - Supersampled shape rendering for smooth edges at any resolution
• 🔧 Flexible API - Both simple and advanced configuration options
• 💎 Artisan Quality - Pixel-perfect output ready for App Store submission

📦 Installation

Package Managers (Recommended)

PyPI (All Platforms)

pip install koubou

macOS/Linux - Homebrew

brew install bitomule/tap/koubou

HTML Templates

kou setup-html

If Google Chrome is already installed, HTML template rendering usually works without any extra setup. kou setup-html installs Playwright Chromium only when it is needed.

Python Developers

pip install koubou[dev]  # With development dependencies

Manual Installation

Option 1: Install Script (Recommended)

git clone https://github.com/bitomule/koubou.git
cd koubou
./install.sh

Option 2: From Source

git clone https://github.com/bitomule/koubou.git
cd koubou
pip install .

Verification

Verify your installation:

kou --version
kou --help
kou setup-html --help

🚀 Quick Start

# Create a sample content-based configuration
kou --create-config my-screenshots.yaml

# Create a sample HTML template project
kou --create-config my-html-screenshots.yaml --mode html

# Generate screenshots
kou generate my-screenshots.yaml

# Prepare HTML rendering if your project uses HTML templates
kou setup-html

# Inspect real frame geometry before designing HTML layouts
kou inspect-frame "iPhone 16 Pro - Black Titanium - Portrait" --output-size iPhone6_9

# Live editing mode - regenerate automatically when files change
kou live my-screenshots.yaml

kou --create-config also creates sample PNG assets in a sibling screenshots/ directory, so the generated YAML can be rendered immediately. In --mode html, it also creates sample templates in templates/ and the generated project is ready to run with kou generate ... --setup-html.

🧩 HTML Templates

Use template: when a screenshot needs full HTML/CSS layout control instead of the standard content pipeline.

screenshots:
  hero:
    template: "templates/hero.html"
    variables:
      headline: "Private cleanup, instantly"
    assets:
      screen: "screenshots/home.png"

• variables: are localizable {{key}} substitutions
• assets: are file-path substitutions exposed to the template as {{key}}
• kou generate config.yaml --setup-html prepares HTML rendering and generates in one run
• kou live config.yaml --setup-html does the same before starting live mode
• kou inspect-frame "<device>" --output-size <size> --output json exposes frame and screen geometry for layout decisions

🔄 Live Editing

Real-time screenshot regeneration when your YAML configuration or assets change.

# Start live editing mode
kou live my-screenshots.yaml

# Adjust debounce delay (default: 0.5s)
kou live my-screenshots.yaml --debounce 1.0

# Enable verbose logging
kou live my-screenshots.yaml --verbose

kou live also starts a local browser dashboard that previews screenshots in YAML order. HTML slides render as live iframes, while standard Koubou slides render as regenerated PNGs in the same grid.

How it works:

• Monitors YAML config and all referenced assets
• Regenerates only affected screenshots
• Debounces rapid changes to prevent excessive regeneration
• Starts a local preview dashboard and auto-opens it when possible
• Shows HTML slides as live HTML and standard Koubou slides as PNG previews
• Uses the base language for preview while localized outputs continue regenerating on disk

Perfect for iterative design - edit assets in design tools, update text, tweak positioning, and see results instantly.

Platform support: macOS and Linux only (standard generation works on Windows)

---

🌍 Multi-Language Localization

Generate localized screenshots for international App Store submissions using xcstrings format from Xcode.

project:
  name: "My App Screenshots"
  output_dir: "Screenshots/Generated"
  device: "iPhone 15 Pro Portrait"
  output_size: "iPhone6_9"

localization:
  base_language: "en"
  languages: ["en", "es", "ja", "fr", "de"]
  xcstrings_path: "Localizable.xcstrings"  # Optional - auto-creates if missing

screenshots:
  welcome_screen:
    content:
      - type: "text"
        content: "Welcome to Amazing App"  # Text becomes localization key
        position: ["50%", "20%"]
        size: 48
        color: "#8E4EC6"
      - type: "image"
        asset: "screenshots/home.png"
        position: ["50%", "60%"]

Output structure:

Screenshots/Generated/
├── en/iPhone_15_Pro_Portrait/welcome_screen.png
├── es/iPhone_15_Pro_Portrait/welcome_screen.png
├── ja/iPhone_15_Pro_Portrait/welcome_screen.png
├── fr/iPhone_15_Pro_Portrait/welcome_screen.png
└── de/iPhone_15_Pro_Portrait/welcome_screen.png

Workflow: Koubou extracts text content and creates/updates your xcstrings file. Edit translations in Xcode's xcstrings editor, then regenerate screenshots. Live mode watches both YAML config and xcstrings file for changes.

Key benefits: Uses iOS-native xcstrings format, natural text as keys (no IDs), supports plurals and device variants, works seamlessly with live mode.

---

🖼️ Localized Assets

Automatically resolve language-specific images for multi-language screenshots. Perfect for RTL layouts, region-specific content, or tools like Maestro that generate per-locale screenshots.

Convention-Based (Recommended)

Organize assets in {lang}/ subdirectories - Koubou resolves them automatically:

localization:
  base_language: "en"
  languages: ["en", "es", "ja"]

screenshots:
  hero_screen:
    content:
      - type: "image"
        asset: "screenshots/hero.png"  # Auto-resolves to screenshots/{lang}/hero.png
        position: ["50%", "50%"]

Directory structure:

screenshots/
├── en/hero.png
├── es/hero.png
├── ja/hero.png
└── hero.png  # Fallback for missing languages

Resolution order: {lang}/path → {base_lang}/path → direct_path

Explicit Mapping

For non-standard structures or external tool outputs:

screenshots:
  onboarding:
    content:
      - type: "image"
        asset:
          en: "maestro/en_iphone/onboarding.png"
          es: "maestro/es_iphone/onboarding.png"
          ja: "maestro/ja_iphone/onboarding.png"
          default: "screenshots/fallback.png"  # Optional
        position: ["50%", "50%"]

Mix both approaches in the same screenshot as needed.

---

📱 App Store Screenshot Sizes

Koubou provides predefined App Store screenshot sizes configured at the project level. All screenshots in a single YAML file use the same output size.

Using Named Sizes

Specify the output size once in your project configuration:

project:
  name: "My App Screenshots"
  output_dir: "Screenshots/Generated"
  device: "iPhone 15 Pro Portrait"
  output_size: "iPhone6_9"  # All screenshots will be 1320×2868

screenshots:
  welcome_screen:
    content:
      - type: "image"
        asset: "screenshots/home.png"

Available Sizes

View all available sizes with descriptions:

kou list-sizes

Common Sizes:

• iPhone6_9 - iPhone 16 Pro Max, 15 Pro Max (1320×2868)
• iPhone6_7 - iPhone 15/14/13/12 Pro Max, Plus (1290×2796)
• iPhone6_1 - iPhone 16/15/14/13 Pro (1179×2556)
• iPadPro12_9 - iPad Pro 12.9" (2048×2732)
• iPadPro11 - iPad Pro 11", iPad Air 11" M2 (1668×2388)
• AppDesktop_2880 - Mac App Store desktop (2880×1800)
• AppDesktop_2560 - Mac App Store desktop (2560×1600)
• AppDesktop_1440 - Mac App Store desktop (1440×900)
• AppDesktop_1280 - Mac App Store desktop (1280×800)

Custom Sizes

You can still specify custom dimensions when needed:

project:
  name: "My App Screenshots"
  device: "iPhone 15 Pro Portrait"
  output_size: [1200, 2600]  # Custom width × height

Multiple Sizes

To generate screenshots for different sizes, create separate YAML files:

• iphone-6-9.yaml - All iPhone 6.9" screenshots
• iphone-6-7.yaml - All iPhone 6.7" screenshots
• ipad-pro.yaml - All iPad Pro screenshots

---

🎨 Configuration

Create screenshots with YAML configuration:

project:
  name: "My Beautiful App"
  output_dir: "Screenshots/Generated"
  device: "iPhone 15 Pro Portrait"
  output_size: "iPhone6_9"  # iPhone 16 Pro Max, 15 Pro Max

defaults:
  background:
    type: linear
    colors: ["#E8F0FE", "#F8FBFF"]
    direction: 180

screenshots:
  welcome_screen:
    content:
      - type: "text"
        content: "Beautiful App"
        position: ["50%", "15%"]
        size: 48
        color: "#8E4EC6"
        weight: "bold"
      - type: "text"
        content: "Transform your workflow today"
        position: ["50%", "25%"]
        size: 24
        color: "#1A73E8"
      - type: "image"
        asset: "screenshots/home.png"
        position: ["50%", "60%"]
        scale: 0.6
        frame: true

See the YAML API Reference below for all available options including gradients, strokes, and advanced positioning.

🎯 Commands

Core Commands

• kou generate <config.yaml> - Generate screenshots from configuration
• kou setup-html - Prepare HTML rendering support for the current installation
• kou live <config.yaml> - Live editing mode with real-time regeneration
• kou inspect-frame "<device>" --output-size <size> - Inspect real frame and screen geometry for layout decisions
• kou list-sizes - List available App Store screenshot sizes
• kou --create-config <output.yaml> - Create a sample configuration file (content by default, html with --mode html)
• kou --version - Show version information
• kou --help - Show detailed help

Command Options

Generate Command

# Emit machine-readable results
kou generate config.yaml --output json

# Prepare HTML rendering and generate in one run
kou generate config.yaml --setup-html

# Enable verbose logging
kou generate config.yaml --verbose

HTML Setup

# Prepare HTML rendering for the current installation
kou setup-html

# See setup diagnostics
kou setup-html --verbose

Frame Inspection

# Human-readable geometry summary
kou inspect-frame "iPhone 16 Pro - Black Titanium - Portrait" --output-size iPhone6_9

# Machine-readable output for agents or tooling
kou inspect-frame "iPhone 16 Pro - Black Titanium - Portrait" --output-size iPhone6_9 --output json

# Custom canvas size
kou inspect-frame "iPhone 16 Pro - Black Titanium - Portrait" --output-size 1200x2600 --output json

Live Editing Command

# Start live editing with default settings
kou live config.yaml

# Prepare HTML rendering before starting live mode
kou live config.yaml --setup-html

# Adjust debounce delay (default: 0.5s)
kou live config.yaml --debounce 1.0

# Enable verbose logging to see file changes
kou live config.yaml --verbose

kou live also prints a local preview URL and opens a browser tab with the live preview dashboard. HTML screenshots are previewed as live HTML, standard screenshots are previewed as PNGs, the dashboard uses the base language for preview, and changed slides hot-reload without waiting for a full page refresh.

Configuration Creation

# Create the default content sample
kou --create-config config.yaml --name "My App Screenshots"

# Create an HTML template sample project
kou --create-config config-html.yaml --mode html --name "My HTML Screenshots"

Upload to App Store Connect

For uploading screenshots, we recommend App Store Connect CLI:

brew install appstoreconnect-cli
asc auth login

# Upload per device type and language
asc assets screenshots upload \
  --version-localization "LOC_ID" \
  --path "./output/en/iPhone_16_Pro_.../" \
  --device-type "IPHONE_69"

Koubou outputs screenshots organized by {language}/{device}/, mapping directly to individual asc upload calls.

🎨 Device Frames

Koubou includes 100+ professionally crafted device frames:

iPhone Frames

• iPhone 16 Pro (Black, Desert, Natural, White Titanium)
• iPhone 16 (Black, Pink, Teal, Ultramarine, White)
• iPhone 15 Pro/Max (All titanium colors)
• iPhone 14 Pro/Max, 12-13 series, and more

iPad Frames

• iPad Air 11"/13" M2 (Blue, Purple, Space Gray, Stardust)
• iPad Pro 11"/13" M4 (Silver, Space Gray)
• iPad Pro 2018-2021, iPad mini, and classic models

Mac & Watch Frames

• MacBook Pro 2021 (14" & 16"), MacBook Air 2020/2022
• iMac 24" Silver, iMac 2021
• Apple Watch Series 4/7, Watch Ultra

📖 YAML API Reference

Project Configuration

project:
  name: string               # Project name
  output_dir: string         # Output directory (default: "output")
  device: string             # Target device frame (default: "iPhone 15 Pro Portrait")
  output_size: string | [int, int]  # Named size ("iPhone6_9") or custom [width, height] (default: "iPhone6_9")

defaults:                    # Default settings applied to all screenshots
  background:                # Default background configuration
    type: "solid" | "linear" | "radial" | "conic"
    colors: [string, ...]    # Hex colors array
    direction: float?        # Degrees for gradients (default: 0)

Screenshot Configuration

screenshots:
  screenshot_id:             # Unique identifier for each screenshot
    content:                 # Array of content items
      - type: "text" | "image" | "highlight" | "zoom"
        # Text content properties
        content: string?     # Text content (for type: "text")
        position: [string, string]  # Position as ["x%", "y%"] or ["xpx", "ypx"]
        size: int?           # Font size (default: 24)
        color: string?       # Hex color (default: "#000000")
        weight: string?      # "normal" or "bold" (default: "normal")
        alignment: string?   # "left", "center", "right" (default: "center")
        # Image content properties
        asset: string | dict? # Image path (string) or localized mapping (dict)
        scale: float?        # Scale factor (default: 1.0)
        frame: bool?         # Apply device frame (default: false)

Background Configuration

background:
  type: "solid" | "linear" | "radial" | "conic"
  colors: [string, ...]      # Hex colors (e.g., ["#667eea", "#764ba2"])
  direction: float?          # Degrees for linear gradients (default: 0)
  center: [string, string]?  # Center point for radial/conic ["x%", "y%"]

Content Items

# Text Content Item
- type: "text"
  content: string            # Text to display
  position: [string, string] # Position as ["50%", "20%"] or ["100px", "50px"]
  size: int                  # Font size in pixels (default: 24)
  
  # Fill Options (choose exactly one):
  color: string              # Solid color (hex format, e.g., "#000000")
  # OR
  gradient:                  # Text gradient
    type: "linear" | "radial" | "conic"
    colors: [string, ...]    # Hex colors array (minimum 2)
    positions: [float, ...]? # Color stops 0.0-1.0 (optional)
    direction: float?        # Angle in degrees (linear)
    center: [string, string]? # Center point (radial/conic)
    radius: string?          # Radius for radial ("50%", "100px")
    start_angle: float?      # Starting angle (conic)
  
  weight: string             # "normal" or "bold" (default: "normal")
  alignment: string          # "left", "center", "right" (default: "center")
  
  # Stroke Options (optional):
  stroke_width: int?         # Stroke width in pixels
  stroke_color: string?      # Solid stroke color (hex format)
  # OR
  stroke_gradient:           # Gradient stroke (same structure as gradient)

# Image Content Item
- type: "image"
  asset: string              # Path to image file
  position: [string, string] # Position as ["50%", "60%"] or ["200px", "300px"]
  scale: float               # Scale factor (default: 1.0)
  frame: bool                # Apply device frame around image (default: false)

# Highlight Content Item
- type: "highlight"
  shape: "circle" | "rounded_rect" | "rect"  # Shape (required)
  position: [string, string] # Center position as ["50%", "50%"]
  dimensions: [string, string] # Width, height as ["20%", "15%"]
  border_color: string?      # Border color in hex (e.g., "#FF3B30")
  border_width: int?         # Border width in pixels (default: 3)
  fill_color: string?        # Fill color in hex, supports alpha (e.g., "#FF3B3020")
  corner_radius: int?        # Corner radius for rounded_rect (default: 16)
  shadow: bool?              # Enable drop shadow (default: false)
  shadow_color: string?      # Shadow color with alpha (default: "#00000040")
  shadow_blur: int?          # Shadow blur radius (default: 15)
  shadow_offset: [string, string]? # Shadow X,Y offset (default: ["0", "6"])
  spotlight: bool?           # Dim everything except highlight (default: false)
  spotlight_color: string?   # Overlay color (default: "#000000")
  spotlight_opacity: float?  # Overlay opacity 0.0-1.0 (default: 0.5)
  blur_background: bool?     # Blur outside highlight area (default: false)
  blur_radius: int?          # Background blur radius (default: 20)

# Zoom Content Item
- type: "zoom"
  source_position: [string, string]  # Center of area to magnify (required)
  source_size: [string, string]      # Crop region size (required)
  display_position: [string, string] # Where magnified view appears
  display_size: [string, string]     # Size of magnified bubble (or use zoom_level)
  zoom_level: float?         # Auto-calculate display_size (e.g., 2.5 = 2.5x)
  shape: "circle" | "rounded_rect"   # Bubble shape (default: "circle")
  border_color: string?      # Border color in hex
  border_width: int?         # Border width (default: 3)
  corner_radius: int?        # For rounded_rect (default: 16)
  shadow: bool?              # Enable drop shadow (default: false)
  shadow_color: string?      # Shadow color with alpha (default: "#00000040")
  shadow_blur: int?          # Shadow blur radius (default: 15)
  shadow_offset: [string, string]? # Shadow X,Y offset (default: ["0", "6"])
  source_indicator: bool?    # Show outline on source region (default: true)
  source_indicator_style: string? # "border" | "dashed" | "fill" (default: "border")
  connector: bool?           # Draw line from source to display (default: false)
  connector_style: string?   # "straight" | "curved" | "facing" (default: "straight")
  connector_color: string?   # Line color (defaults to border_color)
  connector_width: int?      # Line width (default: 2)
  connector_fill: string?    # Fill color between facing connector lines

🏗️ Architecture

Koubou uses a clean, modular architecture:

• CLI Layer (koubou.cli): Command-line interface with rich output
• Configuration (koubou.config): Pydantic-based type-safe configuration
• Generation Engine (koubou.generator): Core screenshot generation logic
• Renderers (koubou.renderers): Specialized rendering for backgrounds, text, frames
• Device Frames (koubou.frames): 100+ device frame assets and metadata

🔧 Development

Setup Development Environment

# Clone the repository
git clone https://github.com/bitomule/koubou.git
cd koubou

# Install in development mode with all dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
black src/ tests/
isort src/ tests/ 
flake8 src/ tests/
mypy src/

Running Tests

# Run all tests with coverage
pytest -v --cov=src/koubou

# Run specific test file
pytest tests/test_generator.py -v

# Run with live output
pytest -s

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (pytest, black, isort, flake8, mypy)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📋 Changelog

See CHANGELOG.md for complete version history.

📄 License

MIT License - see LICENSE for details.

🎯 Koubou Philosophy

In the spirit of Japanese craftsmanship, Koubou embodies:

• 職人気質 (Shokunin-kishitsu) - Artisan spirit and dedication to craft
• 完璧 (Kanpeki) - Pursuit of perfection in every detail
• 簡潔 (Kanketsu) - Elegant simplicity in design and usage
• 品質 (Hinshitsu) - Uncompromising quality in output

Every screenshot generated by Koubou reflects these values - carefully crafted, pixel-perfect, and ready for the world's most demanding app stores.