Og images
三種圖片,目標一致:讓人在看到連結時停留,並在一瞥之間理解應用程式。 每一張都是應用程式的真實截圖,帶有大字標題,放在品牌的底色或亮色桌布上。UI 是主角。除了外框之外,不做任何繪圖。
輸出檔案,位於使用者儲存庫的 launch-assets/og/ 目錄下:
| 檔案 | 尺寸 | 說明 |
|---|---|---|
og.png | 1200×630 | 首頁的連結預覽。 |
og-<id>.png | 1200×630 | 可選:網站每個頁面一張,相同設計,標題來自該頁面。 |
ph/01-<id>.png … 06 | 1270×760 | Product Hunt 圖庫,4 到 6 張投影片。投影片 1 是主視覺。 |
x-header.png | 1500×500 | X 橫幅,清楚保留大頭貼與手機裁切區。 |
meta.html | 要貼入 <head> 的 <meta> 標籤。 |
尺寸與安全區域,以及來源和日期,請參考 references/sizes.md。
使用時機
- 產品發表需要分享圖片、Product Hunt 圖庫或 X 橫幅。
- 網站目前的
og:image只是單色背景上的 Logo,或者根本沒有。 - 版本更新改變了 UI,因此需要從新的截圖重新產生預覽。
截圖是 Mac 風格的橫向視窗或 Island;這些卡片不支援直立的手機螢幕。 不適用於:App Store 截圖(這是另一個技能,有不同的尺寸),或任何需要應用程式本身不具備的 UI 的情況。此技能絕不繪製 UI。
設定(僅需執行一次)
需要 Node 20 或更新版本。Playwright 會安裝在此技能的資料夾中,而不是使用者的儲存庫:
npm install --prefix <skill-folder> [email protected] && npx --prefix <skill-folder> playwright install chromium
如果缺少 Playwright,render.mjs 會印出這行指令並以狀態碼 2 結束。
步驟 0. 品牌資訊
讀取使用者儲存庫中的 launch-assets/brand.json。如果存在,直接使用。如果不存在,則從儲存庫中偵測每個欄位並寫入檔案。僅就你無法找到的資訊,一次性地向使用者提問。
{
"appName": "Halo", "oneLiner": "The Dynamic Island for Mac", "platform": "macos",
"colors": { "bg": "#f5f5f7", "ink": "#1d1d1f", "accent": "#0071e3" },
"fonts": { "family": "-apple-system, 'SF Pro Display', sans-serif", "file": null, "google": null },
"iconPath": "site/assets/icon.png",
"screenshotDirs": ["launch-assets/captures"],
"siteUrl": "https://example.com"
}
appName,oneLiner:來自 README 標題和第一行、網站的<title>和<h1>、Info.plist。colors:來自網站的 CSS 變數、Asset Catalog 的AccentColor、Swift 的Color定義。取用淺色模式的數值。寫成十六進位(#0d7f76);先轉換rgb()、oklch()和hsl()。任何渲染器無法讀取的顏色都算作灰色。fonts.family(一個 CSS 字型堆疊)、fonts.file(儲存庫內含的字型檔案,相對於儲存庫根目錄的路徑,也就是launch-assets的上層資料夾,或null)、fonts.google(例如Geist:wght@400;600,或null)。只有在儲存庫內含該字型檔案時,才使用品牌的字型;否則使用系統字型堆疊或 Google Fonts。切勿將專有字型複製到使用者的儲存庫中。iconPath:應用程式圖示,一個方形 PNG(最好 1024 px),相對於儲存庫根目錄。請在網站的 assets、Asset Catalog 的AppIcon、favicon 資料夾中尋找。必要:圖示和名稱會出現在每張圖片上。siteUrl:meta.html中圖片 URL 的指向位置。非必填;如果沒有,標籤會帶有佔位符。
步驟
-
截圖。 重複使用既有的截圖:
launch-assets/captures/、screenshotDirs,或先前的launch-assets/store-screenshots/shots.json。只有在沒有截圖符合以下規則時,才拍攝新的截圖。首先尋找應用程式自有的截圖方式: snapshot、demo 或 sample-data 標誌(在原始碼、README 和Package.swift中搜尋rg -i "demo|snapshot|screenshot|marketing";例如MyApp --snapshot <dir>或MYAPP_DEMO=1)。在執行標誌之前,先了解其作用。絕對不要執行任何會掃描、清除或寫入真實使用者資料的動作,也絕對不要啟動第二個會保持即時狀態的應用程式實例。 如果某個標誌可能導致上述情況,請停下來並詢問。否則,在 Mac 上,將應用程式放到最前面,顯示出要展示的狀態,然後執行swift <skill-folder>/scripts/capture-window.swift "MyApp" capture.png(應用程式最大的螢幕上視窗,無陰影,Retina 畫素;它會跳過 notch 或選單列應用程式的面板,這些位於更高的視窗圖層上,並會告知此情況)。iOS:xcrun simctl status_bar booted override --time 9:41 --batteryState charged --batteryLevel 100,然後xcrun simctl io booted screenshot capture.png,最後xcrun simctl status_bar booted clear。每張截圖的規則:
- 真實 UI,已聚焦。 作用中視窗:彩色的交通燈號、亮起的側邊欄。灰色、暗淡的視窗視為失敗。
- 已穩定。 沒有計數器正在滾動、沒有載入中動畫、沒有半繪製的內容。
- 中立示範資料。 沒有個人姓名、真實檔案、專案或帳戶名稱,沒有其他公司的產品名稱(除非應用程式自己的網站提到了該整合)。請使用示範模式,絕不使用真實內容的截圖。
- 淺色模式(如果應用程式有的話)。深色截圖僅限於只支援深色模式的應用程式。
- 2x 畫素。 卡片上的截圖最多只能放大到自身畫素的 1.15 倍(超過會渲染失敗),因此連結預覽的視窗需要約 1400 px 寬,圖庫投影片需要 2000 px。
- 真實內容。 沒有空的區塊、沒有假文、在標題提及的部分沒有截斷的文字。
- 適合小尺寸閱讀。 連結預覽中,截圖的顯示寬度約為 600 px。選擇其重點在該尺寸下仍清晰可見的截圖(一個大數字、一個清晰的清單),而不是一個密密麻麻的設定面板。裁剪到重要的部分。
- 使用 SwiftUI
ImageRenderer截圖(例如 notch 應用程式的 Island)時,其角落 flare 會帶有不透明的黄色佔位符:請設定"clean": true。對於浮在卡片上的 Island,請加上"square": true,這會將角落 flare 縮成方形,與主體邊緣齊平。使用crop裁剪掉空白的 notch 行。
當每張截圖都通過檢查清單時,繼續下一步。檢查每個檔案的大小(
sips -g pixelWidth -g pixelHeight)並實際檢視圖片。 -
撰寫文案。
- 連結標題: 應用程式的一句話介紹或頁面本身的標題,使用網站自己的用語:9 個單字或更少,使用 sentence case,無句號,無破折號,無
!。這是卡片上唯一的大型文字,因此越短就能越大。 - 頁面: 如果儲存庫有一個包含多個頁面的網站,請執行
node <skill-folder>/scripts/pages.mjs <site-folder>。它會印出每個頁面的<title>和<h1>。挑選值得擁有自己預覽的頁面(指南、定價頁面、最重要的功能);跳過提及另一家公司產品的頁面。取用<h1>或兩者中較短的那個,移除網站名稱後綴和 "(2026)" 風格的標籤,保持不超過 9 個單字。切勿改寫。 - 投影片: 如果
launch-assets/store-screenshots/shots.json存在,"ph": { "fromShots": "../store-screenshots/shots.json" }會重複使用其中的標題、副標題、截圖和裁剪(前 6 張截圖,"limit"可更改此數量)。否則,撰寫 4 到 6 張投影片:投影片 1 說明應用程式是什麼,後續每張都有一個優勢且能單獨理解。標題 6 個單字或更少,可選的副標題為一個簡短句子。 - X 橫幅標題: 應用程式的一句話介紹。6 個單字或更少。
- 替代文字: 一句話說明圖片內容。預設為
<app>: <title>. <subline>;當截圖有值得說明的內容時,請在連結上撰寫alt。
文案使用網站自己的用語。 每一行都來自網站或 README 並經過縮短;每個數字、名稱和主張都必須在網站上找到。在保留文案之前,請使用
rg在網站內容中確認每一行。 - 連結標題: 應用程式的一句話介紹或頁面本身的標題,使用網站自己的用語:9 個單字或更少,使用 sentence case,無句號,無破折號,無
-
撰寫
launch-assets/og/og.json。{ "brand": "../brand.json", "out": ".", "wallpaper": "auto", "link": { "title": "A Mac cleaner for developers", "capture": "../captures/overview.png", "alt": "Shedi, a Mac cleaner for developers: 43.84 GB found, sorted into safe to clean and check first" }, "pages": [ { "id": "xcode-deriveddata", "title": "Clear Xcode DerivedData", "capture": "../captures/xcode.png" } ], "ph": { "fromShots": "../store-screenshots/shots.json" }, "x": { "title": "A Mac cleaner for developers", "capture": "../captures/overview.png" } }省略
pages、ph或x以跳過該類型。路徑相對於og.json。頁面會繼承link的所有設定(截圖、裁剪、佈局)並覆蓋它指定的項目。link、頁面、投影片或x的可選選項:capture(或captures,最多 3 張,堆疊顯示)、crop({ x, y, w, h },值為 0 到 1,表示裁剪透明邊緣後的截圖比例;crops用於多張截圖)、clean、square、radius、width(截圖寬度佔卡片寬度的比例)、shadow: false、minCoverage。layout:連結卡片可以是side(標題在左,視窗從右下角升起)或below(標題置中,寬截圖在其下方)。預設為:截圖寬高比大於 2:1 時選用below,否則選用side。投影片可以是fit(完整顯示截圖,不裁剪)、bleed(由底部邊緣裁剪,適用於視窗)或pair(堆疊 2 或 3 張截圖)。沒有指定layout且只有一張普通視窗截圖(無clean)的投影片,預設為bleed;其他情況預設為fit。minCoverage:UI 覆蓋率的最低標準(連結 0.3,投影片 0.4,橫幅 0.12)。如果截圖寬度達到卡片寬度的 80%,則無需此檢查(細長的 Island 或工具列無法變得更高)。不要為了隱藏小截圖而降低標準:應該讓它顯示得更大、裁剪它或選擇其他截圖。- 在使用
fromShots的投影片上,可以加上"slides": [{ "id": "<shot id>", ... }]來覆蓋某個投影片的選項。
背景,所有圖片共用:
"wallpaper": "auto"會從內建圖片中挑選色調最接近品牌強調色的圖片(藍色和青色、綠色、暖色、粉紅色),並印出選擇結果及原因。告知使用者選擇結果及原因,並告訴他們可以變更(設定"wallpaper": "snow",或提供一個路徑指向他們自己的明亮、平靜的圖片,寬度至少 2400 px)。灰色強調色,或與每張內建圖片色調相差超過 50 度的強調色,則使用品牌底色(品牌背景色加上少量強調色調和)。省略此鍵則使用品牌底色。此技能內建五張圖片。 -
渲染。
node <skill-folder>/scripts/render.mjs launch-assets/og/og.json每張 PNG 輸出一行:
ok或FAIL、尺寸、檔案大小、實際用於繪製標題的字型、文字與其背後畫素之間的對比度、標題的大小和大寫高度、UI 覆蓋率,以及截圖和桌布被放大了多少倍。--only link|pages|ph|x可只渲染一種類型(其他類型會導致錯誤)。它也會寫入meta.html。檢查項目失敗的情況包括:尺寸不精確、含有 Alpha 色版、檔案超過 5 MB、文字對比度低於 4.5:1(沒有半透明遮罩;請選擇更淡的桌布或更深的字色)、標題的大寫高度低於最小值(連結 40 px,投影片 38 px,橫幅 36 px,確保在 600 px 寬的預覽中仍可閱讀)、需要多行才能容納但空間不足、文案過長或包含破折號(" - " 或 "--")或
!、截圖放大倍率超過 1.15 倍或桌布放大倍率超過 1.2 倍、UI 覆蓋率低於標準(除非截圖寬度達到卡片寬度的 80%,此測量基於截圖的內容畫素而非其外框,因此純黑或純白區域不計入)、任何超出 X 安全區域或在頭像區域內的內容,以及字型回退:fonts.family的第一個名稱必須是實際繪製標題的字型(例如"Inter, sans-serif"但未提供字型檔案,則會使用 SF Pro 繪製:判定為 FAIL)。如果字型堆疊以-apple-system或system-ui開頭,則表示使用系統字型,僅在回退到 Helvetica 或 Arial 時才會失敗。修正og.json中的每個FAIL後重新渲染。 -
QA 檢查。必要,且直接在檔案上執行,而非在設定檔上。
- 尺寸和 Alpha:
sips -g pixelWidth -g pixelHeight -g hasAlpha <每個檔案>。尺寸必須與 sizes.md 完全一致,hasAlpha: no。 - 視覺檢查: 使用 Read 工具以完整尺寸打開每張 PNG。然後執行
node <skill-folder>/scripts/preview.mjs launch-assets/og並打開_preview-600.png和_preview-300.png(每張圖片縮放到 600 px 和 300 px 寬,如同資訊流顯示的樣子),然後刪除這兩個檔案。對每張圖片檢查:- 標題在 300 px 下可讀,沒有內容被裁切或獨自在第二行。
- 輸出行中的字型是你所指定的。
- 截圖清晰,顯示出標題的重點,沒有截斷的文字,沒有個人資料。
- 名稱:沒有競爭對手或其他公司的名稱或標誌,除非該網站提到了該整合;沒有個人姓名。
- 文案:每一行都是網站自己的用語,經過縮短;每個數字都在網站上。
- X 橫幅:左下角(x 小於 420,y 大於 300)保持空白,以放置個人資料照片;內容位於中間區塊,遠離上下各 70 px 的區域。對照 sizes.md 進行檢查,如果可能,在真實的個人檔案頁面上檢查。
- 系列感:投影片閱讀起來像一個家族;沒有兩張傳達相同的重點。
- 修正後重新渲染,然後再次檢查該檔案。
- 完成上述步驟後才進行報告: 檔案列表、
sips輸出,以及任何你無法驗證的項目。告知使用者將 PNG 複製到網站,將meta.html貼入<head>,並在各平台的除錯工具中重新整理快取的預覽。
- 尺寸和 Alpha:
視覺規則
- 淺色優先。 使用亮色桌布或品牌底色,搭配深色字體。避免深色背景搭配螢光色。
- 無光暈、無光環。 深度僅使用 1 px 邊框和低透明度的中性黑色陰影。
- 每張圖片專注於一個任務。 一個標題,一張截圖(或一組),最多一個副標題。
- 大號字型。 標題是在縮圖中唯一能倖存的元素。簡短的文案才能讓字型變大。
- 僅限真實截圖。 UI 絕不進行繪製、重繪或生成。