模板换肤式主题站制作
用途
用一套现成的 HTML 模板当骨架，通过「主题覆盖层 CSS + 素材语义化命名 + 截图自查循环」三件套，快速做出一个某主题（IP / 品牌 / 角色 / 活动）的完整单页网站。
产出形态：index.html + assets/（模板自带的第三方库 + 主题覆盖层）+ images/（语义化命名后的素材）。
什么时候用这个 skill
- 用户给一个模板站 / RAR 包 / 一坨素材，要求"做成某某主题的网站"。
- 用户要求"参考这个页面的结构，换成我们自己的主题"。
- 任何"改主题不改骨架"的网页改造任务。
- 单独需要「用无头浏览器给页面截图自查」——直接跳到 Phase 5，用
scripts/capture.py。
铁律（违反任何一条都会导致返工）
- 绝不修改模板原始的
style.css/responsive.css/*-script.js。
所有改造落在新增的assets/<theme>-theme.css与assets/<theme>-script.js，并在index.html的<head>/</body>里最后引入，靠加载顺序覆盖。这样模板升级、回滚、对比都无痛。 - 改动
index.html之前先备份为_index_backup.html，便于随时 diff 定位回归。 - 渲染结果必须用截图确认，不能凭代码想象。 每个阶段收尾时截图；批量改 CSS 后必须再截一次。这是本流程质量的主要来源。
- 素材一律语义化重命名后再引用。 绝不把
src=http___ci.xiaohongshu.com_585a7a44-..._imageView2_2_w_1080_format_jpg&refer=....webp这种原始文件名写进 HTML。 &、=、中文、空格的文件名必须进images/后重命名掉，否则 URL 会被截断、浏览器编码不一致。
工作流
Phase 0 — 摸清模板骨架（先读，别急着写）
- 列出模板全部文件；重点看
assets/下的第三方库清单（Bootstrap / jQuery / Slick / MixItUp / VenoBox / Owl / Particles / FontAwesome / webfonts）——这决定了哪些区块是白送的。 - 用 Read 通读模板
index.html，在草稿纸上建立区块清单：header / logo条 / navbar / 跑马灯 / 主轮播 / 侧栏速览 / 卡片宫格 / 筛选图鉴 / 视频区 / 滑块商品 / 图集 / 资讯卡片 / footer。 - 记录可复用动效：轮播、进度条、筛选、滑块、灯箱、粒子、返回顶部、深色模式。这些要在 Phase 3 里原样保住。
- 产出类名地图 → 见
references/class-map.md。不要跳这一步，覆盖层 CSS 全靠它。
Phase 1 — 素材收集与语义化命名
- 原始素材（网络下载、截图、AI 生图）全部先丢进一个原始素材目录，不改名。
- 用脚本扫描 + 生成映射骨架：
bash python scripts/copy_images.py scan --src <原始素材目录> --out _image-map.json
脚本会输出每个文件的宽x高 / 宽高比 / 体积，并按宽高比给出槽位建议（横向宽图 → banner、近方图 → card、竖图 → vertical）。 - 按打印出的建议填写
_image-map.json（{"images/<语义名>": "<原始文件名>"}），然后执行：
bash python scripts/copy_images.py apply --src <原始素材目录> --dst <站点目录>/images --map _image-map.json
脚本会报告「缺失原文件」和「空槽位」，零缺失才继续。 - 槽位命名约定（沿用即可，便于覆盖层 CSS 统一处理）：
logo / logo-wide / hero-main / banner-1..N（宽幅背景）/ card-1..N（方形卡片）/ vertical-1..N（竖图）。 - 若素材是
webp但模板/浏览器兼容性有顾虑，保留原扩展名即可（现代 Chrome/Edge 全支持）；不要为了统一而批量转码，避免画质与体积失控。
Phase 2 — 主题覆盖层 CSS
- 复制骨架：
references/theme-override-skeleton.css→<站点>/assets/<theme>-theme.css。 - 先只改
:root主题变量（主色 / 辅色 / 悬停色 / 正文字色 / 三档浅色底），跑一次截图看整体气色对不对，再逐区块精修。 - 按 Phase 0 的区块清单逐段覆盖，顺序与页面视觉顺序一致，并保留骨架里的小节注释。
- 修模板自带的坑：模板常依赖我们没下载到的图片或字体，典型症状与修法见
references/pitfalls.md。最经典的是background-clip:text+ 缺失背景图 → 标题整段消失。 - 覆盖层里尽量用
!important只在与模板内联/高优先级选择器对撞时使用；能靠选择器权重解决就别滥用。 - 末尾补：深色模式适配（若模板有 dark 开关）+ 三段响应式微调。
Phase 3 — 交互脚本
- 复制
assets/<theme>-script.js，按模板原有动效逐个初始化，顺序：年份 → 深色开关 → 粒子 → 轮播进度 → Owl → MixItUp → VenoBox → Slick → 移动端下拉 → 返回顶部 → 表单 → 搜索 → 预加载器。 - 每个初始化都加存在性判断（
if (document.querySelector("#x"))），单页里缺某个区块时不能整段 JS 报错中断。 - 粒子 / 主题色等硬编码颜色，改成与 CSS 变量同源的色值，避免主题换色后动效还留着旧配色。
- 用
window.addEventListener("load")收尾隐藏预加载器；否则页面会永远停在 loading 动画上。
Phase 4 — 内容填充
- 先备份：
cp index.html _index_backup.html。 - 沿着模板原有区块逐块替换文案与图片路径，不新增/不删除区块结构，避免布局崩坏。
- 文案风格：主题介绍类站点用「事实 + 具体数字 + 短句」，一屏内不堆长段落。案例见
references/example-hello-kitty/。 - 全站图片引用统一走
images/<语义名>；外链字体（Google Fonts）如已本地化为assets/gfonts.css，优先用本地版本，保证离线可开。 - 修完立刻进 Phase 5，不要攒到最后。
Phase 5 — 截图自查循环（本流程的质量核心）
# 整页按 2000px 分带截图，产出 shots/band-00.png、band-01.png ...
python scripts/capture.py --root <站点目录> --url /index.html --out shots
# 只看某一屏（定位到 y=2600 的 2000px 高度区间）
python scripts/capture.py --root <站点目录> --out shots --offset 2600
# 只看某个区块（自动测量该元素的位置与高度，精确出图）
python scripts/capture.py --root <站点目录> --out shots --selector .footer
脚本内置本地 HTTP 服务 + 无头 Chrome/Edge。截完必须用 Read 工具看图，逐项核对 references/qa-checklist.md。
发现问题 → 回 Phase 2/4 改 → 重新截同一屏确认，不确认不算修完。
命名带语义便于追溯，例如 shots/f_hero.png（首屏）、shots/f_gal.png（图集）、shots/dbg2.png（第二轮排查）。
Phase 6 — 交付
- 清掉自查产物：
_wb-shot-*.html（脚本自动删）、_shots/、_image-map.json、原始素材目录。保留_index_backup.html（当作用户可回滚的备份）。 - 用
python -m http.server起一次本地服务，按references/qa-checklist.md走一遍交互（轮播、筛选、滑块、灯箱、深色、搜索、返回顶部）。 - 出交付包（zip 或直接给目录），在说明里写清：模板来源、覆盖层文件、素材来源与授权提示。
关键陷阱速查
| 症状 | 根因 | 修法 |
|---|---|---|
| 区块标题整段看不见 | 模板 background-clip:text + 缺失背景图 + 透明文字填充 |
覆盖层强制 background:none + -webkit-text-fill-color:<主色> |
| 卡片列表第 4 张被裁掉 | 模板给滚动区写了固定 height |
覆盖层 height:auto !important; overflow:visible !important |
| 背景图不显示 | 模板用相对路径指向不存在的图 | 覆盖层重指 background-image，或改 HTML 内联 style |
| 装饰方块位置诡异 | 模板靠 top/right 绝对定位装饰元素 |
覆盖层微调 top/right 复位 |
| 区块上下间距过大/过小 | 模板原始 padding 与内容量不匹配 | 覆盖层逐段调 padding，别动模板文件 |
| 截图只有 400px 高 | Chrome --screenshot 只截视口 |
用 scripts/capture.py，它是分带/偏移截图 |
| html2canvas/截图出现空白带 | 视口比内容高 | 用 --selector 精确到区块，别硬压长图 |
完整清单见 references/pitfalls.md。
Bundled resources
scripts/copy_images.py— 扫描原始素材（纯 stdlib 读 PNG/JPEG/GIF/WEBP 尺寸）→ 按宽高比给槽位建议 → 生成_image-map.json→ 按映射复制重命名到images/。scan/apply两个子命令。scripts/capture.py— 无头浏览器截图器：内置本地 HTTP 服务；--full整页单图 / 默认分带 /--offset指定屏 /--selector精确到区块。自动探测 Chrome/Edge 路径，无第三方依赖。assets/scroll-shot.html— 偏移分带截图器（iframe 高度y+band+marginTop:-y，让整页任意区间落到视口内）。assets/probe.html— 页面高度 / 元素位置探针（借--dump-dom执行 JS 后回读结果）。references/theme-override-skeleton.css— 主题覆盖层骨架，含分区注释、深色模式与响应式段落。references/class-map.md— 如何从模板快速提取类名地图。references/pitfalls.md— 模板换肤常见坑与修法（含完整代码片段）。references/qa-checklist.md— 交付前视觉与交互验收清单。references/example-hello-kitty/— 完整实战样本（index.html/hk-theme.css/hk-script.js/_copy_images.py）。
参考实现
references/example-hello-kitty/ 是一套真实跑通的成品：把「动漫爱好者平台」模板换肤成 Hello Kitty 粉红主题，覆盖层 607 行 CSS + 251 行 JS，页面 1094 行。做新主题时建议先读 hk-theme.css 的分区结构，照它的颗粒度写自己那份覆盖层。
