svg-diagram

Generate SVG diagrams, OG images, and dynamic graphics using Satori with Tailwind CSS. Use when creating programmatic images, social cards, or diagrams from JSX/React components.

⭐4stars🔀1forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill enables the programmatic generation of high-quality SVG diagrams, Open Graph (OG) images, and dynamic graphics using Satori and Tailwind CSS. It allows developers to transform JSX and React components into scalable vector graphics, streamlining the creation of visual assets for web applications, automated social media cards, and technical documentation.

Use Cases

  • Automated OG Image Generation: Dynamically create branded social media preview images for blog posts, products, or landing pages using site metadata and React templates.
  • Programmatic Technical Diagrams: Generate scalable system architectures, flowcharts, or data visualizations directly from code descriptions or structured JSON data.
  • Personalized Social Sharing Cards: Produce custom user achievement badges, milestone summaries, or profile cards for social sharing based on real-time user data.
  • Multi-theme Asset Production: Efficiently build and export consistent visual assets that automatically adapt to light and dark modes using Tailwind CSS utility classes.
namesvg-diagram
descriptionGenerate SVG diagrams, OG images, and dynamic graphics using Satori with Tailwind CSS. Use when creating programmatic images, social cards, or diagrams from JSX/React components.

SVG Diagram Generation with Satori

Satori converts JSX/React components to SVG. It powers Vercel's OG Image Generation and is ideal for creating dynamic images programmatically.

Quick Start

import satori from 'satori'

const svg = await satori(
  <div tw="flex flex-col w-full h-full items-center justify-center bg-white">
    <h1 tw="text-6xl font-bold text-gray-900">Hello World</h1>
  </div>,
  {
    width: 1200,
    height: 630,
    fonts: [
      {
        name: 'Inter',
        data: await fetch('https://fonts.gstatic.com/s/inter/v13/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hjp-Ek-_EeA.woff').then(r => r.arrayBuffer()),
        weight: 400,
        style: 'normal',
      },
    ],
  }
)

The tw= Prop (Tailwind Integration)

Use tw= instead of style= for cleaner, Tailwind-based styling:

// with tw= prop (preferred)
<div tw="flex flex-col w-full h-full items-center justify-center bg-white">
  <h1 tw="text-4xl font-bold text-gray-900">Title</h1>
  <p tw="text-xl text-gray-600 mt-4">Subtitle</p>
</div>

// equivalent with style=
<div style={{
  display: 'flex',
  flexDirection: 'column',
  width: '100%',
  height: '100%',
  alignItems: 'center',
  justifyContent: 'center',
  backgroundColor: 'white',
}}>
  <h1 style={{ fontSize: 36, fontWeight: 700, color: '#111827' }}>Title</h1>
  <p style={{ fontSize: 20, color: '#4B5563', marginTop: 16 }}>Subtitle</p>
</div>

Supported Tailwind Classes

Layout:

  • flex, flex-col, flex-row, flex-wrap
  • items-center, items-start, items-end, items-stretch
  • justify-center, justify-start, justify-end, justify-between, justify-around
  • gap-*, gap-x-*, gap-y-*

Sizing:

  • w-*, h-*, w-full, h-full, w-screen, h-screen
  • min-w-*, max-w-*, min-h-*, max-h-*

Spacing:

  • p-*, px-*, py-*, pt-*, pr-*, pb-*, pl-*
  • m-*, mx-*, my-*, mt-*, mr-*, mb-*, ml-*

Typography:

  • text-xs, text-sm, text-base, text-lg, text-xl, text-2xl ... text-9xl
  • font-thin, font-light, font-normal, font-medium, font-semibold, font-bold, font-black
  • text-left, text-center, text-right, text-justify
  • tracking-tight, tracking-normal, tracking-wide
  • leading-tight, leading-normal, leading-relaxed

Colors:

  • text-gray-900, text-blue-500, text-white, etc.
  • bg-white, bg-gray-100, bg-blue-500, etc.
  • border-gray-200, border-blue-500, etc.

Borders:

  • border, border-2, border-4
  • rounded, rounded-lg, rounded-xl, rounded-full
  • border-solid, border-dashed

Effects:

  • shadow, shadow-md, shadow-lg, shadow-xl
  • opacity-*

Responsive Breakpoints:

  • sm:, md:, lg:, xl:, 2xl: prefixes work based on width

Supported CSS Properties

Layout (Flexbox Only - No CSS Grid)

<div tw="flex">           {/* display: flex (default) */}
<div tw="flex flex-col">  {/* flexDirection: column */}
<div tw="flex flex-wrap"> {/* flexWrap: wrap */}

Positioning

<div tw="relative">
  <div tw="absolute top-0 left-0">Positioned</div>
  <div tw="absolute bottom-4 right-4">Corner</div>
</div>

Typography

<p tw="text-4xl font-bold tracking-tight leading-tight">
  Large bold text
</p>
<p tw="text-sm text-gray-500 uppercase">
  Small caps
</p>

Colors & Backgrounds

// solid colors
<div tw="bg-blue-500 text-white">Blue background</div>

// gradients (use style for complex gradients)
<div style={{
  backgroundImage: 'linear-gradient(to right, #3b82f6, #8b5cf6)',
}}>
  Gradient
</div>

Text Gradients

<span style={{
  backgroundImage: 'linear-gradient(90deg, #3b82f6, #8b5cf6)',
  backgroundClip: 'text',
  color: 'transparent',
}}>
  Gradient Text
</span>

Shadows

<div tw="shadow-lg rounded-xl p-6 bg-white">
  Card with shadow
</div>

Transforms (2D Only)

<div style={{ transform: 'rotate(5deg)' }}>Rotated</div>
<div style={{ transform: 'scale(1.1)' }}>Scaled</div>
<div style={{ transform: 'translateX(10px) translateY(5px)' }}>Moved</div>

Common Patterns

Centered Card Layout

<div tw="flex w-full h-full items-center justify-center bg-gray-100">
  <div tw="flex flex-col bg-white rounded-2xl shadow-xl p-12 max-w-2xl">
    <h1 tw="text-5xl font-bold text-gray-900 mb-4">Card Title</h1>
    <p tw="text-xl text-gray-600">Card description goes here</p>
  </div>
</div>
<div tw="flex flex-col w-full h-full bg-white p-16">
  {/* header */}
  <div tw="flex items-center">
    <img src={logoBase64} width={48} height={48} />
    <span tw="ml-4 text-2xl font-semibold text-gray-900">Brand</span>
  </div>

  {/* main content */}
  <div tw="flex flex-1 items-center justify-center">
    <h1 tw="text-6xl font-bold text-gray-900 text-center max-w-4xl">
      Your Dynamic Title Here
    </h1>
  </div>

  {/* footer */}
  <div tw="flex justify-between items-center text-gray-500">
    <span>example.com</span>
    <span>@username</span>
  </div>
</div>

Background Pattern (Dots)

<div
  tw="flex w-full h-full items-center justify-center"
  style={{
    backgroundColor: 'white',
    backgroundImage: 'radial-gradient(circle at 25px 25px, #e5e7eb 2%, transparent 0%)',
    backgroundSize: '50px 50px',
  }}
>
  <h1 tw="text-5xl font-bold">Content over pattern</h1>
</div>

Two Column Layout

<div tw="flex w-full h-full bg-white">
  {/* left column */}
  <div tw="flex flex-col w-1/2 p-12 justify-center">
    <h1 tw="text-5xl font-bold text-gray-900 mb-4">Title</h1>
    <p tw="text-xl text-gray-600">Description text</p>
  </div>

  {/* right column */}
  <div tw="flex w-1/2 bg-blue-500 items-center justify-center">
    <img src={imageBase64} width={300} height={300} />
  </div>
</div>

Component Composition

const Badge = ({ children, color }) => (
  <span tw={`px-3 py-1 rounded-full text-sm font-medium bg-${color}-100 text-${color}-800`}>
    {children}
  </span>
)

const Card = ({ title, tags }) => (
  <div tw="flex flex-col bg-white rounded-xl shadow-lg p-8">
    <h2 tw="text-3xl font-bold text-gray-900 mb-4">{title}</h2>
    <div tw="flex gap-2">
      {tags.map(tag => <Badge color="blue">{tag}</Badge>)}
    </div>
  </div>
)

Light/Dark Mode Build Script

Create diagrams in both light and dark variants automatically:

scripts/generate-diagrams.ts

import satori from 'satori'
import { Resvg } from '@resvg/resvg-js'
import { readFileSync, writeFileSync, mkdirSync } from 'fs'
import { join } from 'path'

// load font once
const interRegular = readFileSync('./fonts/Inter-Regular.ttf')
const interBold = readFileSync('./fonts/Inter-Bold.ttf')

const fonts = [
  { name: 'Inter', data: interRegular, weight: 400, style: 'normal' as const },
  { name: 'Inter', data: interBold, weight: 700, style: 'normal' as const },
]

// theme definitions
const themes = {
  light: {
    bg: 'white',
    bgSecondary: '#f3f4f6',
    text: '#111827',
    textSecondary: '#6b7280',
    accent: '#3b82f6',
    border: '#e5e7eb',
  },
  dark: {
    bg: '#111827',
    bgSecondary: '#1f2937',
    text: '#f9fafb',
    textSecondary: '#9ca3af',
    accent: '#60a5fa',
    border: '#374151',
  },
}

type Theme = typeof themes.light

// your diagram component - receives theme colors
function createDiagram(theme: Theme) {
  return (
    <div
      tw="flex flex-col w-full h-full p-16"
      style={{ backgroundColor: theme.bg }}
    >
      <div tw="flex items-center mb-8">
        <div
          tw="w-12 h-12 rounded-xl flex items-center justify-center text-white text-2xl font-bold"
          style={{ backgroundColor: theme.accent }}
        >
          S
        </div>
        <span
          tw="ml-4 text-2xl font-bold"
          style={{ color: theme.text }}
        >
          My Diagram
        </span>
      </div>

      <div
        tw="flex flex-1 rounded-2xl p-8"
        style={{ backgroundColor: theme.bgSecondary }}
      >
        <div tw="flex flex-col justify-center">
          <h1
            tw="text-5xl font-bold mb-4"
            style={{ color: theme.text }}
          >
            Dynamic Content
          </h1>
          <p
            tw="text-xl"
            style={{ color: theme.textSecondary }}
          >
            Generated with Satori in light and dark mode
          </p>
        </div>
      </div>

      <div
        tw="flex justify-between items-center mt-8 text-sm"
        style={{ color: theme.textSecondary }}
      >
        <span>example.com</span>
        <span>Generated at {new Date().toISOString().split('T')[0]}</span>
      </div>
    </div>
  )
}

interface GenerateOptions {
  name: string
  width?: number
  height?: number
  outputDir?: string
  formats?: ('svg' | 'png')[]
}

async function generateDiagram(options: GenerateOptions) {
  const {
    name,
    width = 1200,
    height = 630,
    outputDir = './output',
    formats = ['svg', 'png'],
  } = options

  mkdirSync(outputDir, { recursive: true })

  for (const [themeName, theme] of Object.entries(themes)) {
    const element = createDiagram(theme)

    // generate SVG
    const svg = await satori(element, { width, height, fonts })

    if (formats.includes('svg')) {
      const svgPath = join(outputDir, `${name}-${themeName}.svg`)
      writeFileSync(svgPath, svg)
      console.log(`Created: ${svgPath}`)
    }

    if (formats.includes('png')) {
      // convert to PNG at 2x resolution for retina
      const resvg = new Resvg(svg, {
        fitTo: { mode: 'width', value: width * 2 },
      })
      const pngData = resvg.render()
      const pngPath = join(outputDir, `${name}-${themeName}.png`)
      writeFileSync(pngPath, pngData.asPng())
      console.log(`Created: ${pngPath}`)
    }
  }
}

// generate all diagrams
async function main() {
  await generateDiagram({ name: 'og-image' })
  await generateDiagram({ name: 'twitter-card', width: 1200, height: 600 })
  await generateDiagram({ name: 'square', width: 1080, height: 1080 })
}

main().catch(console.error)

package.json Scripts

{
  "scripts": {
    "generate:diagrams": "tsx scripts/generate-diagrams.ts",
    "generate:watch": "tsx watch scripts/generate-diagrams.ts"
  },
  "dependencies": {
    "satori": "^0.10.0",
    "@resvg/resvg-js": "^2.6.0"
  },
  "devDependencies": {
    "tsx": "^4.0.0",
    "@types/node": "^20.0.0"
  }
}

Usage

# generate all diagrams
npm run generate:diagrams

# output:
# output/og-image-light.svg
# output/og-image-light.png
# output/og-image-dark.svg
# output/og-image-dark.png
# ...

Converting to PNG

For high-quality PNG output, use @resvg/resvg-js:

import { Resvg } from '@resvg/resvg-js'

const svg = await satori(element, options)

// 2x resolution for retina displays
const resvg = new Resvg(svg, {
  fitTo: { mode: 'width', value: 2400 },  // 2x of 1200
})

const pngBuffer = resvg.render().asPng()

Standard Dimensions

Platform Size Aspect Ratio
Open Graph 1200×630 1.91:1
Twitter Card 1200×600 2:1
LinkedIn 1200×627 1.91:1
Instagram Square 1080×1080 1:1
Instagram Story 1080×1920 9:16

Limitations & Gotchas

Not Supported

  • CSS Grid - use Flexbox only
  • z-index - elements render in document order
  • calc() - no CSS calculations
  • Animations - static output only
  • React hooks - no useState, useEffect, etc.
  • WOFF2 fonts - use TTF, OTF, or WOFF
  • RTL languages - Arabic, Hebrew not supported
  • 3D transforms - 2D only (rotate, scale, translate, skew)

Important Notes

  • Fonts required: Always provide at least one font
  • Default display is flex: All elements default to display: flex
  • Default flexWrap is wrap: Unlike CSS default
  • Images need dimensions: Always specify width/height on <img>
  • Use base64 for images: Avoids network requests during render
  • No currentColor: Except for the color property itself
  • Never pass undefined to style props: Causes trim() crash. Build style objects conditionally instead.
  • Use flexbox, avoid hardcoded dimensions: Let content determine size with padding. Use flex-1, w-full, items-stretch etc. Don't manually wrap text with multiple spans. Exception: icons need fixed sizes.

Font Loading

// good: load font once, reuse
const fontData = await fetch(fontUrl).then(r => r.arrayBuffer())
const fonts = [{ name: 'Inter', data: fontData, weight: 400, style: 'normal' }]

// use same fonts array for multiple renders
const svg1 = await satori(element1, { fonts, width: 1200, height: 630 })
const svg2 = await satori(element2, { fonts, width: 1200, height: 630 })

Recommended: Use fontsource packages for reliable local fonts (avoids network issues):

bun add @fontsource/inter @fontsource/jetbrains-mono
import { readFileSync } from 'fs';
import { join } from 'path';

const FONT_DIR = join(__dirname, 'node_modules/@fontsource/inter/files');
const fonts = [{
  name: 'Inter',
  data: readFileSync(join(FONT_DIR, 'inter-latin-400-normal.woff')), // woff only, not woff2
  weight: 400 as const,
  style: 'normal' as const,
}];

Image Handling

// convert image to base64 for embedding
const imageBuffer = await fetch(imageUrl).then(r => r.arrayBuffer())
const base64 = `data:image/png;base64,${Buffer.from(imageBuffer).toString('base64')}`

// use in component
<img src={base64} width={200} height={200} />

Custom Tailwind Config

await satori(element, {
  width: 1200,
  height: 630,
  fonts,
  tailwindConfig: {
    theme: {
      extend: {
        colors: {
          brand: '#ff6b00',
        },
        fontFamily: {
          display: ['Custom Font'],
        },
      },
    },
  },
})

Debug Mode

Enable bounding boxes to debug layout issues:

await satori(element, {
  width: 1200,
  height: 630,
  fonts,
  debug: true,  // shows element boundaries
})

Resources