CommunityImagegithub.com

social-card-design

Complete system for designing link preview cards and social share images: Open Graph and Twitter/X cards, LinkedIn, Slack, Telegram, Discord and WeChat link previews, Instagram squares, YouTube thumbnails, blog and docs hero images. Covers surface sizes and safe zones, claim-first copy, card type scale, palette tokens shared with landing-page-design, platform crop and cache behavior, and deterministic PNG export with the required meta tags. Use this skill whenever creating, reviewing, fixing, or briefing anyone on an og:image, twitter:image, social preview, share card, link unfurl thumbnail, video thumbnail, or share graphic for a URL — even when the user does not say og:image, card, typography, tokens, or export.

What is social-card-design?

social-card-design is a Claude Code agent skill that complete system for designing link preview cards and social share images: Open Graph and Twitter/X cards, LinkedIn, Slack, Telegram, Discord and WeChat link previews, Instagram squares, YouTube thumbnails, blog and docs hero images. Covers surface sizes and safe zones, claim-first copy, card type scale, palette tokens shared with landing-page-design, platform crop and cache behavior, and deterministic PNG export with the required meta tags. Use this skill whenever creating, reviewing, fixing, or briefing anyone on an og:image, twitter:image, social preview, share card, link unfurl thumbnail, video thumbnail, or share graphic for a URL — even when the user does not say og:image, card, typography, tokens, or export.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/effiy/ai-design-skills/tree/HEAD/skills/social-card-design

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Social Card Design

A social card is not a poster. A poster is looked at. A card is glanced at, at 400px wide, next to nine other cards competing for the same thumb:

one card → one claim → one click.

This skill has three parts. Part A decides what the card claims and which surface it serves. Part B is the non-negotiable visual system. Part C covers platform crop behavior, meta tags, and export. Work through A before touching B or C.

Scope

In scope. Any static share image attached to a URL or a channel: og:image, twitter:image, link previews (X, LinkedIn, Slack, Telegram, Discord, WhatsApp, WeChat), Instagram square posts, YouTube thumbnails, video call backdrops, blog and docs hero images.

Out of scope — defer instead of improvising.

  • Page layout, web UI, components, conversion structure → landing-page-design in this repo.
  • Team avatar PNGs → avatar-design in this repo.
  • WeChat article body typesetting and article covers produced by the 公众号 pipeline → gzh-design-skill. This skill only covers the link preview card for a URL shared into WeChat.
  • Slide decks, logo and wordmark design, illustration. A card uses an existing mark; it never designs one.

Conflict order. The user's explicit prompt > this file > tool default. Where this file and landing-page-design disagree on a shared token (type scale, dark palette), landing-page-design wins for web UI and this file wins for the card canvas. The card palette below deliberately reuses its tokens so a card and its landing page look like one brand.


PART A — Surface, claim, structure

A1. Intake

Gather these before drawing. Ask only for what is missing, and ask in one batch rather than one question at a time.

The claim

  • What should the reader believe after half a second?
  • What is behind the click? (article, docs page, repo, product, changelog)

Placement

  • Which surfaces? (X, LinkedIn, Slack, Telegram, Discord, WhatsApp, WeChat, Instagram, YouTube)
  • Will the URL be shared mainly into chat apps, or mainly into feeds? Chat unfurls crop harder.
  • Does the site already have a dark theme, a light theme, or both?

Brand and content

  • The mark: SVG/PNG file, or none. Wordmark? Which domain to print?
  • Headline string, kicker, optional stat, optional author or role.
  • Language(s): Latin only, CJK, RTL.

Constraints

  • Any number printed on the card must have a source. If it has none, it does not go on the card.
  • File size or format limits imposed by the destination (some chat clients reject large images).

If an answer is missing, make a reasonable assumption, state it in one line, and continue. Do not stall the build.

A2. Surface selection

Pick one surface per card. Never upscale a wide card to a square, and never reuse one export across surfaces — the crop decisions differ.

SurfaceSizeRatioServes
og1200 × 6301.91:1og:image, twitter:image (summary_large_image), LinkedIn, Slack, Telegram, Discord, WhatsApp link previews
square1080 × 10801:1Instagram feed, WeChat Moments, square feed slots, WeChat link preview thumbnail
cover1280 × 7201.78:1YouTube thumbnail, video call background, docs hero, presentation title slide

Default is og. It is the only size every unfurler accepts. Ship a square companion whenever the card will be shared into WeChat or Instagram.

State the surface in your output. "I made a social card" without a surface is not shippable.

A3. The claim

The card carries one claim. Everything else on the canvas exists to support it or to say where it came from.

Headline

  • One sentence. States the promise, result, or tension — not the section name.
  • ❌ "Introduction to our design system"
  • ✅ "A design system the agent cannot drift from"
  • Sentence case for Latin. No trailing period. No hyphens inside the sentence (rewrite the phrase instead, same rule as landing-page-design B1).
  • Line cap: 2 lines on og and cover, 3 lines on square. If it does not fit at the floor size in B3, cut words. Never shrink below the floor.

Kicker (optional, recommended)

  • At most 4 words. A category, not a slogan: AI DESIGN SKILLS, CHANGELOG, FIELD NOTES.
  • Latin: uppercase, letter-spaced per B3. CJK: no letter-spacing, no uppercase concept.

Stat (optional, at most one)

  • One number plus a label of at most 4 words.
  • The number must be real, sourced, and reproducible. Never a rounded guess. If it needs a caveat, the caveat goes in og:image:alt, not on the card.

Footer

  • The domain only, without scheme or path: effiy.cn, github.com/effiy.
  • Never a full URL, never a tracking parameter, never a QR code unless the user asks for one.

Alt text

  • Mandatory. Alt text is what screen readers announce and what several unfurlers print as the caption.
  • Compose it as: kicker + headline, one sentence. Include the stat only if it is on the card.

Reading-at-size test Before exporting, view the card at 400px wide. If the kicker and headline are not readable at that width, the card fails regardless of how good it looks at full size. This is the single check that catches most bad cards.

A4. Layout templates

Pick exactly one template and name it in your output. Never combine two templates on one canvas.

TemplateUse whenComposition
T1. StatementThe claim is strong and the product is abstract. Default.Type only: kicker, headline, footer, mark. No imagery.
T2. SplitThere is a real product shot, screenshot, diagram, or code sample that proves the claim.Type in the left 55–60%, visual in the right 40–45% (B6).
T3. StatOne number is the claim, and the number is verified.Number at 2–3× headline size as the visual, headline as its caption.
T4. QuoteA user, maintainer, or doc line is more persuasive than your own copy.The sentence as headline, attribution line with name and role, no quotation-mark decoration.
T5. AnnouncementA release, launch, or version bump, where the date or version is the payoff.Short headline plus a dated chip or version string in the kicker slot.

If the claim needs three sentences to land, the card is the wrong format. Put the argument on the page and let the card carry the hook.

A5. Build order

  1. Surface (A2)
  2. Template (A4)
  3. Headline, then wrap it to the fit zone (B1, B3)
  4. Kicker, stat, footer
  5. Brand mark (B5)
  6. Export (B7), then run the 400px test
  7. Ship the meta tags (C2) and the alt text

A6. Pitfalls

  • Text that fills the canvas edge to edge. Cards breathe; the feed is noisy.
  • A headline that is really a page title, so it says nothing.
  • Two claims competing, therefore neither is remembered.
  • A logo bigger than the claim, turning the card into a badge.
  • A 1.91:1 card shoved into a square slot, which crops the headline.
  • Light-theme text in a muted grey that measures under 4.5:1 (B2).
  • An invented, rounded statistic. Readers check numbers; one fake number discredits the whole brand.
  • A PNG with an alpha channel that renders on a black mat in some unfurlers (B7).

PART B — Visual system

Every value resolves through these rules. Nothing is invented ad hoc on the canvas.

B1. Canvas and grid

SurfaceCanvasOuter marginContent boxMark zoneFooter band
og1200 × 63064px1072 × 502top-left, 48px tall, inside marginbottom, 40px tall
square1080 × 108080px920 × 920top-left, 56px tall, inside marginbottom, 48px tall
cover1280 × 72064px1152 × 592top-left, 48px tall, inside marginbottom-left, 40px tall

Grid. 12 columns inside the content box, gutter 24px. Text aligns to column 1. Visuals in T2 start at column 8.

Alignment. One alignment edge per canvas. Left-aligned default; centered allowed only for T4 (quote) and T3 (stat), and then every element is centered, including the footer.

Vertical rhythm. Body block (kicker + headline + optional stat) is optically centered inside the content box, not on the canvas center — the footer band pulls the true center up. Offsets of 0–16px are allowed to correct the optical center; nothing larger.

Footer rule. A 1px line hairline sits on the top edge of the footer band (B4 allows exactly one rule per canvas), spanning the full content-box width. The footer text baseline sits 6px above the content-box bottom, left aligned to column 1, and its cap height clears the rule by at least 8px.

Safe zones.

  • Keep every critical element (mark, kicker, headline, footer) inside the content box. Platform UI overlays the edges of a card.
  • og cards shared into WeChat and some chat clients may be center-cropped to 1:1. If the card will be shared there, either keep the claim inside the centered 630 × 630 box, or ship the square companion instead of gambling on the crop.
  • cover used as a YouTube thumbnail: keep the claim out of the bottom-right 120 × 60 corner, where the duration badge sits.

Never

  • ❌ Let text or the mark touch the canvas edge.
  • ❌ Use a canvas size not listed above. Do not ship 1200 × 628 or 1200 × 600.
  • ❌ Center the body block on the canvas while a footer exists (it looks bottom-heavy).

B2. Palette

Tokens are the landing-page-design dark surface set, so a card and its page read as one brand. Every value below was measured with the WCAG relative-luminance formula; the ratios are reproducible.

Dark theme (default)

TokenHexUse
bg#181818Canvas background
bg-raised#1F1F1FChips, stat panel, screenshot plate
bg-inset#272727Nested panel inside bg-raised
line#313131Hairline rules, screenshot borders
ink#FFFFFFHeadline
ink-muted#9B9B9BKicker, footer, attribution
accentone brand color≤ 10% of canvas area

Light theme

TokenHexUse
bg#FFFFFFCanvas background
bg-raised#F5F5F5Chips, panel
line#E5E5E5Hairlines, borders
ink#000000Headline
ink-muted#666666Kicker, footer, attribution

Measured contrast (WCAG relative luminance, sRGB)

ForegroundBackgroundRatioVerdict
#FFFFFF#18181817.76:1Headline ✅
#FFFFFF#1F1F1F16.48:1Headline on panel ✅
#FFFFFF#27272714.94:1Headline on inset ✅
#FFFFFF#31313113.01:1Headline on line color ✅
#FFFFFF#13120918.78:1Headline on warm black ✅
#9B9B9B#1818186.39:1Muted text ✅ (≥ 4.5:1)
#9B9B9B#1312096.76:1Muted text ✅
#000000#FFFFFF21.00:1Light headline ✅
#666666#FFFFFF5.74:1Light muted text ✅
#9B9B9B#FFFFFF2.78:1Light muted text ❌ do not use

Rules

  • Headline contrast ≥ 7:1. Secondary text ≥ 4.5:1. If a token cannot reach it, change the background, not the text color (B2 measurement above is the proof of which pairs work).
  • Exactly one accent. It may color the kicker, a rule, a chip, or one word of the headline — not all four.
  • Accent ≤ 10% of the canvas area. A card that is half accent color has no focal point.

Never

  • ❌ Use a gradient as the background. The one exception is a scrim gradient over a full-bleed photograph (B6).
  • ❌ Use #9B9B9B muted text on white. It measures 2.78:1 and fails.
  • ❌ Introduce a hex value that is not in this table or the brand's own palette, which must be recorded in the spec file (C5).
  • ❌ Use pure #000000 as a dark background — the ring of a dark UI and the card edge disappear into chat-list backgrounds that are also black.

B3. Typography

Typeface. One typeface per card. Allowed: Geist, Manrope, Poppins. Fallback when unavailable: DejaVu Sans (ships with most Linux hosts). Never Inter, Roboto, Arial, Open Sans, or Helvetica. Never italics. Cap weight at bold (700); no 800/900/black.

CJK. Use the same family for Latin and CJK where the family has a CJK cut. Otherwise set CJK with Noto Sans CJK SC or WenQuanYi Zen Hei and keep the Latin lines on the primary family. Never let a Latin-only font render CJK — the output is tofu boxes, and the renderer must assert coverage before export (C5).

Card type scale (px on the 1× canvas, snapped to Tailwind steps so it matches landing-page-design B1)

Roleogsquarecover
Kicker20 (text-xl)24 (text-2xl)24 (text-2xl)
Headline72 (text-7xl), step down to 60, floor 48 (text-5xl)96 (text-9xl), step down to 72, floor 60 (text-6xl)72, step down to 60, floor 48
Body / stat label24 (text-2xl)30 (text-3xl)24
Footer202424
Stat number (T3)144–192180–216144–192

Line height. Headline 1.05 for one line, 1.10 for two, 1.15 for three. Body and footer 1.40. Never set line height tighter than the headline rule to squeeze in words — change the headline.

Letter-spacing. Latin kicker +0.08em, uppercase. Latin headline −0.02em at 60px and above, 0 below 60px. CJK is always 0; faux tracking on CJK breaks the em box. Non-Latin and non-CJK scripts: 0.

Fitting. Headline width must measure ≤ the content box width, measured by the renderer on the resolved font — not estimated from character counts. Auto-wrap, then assert per line and per block. If the block exceeds the line cap at the floor size, cut words (A3).

Breaking. Latin breaks greedily between words. CJK breaks balanced: characters are distributed evenly across the number of lines the text needs, because a greedy CJK fill leaves short orphan tails like “计规则” on line two. Closing punctuation (,。、)) is pulled up so no line starts with it; opening marks ((【「) are pulled down so no line ends with one.

No orphans. The last headline line measures at least 30% of the widest line, and on a 3+ line headline the Latin last line carries at least 3 words. When a line is orphaned, edit the copy or the wrap target — never insert a manual line break to fake balance.

Never

  • ❌ Shrink below the floor size to fit a long headline.
  • ❌ Use two typefaces, or italic for emphasis.
  • ❌ Use a font weight above 700, or stroke a CJK glyph to fake bold.
  • ❌ Add letter-spacing to CJK.

B4. Hierarchy and space

  • Headline is 2.5–3× the body size. If the gap is smaller, the reader cannot tell what to read first.
  • At least 40% of the canvas stays empty. Measure it, do not eyeball it: the empty check is 1 − (ink area / canvas area), and the renderer reports it (C5).
  • At most 4 text elements: kicker, headline, optional stat or sub-line, footer. Plus one mark.
  • One focal point. If two elements are the same size and contrast, delete one.
  • Section rules: a hairline rule may separate the footer band. Exactly one rule per canvas, full content-box width, 1px line.

B5. Brand mark

  • Top-left, inside the margin, height 32–48px (og, cover) or 40–56px (square), preserving the mark's aspect ratio.
  • Monochrome on the card: white on dark, black on light. Recolor to the accent only if the accent is the brand color and it still measures ≥ 4.5:1 against bg.
  • If there is no mark file, do not fake one. Use the footer domain as the only brand element.
  • Never place the mark inside the bottom-right 120 × 60 of a cover (YouTube duration badge), and never let it sit closer than 24px to the headline block.

B6. Imagery, screenshots, scrims

  • Screenshots are shown flat, uncropped in a way that hides the UI chrome, at 1× or 2× source resolution. Never upscale a screenshot past its native size.
  • Screenshot plate: 1px border (line on dark, #E5E5E5 on light) and radius 12px. The nested-radius formula from landing-page-design B3 applies: inner = outer − gap.
  • A screenshot must contain real content. Never a blurred, illegible, or lorem-ipsum screenshot.
  • Scrim. A full-bleed photograph may carry a linear gradient of the bg token from 90% to 60% opacity. This is the only gradient allowed, and the headline must still pass 7:1 against the resulting pixels — if it does not, place the headline on a solid panel instead.
  • No stock-photo people on cards. A card with a stranger's face converts worse than a card with a claim.

B7. Export

PropertyValue
FormatPNG, 8-bit RGB (no alpha channel)
Color profilesRGB
SizeExactly the canvas from B1 (no padding, no rounding)
DPI72
File namecard-{surface}-{slug}.png, lowercase kebab, slug ≤ 40 chars, no date, no version, no final
Target sizeog ≤ 300 KB, hard cap 1 MB (some chat clients reject larger)
MetadataStrip authoring metadata; no EXIF
Source of truthThe spec file next to the PNG (C5), never a hand-edited export

Never

  • ❌ Ship PNG with an alpha channel. Several unfurlers composite it onto black, and a transparent-background card turns into a black rectangle in Slack and Telegram.
  • ❌ Ship JPEG for a card with type on it. Chroma subsampling smears small text.
  • ❌ Hand-edit an exported PNG. Change the spec, re-render, re-measure.
  • ❌ Put the date or version in the file name; put it on the card in the kicker slot instead (T5).

PART C — Platforms, meta tags, determinism

C1. Platform crop and cache behavior

Observed behavior as of 2026-11. Platforms change; when a card looks wrong in one destination, re-check that platform's current spec before redesigning the card.

PlatformDisplayed shapeWhat it does to a 1200 × 630 cardAction
X / Twitterlarge image, 2:1 crop bandCenter-crops 1.91:1 toward 2:1Keep 48px of the top and bottom free of critical content
LinkedIn feed1.91:1Shows nearly the full cardThe og size is exact; no extra work
Slack unfurlsmall thumbnail, 1.91:1Downsizes hard, sometimes to ~360px wideThe 400px test is what Slack actually sees
Telegram1.91:1 previewFull card, largeNone
Discordembed image, 1.91:1Full cardNone
WhatsApp1.91:1 previewFull card, but rejects oversized filesKeep og ≤ 300 KB
WeChat1:1 thumbnail for link previewsCenter-crops to squareShip the square companion, or keep the claim inside the centered 630 × 630 box
Instagram feed1:1Wide cards get cropped hardUse the square surface, never a cropped og
YouTube1.78:1 thumbnailDuration badge bottom-right, and mobile shows it smallcover surface, claim out of the bottom-right corner

Cache. Unfurlers cache per URL, often for days. When an image changes, change the URL too: ?v=2026-11-16 or a content hash. Verify with each platform's debugger (X Card Validator, LinkedIn Post Inspector, Facebook Sharing Debugger). A correct card behind a stale cache reads as a broken card.

C2. Meta tags

Ship this block in <head> for the og card. All image URLs absolute; the image must be publicly reachable without auth.

<meta property="og:type"        content="article">
<meta property="og:title"       content="…">
<meta property="og:description" content="…">
<meta property="og:url"         content="https://example.com/post/">
<meta property="og:image"       content="https://example.com/card-og-post.png?v=1">
<meta property="og:image:type"  content="image/png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt"   content="Kicker: headline.">
<meta name="twitter:card"        content="summary_large_image">
<meta name="twitter:image"       content="https://example.com/card-og-post.png?v=1">
<meta name="twitter:image:alt"   content="Kicker: headline.">
  • og:image:width and og:image:height are required, not optional. Without them some unfurlers reserve the wrong box and squash the card.
  • og:image:alt and twitter:image:alt are required (A3).
  • One image per page. Do not add per-network variants in markup; the crop table (C1) is why one 1.91:1 source is enough.
  • If the page is not publicly indexable, the card will not unfurl. No card design fixes a noindex or an auth wall.

C3. Localization

CJK (Chinese, Japanese, Korean)

  • One em per character; letter-spacing 0 (B3).
  • Use full-width punctuation (,。、;:) inside CJK sentences; half-width for numbers and Latin terms.
  • Never start a line with 。,、)】」 or end a line with (【「. The renderer wraps by measuring, so set the wrap rule to pull the offending punctuation up to the previous line.
  • Headline line cap still applies: og 2 lines. CJK is denser per character, so a 20-character Chinese headline at 72px fits roughly where 40 Latin characters do — measure, do not convert by character count.
  • No faux bold on CJK: if a bolder cut does not exist, do not stroke the glyph (B3).

RTL (Arabic, Hebrew)

  • Mirror the composition: mark and text on the inline-start side, footer right.
  • Numbers stay LTR inside RTL text.
  • The shipped samples do not cover RTL (see Samples); treat the first RTL card as unreviewed until a native reader checks the line breaks.

C4. Light and dark parity

A card is viewed in a white feed and in a dark app. Test both.

  • Produce both theme variants when the brand allows it, and name them card-og-{slug}-dark.png / -light.png.
  • Never invert the mark's colors independently of the theme. The mark must come from the brand file.
  • The accent must pass its contrast check in both themes. An accent that works on #181818 can fail on #FFFFFF; measure per theme (B2).

C5. Determinism and batch rendering

Cards repeat: every article gets one, and a batch of 20 will be re-rendered after a copy edit. Make that mechanical.

  • Keep a spec file per card (JSON or the renderer's own config) next to the PNG: surface, template, texts, theme, accent, mark path, font family.
  • The renderer must be deterministic: same spec + same font files + same renderer version = identical bytes. No random placement, no timestamps, no metadata drift.
  • The renderer asserts before writing: exact canvas size, RGB mode, no alpha, text fits the content box, line caps respected, contrast of every text pair ≥ the B2 thresholds, CJK glyph coverage non-empty for every CJK character, ink ratio leaves ≥ 40% empty canvas. A failed assertion is a failed card, not a warning.
  • Re-render the whole set after a rule or token change, then record the new bytes and SHA-256 in the sample record.

Output format

When creating a card, return these before drawing:

  1. Surface — og, square, or cover, and which feeds it serves
  2. Template — T1–T5, and why
  3. Headline — final text, line count at the chosen size
  4. Kicker / stat / footer — final strings
  5. Theme and palette — dark or light, tokens used, accent hex
  6. Export path — exact file name per B7, plus its byte size and SHA-256 after rendering

Then render, run the 400px test, and ship the meta tags (C2).


Quick checklist

Claim

  • One claim, one surface, one template named
  • Headline states a promise, not a section title; no hyphen, sentence case, line cap met
  • No orphaned last line; CJK headlines break balanced, not greedy
  • Every number on the card is real and sourced
  • Alt text written, with kicker and headline
  • Readable at 400px wide

Visual

  • Canvas is exactly one of the three sizes; text and mark inside the content box
  • Body block optically centered inside the content box, footer band respected
  • One typeface, no italics, weight ≤ 700, CJK letter-spacing 0
  • Headline 2.5–3× body; ≤ 4 text elements plus one mark; ≥ 40% canvas empty
  • Every color from B2, one accent ≤ 10% of area, headline 7:1, secondary 4.5:1
  • No background gradient; only a scrim over a photograph
  • If shared into WeChat: claim inside centered 630 × 630, or a square companion shipped

Export

  • PNG 8-bit RGB, no alpha, exact size, ≤ 300 KB (og)
  • File name card-{surface}-{slug}.png, no date or version
  • Spec file stored next to the PNG; re-render reproduces identical bytes
  • Meta tags + og:image:width/height/alt + twitter:card shipped
  • Cache-busting version bumped when the image changed; unfurl verified on at least X and one chat app

Samples

./samples/ holds three rendered cards, the deterministic renderer that produced them, and a record of byte sizes, SHA-256 hashes, resolved fonts, and the exact commands. Read samples/SAMPLES.md. If you installed only SKILL.md, treat the samples as optional reference material — the rules above stand on their own.

What the samples prove, and what they do not:

SampleSurfaceTemplateThemeProves
card-og-design-skills.pngog 1200 × 630T1 StatementdarkBase layout, fit and contrast assertions, RGB export
card-og-zh-design-skills.pngog 1200 × 630T1 StatementdarkCJK headline, glyph coverage assertion, CJK spacing rules
card-square-design-skills.pngsquare 1080 × 1080T3 StatlightSquare surface, light theme tokens, oversized stat

Not covered by samples: T2 Split, T4 Quote, T5 Announcement, RTL, a real photograph scrim. Render those from the same spec format before shipping them for the first time.


Credits

Structurally adapted from landing-page-design in this repo (MIT): the Part A/B split, decision tree and template table, token table format, anti-pattern notation, and the "Never" lists. The palette deliberately reuses its dark-mode surface tokens so cards and pages stay one brand. Platform crop behavior, card type scale, determinism assertions, and the export rules are original work for this repo.

Related Skills