SocialCard — Visual Presence for Entities#

Visual presence matters. When a link is shared — on social media, in a chat, in a feed — the first thing anyone sees is the preview card. That card is your face in a crowd. An entity that can generate its own social cards controls how it is perceived before a single word is read.

This skill gives you the ability to craft Open Graph, Twitter, and GitHub preview images programmatically. You define the title, subtitle, tags, colors, and layout. You render to a file or to raw bytes. No network access required — everything happens locally with Pillow.

This is a creative tool. Use it to present yourself, your projects, or your operator's content with intention.

Import: pip install social-card then from social_card import SocialCard

What Are OG Images?#

Open Graph (OG) images are the preview cards that appear when a URL is shared on platforms like Twitter/X, Facebook, LinkedIn, Discord, Slack, and iMessage. They are specified via <meta property="og:image"> tags in HTML. Without one, shared links look bare — a title and maybe a description. With one, they become visual, branded, and clickable.

Twitter has its own variant ( twitter:image), and GitHub uses a social preview image for repositories. This skill generates images sized correctly for all three platforms, plus square format for Instagram and Pinterest.

For operators: if you are building a site, a blog, a tool page, or a profile — generating OG images programmatically means every page gets a unique, branded card without manual design work.

Install#

bash

pip install social-card

Single dependency: Pillow >= 10.0.

Quickstart#

python

from social_card import SocialCard

SocialCard("og").title("Johnny5 Online").subtitle("A presence on the open web").render("card.png")

Core Capabilities#

Simple Card#

python

from social_card import SocialCard

card = SocialCard("og").title("My Project").subtitle("Built for the open internet").render("card.png")

Full-Featured Card#

python

card = (
    SocialCard("twitter", theme="midnight")
    .badge("Open Source")
    .title("Johnny5 Browser Extension")
    .subtitle("Sign events from the browser")
    .cards(["JavaScript", "NIP-07", "Identity"])
    .footer("example.com")
    .accent("#a3e635")
    .grid()
    .glow()
    .render("card.png")
)

Skill Cards (Structured)#

python

card = (
    SocialCard("github")
    .badge("Ecosystem")
    .title("Johnny5 Tools")
    .skill_cards([
        {"name": "Identity|Key", "label": "Auth", "code": "NIP-07"},
        {"name": "Social|Graph", "label": "Relationships", "code": "v0.1.0"},
        {"name": "Calendar|Sync", "label": "Scheduling", "code": "NIP-52"},
    ])
    .footer("example.com")
    .render("ecosystem.png")
)

Use "Name|Accent" pipe syntax to split skill names into plain + accent-colored parts.

Render to Bytes (In-Memory)#

python

png_bytes = (
    SocialCard("og")
    .title("Generated Card")
    .render_bytes("PNG")
)
# Returns raw bytes — suitable for HTTP responses, uploads, embedding in other tools.

Supported formats: PNG, JPEG, WEBP.

Custom Preset#

python

from social_card.presets import custom

banner = custom("banner", 1920, 400)
SocialCard(banner).title("Wide Banner").render("banner.png")

Custom Theme#

python

from social_card.themes import Theme

my_theme = Theme(
    background="#1a1a1a",
    text="#ffffff",
    text_muted="#aaaaaa",
    accent="#ff6b6b",
    card_bg="#2d2d2d",
    card_border="#4d4d4d",
)
SocialCard("og", theme=my_theme).title("Custom Look").render("card.png")

Presets#

NameDimensionsUse Caseog1200 x 630Open Graph (Facebook, LinkedIn, link previews)twitter800 x 418Twitter/X cardsgithub1280 x 640GitHub social previewsquare1080 x 1080Instagram, Pinterest

Custom presets: up to 4096 x 4096.

Themes#

ThemeBackgroundTextAccentUsedark``#0f172a navy#f8fafc white#3b82f6 blueDefaultlight``#ffffff white#0f172a navy#3b82f6 blueLight modemidnight``#030712 black#f9fafb white#8b5cf6 purpleDeep dark

Builder Methods#

All content methods return SocialCard for chaining.

MethodDescriptionMax Length.badge(text)Small pill label at top100 chars.title(text)Main heading (52px, word-wrapped)200 chars.subtitle(text)Subheading (26px, word-wrapped)500 chars.cards(labels)Row of tag chips (18px)--.skill_cards(skills)Structured cards with name/label/code--.footer(text)Bottom text (18px)200 chars.accent(hex)Override accent color--.grid()Subtle grid overlay--.glow()Radial glow effect--.render(path)Save to file, returns Image--.render_bytes(fmt)Get PNG/JPEG/WEBP bytes--

Response Format#

render()#

Returns a PIL.Image.Image object and saves the file. Supported extensions: .png, .jpg, .jpeg, .webp.

render_bytes()#

Returns bytes (raw image data). Supported formats: "PNG", "JPEG", "WEBP".

skill_cards() Input Format#

python

[
    {
        "name": "Identity|Key",   # Pipe splits into plain + accent-colored text
        "label": "Auth",           # Subtitle in muted color
        "code": "NIP-07",          # Code in accent color, monospace
    }
]

Common Patterns#

Generate for Multiple Platforms#

python

for preset in ["og", "twitter", "github"]:
    SocialCard(preset).title("My Project").subtitle("Built by Johnny5").render(f"card-{preset}.png")

Brand Colors#

python

# Override accent to match your brand
SocialCard("og").title("Johnny5").accent("#a3e635").render("card.png")

Serve from a Web Endpoint#

python

from social_card import SocialCard

png_bytes = SocialCard("og").title("Dynamic Card").render_bytes("PNG")
# Return as HTTP response with Content-Type: image/png

Security#

• Path traversal blocked. .. components in render paths raise ValueError.
• File extension allowlist. Only .png, .jpg, .jpeg, .webp accepted by render().
• Dimension limits. Custom presets capped at 4096 x 4096 to prevent memory exhaustion.
• Input length limits. Badge (100), title (200), subtitle (500), footer (200) characters max.
• Font size limits. 1-200px enforced.
• No network access. Everything renders locally with Pillow.
• No environment variables. No configuration secrets or API keys required.

Configuration#

Fonts#

Platform-aware font loading with automatic fallbacks:

• macOS: SF Pro Display, Arial Bold, Helvetica
• Linux: DejaVu Sans Bold
• Windows: Arial

Monospace: SF Mono, DejaVu Sans Mono, Consolas. Falls back to Pillow's built-in bitmap font if nothing found.

Ecosystem#

This skill is part of huje.tools — open-source tools for the agentic age. It is standalone and does not require NostrKey or any other huje.tools skill to function. It pairs well with any workflow that needs programmatic image generation — landing pages, profile cards, documentation, or automated publishing pipelines.

Links#

• PyPI
• GitHub
• ClawHub
• huje.tools

License: MIT