Inno-Merkle-TH/social-mockup-studio

Social Mockup Studio

将创意简介转化为 LINE、Facebook 和 TikTok 屏幕的像素级高保真设计稿，适用于任何品牌，覆盖 iOS、Android 或桌面端。该工具严格分离两个永远不应混合的部分：

• 平台 chrome（状态栏、LINE 标题栏、FB 标签栏、TikTok 侧栏等）位于 assets/kit.css 中。它始终看起来像真实的应用程序，绝不模仿品牌。
• 品牌内容（Flex 消息、富菜单设计、广告素材、头像、CTA 样式）仅由 <project>/brand.css 中的变量驱动。

切换品牌 = 切换 brand.css + 图片 + 文案。这正是不同品牌间方案能够进行公平比较的原因。

工作流程

0. 预检（在提出第一个问题之前）。 运行 python3 scripts/preflight.py --brand <品牌网站> --surfaces <line,fb,tiktok>。将其输出的 TELL THE USER 行放入您的第一条回复中：
   • 无浏览器： 说明在此环境中无法渲染、导出或进行视觉检查。
   • 品牌网站或图片来源被屏蔽： 说明情况，列出需要上传的确切文件（logo、富消息主图、图块图片……，以及品牌十六进制颜色和 CTA 文案），或要求用户允许该域名。
   • 切勿使用虚构的素材来填补空白。
   • 将结果复制到 notes.md → 环境部分。
1. 信息采集（提问，而非猜测）。 阅读 references/intake.md 并分轮次使用 AskUserQuestion 提问。首先确定屏幕（第 1b 轮）：询问用户是否已经知道他们需要哪些屏幕（直接采纳他们的列表）或需要帮助（询问目标，然后提出 2-3 个不同规模的故事板）。在构建前确认一个编号的故事板表格，切勿悄无声息地增加或删除屏幕。对于每个 LINE 聊天屏幕，始终询问富菜单是展开的（展开 / 收起 / 无）以及是仅显示新消息（顶部对齐）还是也显示之前的消息。对于富菜单，首先展示布局选择器图片（templates/richmenu-picker.svg/.png，如何根据环境使用见 intake.md 第 3b 轮），然后询问代码。对于 LINE，始终询问富消息、Flex 消息，或两者都要（第 3c 轮，附上来自 references/line.md 的视觉对比）。尽早询问 logo、品牌颜色（十六进制）和确切的 CTA 文案。将每个答案记录在 notes.md → 简介部分，并将每个猜测记录在 → 假设部分以供确认。只有当用户已经回答过某个问题或存在一个合理的默认值时，才可跳过该问题。切勿编造优惠、价格、日期、忠诚度计划或产品声明。应询问，或将其标记为占位符。
2. 搭建脚手架。 bash scripts/new_project.sh <path/to/project-name> → 复制工具包、启动文件 index.html、brand.css 和 notes.md。
3. 品牌 + 图片。 根据采集的信息填充 brand.css。将授权字体放入 brand/fonts/，将 logo（用于头像的单色标记）放入 brand/ 中。 首先清理每个上传的文件： python3 scripts/clean_image.py <files> --for <placement> --edges /tmp/edges.png。该脚本会修剪白色边缘条并将其记录到 assets/clean-log.txt，根据 references/line-image-sizes.md 检查尺寸，并写入一张边缘检查图。打开该检查图并查看它。富消息的默认尺寸是 1040x1040，除非用户确认了 OA Manager 的其他尺寸。您引用的任何平台限制都需要两个或多个来源；如果来源冲突，请说明情况并选择最安全的尺寸。 每个图片位置都使用真实照片。CSS 渐变或占位文本代替摄影作品会使设计稿看起来很假。遵循 references/image-sourcing.md： 用户提供 → 品牌网站/新闻资料包 → 在线查找（scripts/find_images.py "<query>" --orient portrait 构建一个联系表供您查看；然后运行 scripts/fetch_image.py <url> assets/<name>.jpg --crop 4:5）。您也可以搜索任何网页（新闻、零售商、品牌社交媒体）并将其 URL 传递给 fetch_image.py；它会读取该页面的主图。每次下载都会记录在 assets/credits.json 中。
4. 构建截图。 画廊为每个平台提供了一个示例，但并非每个平台 × 操作系统的组合（见下方的矩阵）。将 templates/gallery.html 中最接近的代码块复制到 index.html 中，然后使用 references/devices.md 切换设备：交换 .dev.android ↔ .dev.ios 并应用该操作系统的 chrome 差异（例如 FB 标签在顶部 ↔ 底部标签栏）。编辑文案和图片。平台特定细节见 references/line.md、facebook.md、tiktok.md。
   • 为每个截图赋予唯一的 data-shot ID；它将作为文件名使用。单个截图的自定义 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 富消息默认为 1040x1040（其他尺寸需确认后使用，见 references/line-image-sizes.md；边缘对齐的几何形状标记为 UNVERIFIED），Flex 主图 20:13。
   • 切勿为了适配而删减、缩短或移动简介内容（例如，为了在菜单展开时放置方形图片而移除文本气泡，或为了仅显示“新消息”而将内容底部对齐）。应告知用户并提供选项：紧凑菜单、更短的文本，或添加一个菜单收起的额外屏幕。
   • 工具包中标记为 UNVERIFIED 的细节（当前为 references/line.md 中的富消息边距、圆角和宽度）需记录到 notes.md → 未验证项部分，并包含在您的交付消息中。
   • Thai 文案：将价格、日期、单位和语气词包裹在 <span style="white-space:nowrap"> 中，以避免行尾出现孤立的 "ค่ะ"、"ml" 或单词拆分。
5. 导出（在 Mac 上运行，以确保 iOS 文本能渲染为真正的 SF Pro + Thonburi 字体）。 node scripts/export.cjs <project>（如果在机器上首次运行：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 <project> 生成一个独立的 HTML 文件（dist/<name>.html，双击即可打开）。将其与项目 ZIP 文件一起交付，并明确告知用户：“我无法在此处渲染任何内容，因此这些屏幕未经过视觉检查。请在 Chrome 中打开该 HTML；要保存某个屏幕，右键单击 → 检查 → 在手机框架上抓取节点截图，或在 Mac 上运行导出功能。”然后列出未验证的细节。切勿将未经渲染的结果呈现为已检查状态，也切勿空手而归。
   • 单文件 HTML： 始终使用 scripts/bundle.py 构建，切勿使用临时脚本。它会语法检查每个内联脚本（node --check），如果任何图标 ID 或文件缺失则失败，并且当存在浏览器时会确认状态栏和图标是否正常渲染。曾经有一次临时打包工具损坏了图标精灵并导致 kit.js 失效，导致没有状态栏或图标。
   • 在非 macOS 系统上，iOS 文本会使用 Inter 替代 SF Pro（kit.js 会自动进行替换）。请在 notes.md 中说明这一点，并提供在 Mac 上重新导出以获取最终客户文件的选项。
6. 像客户一样审查。 以全尺寸（不仅仅是总览图）打开每张 PNG 图片，并运行 references/qa-checklist.md。针对每个截图，在 notes.md 中填写“交付前检查 vs 简介”部分：确认所有简介文案都存在，锚定方式、菜单状态和消息格式符合要求，没有任何内容被移除。将您的设计稿与 references/screens/device/ 中的真实设备截图（或要求用户提供同种平台的最新手机截图）并排比较。平台的用户界面每几个月就会变化，真实的截图是唯一可靠的真实依据。
7. 如实记录和交付。 更新 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。简要版本如下：

• 平台 chrome 绝不使用品牌颜色。LINE 标题栏、FB/TikTok 界面保持原生样式。
• 所有屏幕应遵循一条连贯的时间线（预告 → 发布 → 预售 → 上架 → 持续推广）。日期、星期几、倒计时和“有效期至”必须一致。检查每个日期的星期几是否正确。
• 不要编造品牌未运营的权益（积分、会员等级、免费赠品）。如果简介中未提及，则将其视为占位符或待提问项。
• 内容锚定在真实应用锚定的位置。一个新的 LINE 会话从顶部开始；较长的会话则是底部对齐的（.ln-msgs.bottom）。大片空白区域看起来不真实。
• 图片必须能在手机尺寸下阅读。小于约 60 像素的产品缩略图是看不见的，因此要么裁剪得更紧凑，要么放大。
• 使用合理的数字（点赞、评论、时间、电量），并保持状态栏时间与故事一致（07:30 的推送不应显示 21:14）。
• LINE 富菜单是一张设计好的图片（2500x1686 或 2500x843），而不是原生的 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	各平台的结构、限制、CSS 类映射
references/devices.md	设备框架、状态栏、操作系统差异
references/realism-rules.md、qa-checklist.md、localization-th.md	质量标准
references/screens/	带有日期的真实应用截图 + calibrate/ 目录中的校准副本
references/typography-and-ratios.md	每个平台实际使用的字体、实测尺寸、媒体比例
scripts/calibrate.cjs	将工具包副本叠加到真实截图上（并排/混合/差异 + 按频段评分）