Communitygithub.com

brainzcode/premium-landing

提供真正可用的链接预览和网站图标——Open Graph 和 Twitter 卡片标签、正确构图的 1200×630 分享图片以及完整的图标集(SVG、ICO、apple-touch、maskable manifest 图标)。当被问及社交分享、OG 图片、Open Graph、Twitter 卡片、链接预览、分享图片、网站图标、应用图标、apple touch 图标或 Web 清单时使用。当分享链接预览显示空白、显示错误图片或网站图标不显示时也应使用。包含绝对 URL 陷阱(它会静默地使所有预览失效)和字体陷阱(它会在其他机器上破坏 SVG 图标)。

premium-landing 是什么?

该技能提供了一套全面且经过实战检验的社交分享元数据和网站图标配置。它专注于解决最常见的问题:确保 `og:image` 和 `og:url` 使用绝对 URL,这在链接预览在 Facebook、X 和 Slack 等平台上显示为空白时是首要检查项。此外,它还涵盖了完整的标签集,包括正确的属性(`og:` 使用 `property=`,`twitter:` 使用 `name=`)、正确配置 `twitter:card` 为 `summary_large_image` 以及声明图片尺寸以确保卡片即时渲染。 在图片生成方面,该技能强调在 1.905:1 的宽高比下渲染分享图片,而不是裁剪屏幕截图,以避免破坏设计构图。它还解决了“短视口陷阱”——当页面采用全高英雄区时,一个更窄的视口会导致 `object-fit: cover` 媒体过度裁剪;解决方案是以更高的视口渲染,然后裁剪出正确的宽高比。对于网站图标,该技能明确警告不要在 SVG 图标中使用 `<text>`,因为它依赖于观看者的本地字体,而是建议使用路径来保证字体无关的渲染。 该技能包含一个完整的 Python 生成脚本,该脚本从品牌字体中提取字形,为整个图标集(常规图标和可掩码图标)创建栅格化图块,并裁剪分享图片。它还提供了一个验证脚本来在部署前检查常见陷阱,并提供了每个平台的重置缓存工具。支持的平台包括所有使用 Open Graph 和 Twitter 卡片的社交网络,以及任何使用标准 HTML 头和 Web 清单的网站。

兼容平台~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 的新对话。

文档

社交分享与网站图标

唯一重要的事

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="品牌">
<meta property="og:locale"      content="zh_CN">
<meta property="og:url"         content="https://example.com/">
<meta property="og:title"       content="品牌 - 简介">
<meta property="og:description" content="一句话。大约 110 个字符。">
<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="图片内容描述">

<meta name="twitter:card"        content="summary_large_image">
<meta name="twitter:title"       content="品牌 - 简介">
<meta name="twitter:description" content="一句话。大约 110 个字符。">
<meta name="twitter:image"       content="https://example.com/og-image.jpg">
<meta name="twitter:image:alt"   content="图片内容描述">

三个容易出错的地方:

og: 使用 property=,twitter: 使用 name=。 混淆它们会静默地被忽略,因此标签在源代码中看起来存在但没有任何作用。一些解析器容忍 og: 上的 name=,但不要依赖它。

twitter:card 必须是 summary_large_image。 默认是一个小方形卡片,图片作为缩略图放在文本旁边,这会浪费 1200x630 的图片。

声明 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"

短视口陷阱

如果页面有全高的英雄区(100vh / 100svh),直接按 1.905:1 渲染会得到一个比真实桌面屏幕短得多的视口。任何使用 object-fit: cover 的媒体裁剪程度会比实际使用时严重得多,通常能正常分开的元素会互相碰撞——典型情况是标题标志落在主题头部上。

应使用更高的视口渲染,使媒体的裁剪方式与实际使用一致,然后从中切出 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     # 顶部对齐裁剪

在选择之前,比较顶部对齐裁剪和居中裁剪的效果。顶部对齐通常能保持品牌元素(实用工具栏、导航、品牌标志);居中裁剪通常能保持主题和行动号召。你无法同时拥有两者,因为全高英雄区的高度超过了 1.905:1 所允许的范围。

构图

卡片在信息流中大约呈现为 500 像素宽,并且每个平台的裁剪方式不同(LinkedIn 和 Slack 比 Facebook 更严格)。任何必须在卡片内可见的内容都要放在中央 80% 的区域内,并确保任何文字字号足够大,在缩小到一半时仍可阅读。细小的 UI 细节会消失;大的品牌标志和强烈的图像则不会。

网站图标

字体陷阱

不要在 SVG 网站图标中使用 <text>。

<!-- 损坏:使用观看者本机任何可用的后备字体渲染 -->
<svg ...><text x="50%" y="50%" font-family="Geist">G</text></svg>

SVG 在观看者的机器上渲染,你使用的网页字体并不存在。应将字形提取为路径,使其与字体无关且与分辨率无关。请参阅下面的脚本。

透明度陷阱

深色字形在透明背景上会在深色浏览器 chrome 中消失,浅色字形在浅色背景上也会消失。应将图标绘制在填充的图块上。这也使得标记在标签栏、书签和主屏幕上具有一致的轮廓。

文件集

文件尺寸原因
/favicon.ico16, 32, 48即使你声明了其他图标,浏览器也会隐式请求此路径;请将其保持在 web 根目录
favicon.svg可缩放现代浏览器更偏好此格式,在任何显示器上都能保持清晰
apple-touch-icon.png180iOS 主屏幕
icon-192.png192清单
icon-512.png512清单、启动画面
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">

可遮罩安全区域

Android 会将图标裁剪成任意形状(圆形、圆角方形、泪滴形)。maskable 图标必须将所有重要内容保留在中央 80% 的圆形区域内,这意味着大约 40% 的图块边缘是可丢弃的填充区域。直接重用普通图标会导致其边缘被切掉。

实际操作中:如果标准图标中字形覆盖了图块的 60%,对于可遮罩图标,应将其降至约 40%。同时提供两者,并分别使用 "purpose": "any" 和 "purpose": "maskable" 作为独立条目。切勿将两种目的放在同一个文件上。

Web 清单

{
  "name": "品牌",
  "short_name": "品牌",
  "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)

没有品牌字体?任何几何无衬线字体都可用于字母组合。将现有的标志 PNG 栅格化到图块上也可以;只需将其居中在相同的 COVER 比例内,并保持可遮罩变体更小即可。

部署前验证

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} 不是绝对 URL: {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("检查通过")

检查清单:

  • og:image 和 og:url 是绝对 URL,指向真实主机,能在隐私窗口中加载
  • 声明的 og:image:width / height 与实际文件匹配
  • twitter:card 是 summary_large_image
  • og: 标签使用 property=,twitter: 标签使用 name=
  • 所有占位符域名已替换(搜索一下;通常有四个)
  • favicon.ico 位于 web 根目录,而不只是在 assets 文件夹中
  • SVG 网站图标包含 <path>,没有 <text>
  • 图标图块是填充的,可以在深色和浅色浏览器 chrome 中正常显示
  • 可遮罩图标已填充到中央 80%
  • theme_color 与页面顶部边缘颜色匹配

缓存

每个平台都会积极缓存,并在修复后继续提供旧卡片。重新抓取:

LinkedIn 缓存最严重,除非你运行检查器,否则它基本上会在 7 天内忽略更改。如果某个 URL 已经以损坏的卡片被广泛分享,添加查询字符串(?v=2)会强制进行全新抓取。

网站图标在浏览器中也会被强缓存。请在隐私窗口中测试;正常的重新加载通常会继续提供旧图标。

占位符域名

当真实域名尚不明确时,使用 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.

相关技能