Communitygithub.com

brainzcode/premium-landing

링크 미리보기와 파비콘을 실제로 작동하게 만들어주는 스킬입니다. 오픈그래프/트위터 카드 태그, 올바른 1200x630 공유 이미지, 완전한 파비콘 세트(SVG, ICO, apple-touch, maskable manifest 아이콘)를 제공합니다.

premium-landing란 무엇인가요?

이 스킬은 소셜 공유 및 파비콘과 관련된 모든 작업을 처리하는 완벽한 솔루션입니다. 소셜 미리보기(OG 이미지, 트위터 카드)를 위해 `og:image`와 `og:url`이 반드시 절대 URL(publicly reachable host)이어야 한다는 핵심 규칙을 강조하며, 상대 경로로 인해 미리보기가 깨지는 흔한 실수를 방지합니다. 1200x630 공유 이미지 제작 시 전체 뷰포트에서 크롭하는 대신 정확한 비율로 렌더링하는 방법과, 짧은 뷰포트 트랩(short-viewport trap)으로 인한 미디어 크롭 문제를 해결하는 팁을 제공합니다. 파비콘의 경우 `<text>` 대신 `<path>`를 사용해야 폰트 트랩을 피할 수 있으며, 투명 배경 대신 채워진 타일 위에 그려야 브라우저 크롬에서 사라지지 않습니다. 또한 Android adaptive mask를 위한 maskable 아이콘의 중앙 80% 안전 영역과, `theme_color`가 페이지 상단과 일치해야 하는 중요성까지 실제 배포 환경에서 바로 적용 가능한 지침과 생성 스크립트를 제공합니다. 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이어야 합니다.

크롤러는 자신의 서버에서 이 값을 가져옵니다. 페이지 컨텍스트, 쿠키, 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="ko_KR">
<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자에서 잘립니다. 의미를 앞부분에 배치하세요.

공유 이미지

1200x630 (1.905:1). 디자인에 알파 채널이 필요하지 않다면 JPEG를 사용하세요. 모든 플랫폼이 흰색 배경 위에 합성하므로 필요하지 않습니다. 약 1MB 미만으로 유지하세요. 하드 제한은 8MB(Facebook)와 5MB(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     # 상단 고정

선택하기 전에 상단 고정 자르기와 중앙 자르기를 비교하세요. 상단 고정은 보통 브랜드 페니처(유틸리티 바, 내비게이션, 워드마크)를 유지하고, 중앙은 주제와 행동 유도(Call to Action)를 유지합니다. 전체 높이 히어로가 1.905:1이 허용하는 것보다 더 크기 때문에 둘 다 가질 수 없습니다.

프레이밍

카드는 피드에서 약 500px 너비로 렌더링되며, 각 플랫폼마다 다르게 자릅니다(LinkedIn과 Slack이 Facebook보다 더 좁게 자릅니다). 반드시 살아남아야 하는 요소는 중앙 80% 안에 두고, 모든 텍스트는 절반 크기에서도 읽을 수 있을 만큼 크게 설정하세요. 미세한 UI 디테일은 사라집니다. 큰 워드마크와 강력한 이미지는 살아남습니다.

파비콘

폰트 트랩

SVG 파비콘에 <text>를 넣지 마세요.

<!-- 문제 발생: 사용자가 가지고 있는 폴백 폰트로 렌더링됨 -->
<svg ...><text x="50%" y="50%" font-family="Geist">G</text></svg>

SVG는 사용자의 기기에서 렌더링되는데, 그 기기에는 당신의 웹폰트가 없습니다. 글리프를 **경로(path)**로 추출하여 글꼴에 독립적이고 해상도에 독립적으로 만드세요. 아래 스크립트를 참조하세요.

투명도 트랩

투명 배경 위의 어두운 글리프는 어두운 브라우저 크롬에서 사라지고, 밝은 글리프는 밝은 배경에서 사라집니다. 아이콘을 채워진 타일 위에 그리세요. 이렇게 하면 탭 바, 북마크, 홈 화면에서 마크가 일관된 실루엣을 가집니다.

파일 세트

파일크기이유
/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">

Maskable 안전 영역

Android는 아이콘을 임의의 모양(원, 둥근 사각형, 물방울)으로 자릅니다. maskable 아이콘은 모든 중요한 콘텐츠를 중앙 80% 원 안에 유지해야 하며, 이는 타일 가장자리의 약 40%가 버릴 수 있는 여백임을 의미합니다. 일반 아이콘을 재사용하면 가장자리가 잘려나갑니다.

실제로: 표준 아이콘에서 글리프가 타일의 60%를 차지한다면, maskable 아이콘에서는 약 40%로 줄이세요. 두 가지를 모두 제공하고, "purpose": "any"와 "purpose": "maskable"을 별도 항목으로 추가하세요. 절대 두 목적을 하나의 파일에 넣지 마세요.

웹 매니페스트

{
  "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는 모바일 브라우저 크롬에 색상을 입히므로, 브랜드의 메인 색상이 아니라 페이지 최상단에 있는 것과 일치해야 합니다. 페이지가 검은색 유틸리티 바에서 열리면 그 검은색을 사용하세요. 불일치는 렌더링 버그로 읽힙니다. <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 비율 안에 중앙에 배치하고 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}가 절대 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= 사용
  • 모든 플레이스홀더 도메인 교체 (검색해보세요. 보통 4개 있습니다)
  • favicon.ico가 웹 루트에 있는지 (assets 폴더에만 있는 것이 아님)
  • SVG 파비콘에 <path>가 포함되어 있고 <text>가 없음
  • 아이콘 타일이 채워져 있어 어둡고 밝은 브라우저 크롬에서도 잘 보임
  • maskable 아이콘이 중앙 80%에 패딩되어 있음
  • theme_color가 페이지 상단 가장자리와 일치

캐싱

모든 플랫폼은 적극적으로 캐싱하며, 수정한 후에도 계속 이전 카드를 제공합니다. 다시 스크래핑하세요:

LinkedIn은 가장 강력하게 캐싱하며 인스펙터를 실행하지 않으면 약 7일 동안 변경 사항을 효과적으로 무시합니다. URL이 이미 깨진 카드로 널리 공유된 경우 쿼리 문자열(?v=2)을 추가하면 새로운 스크래핑이 강제됩니다.

파비콘도 브라우저에서 강력하게 캐싱됩니다. 비공개 창에서 테스트하세요. 일반 새로고침은 보통 이전 것을 계속 제공합니다.

플레이스홀더 도메인

실제 도메인을 아직 모르는 경우 example.com의 서브도메인을 사용하세요(https://brand.example.com). RFC 2606이 이를 예약하므로 플레이스홀더임이 명백하며 실수로 다른 사람이 소유한 도메인을 가리킬 수 없습니다. 배포된 메타데이터에 소유되지 않은 plausible한 도메인을 절대 남기지 마세요.

교체 지시를 블록 바로 위의 주석과 프로젝트 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.

관련 스킬