thumbnail-design

Thumbnail Design

Create high-impact thumbnails optimized for clicks and readability at small sizes. Covers YouTube thumbnails, article headers, OG images, and video covers.

---

Step 1: Load Design Context

1. Read .agents/design-context.md first -- brand colors (hex), fonts, style archetype
2. If missing, use the design-context Default Fallbacks and tell the user defaults were used
3. Thumbnails prioritize readability and impact over strict brand guidelines -- but brand colors create channel recognition

---

Gemini Image Generation Path

Pipeline/CLI: image-generation. Prompt craft, cropping, and text-overlay fallback: graphic-design Step 3.

1. Generate at the Gemini ratio in the Step 2 table; crop with --resize WxH (e.g. --aspect-ratio 16:9 --resize 1280x720)
2. Real people: pass their photo with --image and say "keep this person's face and identity unchanged". Don't invent likenesses of real people
3. Read the output PNG, then check it shrunk: python -c "from PIL import Image; Image.open('thumb.png').resize((168,94), Image.LANCZOS).save('thumb_small.png')" and Read thumb_small.png. Text must still be readable and the face expression visible. Fix one issue per follow-up turn

Example Prompts

• YouTube Thumbnail: "Create a YouTube thumbnail (16:9). [subject] on the left side with [expression/pose]. Bold text '[title]' in [color] with dark outline on the right. [background style]. High contrast, readable at small size."
• Article Header: "Create a landscape article header image. Abstract [color palette] gradient background. Title '[headline]' in bold white sans-serif, centered. Subtle geometric shapes. Clean, editorial feel."
• OG Image: "Create a landscape Open Graph image for [brand/site]. Keep all text inside the central 80%. Logo top-left, title '[text]' large and centered, tagline below in lighter weight. [brand color] gradient background. Professional, shareable."

---

Step 2: Identify Format and Dimensions

Format	Dimensions	Aspect Ratio	Gemini ratio	Notes
YouTube Thumbnail	1280 x 720	16:9	16:9	Min 640px wide; JPG/PNG under 2 MB; must read at 168x94
YouTube Shorts Cover	1080 x 1920	9:16	9:16	Shelf shows a center crop -- keep text mid-frame
Article Header / Hero	1200 x 630	1.91:1	16:9 + crop	Blog post header
OG Image (Open Graph)	1200 x 630	1.91:1	16:9 + crop	Link previews on FB, LinkedIn, Slack, X
X large-image card	1200 x 628	~1.91:1	16:9 + crop	X can crop toward 2:1 -- keep margins
Podcast Cover	3000 x 3000	1:1	1:1 (4K)	Apple: 1400-3000px square, JPG/PNG, RGB
Course Thumbnail	1280 x 720 (Udemy min 750 x 422)	16:9	16:9	Udemy, Skillshare
Vimeo Thumbnail	1280 x 720	16:9	16:9	Same as YouTube

---

Step 3: Thumbnail Composition Principles

The 3-Second Rule

A thumbnail must communicate its message in under 3 seconds. If someone cannot understand the topic at a glance, the thumbnail fails.

Readability at Small Sizes

YouTube thumbnails display as small as 168x94 pixels in the sidebar. Test every design mentally at that size.

Rules:

• Maximum 5-7 words of text
• Font size minimum: 60px at 1280x720 (equivalent to ~8px at sidebar size)
• No thin fonts -- use bold or black weights only
• High contrast between text and background (always)
• No small details that vanish at reduced size

The Three-Element Maximum

The best thumbnails have at most 3 visual elements:

1. A face or focal image
2. Bold text (2-5 words)
3. A supporting visual element (icon, arrow, emoji, product)

More than 3 elements creates clutter.

---

Step 4: Click-Worthy Composition Frameworks

Curiosity Gap

Show enough to intrigue but not enough to satisfy. The viewer must click to learn more.

Layout:
- Left side: Expressive face (surprise, shock, excitement)
- Right side: Bold text with ONE missing piece
- Example: "I tried [PRODUCT] for 30 days..." with shocked face
- Use "?" or "..." to create open loops

Before / After

Show transformation. The contrast drives clicks.

.before-after {
  display: grid;
  grid-template-columns: 1fr 1fr;
  height: 100%;
}
.before {
  background: #E5E7EB; /* muted, desaturated */
  filter: grayscale(30%);
  display: flex;
  align-items: center;
  justify-content: center;
}
.after {
  background: linear-gradient(135deg, var(--primary), var(--accent));
  display: flex;
  align-items: center;
  justify-content: center;
}
.divider-arrow {
  position: absolute;
  left: 50%;
  top: 50%;
  transform: translate(-50%, -50%);
  font-size: 64px;
  z-index: 10;
  /* Large arrow pointing right: → */
}

Numbers / Lists

Numbers grab attention. "7 Tips", "$10K", "100 Days".

Layout:
- Giant number: 120-200px, bold, gradient or accent color
- Supporting text: 36-48px next to or below number
- Background: clean gradient, not busy
- Optional icon related to the topic

Reaction / Emotion

Human faces expressing emotion are the highest-performing thumbnail element.

Layout:
- Face/headshot: 60% of frame, positioned left or right
- Expressive emotion: surprise, excitement, disbelief, joy
- 2-3 words of text on the opposite side
- Colored border or glow behind the face to separate from background

Versus / Comparison

Two things side by side with "VS" in the middle.

.versus {
  display: grid;
  grid-template-columns: 1fr auto 1fr;
  align-items: center;
  height: 100%;
}
.vs-badge {
  font-size: 72px;
  font-weight: 900;
  color: var(--accent);
  text-shadow: 0 0 30px rgba(var(--accent-rgb), 0.5);
  z-index: 2;
}
.side-a { background: linear-gradient(135deg, #1a1a2e, #16213e); }
.side-b { background: linear-gradient(135deg, #2d1b00, #462300); }

---

Step 5: Text Treatment for Thumbnails

Maximum Impact Text

/* Primary thumbnail text */
.thumb-text {
  font-family: 'Inter', 'Arial Black', sans-serif;
  font-size: 80px;
  font-weight: 900;
  color: #FFFFFF;
  text-transform: uppercase;
  line-height: 0.95;
  letter-spacing: -0.02em;

  /* Always add stroke + shadow for readability over any background */
  -webkit-text-stroke: 3px rgba(0, 0, 0, 0.8);
  paint-order: stroke fill;
  text-shadow:
    4px 4px 0 rgba(0, 0, 0, 0.9),
    0 0 20px rgba(0, 0, 0, 0.5);
}

/* Accent word highlight */
.thumb-text .highlight {
  color: var(--accent);
  -webkit-text-stroke-color: rgba(0, 0, 0, 0.9);
}

Text Background Techniques

/* Solid pill behind text */
.text-pill {
  display: inline-block;
  background: var(--primary);
  padding: 8px 24px;
  border-radius: 8px;
  font-weight: 800;
  font-size: 48px;
}

/* Angled highlight bar */
.text-bar {
  display: inline-block;
  background: var(--accent);
  padding: 8px 20px;
  transform: skewX(-5deg);
}
.text-bar span {
  display: inline-block;
  transform: skewX(5deg); /* counter-skew for straight text */
}

/* Blurred backdrop */
.text-backdrop {
  background: rgba(0, 0, 0, 0.6);
  backdrop-filter: blur(8px);
  padding: 12px 24px;
  border-radius: 8px;
}

---

Step 6: Face and Emotion Techniques

Face Cutout with Glow

.face-container {
  position: relative;
  z-index: 2;
}
.face-container img {
  /* Remove background in advance or use object-fit */
  height: 100%;
  object-fit: contain;
  object-position: bottom;
  filter: drop-shadow(0 0 30px rgba(var(--primary-rgb), 0.6));
}
/* Glow ring behind face */
.face-container::before {
  content: '';
  position: absolute;
  width: 80%;
  height: 80%;
  top: 10%;
  left: 10%;
  border-radius: 50%;
  background: radial-gradient(circle, rgba(var(--primary-rgb), 0.4), transparent 70%);
  z-index: -1;
}

Emoji Accents (When No Face Available)

Use oversized emojis as visual anchors when no photo is available:

.emoji-accent {
  font-size: 120px;
  position: absolute;
  /* Slight rotation adds energy */
  transform: rotate(-10deg);
  filter: drop-shadow(4px 4px 0 rgba(0,0,0,0.3));
}

---

Step 7: Color Psychology for Thumbnails

Color	Association	Best For
Red (#EF4444)	Urgency, excitement, danger	Breaking news, warnings, hot takes
Yellow (#EAB308)	Attention, optimism, energy	Tips, positive content, highlights
Blue (#3B82F6)	Trust, calm, professionalism	Tutorials, educational, tech
Green (#22C55E)	Growth, success, money	Finance, results, positive outcomes
Orange (#F97316)	Energy, creativity, warmth	Creative content, DIY, food
Purple (#8B5CF6)	Premium, mystery, wisdom	Luxury, deep dives, advanced topics
Black (#000000)	Power, elegance, sophistication	Dramatic reveals, premium content
White (#FFFFFF)	Clean, minimal, modern	Minimalist channels, Apple-style

Contrast Pairings That Pop

• Yellow text on dark blue background
• White text on deep red or purple
• Black text on bright yellow
• Cyan accent on dark background
• Red accent on dark gray/charcoal

---

Step 8: YouTube-Specific Optimization

Sidebar Readability Test

The thumbnail will appear at roughly 168x94px in the sidebar. At this size:

• Only bold, high-contrast text is readable
• Faces must be large enough to show expression
• Details vanish -- keep it simple
• The overall color scheme must be distinct from surrounding thumbnails

Overlay Zones

YouTube overlays the video duration in the bottom-right corner (dark pill with white text), a red watch-progress bar along the bottom edge for watched videos, and hover icons (Watch Later, Add to queue) in the top-right. Keep critical content out of all three.

/* Duration overlay safe zone */
.youtube-safe {
  /* Avoid content in this area */
  position: absolute;
  bottom: 0;
  right: 0;
  width: 120px;
  height: 40px;
  /* This zone is covered by YouTube's duration badge */
}

Channel Consistency

Create a thumbnail system with recurring elements:

• Consistent background color or gradient per series
• Same font treatment across all thumbnails
• Recurring layout structure (face left + text right, or vice versa)
• Brand color as a signature element (colored border, text highlight)

---

Step 9: Article Header / OG Image Design

OG Image Requirements

• Dimensions: 1200 x 630 (recommended by most platforms); declare them with og:image:width / og:image:height meta tags
• File size: under 1MB for fast loading (platform caps are higher, e.g. 5-8MB)
• Use an absolute HTTPS URL in og:image; add twitter:card = summary_large_image for X
• Text: readable when scaled to ~600x315 (half size in some feeds)
• Avoid text in the outer 10% margins (may be cropped)

Article Header Layout

.article-header {
  width: 1200px;
  height: 630px;
  position: relative;
  display: flex;
  align-items: center;
  padding: 60px 80px;
  background: linear-gradient(135deg, #0F172A, #1E293B);
  overflow: hidden;
}

.article-header .title {
  font-family: var(--font-heading);
  font-size: 56px;
  font-weight: 800;
  color: #F8FAFC;
  line-height: 1.15;
  max-width: 700px;
  text-wrap: balance;
}

.article-header .meta {
  display: flex;
  align-items: center;
  gap: 12px;
  margin-top: 24px;
  font-size: 18px;
  color: rgba(248, 250, 252, 0.7);
}

.article-header .brand {
  position: absolute;
  bottom: 40px;
  right: 60px;
  font-size: 20px;
  font-weight: 700;
  color: var(--primary);
}

/* Decorative accent */
.article-header::before {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  height: 6px;
  background: linear-gradient(90deg, var(--primary), var(--accent));
}

---

Step 10: Output and Export

Generate as self-contained HTML with fixed dimensions:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@700;800;900&display=swap" rel="stylesheet">
  <style>
    body { margin: 0; padding: 0; display: flex; justify-content: center; align-items: center;
           min-height: 100vh; background: #1a1a1a; }
    .thumbnail {
      width: 1280px;
      height: 720px;
      position: relative;
      overflow: hidden;
      /* ... design styles ... */
    }
  </style>
</head>
<body>
  <div class="thumbnail">
    <!-- Thumbnail content -->
  </div>
</body>
</html>
<!-- Export (window size = canvas size, so the centered canvas fills the frame exactly):
     node <graphic-design>/scripts/render.mjs thumb.html --size 1280x720 --out thumb.png
     (without the graphic-design skill: chromium --headless --hide-scrollbars --window-size=1280,720 --screenshot=thumb.png thumb.html) -->

Then Read the PNG and run the same 168x94 shrink test as for Gemini output.

---

Quality Checklist

• Output PNG was Read at full size and shrunk to 168x94px -- text spelled right and readable
• Maximum 5-7 words of text
• 3 or fewer visual elements
• High contrast text (stroke + shadow for safety)
• Clear focal point that communicates the topic
• Bottom-right corner, bottom edge, and top-right are clear (duration badge, progress bar, hover icons)
• Colors are distinct from platform UI (avoid pure white or YouTube red)
• Brand consistency with other thumbnails in the series
• Emotional hook -- face, number, or curiosity element
• Design-context colors and fonts are applied where appropriate