Shpigford/feature-image

Generate a branded social media image for announcing a feature or update. The image is built as an HTML page styled to match the project's brand, then screenshotted with Playwright.

Phase 1: Ensure Playwright is Available

npx playwright --version 2>/dev/null || (echo "Installing Playwright..." && npx playwright install chromium)

If installation fails, inform the user and suggest npm install -D playwright && npx playwright install chromium.

Phase 2: Understand What Changed (Git-Aware)

Analyze the recent git history to understand what feature/update to announce:

1. Check recent commits:

   git log --oneline -20
   

2. Check current diff (staged + unstaged):

   git diff HEAD --stat
   git diff HEAD -- '*.tsx' '*.jsx' '*.vue' '*.svelte' '*.html' '*.css' '*.scss' '*.rb' '*.erb'
   

3. Check recent branch name (often describes the feature):

   git branch --show-current
   

4. Synthesize what the feature/update is from this context.

5. Present findings to user with AskUserQuestion:

   • Header: "Feature"
   • Question: "Based on recent changes, it looks like you're working on [X]. What should this announcement be about?"
   • Options:
     • "[Auto-detected feature description]" - Use what was detected
     • "Something else" - Let user describe it
   • If $1 was provided as an argument, use that instead of asking.

Phase 3: Auto-Generate Announcement Text

Generate text elements for the image:

• Headline: A punchy, short headline (3-8 words) about the feature
• Tagline: A one-sentence supporting description
• Badge/Label: Optional category label (e.g., "New Feature", "Update", "Improvement")

Present these to the user with AskUserQuestion:

• Header: "Copy"
• Question: "Here's the text I'd put on the image. Want to adjust anything?"
• Options:
  • "Looks good" - Use as-is
  • "Edit headline" - User provides custom headline
  • "Edit everything" - User provides all text
  • "No text overlay" - Generate image without text

Phase 4: Choose Platform & Size

Use AskUserQuestion:

• Header: "Platform"
• Question: "What platform is this image for?"
• Options:
  • "Twitter/X (1200x675)" - Standard Twitter card size
  • "LinkedIn (1200x627)" - LinkedIn share image
  • "Instagram (1080x1080)" - Square format
  • "Open Graph (1200x630)" - Universal social preview

Store the chosen width and height for the Playwright viewport.

Phase 5: Choose Visual Style

Use AskUserQuestion:

• Header: "Style"
• Question: "What visual style should the image use?"
• Options:
  • "Stylized mockup (Recommended)" - Simplified, polished recreation of UI elements using the app's actual components and CSS. Recognizable but not pixel-perfect.
  • "Screenshot + overlay" - Takes a real screenshot of the running app and adds branded text overlays, gradients, and annotations.
  • "Abstract/illustrative" - Uses brand colors and typography to create a geometric or gradient design that suggests the feature without replicating specific UI.

Style: Stylized Mockup

This is the most involved style. The goal is to create a representation of the UI that feels like the app without being a literal screenshot.

1. Find relevant UI components related to the feature:

   • Search for component files that match the feature (e.g., if the feature is "dark mode", find theme toggle components)
   • Read the component markup to understand the UI structure
   • Note key visual elements: buttons, cards, inputs, tables, navigation items

2. Extract visual patterns from components:

   • Border radius values
   • Shadow styles
   • Specific layout patterns (sidebar + main, card grids, etc.)
   • Icon usage
   • Interactive element styles (buttons, toggles, inputs)

3. Build a simplified HTML mockup that:

   • Shows the key UI elements of the feature in a stylized, editorial layout
   • Uses the actual brand colors, fonts, and border-radius from the codebase
   • Adds subtle visual polish (soft shadows, slight gradients, generous whitespace)
   • Frames the UI in a "browser window" or "device frame" if appropriate
   • Is NOT a full working page -- it's a curated, art-directed composition

Style: Screenshot + Overlay

1. Ask the user for the URL of the running app (suggest common localhost URLs)
2. Navigate to the relevant page with Playwright
3. Take a base screenshot
4. Create an HTML overlay page that:
   • Embeds the screenshot as a background image
   • Adds a gradient overlay (using brand colors) for text readability
   • Places headline and tagline text on top
   • Adds a badge/label if applicable
5. Screenshot the overlay page

Style: Abstract/Illustrative

Build an HTML page with:

• A gradient or geometric background using brand colors
• The project logo (if found in /public, /assets, or /src/assets)
• Large, bold headline text using the project's font
• Supporting tagline
• Abstract shapes, lines, or patterns that evoke the feature category
• Clean, modern aesthetic with generous whitespace

Phase 6: Deep Brand Analysis

This is the most important phase. Spend real time here. The generated image must feel like it was made by the same team that built the product -- not a generic template with brand colors swapped in. The goal is to internalize the brand's visual identity so deeply that the image is indistinguishable from something the design team would produce.

6.1: Study Existing Marketing Materials First

Before looking at config files, study how the brand actually presents itself. These are your primary references:

1. Landing pages and marketing pages -- search for:

   • pages/index, app/page, pages/home, components/landing/, components/marketing/, components/hero
   • Any files with landing, marketing, home, hero, cta in the name
   • Read these files thoroughly. Note the exact tone, layout patterns, how they compose text + visuals, gradient directions, decorative elements, background treatments

2. Existing social/OG images -- search for:

   • og-image, social, share, twitter, preview in /public or /assets
   • Any existing announcement or marketing images in the repo
   • These are your strongest reference for what the brand considers "on-brand" for social

3. Blog or changelog pages -- search for:

   • blog, changelog, updates, announcements in page/route files
   • These show how the brand communicates updates -- mirror this tone and style

4. Email templates -- search for:

   • email, mailer, newsletter templates
   • These reveal another facet of the brand's visual language

5. README and docs -- check for badges, banner images, or styled headers that reveal brand personality

6.2: Color Palette

Extract the full color system, not just primary/secondary:

1. Tailwind config (tailwind.config.js, tailwind.config.ts):

   • Read the entire theme.extend.colors block
   • Note the full palette: primary, secondary, accent, neutral, success, warning, error
   • Pay attention to color relationships -- how does the brand pair colors?

2. CSS custom properties (search for :root in global CSS files):

   • Look for --primary, --brand, --accent, --background, --foreground, --muted, --card or similar
   • Extract HSL/RGB/hex values
   • Note if there are separate light/dark mode palettes

3. Design token files (search for tokens, theme, design-system in filenames):

   • Extract color definitions and semantic mappings

4. Actual usage in marketing components:

   • Read hero sections, CTA buttons, feature cards, pricing tables
   • Note which colors are used for backgrounds vs. text vs. accents vs. borders
   • Look for gradient definitions -- exact stops, directions, and where they're used
   • Find the brand's "signature" color combinations (e.g., dark bg + bright accent, soft pastels, bold primaries)

6.3: Typography

1. Font imports (search for @import with font URLs, @font-face, or Google Fonts links)
2. Tailwind fontFamily config
3. CSS font-family declarations on body/headings
4. Package.json for font packages (e.g., @fontsource/*, next/font)
5. Actual heading styles -- read marketing page headings to see:
   • Font weight (bold? black? medium?)
   • Letter spacing (tight? normal? wide?)
   • Text transform (uppercase? normal?)
   • Line height
   • How headlines are sized relative to body text

For the image, use the detected font. If it's a Google Font, include the <link> tag in the HTML. If it's a local/custom font, fall back to a similar system font or Google Font alternative.

6.4: Logo & Assets

Search for logo files:

public/logo*, public/images/logo*, src/assets/logo*, assets/logo*
public/*.svg (check for logo-like SVGs)
public/brand*, src/assets/brand*

If a logo is found, embed it in the image (inline SVG or base64-encoded).

Also look for:

• Icon libraries or custom icon sets used in the app
• Illustration styles (line art? filled? duotone?)
• Background patterns or textures
• Decorative elements (dots, grids, blobs, rings)

6.5: Visual Language & Patterns

Go beyond basic config -- study the visual personality of the brand:

• Border radius: Is the app rounded (rounded-xl, rounded-2xl) or sharp (rounded-none, rounded-sm)? Use the exact same radii.
• Shadows: Soft/elevated or flat? What shadow values are used? (e.g., shadow-lg vs shadow-sm vs no shadow)
• Dark mode: Is dark mode the default or primary theme? What's the background color?
• Gradients: Are gradients used prominently? What direction, what colors, where?
• Glass/blur effects: Any backdrop-blur usage? Translucent cards?
• Borders: Are borders used for separation or are things borderless? What color/opacity?
• Spacing rhythm: Is the design dense and compact or airy with lots of whitespace?
• Decorative elements: Does the brand use background grids, dot patterns, glow effects, noise textures, gradient orbs?
• Animation style: While animation won't appear in the image, the feel of a brand that uses smooth spring animations vs. no animations tells you about its personality

6.6: Synthesize a Brand Brief

Before building the image, write a short internal summary of the brand's visual identity:

• "This brand uses [dark/light] backgrounds with [color] accents. Typography is [font] at [weight], [tight/normal] letter spacing. The aesthetic is [minimal/bold/playful/corporate]. Key visual motifs include [gradients/glass/sharp corners/etc]. Marketing pages use [layout pattern] with [decorative elements]."

Use this brief as your guide for every design decision in the image. Every element should pass the test: "Would this look at home on their landing page?"

Phase 7: Build the HTML Image Page

Unique temp files: To avoid race conditions when multiple agents run in parallel, generate a slug-based ID for this run. Format: {project-slug}-{feature-slug}-{short-id} where project slug comes from the directory name or package.json name, feature slug is a 2-3 word kebab-case summary of the feature, and short ID is 4-6 random alphanumeric chars. Example: baremetrics-dark-mode-a3f2. Use this slug in all temp file paths below (shown as [UNIQUE_ID]). Both the HTML file and the capture script must use the same slug.

Create a self-contained HTML file at /tmp/feature-image-[UNIQUE_ID]-page.html that:

1. Is exactly the chosen dimensions (viewport-sized, no scroll)
2. Embeds all styles inline (no external CSS dependencies)
3. Includes fonts via Google Fonts link (or similar CDN)
4. Uses the detected brand colors, fonts, and visual patterns
5. Contains the chosen text overlay (headline, tagline, badge)
6. Matches the chosen visual style (mockup, screenshot+overlay, or abstract)

HTML Structure Template

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <link href="https://fonts.googleapis.com/css2?family=[DETECTED_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: '[DETECTED_FONT]', system-ui, sans-serif;
    }
    body {
      background: [BRAND_GRADIENT_OR_COLOR];
      color: [TEXT_COLOR];
      display: flex;
      /* Layout depends on style choice */
    }
    /* ... style-specific CSS ... */
  </style>
</head>
<body>
  <!-- Content depends on style choice -->
</body>
</html>

Design Quality Guidelines

The image should look like it was designed by a professional. Follow these principles:

• Hierarchy: Headline is the largest element. Tagline supports it. Badge is small.
• Contrast: Text must be easily readable against the background.
• Alignment: Use a clear grid. Left-align or center consistently.
• Polish: Subtle shadows, smooth gradients, refined typography (letter-spacing, line-height).
• Restraint: Don't use more than 2-3 colors. Don't use more than 2 font weights.

Space Usage (CRITICAL)

These images will be viewed at small sizes in social feeds, timeline cards, and link previews. Every pixel matters. Dead space is wasted space.

Mandatory rules:

1. Fill the canvas. Content should use 85-95% of the available area. Padding should be tight -- 40-60px max on a 1200px-wide image, not 100+.
2. Make text BIG. Headlines should be 48-72px minimum (at 1x). If the headline is short (3-4 words), go even bigger -- 80-100px. The text needs to be readable at thumbnail size (~400px wide). If you squint at the image and can't read the headline, it's too small.
3. No empty centers. If the layout has a headline on top and a UI mockup on the bottom, don't leave a big gap in the middle. Stack elements tightly or fill the space with supporting content.
4. UI mockups should be large. If showing a stylized UI element, it should take up at least 50-60% of the image area. Don't render a tiny card floating in a sea of background gradient.
5. Edge-to-edge when appropriate. UI mockups can bleed off the edges of the canvas -- this looks more dynamic and uses space better than centering everything with margins.
6. Badge/label text should be 14-18px, not smaller. It needs to be visible.
7. Test at thumbnail size. Before finalizing, mentally shrink the image to 400px wide. Can you still read the headline? Can you tell what the UI shows? If not, make things bigger.

Common mistakes to avoid:

• A small headline centered in the middle of a large background -- scale it up, push it to a corner or edge
• A UI mockup that's 30% of the canvas surrounded by gradient -- make it dominant
• Excessive padding that makes content feel like it's floating in space
• Tagline text at 14-16px -- bump it to 20-24px minimum
• Using the same spacing between all elements instead of grouping related items tightly

Phase 8: Screenshot with Playwright

Create and run a Node.js script:

import { chromium } from 'playwright';
import { readFileSync } from 'fs';

async function capture() {
  const browser = await chromium.launch();
  const context = await browser.newContext({
    viewport: { width: [WIDTH], height: [HEIGHT] },
    deviceScaleFactor: 2, // Retina quality
  });
  const page = await context.newPage();

  // Load the HTML file
  const html = readFileSync('/tmp/feature-image-[UNIQUE_ID]-page.html', 'utf-8');
  await page.setContent(html, { waitUntil: 'networkidle' });

  // Wait for fonts to load
  await page.waitForTimeout(1000);

  await page.screenshot({
    path: './feature-image.png',
    type: 'png',
  });

  await browser.close();
  console.log('Saved: ./feature-image.png');
}

capture().catch(console.error);

Save the script to /tmp/feature-image-[UNIQUE_ID]-capture.mjs, run it, then clean up:

node /tmp/feature-image-[UNIQUE_ID]-capture.mjs && rm /tmp/feature-image-[UNIQUE_ID]-capture.mjs /tmp/feature-image-[UNIQUE_ID]-page.html

Phase 9: Verify & Present

1. Check the file exists and has reasonable size:

   ls -la ./feature-image.png
   sips -g pixelWidth -g pixelHeight ./feature-image.png 2>/dev/null || file ./feature-image.png
   

2. Read the image using the Read tool to show it to the user.

3. Ask if adjustments are needed with AskUserQuestion:

   • Header: "Result"
   • Question: "Here's your feature image. What do you think?"
   • Options:
     • "Looks great" - Done
     • "Adjust colors" - Tweak the color palette
     • "Adjust text" - Change headline/tagline
     • "Try different style" - Switch to another visual style
   • If adjustments are needed, go back to the relevant phase and regenerate.

4. Output summary:

   Generated: ./feature-image.png
   Size: [W]x[H] @ 2x ([actual_W]x[actual_H] pixels)
   Platform: [chosen platform]
   Style: [chosen style]
   

Error Handling

• Playwright not found after install attempt: Suggest manual installation with npm install -D playwright && npx playwright install chromium
• No git history: Skip git analysis, ask user directly what the feature is
• No brand colors found: Fall back to a clean, neutral palette (dark background, white text, blue accent)
• No fonts detected: Fall back to Inter (Google Font) as a safe, modern default
• Screenshot fails: Check if the HTML file was created correctly, try with a simpler layout
• Font not loading in screenshot: Increase the wait timeout, or fall back to system fonts

Tips for Best Results

1. Run this skill from within the project directory so brand detection works
2. If the app has a running dev server, the "Screenshot + overlay" style will produce the most authentic results
3. For abstract style, the skill works well even without UI components to reference
4. The generated image is 2x resolution (retina) -- it will look sharp on all screens