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-designin this repo. - Team avatar PNGs →
avatar-designin 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.
| Surface | Size | Ratio | Serves |
|---|---|---|---|
og | 1200 × 630 | 1.91:1 | og:image, twitter:image (summary_large_image), LinkedIn, Slack, Telegram, Discord, WhatsApp link previews |
square | 1080 × 1080 | 1:1 | Instagram feed, WeChat Moments, square feed slots, WeChat link preview thumbnail |
cover | 1280 × 720 | 1.78:1 | YouTube 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-designB1). - Line cap: 2 lines on
ogandcover, 3 lines onsquare. 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.
| Template | Use when | Composition |
|---|---|---|
| T1. Statement | The claim is strong and the product is abstract. Default. | Type only: kicker, headline, footer, mark. No imagery. |
| T2. Split | There 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. Stat | One number is the claim, and the number is verified. | Number at 2–3× headline size as the visual, headline as its caption. |
| T4. Quote | A 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. Announcement | A 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
- Surface (A2)
- Template (A4)
- Headline, then wrap it to the fit zone (B1, B3)
- Kicker, stat, footer
- Brand mark (B5)
- Export (B7), then run the 400px test
- 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
| Surface | Canvas | Outer margin | Content box | Mark zone | Footer band |
|---|---|---|---|---|---|
og | 1200 × 630 | 64px | 1072 × 502 | top-left, 48px tall, inside margin | bottom, 40px tall |
square | 1080 × 1080 | 80px | 920 × 920 | top-left, 56px tall, inside margin | bottom, 48px tall |
cover | 1280 × 720 | 64px | 1152 × 592 | top-left, 48px tall, inside margin | bottom-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.
ogcards 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 thesquarecompanion instead of gambling on the crop.coverused 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)
| Token | Hex | Use |
|---|---|---|
bg | #181818 | Canvas background |
bg-raised | #1F1F1F | Chips, stat panel, screenshot plate |
bg-inset | #272727 | Nested panel inside bg-raised |
line | #313131 | Hairline rules, screenshot borders |
ink | #FFFFFF | Headline |
ink-muted | #9B9B9B | Kicker, footer, attribution |
accent | one brand color | ≤ 10% of canvas area |
Light theme
| Token | Hex | Use |
|---|---|---|
bg | #FFFFFF | Canvas background |
bg-raised | #F5F5F5 | Chips, panel |
line | #E5E5E5 | Hairlines, borders |
ink | #000000 | Headline |
ink-muted | #666666 | Kicker, footer, attribution |
Measured contrast (WCAG relative luminance, sRGB)
| Foreground | Background | Ratio | Verdict |
|---|---|---|---|
#FFFFFF | #181818 | 17.76:1 | Headline ✅ |
#FFFFFF | #1F1F1F | 16.48:1 | Headline on panel ✅ |
#FFFFFF | #272727 | 14.94:1 | Headline on inset ✅ |
#FFFFFF | #313131 | 13.01:1 | Headline on line color ✅ |
#FFFFFF | #131209 | 18.78:1 | Headline on warm black ✅ |
#9B9B9B | #181818 | 6.39:1 | Muted text ✅ (≥ 4.5:1) |
#9B9B9B | #131209 | 6.76:1 | Muted text ✅ |
#000000 | #FFFFFF | 21.00:1 | Light headline ✅ |
#666666 | #FFFFFF | 5.74:1 | Light muted text ✅ |
#9B9B9B | #FFFFFF | 2.78:1 | Light 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
#9B9B9Bmuted 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
#000000as 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)
| Role | og | square | cover |
|---|---|---|---|
| Kicker | 20 (text-xl) | 24 (text-2xl) | 24 (text-2xl) |
| Headline | 72 (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 label | 24 (text-2xl) | 30 (text-3xl) | 24 |
| Footer | 20 | 24 | 24 |
| Stat number (T3) | 144–192 | 180–216 | 144–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 (
lineon dark,#E5E5E5on light) and radius 12px. The nested-radius formula fromlanding-page-designB3 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
bgtoken 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
| Property | Value |
|---|---|
| Format | PNG, 8-bit RGB (no alpha channel) |
| Color profile | sRGB |
| Size | Exactly the canvas from B1 (no padding, no rounding) |
| DPI | 72 |
| File name | card-{surface}-{slug}.png, lowercase kebab, slug ≤ 40 chars, no date, no version, no final |
| Target size | og ≤ 300 KB, hard cap 1 MB (some chat clients reject larger) |
| Metadata | Strip authoring metadata; no EXIF |
| Source of truth | The 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.
| Platform | Displayed shape | What it does to a 1200 × 630 card | Action |
|---|---|---|---|
| X / Twitter | large image, 2:1 crop band | Center-crops 1.91:1 toward 2:1 | Keep 48px of the top and bottom free of critical content |
| LinkedIn feed | 1.91:1 | Shows nearly the full card | The og size is exact; no extra work |
| Slack unfurl | small thumbnail, 1.91:1 | Downsizes hard, sometimes to ~360px wide | The 400px test is what Slack actually sees |
| Telegram | 1.91:1 preview | Full card, large | None |
| Discord | embed image, 1.91:1 | Full card | None |
| 1.91:1 preview | Full card, but rejects oversized files | Keep og ≤ 300 KB | |
| 1:1 thumbnail for link previews | Center-crops to square | Ship the square companion, or keep the claim inside the centered 630 × 630 box | |
| Instagram feed | 1:1 | Wide cards get cropped hard | Use the square surface, never a cropped og |
| YouTube | 1.78:1 thumbnail | Duration badge bottom-right, and mobile shows it small | cover 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:widthandog:image:heightare required, not optional. Without them some unfurlers reserve the wrong box and squash the card.og:image:altandtwitter:image:altare 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
noindexor 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:
og2 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
#181818can 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:
- Surface —
og,square, orcover, and which feeds it serves - Template — T1–T5, and why
- Headline — final text, line count at the chosen size
- Kicker / stat / footer — final strings
- Theme and palette — dark or light, tokens used, accent hex
- 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
squarecompanion 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:cardshipped - 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:
| Sample | Surface | Template | Theme | Proves |
|---|---|---|---|---|
card-og-design-skills.png | og 1200 × 630 | T1 Statement | dark | Base layout, fit and contrast assertions, RGB export |
card-og-zh-design-skills.png | og 1200 × 630 | T1 Statement | dark | CJK headline, glyph coverage assertion, CJK spacing rules |
card-square-design-skills.png | square 1080 × 1080 | T3 Stat | light | Square 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.