Communitygithub.com

brainzcode/premium-landing

リンクプレビューとファビコンを確実に機能させます。Open Graph・Twitter Cardタグ、適切にフレーミングされた1200x630の共有画像、完全なファビコンセット(SVG、ICO、apple-touch、マスク可能マニフェストアイコン)を提供します。

premium-landing とは?

このスキルは、ソーシャル共有やリンクプレビュー、ファビコンに関するあらゆる問題を解決するための包括的なガイドです。`og:image`と`og:url`が絶対URLである必要があるという「絶対URLトラップ」を中心に、最も一般的なプレビュー失敗の原因を解説します。また、SVGファビコンに`<text>`を使うと他のマシンでフォントが存在せず壊れる「フォントトラップ」についても警告します。1200x630の共有画像の正しいレンダリング方法(クロップではなくアスペクト比を維持)、ファビコンのファイルセット(ICO、SVG、apple-touch-icon、マニフェストアイコン)、Webマニフェストの設定、そして検証スクリプトまでを含んでいます。このスキールは、Claude Code、Cursor、CodexなどのAIエージェントツールで使用することを想定しており、開発者がソーシャルプレビューやファビコンを確実に機能させるために必要なすべての知識を提供します。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ソーシャル共有とファビコン

最も重要なこと

og:image と og:url は、パブリックに到達可能なホスト上の絶対URLでなければなりません。

クローラーは自身のサーバーからこれらを取得します。ページのコンテキスト、Cookie、リファラーはなく、相対パスが何に対する相対パスなのかも認識しません。/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が絶対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.">

間違えやすい3つの詳細:

og: は property= を使用し、twitter: は name= を使用します。 これらを混同すると暗黙的に無視されるため、タグはソース上に存在しているように見えても何も機能しません。一部のパーサーは og: での name= を許容しますが、それに依存しないでください。

twitter:card は summary_large_image でなければなりません。 デフォルトは画像がテキストの横にサムネイルとして表示される小さな正方形のカードで、1200x630の画像が無駄になります。

og:image:width と og:image:height を宣言すると、カードが即座にレンダリングされます。 これらがないと、プラットフォームはアスペクト比を知る前に画像をダウンロードする必要があるため、リンクを最初に共有した人にはテキストのみのカードが表示されることがよくあります。これらは実際のファイルと一致している必要があります。推測せずに測定してください。

コピーの長さ:タイトルは約60文字、説明はプラットフォームによって約110〜200文字で切られます。意味は先頭に詰めてください。

共有画像

1200x630 (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 px幅でレンダリングされ、各プラットフォームのクロップ方法は異なります(LinkedInとSlackはFacebookよりも厳しいです)。中央80% 以内に残さなければならないものはすべて配置し、半分のサイズでも読める大きさでタイプを設定してください。細かいUIの詳細は消えます。大きなワードマークと強い画像は消えません。

ファビコン

フォントトラップ

SVGファビコンに <text> を入れないでください。

<!-- 壊れる:閲覧者がたまたま持っているフォールバックフォントでレンダリングされる -->
<svg ...><text x="50%" y="50%" font-family="Geist">G</text></svg>

SVGは閲覧者のマシン上でレンダリングされ、あなたのウェブフォントはそこには存在しません。グリフをパスとして抽出することで、フォントに依存せず、解像度にも依存しなくなります。以下のスクリプトを参照してください。

透過性トラップ

透明な背景上の暗いグリフは暗いブラウザクロームに溶け込み、明るいグリフは明るいブラウザクロームに溶け込みます。アイコンは塗りつぶされたタイル上に描いてください。これにより、タブバー、ブックマーク、ホーム画面全体で一貫したシルエットが得られます。

ファイルセット

ファイルサイズ理由
/favicon.ico16, 32, 48ブラウザは他のファイルを宣言していても暗黙的にこのパスを要求します。ウェブルートに配置してください
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": "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 はモバイルブラウザのクロームを着色するため、ブランドのメインカラーではなく、ページの最上部にあるものに合わせる必要があります。ページが黒いユーティリティバーで始まる場合は、その黒を使用してください。不一致はレンダリングバグとして読み取られます。<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が反転:フォントは上向き、SVGは下向き

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("ok")

チェックリスト:

  • og:image と og:url が絶対URLで、実際のホスト上にあり、プライベートウィンドウで読み込める
  • 宣言された og:image:width / height が実際のファイルと一致している
  • twitter:card が summary_large_image である
  • og: タグは property= を、twitter: タグは name= を使用している
  • すべてのプレースホルダードメインが置き換えられている(grepで検索。通常4つあります)
  • favicon.ico がウェブルートにあり、アセットフォルダ内だけではない
  • SVGファビコンに <path> が含まれており、<text> がない
  • アイコンタイルが塗りつぶされており、ダークモードとライトモードのブラウザクロームの両方で機能する
  • マスク可能アイコンが中央80%にパディングされている
  • theme_color がページの上端と一致している

キャッシュ

すべてのプラットフォームは積極的にキャッシュし、修正後も古いカードを提供し続けます。再スクレイピング:

LinkedInは最も強力にキャッシュし、インスペクターを実行しない限り、約7日間変更を事実上無視します。壊れたカードでURLがすでに広く共有されている場合は、クエリ文字列(?v=2)を追加すると強制的に新しくスクレイピングされます。

ファビコンもブラウザ内で強力にキャッシュされます。プライベートウィンドウでテストしてください。通常のリロードでは通常、古いものが提供され続けます。

プレースホルダードメイン

実際のドメインがまだわからない場合は、example.com のサブドメイン(https://brand.example.com)を使用してください。RFC 2606によって予約されているため、間違いなくプレースホルダーであり、偶然に他の誰かが所有するドメインを指すことはありません。出荷されたメタデータに、もっともらしいが未所有のドメインを残さないでください。

置換手順をブロックのすぐ上のコメントおよびプロジェクトのREADMEに記述し、いくつの出現箇所があるかを記載してください。通常は4つです: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.

関連スキル