---
name: social-card
description: Generate social-share card images from a title + subtitle (and optional background image). Three formats — og (1200x630 Open Graph / Twitter), square (1080x1080 IG grid), story (1080x1920 IG/TikTok story). Polished editorial typography defaults, dark-mode aesthetic, optional gradient overlay over background images. Pure PIL. Use when the user asks for an OG card, share image, link preview, IG grid post, story image, or release announcement card.
---


# social-card

Generate polished social-share card images from a title + subtitle, with optional background image.

## Formats

- **og** — 1200x630 (Open Graph / Twitter card / link preview)
- **square** — 1080x1080 (Instagram grid post)
- **story** — 1080x1920 (Instagram / TikTok story, 9:16)

## Usage

```bash
# Basic OG card on solid dark
python3 scripts/card.py --title "DEMON 01" --subtitle "out now" --format og --output card.png

# With background image
python3 scripts/card.py --title "Release Friday" --subtitle "pre-save link in bio" \
  --image cover.jpg --format square --output ig.png

# Story format with custom accent
python3 scripts/card.py --title "TONIGHT" --subtitle "live @ 9pm" \
  --format story --accent "#00FFAA" --output story.png

# Light theme
python3 scripts/card.py --title "newsletter #42" --subtitle "this week in shipping" \
  --format og --theme light --output news.png
```

## Flags

- `--title` (required) — main heading, auto-fits to width, max 3 lines
- `--subtitle` (optional) — secondary line below title
- `--image` (optional) — background image path; cover-cropped to fit
- `--format` — `og` | `square` | `story` (default `og`)
- `--theme` — `dark` (default) | `light`
- `--accent` — hex color for the accent bar above the title (default `#FF3B30`)
- `--output` (required) — output PNG path
- `--font-title` (optional) — TTF/OTF path for title font
- `--font-body` (optional) — TTF/OTF path for subtitle font

## Notes

- Auto-installs Pillow on first run.
- Title auto-shrinks and wraps (max 3 lines) to fit the available width.
- Background images get a 70% black gradient overlay in dark theme so the title stays legible.
- Default fonts fall back to Helvetica → DejaVu → PIL default in that order.

## Output

Single PNG at the requested resolution. Drop into Twitter/og:image meta tags, IG, TikTok, or a release announcement.