/design

Social Photos Design Guide

Design social media images via HTML/CSS rendering + screenshot export. Orchestrates the bundled ui-ux-pro-max, brand, and design-system skills; screenshot export runs through Chrome headless, Playwright, or Puppeteer.

Platform Sizes

Workflow

Step 1: Plan the Work

Create TODO tasks with the runtime's native task list. Break down into:

• Requirement analysis task
• Idea generation task(s)
• HTML design task(s) — can parallelize per size/variant
• Screenshot export task(s) — can parallelize per file
• Report generation task

Spawn parallel subagents for independent tasks (e.g., multiple HTML files for different sizes).

Step 2: Analyze Requirements

Parse user input for:

• Subject/topic — what the social photo represents
• Target platforms — which sizes needed (default: Instagram Post 1:1 + Story 9:16)
• Visual style — minimalist, bold, gradient, photo-based, etc.
• Brand context — read from docs/brand-guidelines.md if exists
• Content elements — headline, subtext, CTA, images, icons
• Quantity — how many variations (default: 3)

Step 3: Generate Ideas

Create 3-5 concept ideas that:

• Match the input prompt/requirements
• Consider platform-specific best practices
• Vary in composition, color, typography approach
• Align with brand guidelines if available

Present ideas to user via AskUserQuestion for approval before designing.

Step 4: Design HTML Files

Use these bundled skills in sequence:

1. brand — Extract brand colors, fonts, voice from user's project
2. design-system — Get design tokens (spacing, typography scale, color palette)
3. ui-ux-pro-max — Layout, hierarchy, visual balance; search a different style, palette, or font pairing per concept for design variety.

For each approved idea + each target size, create an HTML file:

output/social-photos/
├── idea-1-instagram-post-1080x1080.html
├── idea-1-instagram-story-1080x1920.html
├── idea-2-instagram-post-1080x1080.html
├── idea-2-instagram-story-1080x1920.html
└── ...

HTML Design Rules

• Viewport — Set exact pixel dimensions matching target size
• Self-contained — Inline all CSS, embed fonts via Google Fonts CDN
• No scrolling — Everything fits in one viewport
• High contrast — Text readable at thumbnail size
• Brand-aligned — Use extracted brand colors/fonts
• Safe zones — Critical content within central 80% area
• Typography — Min 24px for headlines, min 16px for body at 1080px width
• Visual hierarchy — One focal point, clear reading flow

HTML Template Structure

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width={WIDTH}, initial-scale=1.0">
  <link href="https://fonts.googleapis.com/css2?family={FONT}&display=swap" rel="stylesheet">
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    html, body {
      width: {WIDTH}px;
      height: {HEIGHT}px;
      overflow: hidden;
      font-family: '{FONT}', sans-serif;
    }
    .canvas {
      width: {WIDTH}px;
      height: {HEIGHT}px;
      position: relative;
      /* Background: gradient, solid, or image */
    }
    /* Design tokens from brand/design-system */
  </style>
</head>
<body>
  <div class="canvas">
    <!-- Content layers -->
  </div>
</body>
</html>

Step 5: Screenshot Export

Use Chrome headless, Playwright, or Puppeteer to capture exact-size screenshots.

IMPORTANT: Always add a delay (3-5s) after page load for fonts/images to fully render before capture.

Option A: Chrome Headless CLI (Recommended — zero dependencies)

CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
DELAY=5  # seconds for fonts/images to load

"$CHROME" \
  --headless \
  --disable-gpu \
  --no-sandbox \
  --hide-scrollbars \
  --window-size="${WIDTH},${HEIGHT}" \
  --virtual-time-budget=$((DELAY * 1000)) \
  --screenshot="output.png" \
  "file:///path/to/file.html"

Key flags:

• --virtual-time-budget=5000 — waits 5s virtual time for assets (Google Fonts, images) to load
• --hide-scrollbars — prevents scrollbar artifacts in screenshots
• --window-size=WxH — sets exact pixel dimensions

Option B: Browser automation provided by the runtime

If the runtime offers a browser-automation or screenshot capability (for example a browser MCP server), use it to:

1. Open each HTML file in browser
2. Set viewport to exact target dimensions
3. Wait 3-5s for fonts/images to fully load
4. Screenshot full page to PNG
5. Save to output/social-photos/exports/

Option C: Playwright script

const { chromium } = require('playwright');

async function captureScreenshots(htmlFiles) {
  const browser = await chromium.launch();

  for (const file of htmlFiles) {
    const [width, height] = file.match(/(\d+)x(\d+)/).slice(1).map(Number);

    const page = await browser.newPage();
    await page.setViewportSize({ width, height });
    await page.goto(`file://${file}`, { waitUntil: 'networkidle' });
    // Wait for fonts/images to fully render
    await page.waitForTimeout(3000);

    const outputPath = file.replace('.html', '.png').replace('social-photos/', 'social-photos/exports/');
    await page.screenshot({ path: outputPath, type: 'png' });
    await page.close();
  }

  await browser.close();
}

Option D: Puppeteer script

const puppeteer = require('puppeteer');

async function captureScreenshots(htmlFiles) {
  const browser = await puppeteer.launch();

  for (const file of htmlFiles) {
    const [width, height] = file.match(/(\d+)x(\d+)/).slice(1).map(Number);

    const page = await browser.newPage();
    await page.setViewport({ width, height, deviceScaleFactor: 2 }); // 2x for retina
    await page.goto(`file://${file}`, { waitUntil: 'networkidle0' });
    // Wait for fonts/images to fully render
    await new Promise(r => setTimeout(r, 3000));

    const outputPath = file.replace('.html', '.png').replace('social-photos/', 'social-photos/exports/');
    await page.screenshot({ path: outputPath, type: 'png' });
    await page.close();
  }

  await browser.close();
}

IMPORTANT: Use deviceScaleFactor: 2 for retina-quality output (Puppeteer only).

Step 6: Verify & Fix Designs

Open each exported PNG in an available browser or image viewer and inspect it:

1. Open exported screenshots and check for layout/styling issues
2. Verify: fonts rendered correctly, colors match brand, text readable at thumbnail size
3. Check: no overflow, no cut-off content, safe zones respected, visual hierarchy clear
4. If issues found → fix HTML source → re-export screenshot → verify again
5. Repeat until all designs pass visual QA

Common issues to check:

• Fonts not loaded (fallback to system fonts)
• Text overflow or clipping
• Elements outside safe zone (central 80%)
• Low contrast text (below WCAG AA 4.5:1)
• Misaligned elements or broken layouts

Step 7: Generate Summary Report

Save the report as plans/reports/{YYMMDD}-social-photos-{topic}.md.

Report structure:

# Social Photos Design Report

## Overview
- Prompt/requirements: {original input}
- Platforms: {target platforms}
- Variations: {count}
- Style: {chosen style}

## Ideas Generated
1. **{Idea name}** — {brief description, rationale}
2. ...

## Design Decisions
- Color palette: {colors used, why}
- Typography: {fonts, sizes, why}
- Layout: {composition approach, why}
- Brand alignment: {how brand guidelines influenced design}

## Output Files
| File | Size | Platform | Preview |
|------|------|----------|---------|
| exports/{filename}.png | {WxH} | {platform} | {description} |

## Why This Works
- {Platform-specific reasoning}
- {Brand alignment reasoning}
- {Visual hierarchy reasoning}
- {Engagement potential reasoning}

## Recommendations
- {A/B test suggestions}
- {Platform-specific tips}
- {Iteration opportunities}

Step 8: Organize Output

Organize all output files and reports:

• Move/copy exported PNGs to proper asset directories
• Ensure reports are in plans/reports/ under the name from Step 7
• Clean up intermediate HTML files if requested
• Tag outputs with metadata (platform, size, concept name)

Design Best Practices

Platform-Specific Tips

• Instagram — Visual-first, minimal text (<20%), strong colors, lifestyle feel
• Facebook — Informative, can have more text, eye-catching in feed
• Twitter/X — Bold headlines, contrast for dark/light mode, clear message
• LinkedIn — Professional, clean, data-driven visuals, thought leadership
• Pinterest — Vertical format, text overlay on images, how-to style
• YouTube — Face close-ups perform best, bright colors, readable at small size
• TikTok — Trendy, energetic, bold typography, youth-oriented

Art Direction Styles (Reuse from Banner)

Color & Contrast

• Ensure WCAG AA contrast ratio (4.5:1 min) for all text
• Test designs at 50% size to verify readability
• Consider platform dark/light mode compatibility
• Use brand primary color as dominant, secondary as accent

Typography Hierarchy

Security & Scope

This sub-skill handles social media image design only. Does NOT handle:

• Video content creation
• Animation/motion graphics
• Print production files (CMYK, bleed)
• Direct social media posting/scheduling
• AI image generation (supply images, or generate them with a separate authorized capability)