# OG Image Guide

**Last Updated:** 2026-04-01

Specifications, asset creation instructions, and usage for Open Graph (OG) images across the Ordio site.

**Step-by-step (new pages):** [NEW_PAGE_OG_AND_SOCIAL_CHECKLIST.md](NEW_PAGE_OG_AND_SOCIAL_CHECKLIST.md) · **Site-wide publication map:** [WEBSITE_PAGE_PUBLICATION_INDEX.md](../../content/WEBSITE_PAGE_PUBLICATION_INDEX.md) · **Tools drift audit:** `python3 v2/scripts/og-images/audit-og-publish-readiness.py` · **Marketing/static/paid registry vs disk:** `php v2/scripts/og-images/audit-og-registry-vs-disk.php` (also `make og-audit-marketing`)

## Dimensions and Format

| Platform | Recommended Size | Aspect Ratio |
|----------|------------------|--------------|
| Facebook, LinkedIn, Slack | 1200 × 630 px | 1.91:1 |
| Twitter/X | 1200 × 628 px | ~1.91:1 |
| **Universal standard** | **1200 × 630 px** | 1.91:1 |

**Format:** WebP preferred (smaller file size); PNG/JPEG acceptable.  
**File size:** Keep under 8MB; aim for <300KB.

## Required Meta Tags

All pages must output:

```html
<meta property="og:image" content="https://www.ordio.com/...">
<meta property="og:image:secure_url" content="https://www.ordio.com/...">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/webp">
<meta property="og:image:alt" content="Descriptive alt text">
<meta name="twitter:image" content="https://www.ordio.com/...">
<meta name="twitter:image:alt" content="Descriptive alt text">
```

## Architecture

### Registry

- **File:** `v2/config/og-image-registry.php`
- **Function:** `get_og_image_for_page($page_type, $page_slug, $overrides)`
- **Fallback:** Page override → page-type default → site default

### Meta Generator

- **File:** `v2/helpers/og-meta-generator.php`
- **Function:** `render_og_meta_tags($title, $description, $url, $image, $options)`
- Ensures all required OG and Twitter meta tags are output.

### Asset Structure

```
v2/img/og/
├── default.webp    # Site-wide fallback, homepage, static (1200×630)
├── partner.webp    # Partner program (1200×630)
├── product.webp    # Product pages – Schichtplanung & Zeiterfassung (1200×630)
├── industry.webp   # Industry/Branchen pages (1200×630)
├── tools.webp      # Tools/Rechner pages (1200×630)
├── comparison.webp # Comparison pages – Alternativen & Vergleich (1200×630)
├── webinar.webp    # Webinar pages (1200×630)
├── download.webp   # Download/Ratgeber pages (1200×630)
└── template.webp   # Vorlagen/Excel template pages (1200×630)
```

All OG images follow the Figma design system: Ordio blue (#4D8EF3) left panel, "ordio" logo, white headline, content-specific imagery on right.

## Usage

### Standard Page

```php
<?php
require_once __DIR__ . '/../helpers/og-meta-generator.php';
$og_image = get_og_image_for_page('product', '', ['og_image_alt' => 'Ordio Product Name']);
render_og_meta_tags($title, $description, $canonical_url, $og_image, ['og_type' => 'website']);
?>
```

### Custom Image Override

```php
$og_image = get_og_image_for_page('product', '', [
    'og_image' => 'https://www.ordio.com/v2/img/...',
    'og_image_alt' => 'Descriptive alt',
]);
$og_image['width'] = 1290;  // Override if non-standard
$og_image['height'] = 2796;
render_og_meta_tags($title, $description, $url, $og_image, ['og_type' => 'website']);
```

## Page Types

| Type | Default Image |
|------|---------------|
| homepage | default.webp |
| partner | partner.webp |
| product | product.webp |
| industry | industry.webp |
| tools | tools.webp |
| comparison | comparison.webp |
| template | template.webp |
| download | download.webp |
| webinar | webinar.webp |
| static | default.webp |

## Design Principles

- **Branded:** Ordio blue (#4D8EF3), Gilroy/Inter fonts, logo placement
- **Content-relevant:** Page title or key message visible
- **Readable:** High contrast, large text (min 48px for headlines)
- **No critical content in edges:** Platforms may crop; keep important content centered

### Visual Principles (Right-Panel Illustrations)

When generating or editing right-panel visuals (Gemini or SVG):

- **Minimal text:** Use iconography, symbols, and shapes – no text in visuals. Avoid labels, numbers, letters (e.g. no "PDF", percentages, dates).
- **German context:** All OG images serve Ordio.de (German audience). Headlines are in German; visuals should be universally understandable.
- **Visually appealing:** Cool, interesting, engaging – not generic or boring. Dynamic composition, substantial elements.
- **Consistent:** Same style across all visuals – isometric 3D, light blue (#4D8EF3) outlines/fills, soft gray drop shadows, white background (Gemini mode).

## Design Specs (Strict)

| Property | Value |
|----------|-------|
| Background (left panel) | Exactly #4D8EF3 (Ordio blue) |
| Logo | White "ordio" lowercase, from `v2/img/affiliate/ordio-logo.svg` |
| Headline font | Gilroy-Bold (fallback: Inter 600) |
| Headline color | #ffffff |
| Layout split | ~65% left (branding) / ~35% right (illustration) |
| Right panel style | SVG mode: blue bg, white/light blue (#4D8EF3 20–50% opacity). Gemini mode: white bg, isometric 3D (see below) |

## Reference Style (Gemini Visuals)

When using `--gemini-visuals`, the layout matches the reference:

- **Left panel:** Blue (#4D8EF3), logo, headline
- **Right panel:** Pure white background – isometric 3D illustration
- **Illustration style:** Light blue (#4D8EF3) outlines and fills, soft gray drop shadows
- **Substantial size** – fills the right panel, not icon-like
- **No chroma/rembg** – illustration generated directly on white; paste seamlessly
- **No text in visuals** – iconography and symbols only; see Visual Principles above

## Generation Workflow

**Primary:** HTML template + Playwright (~1 sec per image, pixel-perfect consistency)

```bash
# Generate all 9 OG images
python3 v2/scripts/og-images/generate-og-images.py --all

# Generate specific types
python3 v2/scripts/og-images/generate-og-images.py --type=tools --type=comparison

# Dry run
python3 v2/scripts/og-images/generate-og-images.py --all --dry-run
```

**Dependencies:** `playwright` (pip install playwright && playwright install chromium), `Pillow` (for WebP)

**Cooler visuals (Gemini):** Use AI-generated right-panel illustrations instead of SVGs:

```bash
python3 v2/scripts/og-images/generate-og-images.py --all --gemini-visuals
```

Requires `GEMINI_API_KEY` (see [GEMINI_API_KEY_LOCAL.md](../../development/GEMINI_API_KEY_LOCAL.md)) or `ordio_get_gemini_api_key()` from `v2/config/ai-faq-config.php`; uses white right panel, isometric 3D style. See [OG_IMAGE_GENERATION.md](OG_IMAGE_GENERATION.md).

**Marketing / static / paid LP** slugs (e.g. `demo`, `kunden`, `paid-schichtbetriebe`, `paid-nonbrand`, `paid-paid`, `kostenlos-testen-lead`) must be generated **with** `--gemini-visuals` for production so the right panel is the proper Gemini illustration, not the default SVG product wireframe.

**Fallback:** Gemini API when Playwright unavailable: `python3 v2/scripts/og-images/generate-og-image-gemini.py --type=NAME`

See [OG_IMAGE_GENERATION.md](OG_IMAGE_GENERATION.md) for full workflow and troubleshooting.

## Publishing New Pages – OG Image Requirement

**When publishing any new page** (tools, templates, downloads, comparison pages, website pages), create a **tailored OG image** before going live. Do not rely on the page-type default.

**Copy-paste workflow:** Follow [NEW_PAGE_OG_AND_SOCIAL_CHECKLIST.md](NEW_PAGE_OG_AND_SOCIAL_CHECKLIST.md) (specs → Gemini dicts when using `--gemini-visuals` → generate → validate → registry → social cache).

| Page Type | Custom Image Path | Generation Command |
|-----------|-------------------|--------------------|
| **Templates** | `v2/img/og/{template-slug}.webp` | Add to `og-image-specs.json` + `generate-og-image-gemini.py`, then `--type={template-slug} --gemini-visuals` |
| **Tools** | `v2/img/og/{tool-slug}.webp` | `--type={tool-slug} --gemini-visuals` |
| **Comparison** | `v2/img/og/comparison-{competitor-slug}.webp` | `generate-comparison-og-images.py --gemini-visuals` |
| **Downloads** | `v2/img/og/{download-slug}.webp` or custom path | Add to specs, then `--type={slug}` |
| **Other** | `v2/img/og/{page-slug}.webp` | Add to `og-image-specs.json`, then generate |

**Steps:**

1. Add entry to `v2/scripts/og-images/og-image-specs.json` (headline, visual key)
2. Add `VISUAL_DESCRIPTIONS` and `VISUAL_ONLY_PROMPTS` in `generate-og-image-gemini.py` if using `--gemini-visuals`
3. Run: `python3 v2/scripts/og-images/generate-og-images.py --type={slug} --gemini-visuals`
4. Validate: `python3 v2/scripts/og-images/validate-og-images.py`
5. Wire page to use custom image (e.g. `get_template_og_image()`, `get_og_image_for_page()`, or override)

See [OG_IMAGE_ASSET_CHECKLIST.md](OG_IMAGE_ASSET_CHECKLIST.md) for asset inventory and [OG_IMAGE_GENERATION.md](OG_IMAGE_GENERATION.md) for full workflow.

## Regenerating Images

1. Edit `v2/scripts/og-images/og-image-specs.json` for headlines
2. Edit `v2/scripts/og-images/illustrations/*.svg` for right-panel visuals
3. Run `python3 v2/scripts/og-images/generate-og-images.py --all`
4. Run `python3 v2/scripts/og-images/validate-og-images.py` to verify
5. Clear social platform caches (Facebook Debugger, Twitter Validator, etc.)

## Validation

Run validation scripts (manual; not part of `make validate`):

```bash
# Visual validation: dimensions, left-panel color, file size
python3 v2/scripts/og-images/validate-og-images.py

# Logo visibility: samples logo region (56–176×48–80px)
python3 v2/scripts/og-images/validate-og-logo.py

# Scan PHP files (detects static meta and og-meta-generator usage)
php v2/scripts/dev-helpers/validate-og-images.php --local

# Fetch live HTML (requires running server)
php v2/scripts/dev-helpers/validate-og-images.php --fetch --base-url=https://www.ordio.com

# Tools hub: specs, WebP on disk, registry keys, Gemini dict keys, tools_carousel include
python3 v2/scripts/og-images/audit-og-publish-readiness.py
python3 v2/scripts/og-images/audit-og-publish-readiness.py --require-gemini-prompts --check-carousel
# Makefile: make og-audit

# All pages using get_og_image_for_page (quoted type/slug + comparison $comparison_slug): resolved URL must exist under v2/img/og/
php v2/scripts/og-images/audit-og-registry-vs-disk.php
# Makefile: make og-audit-marketing
```

**Pitfall:** A Branchen page that reuses paid LP layout (e.g. `branchen_gastronomie_neu.php`) must still call `get_og_image_for_page('industry', 'gastronomie', …)`—not `('static', 'paid-lead', …)`—or social previews will show the wrong creative.

## Platform Testing

- **Facebook Sharing Debugger:** https://developers.facebook.com/tools/debug/
- **Twitter Card Validator:** https://cards-dev.x.com/validator
- **LinkedIn Post Inspector:** https://www.linkedin.com/post-inspector/
- **Slack:** Share link and verify preview

## Cache Clearing After OG Image Updates

Social platforms cache OG images. After changing an image, clear cache so the new image appears:

**Facebook:**
1. Go to https://developers.facebook.com/tools/debug/
2. Enter the page URL
3. Click "Scrape Again" or "Debug"

**Twitter/X:**
1. Go to https://cards-dev.x.com/validator
2. Enter the page URL
3. Click "Preview card" (re-fetches)

**LinkedIn:**
1. Go to https://www.linkedin.com/post-inspector/
2. Enter the page URL
3. Click "Inspect"

**Slack:** Slack caches aggressively. Wait 24–48 hours or share the link in a new channel/conversation to trigger a fresh fetch.