marcolang/marketing-skills/instagram-carousel

Instagram Carousel Generator

Generates fully self-contained, swipeable HTML carousels where every slide is designed to be exported as an individual 1080×1350px PNG for Instagram.

Step 1: Collect Brand Details

Before generating, ask the user for the following (if not already provided):

1. Brand name — displayed on first and last slides
2. Instagram handle — shown in the IG frame header
3. Primary brand color — hex code, or describe and Claude picks one
4. Logo — SVG path, brand initial, or skip
5. Font preference — see typography table below, or specific Google Fonts
6. Tone — professional, casual, playful, bold, minimal, etc.
7. Images — profile photo, screenshots, product images, etc.
8. Idioma dos slides — default: Português (BR) unless specified otherwise
9. Carousel format — standard (7 slides) or alternate sequence (see sequences section)

If the user provides a website URL or brand assets, derive colors and style from those.

If the user says "make me a carousel about X" without brand details, ask before generating. Don't assume defaults.

Handling User-Provided Images

This section applies from the very first HTML generation — not only during export.

When the user provides an image file path (e.g., /home/user/gestante.png, /mnt/user-data/uploads/foto.jpg):

⚠️ Critical Rules

1. NEVER use relative paths (gestante.png) — they break in every browser context except the exact folder the HTML lives in.
2. NEVER use `background: url(filepath)` — leads to 1.5MB+ base64 inline strings that crash the browser parser.
3. ALWAYS embed as base64 `data:` URI — works in preview, export, and any environment.
4. ALWAYS generate the HTML via Python (Path.write_text()) — shell heredocs interpolate $ and backticks, corrupting base64 strings.

Step-by-step: embed an image

# 1. Check the actual file format (extension may lie)
file /path/to/image.png

import base64
from pathlib import Path
# 2. Read and encode
img_path = Path("/path/to/image.png")
# Use "image/jpeg" if `file` command says JPEG, else "image/png"
mime = "image/jpeg"  # or "image/png"
b64 = base64.b64encode(img_path.read_bytes()).decode()
data_uri = f"data:{mime};base64,{b64}"
# 3. Inject into HTML template as a Python variable — never via shell
html = f"""
<div style="position:relative;width:100%;height:100%;">
  <img src="{data_uri}"
       style="position:absolute;inset:0;width:100%;height:100%;object-fit:cover;z-index:0;">
  <div style="position:absolute;inset:0;background:rgba(255,255,255,0.35);z-index:1;"></div>
  <!-- slide content goes here, z-index:2 -->
</div>
"""
Path("/home/claude/carousel.html").write_text(html, encoding="utf-8")

Image as slide background (most common use)

<!-- Inside the slide div, before any content -->
<img src="{data_uri}"
     style="position:absolute;inset:0;width:100%;height:100%;object-fit:cover;z-index:0;">
<!-- Semi-transparent overlay so text stays readable -->
<div style="position:absolute;inset:0;background:rgba(255,255,255,0.35);z-index:1;"></div>
<!-- All slide content must have z-index:2 or higher -->

For dark slides, use rgba(0,0,0,0.45) as the overlay instead.

Common image mistakes to avoid

Step 2: Derive the Full Color System

From the user's single primary brand color, generate the full 6-token palette:

BRAND_PRIMARY   = {user's color}                    // Main accent — progress bar, icons, tags
BRAND_LIGHT     = {primary lightened ~20%}           // Secondary accent — tags on dark, pills
BRAND_DARK      = {primary darkened ~30%}            // CTA text, gradient anchor
LIGHT_BG        = {warm or cool off-white}           // Light slide background (never pure #fff)
LIGHT_BORDER    = {slightly darker than LIGHT_BG}    // Dividers on light slides
DARK_BG         = {near-black with brand tint}       // Dark slide background

Rules for deriving colors:

• LIGHT_BG: tinted off-white complementing the primary (warm → warm cream, cool → cool gray-white)
• DARK_BG: near-black with subtle brand tint (warm → #1A1918, cool → #0F172A)
• LIGHT_BORDER: always ~1 shade darker than LIGHT_BG
• Brand gradient: linear-gradient(165deg, BRAND_DARK 0%, BRAND_PRIMARY 50%, BRAND_LIGHT 100%)

Step 3: Set Up Typography

Based on the user's font preference, pick a heading font and body font from Google Fonts.

Font size scale (fixed across all brands):

• Headings: 28–34px, weight 600, letter-spacing -0.3 to -0.5px, line-height 1.1–1.15
• Body: 14px, weight 400, line-height 1.5–1.55
• Tags/labels: 10px, weight 600, letter-spacing 2px, uppercase
• Step numbers: heading font, 26px, weight 300
• Small text: 11–12px

Apply via CSS classes .serif (heading font) and .sans (body font) throughout all slides.

Slide 1 — Hook Rules

The first slide must stop the scroll in under 1 second. Prioritize these formats:

Rules:

• Never start with the brand name as headline
• Visual proof on Slide 1 whenever possible (screenshot, result, real number)
• Hook must promise value that the following slides deliver

Slide Sequences

Standard (7 slides — default)

Listicle (5–10 slides)

Use for: "X ferramentas", "X erros", "X dicas"

Tutorial (7 slides)

Comparação (5 slides)

General rules for all sequences:

• Start with a hook — first slide must stop the scroll
• End CTA on brand gradient — no swipe arrow, progress bar at 100%
• Alternate light and dark backgrounds for visual rhythm
• Adapt sequence to topic — not every carousel needs all slides

Slide Architecture

Format

• Aspect ratio: 4:5 (Instagram carousel standard)
• Each slide is self-contained — all UI elements baked into the image
• Alternate LIGHT_BG and DARK_BG backgrounds for visual rhythm

Required Elements on Every Slide

1. Progress Bar (bottom of every slide)

Shows position in the carousel. Fills as user swipes.

• Position: absolute bottom, full width, 28px horizontal padding, 20px bottom padding
• Track: 3px height, rounded corners
• Fill width: ((slideIndex + 1) / totalSlides) * 100%
• Light slides: rgba(0,0,0,0.08) track, BRAND_PRIMARY fill, rgba(0,0,0,0.3) counter
• Dark slides: rgba(255,255,255,0.12) track, #fff fill, rgba(255,255,255,0.4) counter
• Counter label beside the bar: "1/7" format, 11px, weight 500

function progressBar(index, total, isLightSlide) {
  const pct = ((index + 1) / total) * 100;
  const trackColor = isLightSlide ? 'rgba(0,0,0,0.08)' : 'rgba(255,255,255,0.12)';
  const fillColor = isLightSlide ? BRAND_PRIMARY : '#fff'; // use actual BRAND_PRIMARY value
  const labelColor = isLightSlide ? 'rgba(0,0,0,0.3)' : 'rgba(255,255,255,0.4)';
  return `<div style="position:absolute;bottom:0;left:0;right:0;padding:16px 28px 20px;z-index:10;display:flex;align-items:center;gap:10px;">
    <div style="flex:1;height:3px;background:${trackColor};border-radius:2px;overflow:hidden;">
      <div style="height:100%;width:${pct}%;background:${fillColor};border-radius:2px;"></div>
    </div>
    <span style="font-size:11px;color:${labelColor};font-weight:500;">${index + 1}/${total}</span>
  </div>`;
}

⚠️ Important: Always replace BRAND_PRIMARY with the actual hex value before rendering. Never leave it as a variable name in the HTML output.

2. Swipe Arrow (right edge — every slide EXCEPT the last)

Subtle chevron guiding the user to keep swiping. Removed on the last slide.

• Position: absolute right, full height, 48px wide
• Background: gradient fade transparent → subtle tint
• Chevron: 24×24 SVG, rounded strokes
• Light slides: rgba(0,0,0,0.06) bg, rgba(0,0,0,0.25) stroke
• Dark slides: rgba(255,255,255,0.08) bg, rgba(255,255,255,0.35) stroke

function swipeArrow(isLightSlide) {
  const bg = isLightSlide ? 'rgba(0,0,0,0.06)' : 'rgba(255,255,255,0.08)';
  const stroke = isLightSlide ? 'rgba(0,0,0,0.25)' : 'rgba(255,255,255,0.35)';
  return `<div style="position:absolute;right:0;top:0;bottom:0;width:48px;z-index:9;display:flex;align-items:center;justify-content:center;background:linear-gradient(to right,transparent,${bg});">
    <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
      <path d="M9 6l6 6-6 6" stroke="${stroke}" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
    </svg>
  </div>`;
}

Reusable Components

Strikethrough pills

<span style="font-size:11px;padding:5px 12px;border:1px solid rgba(255,255,255,0.1);border-radius:20px;color:#6B6560;text-decoration:line-through;">{Old tool}</span>

Tag pills

<span style="font-size:11px;padding:5px 12px;background:rgba(255,255,255,0.06);border-radius:20px;color:{BRAND_LIGHT};">{Label}</span>

Prompt / quote box

<div style="padding:16px;background:rgba(0,0,0,0.15);border-radius:12px;border:1px solid rgba(255,255,255,0.08);">
  <p class="sans" style="font-size:13px;color:rgba(255,255,255,0.5);margin-bottom:6px;">{Label}</p>
  <p class="serif" style="font-size:15px;color:#fff;font-style:italic;line-height:1.4;">"{Quote text}"</p>
</div>