Social Mockup Studio
將需求摘要轉化為 LINE、Facebook 和 TikTok 螢幕的精確模擬圖，適用任何品牌、平台與裝置。這個工具組嚴格區分兩個永遠不該混合的元素：
- 平台外框（狀態列、LINE 標題列、FB 分頁列、TikTok 側欄…）位於
assets/kit.css中，永遠看起來像真實應用程式，而不是品牌風格。 - 品牌內容（Flex 訊息、豐富選單素材、廣告創意、頭像、CTA 按鈕樣式）僅由
<project>/brand.css變數驅動。
切換品牌 = 切換 brand.css + 圖片 + 文案。這正是讓跨品牌結果得以公平比較的關鍵。
工作流程
- 前置檢查（在問任何問題之前）。 執行
python3 scripts/preflight.py --brand <品牌網站> --surfaces <line,fb,tiktok>。將其產生的 TELL THE USER 行放入你的第一個回覆中：- 沒有瀏覽器： 告知此處無法進行任何渲染、匯出或視覺檢查。
- 品牌網站或圖片來源被封鎖： 告知此事，並明確指出需要上傳的檔案（標誌、豐富訊息英雄圖、磚塊圖…，以及品牌十六進位色碼和 CTA 用語），或要求使用者允許該網域。
- 絕對不要使用虛構的素材來填補空缺。
- 將結果複製到 notes.md → Environment。
- 需求引導（提問，不要猜測）。 閱讀
references/intake.md，並使用 AskUserQuestion 分輪次提問。先確定螢幕畫面（第 1b 輪）：詢問使用者是否已經知道他們想要的畫面（接受他們的清單），或需要協助（詢問目標，然後提出 2-3 個不同規模的故事板）。在開始建置前，確認好一個編號的故事板表格，並且切勿在不告知的情況下新增或刪除畫面。對於每個 LINE 聊天畫面，務必詢問豐富選單是開啟（開啟 / 收起 / 無）以及是否只顯示新訊息（頂部錨定）或包含之前的訊息。對於豐富選單，先顯示佈局選擇器圖片（templates/richmenu-picker.svg/.png，intake.md 第 3b 輪會說明依環境的操作方式），然後詢問選擇哪個代碼。對於 LINE，務必詢問豐富訊息、Flex 或兩者都要（第 3c 輪，附上來自references/line.md的視覺比較）。及早詢問標誌、品牌顏色（十六進位）和確切的 CTA 用語。將每個答案記錄在notes.md→ Brief，每個猜測記錄在 → Assumptions 以供確認。僅在使用者已回答或存在合理的預設值時才跳過問題。切勿發明優惠、價格、日期、忠誠度計畫或產品宣稱。提問，或將其標記為佔位符。 - 建立專案架構。
bash scripts/new_project.sh <path/to/專案名稱>→ 複製工具組、入門index.html、brand.css和notes.md。 - 品牌 + 圖片。 根據需求引導填入
brand.css。將授權字型放在brand/fonts/，標誌（用於頭像的單色標記）放在brand/。 首先清理每個上傳的檔案：python3 scripts/clean_image.py <檔案> --for <放置位置> --edges /tmp/edges.png。它會修剪白色邊緣條並記錄到assets/clean-log.txt，檢查尺寸是否與references/line-image-sizes.md相符，並寫入邊緣檢查表。打開檢查表並查看。豐富訊息的預設尺寸是 1040×1040，除非使用者確認了其他 OA Manager 尺寸。任何你引用的平台限制都需要兩個或更多來源；如果來源衝突，說明衝突情況並選擇最安全的選項。 每個圖片位置都應使用真實照片。使用 CSS 漸層或佔位文字代替照片正是讓模擬圖看起來假的原因。遵循references/image-sourcing.md： 使用者提供 → 品牌網站/新聞資料 → 線上尋找（scripts/find_images.py "<查詢詞>" --orient portrait會建立一個聯繫表供你查看；然後使用scripts/fetch_image.py <網址> assets/<名稱>.jpg --crop 4:5）。你也可以搜尋任何網頁（新聞、零售商、品牌社群）並將其網址傳遞給 fetch_image.py；它會讀取該頁面的主要圖片。每次下載都會記錄在assets/credits.json中。 - 建立畫面。 圖庫中每個頁面類型只有一個範例，而非每個頁面類型 × 作業系統的組合（請參閱下方的矩陣）。從
templates/gallery.html複製最接近的區塊到index.html，然後使用references/devices.md切換裝置：交換.dev.android↔.dev.ios並應用該作業系統的外框差異（例如 FB 分頁在頂部 ↔ 底部分頁列）。編輯文案和圖片。平台特有資訊在references/line.md、facebook.md、tiktok.md中。- 為每個畫面賦予唯一的
data-shotid；它會成為檔案名稱。每個畫面的 CSS 可以使用[data-shot="id"]設定範圍。 - 使用專案前綴命名專案類別（例如
.sb-hero，而非.kv/.hero），以免與工具組類別衝突。 - 字型和比例（閱讀
references/typography-and-ratios.md）： 應用程式繪製的文字（對話泡泡、Flex、貼文內文、CTA 按鈕、說明文字）一律使用平台字型，因此絕不要對其套用--brand-head/--brand-body。品牌字型僅用於圖片內部。媒體區塊使用比例而非固定高度：FB 動態消息 4:5、輪播 1:1、Stories/Reels/TikTok 9:16、LINE 豐富訊息預設 1040×1040（其他尺寸需經確認，請參閱references/line-image-sizes.md；邊對邊幾何未經確認）、Flex 英雄圖 20:13。 - 切勿為了讓內容符合畫面而刪減、縮短或移動需求內容（例如移除文字對話泡泡以便在選單開啟時放進方形圖片，或將「僅新訊息」的聊天底部錨定）。告知使用者並提供選項：緊湊選單、較短文字、或一個選單收起狀態的額外畫面。
- 標記為 UNVERIFIED 的工具組細節（目前在
references/line.md中的豐富訊息邊距、圓角和寬度）需記錄在 notes.md → Unverified 以及你的交付訊息中。 - 泰文文案：將價格、日期、單位和最終助詞包裹在
<span style="white-space:nowrap">中，確保行尾不會出現孤立的「ค่ะ」、「ml」或拆分單詞。
- 為每個畫面賦予唯一的
- 匯出（在 Mac 上進行，以便 iOS 文字使用真實的 SF Pro + Thonburi 渲染）。
node scripts/export.cjs <專案>（首次在機器上執行：cd scripts && npm install；如果 Playwright 的瀏覽器未下載，會回退到已安裝的 Google Chrome）。它僅提供專案資料夾。→captures/NN-<shot-id>.png（3 倍手機、2 倍桌面、透明背景）、00-overview.png、qa.json。修正它列印出的每個失敗請求和 QA 問題。- 如果無法在此處執行匯出（Claude 應用程式 / Cowork 沙箱沒有 Node、Playwright 或網路連線）：嘗試
cd scripts && npm install && npx playwright install chromium一次。如果仍然失敗，嘗試使用 Python（pip install playwright && python -m playwright install chromium）並自行以 3 倍像素截取每個.frame。作為最後手段，執行python3 scripts/bundle.py <專案>來製作一個自包含的 HTML（dist/<名稱>.html，雙擊即可開啟）。將其與專案 ZIP 一起交付，並直接告知使用者：「我無法在此渲染任何內容，因此這些畫面未經視覺檢查。請在 Chrome 中開啟 HTML；若要儲存畫面，請在手機框架上按右鍵 → 檢查 → Capture node screenshot，或在 Mac 上執行匯出。」然後列出未驗證的細節。切勿將未渲染的結果呈現為已檢查狀態，也切勿空手而回。 - 單一檔案 HTML： 務必使用
scripts/bundle.py建置，切勿使用臨時腳本。它會對每個內嵌腳本進行語法檢查（node --check），如果任何圖標 id 或檔案遺失則失敗，並且在瀏覽器存在時會確認狀態列和圖標能正確渲染。一個臨時打包工具曾經毀壞圖標精靈並導致 kit.js 失效，進而造成狀態列或圖標遺失。 - 非 macOS 系統上，iOS 文字會使用 Inter 代替 SF Pro（kit.js 會進行切換）。在 notes.md 中說明此事，並提供在 Mac 上重新匯出以取得最終客戶檔案。
- 如果無法在此處執行匯出（Claude 應用程式 / Cowork 沙箱沒有 Node、Playwright 或網路連線）：嘗試
- 像客戶一樣審查。 以全尺寸（而不僅僅是總覽圖）開啟每個 PNG，並執行
references/qa-checklist.md。針對每個畫面，填寫 notes.md →「Pre-delivery check against the Brief」：所有需求文案都存在、錨定方式、選單狀態和訊息格式如所詢問、沒有任何內容被移除。將你的模擬圖與來自references/screens/device/的真實裝置截圖並排比較（或要求使用者提供同一頁面的手機截圖）。平台 UI 每隔幾個月就會變更，真實截圖是唯一的地面實況。 - 誠實記錄並交付。 更新
notes.md：佔位符、假設、未驗證的細節、圖片來源和清理日誌、時間表。交付訊息必須包含： (a) 檔案路徑； (b) 哪些內容被檢查過，哪些沒有，例如「已渲染並在 100% 下檢查」vs「未在此渲染」； (c) 需確認的假設，以簡短列表呈現（特別是在首次交付時）； (d) 未驗證的細節； (e) 任何你無法放進畫面的需求項目，以及你提供的選項。
圖庫矩陣（✓ = 現成的畫面；其他 = 從同一行調整）
| 頁面類型 | Android | iOS | 桌面版 |
|---|---|---|---|
| LINE OA 聊天 + Flex | ✓ 深色 | ✓ 淺色 | – （工具組中尚無） |
| LINE 豐富選單（12 個 OA Manager 範本 + 自訂 + 分頁） | ✓ 深色 L6，✓ 分頁式 | ✓ 大型 L4b，✓ 緊湊型 C2l | – （LINE PC 上不顯示） |
| LINE 推播 / 鎖定畫面 | 調整（.android .notif） | ✓ | – |
| FB 動態消息單張圖片 | ✓ 淺色 | ✓ 深色 | ✓ |
| FB 輪播 | 調整 | ✓ 淺色 | 調整 |
| FB Stories/Reels | 調整 | ✓ | – |
| TikTok 頁內 / Spark / 產品卡 | ✓ 頁內 | ✓ Spark，✓ 產品卡 | ✓ |
真實感規則（經過慘痛教訓學到）
每個專案至少閱讀一次 references/realism-rules.md。簡要版本：
- 平台外框永遠不使用品牌顏色。LINE 標題列、FB/TikTok UI 保持原生樣式。
- 所有畫面遵循一致的時間軸（預告 → 上市 → 預購 → 開賣 → 維持）。日期、星期幾、倒數計時和「有效期限」必須一致。檢查每個日期的星期幾。
- 不要發明品牌未實施的福利（點數、會員等級、免費贈品）。如果需求摘要未提及，那就是佔位符或一個問題。
- 內容的錨定方式與真實應用程式一致。新的 LINE 討論串從頂部開始；長的討論串則底部對齊（
.ln-msgs.bottom）。大片的空白區域看起來很假。 - 圖片必須在手機尺寸下清晰可辨。小於約 60 像素的產品縮圖是看不見的，因此請裁剪得更緊湊或放大。
- 使用合理的數字（讚數、留言數、時間、電量），並保持狀態列時間與故事一致（07:30 的推播不該顯示 21:14）。
- LINE 豐富選單是一個設計好的圖片（2500×1686 或 2500×843），而非原生 UI 磚塊。將其作為藝術品設計。
當工具組中缺少某個元素時
在專案的 index.html <style> 中使用相同的慣例（平台 vs 品牌變數）來建置它。如果它是可重複使用的（例如新的頁面類型如 LINE VOOM、FB Messenger、TikTok TopView），請將其添加到 assets/kit.css + templates/gallery.html 中，並告知以便團隊可以將其整合到上游。
檔案
| 路徑 | 說明 |
|---|---|
assets/kit.css、kit.js、icons.svg、fonts/ | 工具組（複製到每個專案作為 kit/） |
templates/gallery.html | 每個頁面類型 × 作業系統，從這裡複製區塊 |
templates/brand.example.css | 包含註解的品牌變數 |
templates/index.starter.html、notes.template.md | 專案起手式 |
scripts/new_project.sh | 建立專案架構 |
scripts/preflight.py | 步驟 0：我們能渲染嗎？是 Mac 嗎？品牌網站和圖片來源可存取嗎？列印出要告訴使用者的內容 |
scripts/clean_image.py | 修剪上傳圖片的白色邊緣（已記錄）、依放置位置檢查尺寸、邊緣放大 QA 檢查表 |
scripts/bundle.py | 一個自包含的 HTML（內嵌 CSS/JS/字型/圖片/精靈），包含語法、圖標和渲染檢查 |
templates/richmenu-picker.svg / .png | 每個豐富選單佈局及其代碼，在需求引導階段顯示給使用者；使用 scripts/richmenu_picker.py --png 重建 |
references/line-image-sizes.md | LINE 豐富訊息 / 豐富選單 / Flex / 圖片依傳送路線的尺寸，附來源和衝突資訊 |
scripts/find_images.py、fetch_image.py | 線上尋找真實照片（聯繫表）· 下載 + 裁剪 + 記錄來源 |
references/image-sourcing.md | 圖片來源、依放置位置的裁剪方式、廣告素材規則 |
scripts/export.cjs | 渲染 + QA（需要在 scripts/ 下執行一次 npm install） |
references/intake.md | 提問輪次 + 預設值 |
references/line.md、facebook.md、tiktok.md | 每個平台的架構、限制、類別對應 |
references/devices.md | 框架、狀態列、作業系統差異 |
references/realism-rules.md、qa-checklist.md、localization-th.md | 品質標準 |
references/screens/ | 標註日期的真實應用程式截圖 + calibrate/ 複製品 |
references/typography-and-ratios.md | 每個平台實際使用的字型、測量尺寸、媒體比例 |
scripts/calibrate.cjs | 將工具組複製品疊加到真實截圖上（並排/混合/差異 + 各頻段評分） |