Themed One-Page Site · 主题单页网站生成
产出物是一个自包含的单文件 HTML：图片全部压缩后以 base64 内嵌，无外部依赖，双击即可打开，也可以直接发布成在线链接。整站交互（吸顶导航、卡片悬停、轮播、回到顶部、入场动画、数字滚动）全部用原生 CSS/JS 实现。
何时使用
- “把 XX 的资料做成一个网页 / 主题站 / 介绍页”
- “照着某个网站的样子做一个 XX 主题的页面”（沿用现成模板的设计语言）
- “把这些图片塞进网页里，要一个文件就能发给别人”
- “给网页里的角色/人物图做统一风格的卡片和头像”
目录结构
themed-onepage-site/
├── SKILL.md 本文件
├── scripts/
│ ├── build_site.py 图片压缩 + base64 内嵌，产出单文件 HTML（核心）
│ ├── cutout.py 素材抠像 → 统一风格卡片图 + 圆形头像
│ ├── analyze_image.py 分析素材图背景/前景，为抠像定阈值
│ └── shot.py 无头浏览器整页截图 + 元素盒模型探测（核验）
├── assets/
│ ├── site_template.html 佩奇案例模板（含 {{IMG1}}..{{IMG6}} 占位符，约 64KB）
│ ├── site_images.json 佩奇案例的原始图片参数（用于 1:1 复现成品）
│ ├── images/ 案例源图：img1..img6（站内配图）+ char-*.jpg（角色素材）
│ ├── reference-template/ 「简约休闲生活博客」模板原文（设计语言来源，含 bootstrap 等）
│ └── examples/peppa-theme-site.html 佩奇案例成品（0.5MB，可直接打开看效果）
└── references/
└── case-peppa.md 佩奇案例完整复盘：流程、参数与踩过的坑
依赖：pip install pillow numpy scipy（scipy 仅 cutout.py / analyze_image.py 需要）。核验用的无头浏览器自动查找 Chrome/Edge，也可用环境变量 CHROME_PATH 指定。
工作流
第 1 步：定内容与设计语言
- 内容来源优先级：用户给的资料 > 权威百科词条 > 官网。整理成若干板块（案例里是：首屏 intro → 数据 stats → 分季 seasons → 角色 characters → 剧情 story → CTA → 奖项 awards → 衍生 derivative → footer）。
- 若要沿用某个现成模板的设计语言：提取它的主色、字体搭配、卡片圆角/阴影、留白节奏、动效，然后把主色替换成主题色。不要整站照抄它的 HTML，只借“气质”。
- 主题色落地方式：模板把颜色集中在
:root的 CSS 变量里（--primary、--primary-dark、--primary-soft、--primary-pale、--primary-light、--primary-lighten、--ink、--body等）。改主题只需要改这一处——模板中#e8537e字面量只出现 3 次，其余 56 处都走var(--primary)。顺带更新<title>、meta description 和内联 SVG favicon。
第 2 步：改模板内容
复制 assets/site_template.html 作为工作底稿，替换文案与板块。结构约束：
- 所有板块都用
<section>，导航锚点与id对应（案例：#seasons #characters #story #awards #derivative）。 - 数字滚动动画的元素写
data-count="目标值"（可加data-suffix）；入场动画的元素加data-reveal。 - 图片一律走 CSS 变量：模板头部
:root{--img1:url("{{IMG1}}");...}，页面里用class="pic"+style="background-image:var(--img1)"引用。新增图片就加--imgN与对应占位符。
第 3 步（可选）：素材抠像与合成
素材照片构图杂乱时，先抠像再统一贴到同一张“天空渐变 + 云 + 草坡”卡片底上，视觉整齐度远高于直接放四张不同的照片：
# 先分析一张图，确定背景色与阈值
python scripts/analyze_image.py raw.jpg --bg 86,192,232 --vis mask.png
# 再按佩奇案例的四套规则抠像并合成（可 --only peppa,mummy 挑选，可 --sky-top/--hill-top 换配色）
python scripts/cutout.py --src ./raw --out ./gen
四套规则（cut_peppa/cut_george/cut_mummy/cut_daddy）是针对那 4 张源图的背景特征写的。换新图必须先用 analyze_image.py 看背景，再改阈值，不要指望默认阈值通吃。已带 alpha 通道的图通常只需收紧羽化边缘，不必重抠。
第 4 步：压缩内嵌，产出单文件
# 自动模式：占位符 {{IMG1}} 按“文件名主干同名”匹配 images 目录（img1.png/img1.jpg 均可）
python scripts/build_site.py --template site.html --images ./images --out 主题站.html
# 精确模式：用映射表控制每张图的长边与质量（相对路径按映射表所在目录解析）
python scripts/build_site.py --template site.html --images ./images --map assets/site_images.json --out 主题站.html
脚本会等比缩放（默认长边 1000）、不透明图存 JPEG q82、带透明通道的图自动转 WebP q88（保留 alpha），并把仍有未替换占位符的情况当作错误退出。佩奇案例 6 张图 991KB → 315KB，成品 0.48MB。
第 5 步：无头浏览器核验
# 多尺寸截图（默认会生成“冻结版”页面：停用入场动画、隐藏 loading、计数直接写终值）
python scripts/shot.py 主题站.html --out shot.png --shots 485x900,768x1000,1440x1000
# 探测元素盒模型与横向溢出（定位“图不见了/被裁掉”类问题最快）
python scripts/shot.py 主题站.html --probe ".intro-art,footer"
硬性约束（违反任何一条都会返工）
- 每张图只内嵌一次。 同一张图若用
<img src="data:...">会被重复内嵌（案例中同一张图出现 17 次，文件从 0.48MB 涨到 1.17MB）。必须走 CSS 变量。 - 透明图用 WebP 存 base64，JPEG 会丢 alpha；反之不透明图别用 PNG/WebP，JPEG q82 体积最小。
- 截图前必须冻结动画（shot.py 默认已做），否则
[data-reveal]定格在半透明中途状态，会把正常的排版误判成异常。 - 无头 Chrome 有最小视口宽度（实测约 485px）。验证窄屏必须显式
--width 485，传 320/412 得到的仍是 485px 的布局，会误判“内容被裁切”。 background-size:cover对近方形图在宽扁容器里调background-position的 X 轴无效——想改变横向取景要显式放大，如background-size:150% auto。margin:0 auto在弹性/收缩父级里会把宽度塌陷成 0（案例中.intro-art在 ≤991px 因此整块不显示）。宽度异常时先查父级，用--probe看盒模型。- 单文件体积控制经验值：6 张配图 + 全站样式 ≈ 0.5MB；超过 1.5MB 就该压长边或降质量。
换主题检查清单
- [ ]
:root主色系变量（6 个 primary 变量 + favicon SVG） - [ ]
<title>/ meta description / 首屏大标题与副标题 - [ ] stats 区 4 个数字（
data-count） - [ ] 各板块的
id与导航锚点一一对应 - [ ]
--img1..--img6占位符与assets/site_images.json（或 --map）对应 - [ ] 卡片图重新合成（cutout.py 的配色可用
--sky-top/--hill-top跟随主题） - [ ] shot.py 三档尺寸截图核验 +
--probe查关键区块
版权提示
assets/ 里的图片与 reference-template/ 来自网络素材与第三方模板，仅作为本技能的本地参考与示例；对外发布前确认素材授权，或替换为自有素材。模板结构与代码可自由改用。
深入阅读
references/case-peppa.md 记录了佩奇案例的完整制作过程：内容怎么组织、模板设计语言怎么提取、每一步的参数与踩坑细节。做新主题前先读它，能少走一遍弯路。
