Communitygithub.com

brainzcode/premium-landing

建立真正可用的連結預覽與 favicon — Open Graph 和 Twitter Card 標籤、正確裁剪的 1200×630 分享圖片,以及完整的 favicon 組(SVG、ICO、apple-touch、maskable manifest 圖示)。當被問及社群分享、OG 圖片、Open Graph、Twitter Card、連結預覽、分享圖片、favicon、應用程式圖示、apple touch icon 或網頁 manifest 時使用。也適用於分享連結預覽為空白、顯示錯誤圖片或 favicon 無法顯示的情況。包含會讓所有預覽無聲失敗的絕對 URL 陷阱,以及會在其他機器上破壞 SVG favicon 的字型陷阱。

premium-landing 是什麼?

這個技能提供了一套完整的社交分享與 favicon 解決方案,專為 AI 代理(如 Claude Code、Cursor、Codex 等)設計。它精確說明了如何設定 Open Graph 與 Twitter Card 標籤,確保社群平台能正確抓取連結預覽。核心關鍵在於 `og:image` 與 `og:url` 必須使用絕對路徑,否則預覽會完全空白。此外,還涵蓋了分享圖片的正確做法,包括以 1200×630 比例渲染、避免常見的短視窗陷阱,以及透過合適的裁剪保留設計重點。在 favicon 方面,技能強調了 SVG favicon 中不可使用 `<text>` 元素(需轉換為路徑)、圖示需有填滿背景以避免在深淺底色中消失,以及 maskable 圖示的中央 80% 安全區規則。最後,還提供了完整的 Python 生成腳本與驗證 checklist,協助自動產出所有必要的圖示與標籤。支援所有主流平台如 Facebook、X (Twitter)、LinkedIn、Slack 以及 iOS 與 Android 的 PWA 需求。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/brainzcode/premium-landing/tree/HEAD/plugins/premium-landing/skills/social-share-favicons

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

社交分享與 favicon

唯一重要的事

og:image 與 og:url 必須是公開可達主機上的絕對 URL。

爬蟲是從自己的伺服器抓取這些資源。它沒有頁面上下文、沒有 cookie、沒有 referer,也不知道你的相對路徑相對於什麼。像 /assets/og.jpg 或 assets/og.jpg 這樣的路徑解析不到任何東西,卡片就會以空白呈現。

<!-- 無效:到處都顯示空白卡片 -->
<meta property="og:image" content="assets/images/og-image.jpg">

<!-- 有效 -->
<meta property="og:image" content="https://example.com/assets/images/og-image.jpg">

這是預覽失敗最常見的單一原因。在除錯其他任何東西之前,先確認 URL 是絕對的,並且在無痕視窗中能正常載入。

推論:預覽在 localhost 或 file:// 上無法運作。你在本地做的任何事情都不會產生真正的預覽。先部署,再驗證。

標籤集合

<link rel="canonical" href="https://example.com/">

<meta property="og:type"        content="website">
<meta property="og:site_name"   content="Brand">
<meta property="og:locale"      content="en_US">
<meta property="og:url"         content="https://example.com/">
<meta property="og:title"       content="Brand - what it is">
<meta property="og:description" content="One sentence. Around 110 characters.">
<meta property="og:image"       content="https://example.com/og-image.jpg">
<meta property="og:image:type"  content="image/jpeg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt"   content="What is in the picture.">

<meta name="twitter:card"        content="summary_large_image">
<meta name="twitter:title"       content="Brand - what it is">
<meta name="twitter:description" content="One sentence. Around 110 characters.">
<meta name="twitter:image"       content="https://example.com/og-image.jpg">
<meta name="twitter:image:alt"   content="What is in the picture.">

三個容易弄錯的細節:

og: 使用 property=,twitter: 使用 name=。 搞混它們會被靜默忽略,所以標籤在原始碼中看起來存在但實際上沒有任何作用。有些解析器能容忍 og: 使用 name=,但不要依賴這個特性。

twitter:card 必須是 summary_large_image。 預設值是一個小方塊卡片,圖片以縮圖形式顯示在文字旁邊,這會浪費一張 1200×630 的圖片。

宣告 og:image:width 與 og:image:height 可以讓卡片立即呈現。 如果沒有宣告,平台必須先下載圖片才能知道比例,因此第一個分享連結的人經常看到只有文字的卡片。它們必須與實際檔案相符。請測量,不要猜測。

文字長度:標題大約在 60 字元處截斷,描述則依據平台在 110 到 200 字元之間。請將重點放在開頭。

分享圖片

1200×630(1.905:1)。使用 JPEG,除非設計需要透明度(但不需要,因為所有平台都是在白色背景上合成)。保持在約 1 MB 以下;硬性上限是 8 MB(Facebook)和 5 MB(X),但大檔案會在抓取時超時。

以目標比例渲染,不要裁切螢幕截圖

對任意的螢幕截圖進行裁切以符合 1.905:1 會拋棄設計師選擇的構圖。改為以該比例渲染來源:

# 1440x756 正好是 1.905:1,所以它可以縮放到 1200x630 而不需要裁切
chrome --headless --disable-gpu --hide-scrollbars --virtual-time-budget=8000 \
  --window-size=1440,756 --screenshot=og-src.png "file://$PWD/index.html"

短視窗陷阱

如果頁面有一個全高的 hero(100vh / 100svh),以 1.905:1 直接渲染會得到一個遠比真實桌機螢幕短的視窗。任何使用 object-fit: cover 的媒體都會比實際使用時裁切得更厲害,而且通常會錯開的元素會互相碰撞——典型情況是標頭 logo 落在主體人物的頭上。

請在更高的視窗中渲染,讓媒體的裁切方式與實際使用時相同,然後從中裁出 1.905:1 的區域:

chrome --headless ... --window-size=1440,1000 --screenshot=og-src.png "file://$PWD/index.html"
ffmpeg -i og-src.png -vf "crop=1440:756:0:0" -q:v 2 og-crop.png     # 頂部對齊

在選擇之前,比較頂部對齊裁切與中央對齊裁切。頂部對齊通常能保留品牌傢俱(工具列、導航、商標詞);中央對齊通常能保留主體和行動呼籲。你無法兩者兼顧,因為全高 hero 比 1.905:1 允許的還要高。

構圖

卡片在資訊流中大約以 500 px 寬度呈現,而且每個平台的裁切方式不同(LinkedIn 和 Slack 比 Facebook 更緊)。請將任何必須保留的元素放在中央 80% 的區域內,並將任何文字設定為足以在半尺寸下閱讀的大小。精細的 UI 細節會消失;一個大字詞和一個強而有力的圖片則不會。

Favicon

字型陷阱

不要在 SVG favicon 中使用 <text>。

<!-- 會出錯:以觀看者機器上任何可用的後備字型渲染 -->
<svg ...><text x="50%" y="50%" font-family="Geist">G</text></svg>

SVG 是在觀看者的機器上渲染的,而你的網路字型並不存在於該機器上。請將字形提取為路徑,使其與字型無關且解析度無關。請參考下方的腳本。

透明度陷阱

深色字形在透明背景上會與深色瀏覽器 chrome 融為一體,而淺色字形則會在淺色背景上消失。請在填滿的磚塊上繪製圖示。這也能讓標記在頁籤欄、書籤和主螢幕上具有一致的輪廓。

檔案集合

檔案大小原因
/favicon.ico16, 32, 48即使你宣告了其他圖示,瀏覽器也會隱含地請求這個路徑;請將其保持在網站根目錄
favicon.svg可縮放現代瀏覽器偏好的格式,在任何顯示器上都能保持清晰
apple-touch-icon.png180iOS 主螢幕
icon-192.png192manifest
icon-512.png512manifest、啟動畫面
icon-maskable-512.png512Android 自適應遮罩
<link rel="icon" href="/favicon.ico" sizes="32x32">
<link rel="icon" href="/assets/icons/favicon.svg" type="image/svg+xml">
<link rel="apple-touch-icon" href="/assets/icons/apple-touch-icon.png">
<link rel="manifest" href="/site.webmanifest">

Maskable 安全區

Android 會將圖示裁剪為任意形狀(圓形、圓角方形、淚滴形)。maskable 圖示必須將所有重要內容保留在中央 80% 圓形內,這意味著磚塊邊緣大約有 40% 是可拋棄的內距。重複使用普通圖示會導致邊緣被削掉。

實務上:如果標準圖示中字形覆蓋了磚塊的 60%,則在 maskable 圖示中將其降至約 40%。同時提供兩者,並分別使用 "purpose": "any" 和 "purpose": "maskable"。永遠不要將兩個目的放在同一個檔案上。

Web manifest

{
  "name": "Brand",
  "short_name": "Brand",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "background_color": "#f7f6f4",
  "theme_color": "#0a0a0a",
  "icons": [
    { "src": "/assets/icons/favicon.svg", "type": "image/svg+xml", "sizes": "any" },
    { "src": "/assets/icons/icon-192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
    { "src": "/assets/icons/icon-512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" },
    { "src": "/assets/icons/icon-maskable-512.png", "type": "image/png", "sizes": "512x512", "purpose": "maskable" }
  ]
}

theme_color 會為行動瀏覽器 chrome 上色,因此它應該與頁面最頂部的任何元素相符,而不是品牌的主要顏色。如果頁面以一個黑色工具列開頭,就使用那個黑色。不匹配看起來像是渲染錯誤。請在 <meta name="theme-color"> 中鏡像設定。

background_color 是在首次繪製之前、圖示後方的啟動畫面,因此它應該與頁面背景相符。

生成腳本

需要 pillow 和 fonttools。會產生整套圖示以及分享圖片。

import os
from PIL import Image, ImageDraw, ImageFont
from fontTools.ttLib import TTFont
from fontTools.pens.svgPathPen import SVGPathPen
from fontTools.pens.boundsPen import BoundsPen

FONT   = "brand.ttf"      # 實際的品牌字型,使用商標詞所用的字重
CHAR   = "G"
INK    = "#0a0a0a"        # 磚塊
PAPER  = "#f2f1ed"        # 字形
COVER  = 0.60             # 字形高度佔磚塊的比例
OUT    = "assets/icons"
os.makedirs(OUT, exist_ok=True)

# ── SVG:將字形作為真正的路徑,因此不依賴觀看者的字型 ──
f  = TTFont(FONT)
gs = f.getGlyphSet()
name = f.getBestCmap()[ord(CHAR)]

bp = BoundsPen(gs); gs[name].draw(bp)
x0, y0, x1, y1 = bp.bounds
pen = SVGPathPen(gs); gs[name].draw(pen)
d = pen.getCommands()

VB = 64
s  = (VB * COVER) / (y1 - y0)
tx = (VB - (x1 - x0) * s) / 2 - x0 * s
ty = (VB + (y1 - y0) * s) / 2 + y0 * s      # y 翻轉:字型是 y 向上,SVG 是 y 向下

open(f"{OUT}/favicon.svg", "w").write(
    f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {VB} {VB}">'
    f'<rect width="{VB}" height="{VB}" fill="{INK}"/>'
    f'<path transform="translate({tx:.3f} {ty:.3f}) scale({s:.5f} -{s:.5f})" '
    f'd="{d}" fill="{PAPER}"/></svg>')

# ── 點陣圖磚塊 ────────────────────────────────────────────────────────────
def tile(px, cover=COVER):
    img = Image.new("RGB", (px, px), INK)
    dr  = ImageDraw.Draw(img)
    fnt = ImageFont.truetype(FONT, px * 2)
    bb  = dr.textbbox((0, 0), CHAR, font=fnt)
    fnt = ImageFont.truetype(FONT, int(px * 2 * (px * cover) / (bb[3] - bb[1])))
    bb  = dr.textbbox((0, 0), CHAR, font=fnt)
    dr.text(((px - (bb[2] - bb[0])) / 2 - bb[0],
             (px - (bb[3] - bb[1])) / 2 - bb[1]), CHAR, font=fnt, fill=PAPER)
    return img

tile(180).save(f"{OUT}/apple-touch-icon.png", optimize=True)
tile(192).save(f"{OUT}/icon-192.png", optimize=True)
tile(512).save(f"{OUT}/icon-512.png", optimize=True)
tile(512, cover=0.42).save(f"{OUT}/icon-maskable-512.png", optimize=True)  # 40% 安全區
tile(256).save("favicon.ico", sizes=[(16, 16), (32, 32), (48, 48)])

# ── 分享圖片:將較高渲染結果裁切至比例,然後縮小 ──────────────────────────────
src = Image.open("og-src.png").convert("RGB")          # 例如 1440x1000
src.crop((0, 0, 1440, 756)).resize((1200, 630), Image.LANCZOS).save(
    "assets/images/og-image.jpg", quality=88, optimize=True, progressive=True)

沒有品牌字型嗎?任何幾何無襯線字體都適用於字母組合。將現有的 Logo PNG 點陣化到磚塊上也可以;只需將其置中在相同的 COVER 比例內,並保持 maskable 變體較小即可。

出貨前驗證

import re, json, os
from PIL import Image
s = open("index.html").read()
tags = dict(re.findall(r'(?:property|name)="((?:og|twitter):[^"]+)"\s+content="([^"]+)"', s))

for t in ("og:url", "og:image", "twitter:image"):
    assert tags[t].startswith("http"), f"{t} 不是絕對路徑:{tags[t]}"

w, h = Image.open("assets/images/og-image.jpg").size
assert (str(w), str(h)) == (tags["og:image:width"], tags["og:image:height"]), "宣告的大小錯誤"
assert tags["twitter:card"] == "summary_large_image"

m = json.load(open("site.webmanifest"))
for i in m["icons"]:
    assert os.path.isfile(i["src"].lstrip("/")), f"缺少圖示 {i['src']}"
print("ok")

檢查清單:

  • og:image 和 og:url 是絕對路徑,位於真實主機上,能在無痕視窗中載入
  • 宣告的 og:image:width / height 與實際檔案相符
  • twitter:card 是 summary_large_image
  • og: 標籤使用 property=,twitter: 標籤使用 name=
  • 所有預留網域都已替換(搜尋一下;通常有四個)
  • favicon.ico 位於網站根目錄,而不僅僅在 assets 資料夾中
  • SVG favicon 包含 <path>,沒有 <text>
  • 圖示磚塊已填滿,以便在深色和淺色瀏覽器 chrome 中都能正常顯示
  • maskable 圖示已留邊至中央 80%
  • theme_color 與頁面頂部邊緣相符

快取

每個平台都積極快取,並且在你修復後仍會繼續提供舊的卡片。請重新抓取:

LinkedIn 的快取最強,除非你執行檢查工具,否則在約 7 天內實際上會忽略更改。如果一個 URL 已經以損壞的卡片被廣泛分享,加上查詢字串(?v=2)可以強制進行新的抓取。

Favicon 在瀏覽器中快取也很強。請在無痕視窗中測試;正常重新載入通常會繼續提供舊的 favicon。

預留網域

當真實網域還未知時,請使用 example.com 的子網域(https://brand.example.com)。RFC 2606 保留了它,因此它明確是一個預留地,永遠不會意外指向別人擁有的網域。不要將看似合理但無人擁有的網域留在出貨的中繼資料中。

將替換說明直接放在區塊上方的註解中以及專案的 README 中,並說明有多少處出現。通常是四處:canonical、og:url、og:image、twitter:image。

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

brainzcode/premium-landing

Add a studio or agency build credit to a website footer — "Site by <Studio>" linking to the studio's site. Use when finishing or shipping a site, adding a footer, or when asked for an agency credit, build credit, designed-by line, or attribution. Covers wording, placement opposite the client's copyright, markup for each stack, styling from the host site's tokens, and the sitewide-footer-link SEO footprint when the same credit runs across many client sites.

brainzcode/premium-landing

Build a complete premium landing page, either replicated from a reference screenshot/URL or designed from a written brief, in HTML, React, Next.js or Astro. Use when asked to build, design, replicate or clone a landing page, marketing page, or one-page site; when handed a design screenshot or Figma/Pinterest reference to turn into code; or when a landing page needs a full premium pass. Covers design tokens, section patterns, the layout traps that silently break grids and marquees, and screenshot-based responsive verification from 320px to 1920px.

brainzcode/premium-landing

Add Lenis smooth scrolling to a site correctly — setup, anchor offsets for sticky headers, scroll locking for modals and menus, reduced-motion handling. Use when asked for smooth scroll, Lenis, momentum/eased scrolling, or when smooth scroll broke a sticky header, a modal lock, or anchor links. Includes the sticky-position trap that only appears at non-zero scroll.

brainzcode/premium-landing

Build true Apple-style liquid glass in the browser — real refraction via SVG displacement maps, chromatic dispersion, specular edges. Use when asked for liquid glass, glassmorphism, frosted/glass cards, glass navbars, or when a blur-based "glass" effect looks flat. Includes the performance trap that makes backdrop-filter stutter on scroll and the contrast trap that makes text unreadable on glass.

brainzcode/premium-landing

Build a premium mobile nav — a hamburger button that morphs into a close X, a full-screen overlay panel with staggered link reveal, scroll lock, focus trap, and reduced-motion handling. Use when asked for a mobile menu, hamburger/burger button, nav drawer, off-canvas menu, or when a menu loses scroll position, still scrolls behind on iOS, leaks Tab focus to the page underneath, or the close button stops responding. Includes the z-index trap that swallows the close button and the iOS rubber-band trap.

brainzcode/premium-landing

Rebuild a design accurately from a supplied reference — a screenshot, PDF page, mockup or live URL — by measuring it numerically instead of eyeballing it. Use when asked to replicate, clone, match or rebuild a design "exactly", "1 to 1" or "with no mistakes", or when a build drifts from its reference. Covers extracting the true content box from a padded screenshot, deriving element positions as percentages, solving object-fit framing, and knowing when a reference cannot be matched.

brainzcode/premium-landing

Source free, licence-clear photography for a site from Unsplash — searching by mood rather than noun, sizing and cropping for the slot, honouring the API's hotlink and download-tracking requirements, and writing real alt text. Use when a page needs a hero image, section photography, avatars or card art and none was supplied; when placeholder greys need replacing with real imagery; or when asked to find, pick or swap photos for a design.

相關技能