Frontend Slides Bold Template Pack 解析：基于元数据索引的渐进式风格模板系统与固定 16:9 舞台实现

本篇技术指南围绕 frontend-slides 技能包中的 Bold Template Pack（位于 bold-template-pack/README.md）展开，讲解它如何把 beautiful-html-templates 的 34 套大胆设计系统以“渐进式披露”方式接入 frontend-slides，而不让它们成为每套演示的默认样式。读完本文，你将掌握：如何通过 selection-index.json 元数据快速筛选候选模板、如何按“1 安全预设 + 1 bold 模板 + 1 通配项”的组合生成视觉预览、design.md 与 preview.md 各自的职责边界，以及最终把任意 viewport-fluid 模板翻译成固定 1920×1080 舞台的完整实现契约。

一、Bold Template Pack 是什么：设计系统的“可选项”而非“默认项”

Bold Template Pack 的核心定位在文档第一段就写得很清楚：把 beautiful-html-templates 的 design systems 带进 frontend-slides 技能，同时不让它们成为每套 deck 的默认样式。也就是说，它是一组可选的“大胆风格”模板库，与 frontend-slides 自带的 12 个安全预设（见 STYLE_PRESETS.md）形成互补：

• 安全预设（safe presets）：如 Bold Signal、Electric Studio、Dark Botanical，风格克制、稳妥，适合任意场合；
• Bold 模板：如 Studio、Neo-Grid Bold、Editorial Tri-Tone，视觉激进、个性鲜明，仅在风格探索阶段被“提名”为候选；
• 通配项（wildcard）：可以是第二个 bold 模板，也可以是 Agent 自生成的自定义设计。

在项目根目录的 README.md 中，Bold Template Pack 被列为关键特性之一（“Optional design-forward templates ... loaded progressively so safe presets still work as the default fallback”），并且以“三份截图 × 34 套模板”的图库形式展示了每套模板在不同版式下的表现。用户可见的技能包路径位于 plugins/frontend-slides/skills/frontend-slides/bold-template-pack/，与仓库根目录的 bold-template-pack/ 互为镜像。

二、What To Read：渐进式读取协议（如何避免“读爆”模板库）

Bold Template Pack README 用整整一个小节规定了 Agent 的读取顺序，这是“渐进式披露”（progressive disclosure）原则在文件系统层面的落地。文档原文给出了 6 条硬性规则：

1. 先读 bold-template-pack/selection-index.json——即 selection-index.json；
2. 只凭元数据初筛候选，关注的字段为：mood、tone、best_for、avoid_for、formality、density、scheme；
3. 标题页预览时，只读被初筛候选对应的 preview.md；
4. 用户选定某一 bold 模板后，才去读且只读那一个模板的完整 design.md；
5. 不要读包内所有 design.md；
6. 除非所选 design.md 缺失关键实现细节，否则不要读源模板库的 template.html。

文档还特别强调：完整的源元数据索引不会打包进用户可见的技能包，正常生成流程只使用 selection-index.json。这一设计在 SKILL.md 的 Phase 2（Style Discovery）中得到了呼应：Agent 先读紧凑索引，再读被初筛候选的 preview 卡片，直到用户选定后才加载唯一一份 design.md。其工程动机很实际：34 套模板的完整设计文档体量巨大，全部读取既浪费 token 又会干扰决策；让用户通过“元数据筛选 → 视觉卡片对比 → 最终选定”三段式路径来探索风格，正是“Show, Don't Tell”的体现。

三、selection-index.json：34 套模板的元数据索引解剖

selection-index.json 是整个 Bold Template Pack 的入口数据文件，采用严格的 JSON 结构，顶层包含：

• schema_version: 1 —— 索引格式版本；
• pack_name —— “Beautiful HTML Templates - Bold Design Pack”；
• source_repo —— 源模板仓库标识；
• template_count: 34 —— 模板总数（与仓库内 templates/ 目录下的 34 个子目录一一对应）；
• usage —— 使用指引（selection / previews / final_generation / never 四段说明，与 README 的读取协议一致）；
• frontend_slides_policy —— 本索引声明的舞台政策：layout_model: fixed-stage、canvas_width: 1920、canvas_height: 1080、scaling: scale-stage-to-viewport、移动端行为为“保持 16:9 舞台，用 letterbox/pillarbox 而非重排内容”；
• templates —— 34 个模板对象组成的数组。

每个模板对象都携带一组结构化的“决策元数据”，这是初筛的全部依据：

字段	类型	作用
slug	string	目录名/唯一标识，如 studio、neo-grid-bold
name	string	展示名，如 Studio、Neo-Grid Bold
tagline	string	一句话风格描述，如 Studio 的 “Black canvas with electric-yellow type; high-voltage design studio aesthetic.”
mood	string[]	情绪标签，如 electric, bold, graphic, design-led, high-contrast
tone	string[]	语气标签，如 graphic, loud, modern, intentional
formality	enum	正式度：low / medium-low / medium / medium-high / high
density	enum	信息密度：low / medium / medium-high / high
scheme	enum	明暗色系：light / dark / mixed
best_for	string	推荐使用场景（软信号，非硬性行业过滤器）
avoid_for	string	应回避的场景
preview_md	string	预览卡片相对路径（bold-template-pack/templates/<slug>/preview.md）
design_md	string	设计文档相对路径（bold-template-pack/templates/<slug>/design.md）

初筛策略（来自 README 与 SKILL.md Phase 2 的双重规定）：把用户的目的与情绪和候选模板的 mood/tone/best_for/avoid_for 匹配，把正式度要求对应到 formality，把阅读/演讲模式对应到 density，再结合 scheme 确定明暗基调。best_for 里的行业举例只是“软信号”，不是硬性过滤。例如：

• 需要“董事会级别”庄重感：优先 formality: high 的 Signal（deep navy + muted-gold，avoid_for 明确写了“不宜需要热烈、快速或刻意俏皮的场合”）或 Cartesian（quiet、warm-minimal）；
• 需要杂志封面式的视觉冲击：Bold Poster（density: low，只适合少量大字号陈述）或 Studio（black + electric-yellow）；
• 需要中英双语正式报告：Broadside（自带 bilingual Latin/Chinese type stack）、Grove 或 Monochrome（均标注适用于 bilingual EN/CN reports）。

四、How To Use In Frontend Slides：三选一预览混合与正式度调优

README 规定，在 frontend-slides 的 Phase 2（风格探索）中，默认的**预览混合（preview mix）**必须是：

• 1 个来自 STYLE_PRESETS.md 的安全选项（可读性兜底）；
• 至少 1 个来自本包（Bold Template Pack）的 bold 选项；
• 1 个通配项，它可以是另一个 bold 模板，也可以是 Agent 自生成的自定义设计。

然后根据场合的正式度调整这个默认混合的“语气”（tone）：

• 面向董事会、法务、监管、医疗、投资人更新或高度正式的内部 deck：让安全选项极其克制，从 bold 模板中挑选更冷静、更高正式度的款式（如 Signal、Vellum、Cartesian），通配项应显得权威、具体，而不是仅仅“好看”；
• 面向大胆、编辑感、表达欲强、实验性或高度设计的 deck：安全选项保留为可读的兜底，选定一个强有力的 bold 模板，通配项用来放第二套冒险风格或更贴合用户场合与氛围的自定义设计。

如果通配项是自定义设计，它必须遵守 frontend-slides 的 no-slop 美学（与 SKILL.md 的 Design Aesthetics 一致）：独特的排版、坚定的调色板、可识别的版式系统、与上下文相关的视觉想法、固定的 16:9 舞台行为，并且页面上不得出现 “custom”、“wildcard”、“template”、“preview” 等流程标签。

五、Implementation Contract：design.md 与 preview.md 的角色分工

README 用“Implementation Contract”一节划清了两种文档的职责：

• design.md 是设计系统参考（design-system reference）——把它当作一份“风格配方”（style recipe），而不是可以整段复制的内容；
• preview.md 只是一张轻量级风格卡（style card），用于生成三个标题页候选（title-slide options）。

这意味着读取策略上的不对称：preview.md 只承载 Selection Metadata（slug/tagline/mood/tone/formality/density/scheme/best_for/avoid_for）、Visual Snapshot 和 Preview Ingredients，足够拼出一张 1920×1080 的标题页；而 studio/design.md 则以 frontmatter + 章节形式给出完整的设计令牌（color tokens、typography tokens、spacing、components）、Do's and Don'ts、CJK 处理策略与迭代指南，供最终整幅 deck 使用。

另一个硬性契约是预览真实性（preview authenticity）：预览页必须是用户 deck 的真实标题页，不得把模板名、选项标签、文件名、路径、preview.md、“generated from”或用户需求备注渲染到幻灯片上——模板/风格名称只能出现在给用户的聊天消息里。这一条在 SKILL.md 中被标记为 NON-NEGOTIABLE。

六、最终生成契约：从 viewport-fluid 到固定 1920×1080 舞台

README 对“最终 slides 生成”列出了六项要求，每一条都能在仓库源码中找到对应实现：

1. 保持 frontend-slides 输出为单文件自包含 HTML——对应 html-template.md 中的“Single self-contained HTML file, all CSS/JS inline”；
2. 完整引入 viewport-base.css 的内容——该文件位于 viewport-base.css，固定 .deck-stage 为 1920×1080、.slide 以 visibility/opacity/pointer-events 控制显隐（严禁 display:none 切换），并内置 @media print 逐页打印与 prefers-reduced-motion 支持；
3. 每副 deck 一律生成固定 1920×1080 舞台，并整体等比缩放至视口——即使源模板原本是 viewport-fluid 也照此处理；
4. 把源 design.md 中的 vw、vh、clamp() 值视为“设计比例”，翻译成 1920×1080 舞台坐标，而不是在最终 deck 中保留实时视口重排规则；
5. 保留所选模板的字体、调色板、装饰词汇、间距节奏与组件语法；
6. 以用户真实内容为第一优先级，模板风格只塑造呈现方式，不覆盖信息或结构。

固定舞台的底层实现可以在仓库根目录的 deck-stage.js 中看到：它定义 <deck-stage> Web Component，默认设计尺寸 DESIGN_W_DEFAULT = 1920、DESIGN_H_DEFAULT = 1080，通过 _fit() 计算 scale = min(innerWidth/1920, innerHeight/1080) 后对整块 canvas 施加 transform: scale(s)，从而实现整体等比缩放、letterbox 留边；noscale 属性供 PPTX 导出器以 1:1 几何尺寸抓取 DOM；同时内置键盘导航（←/→、PgUp/PgDn、Space、Home/End、数字键跳页）、触屏三分区点按、slidechange CustomEvent 广播与打印分页支持。

值得注意的是，源模板（如 Studio）的 design.md 会声明“viewport-fluid”历史行为（canvas: 100vw × 100vh），但其自带的 Frontend Slides Fixed-Stage Policy 明确写道：该政策优先级高于源模板任何响应式行为，后文若出现 viewport-fluid 描述只能当作源历史（source history），而不是 frontend-slides 的目标生成模型。这正是 README 中“fixed 1920×1080 stage scaled uniformly”与“Treat vw/vh/clamp() values as design proportions”两句话的出处。

七、案例解剖：Studio 模板的 design.md 与 preview.md

以 Studio（bold-template-pack/templates/studio/）为例，可以完整看到 design.md 的结构与 preview.md 的轻量定位。

preview.md（studio/preview.md）只有四部分：文件说明（指明正式设计文档路径）、Selection Metadata（slug/tagline/mood/tone/formality/density/scheme/best_for/avoid_for）、Visual Snapshot（一段风格速写）、Preview Ingredients（调色板、字体与 5 条 signature move）。它足够让 Agent 在 1920×1080 固定舞台下拼出一张真实标题页，且不会透露任何流程标签。

design.md（studio/design.md）则是完整的“设计系统配方”，其结构可归纳为：

• frontmatter 令牌区：colors（near-black #1C1C1C、acid-yellow #F5D200 及 opacity 派生色）、color-aliases（c-bg/c-fg/c-accent 等）、typography（display 12vw/900/uppercase 到 label 0.72vw mono）、spacing（pad-x 5vw、pad-y 5vh、gap 体系）、canvas、components（chrome-bar、cover-meta、stat-card、bullet-marker、chart 等）；
• Frontend Slides Fixed-Stage Policy：声明最终 deck 必须固定 1920×1080、整体缩放、可 letterbox/pillarbox 但不得重排；
• Overview / Key Characteristics：type-as-graphic-mass 理念、二元调色板（near-black ↔ acid-yellow）、双字体职责分离（Barlow 900 承载一切标题，IBM Plex Mono 只承载元数据）、扁平无阴影无圆角；
• Colors / Typography / Layout / Depth and Elevation / Shapes and Treatment：含完整的类型尺度表、间距令牌表、border 权重规范（1px hairline 与 2px anchor rule）与装饰元素清单；
• Do's and Don'ts：10 条 Do、10 条 Don't，例如“display 只用 weight 900”“不得引入第三种颜色”“不得使用圆角/阴影/渐变”“单调内容占比勿超过约 60%”；
• Responsive Behavior / Presenter Behavior / Print Behavior：源模板的历史行为与动画节奏（0.5s 动画 vs Signal 的 0.65s，即“agency urgency, not editorial grace”）；
• CJK & International Content：中文配对表（Barlow 900 换 Noto Serif SC 700，采用“整行替换字体”的 Strategy A）、行高/字距/全角标点/pangu spacing 等规则，以及已知缺口说明；
• Iteration Guide / Known Gaps：新增 slide 的 10 条迭代清单与已知局限（字体 CDN 依赖、小视口下 5vw 内边距的边界、图片占位符替换方式等）。

从这套结构可以推断：design.md 是可执行的样式规范而非成品代码，Agent 需要把它转译进固定舞台并逐项落实；preview.md 则只服务于风格探索阶段的“轻决策”。

八、质量验证：文本溢出与面板重叠的双重检查

README 最后一条契约给出了一个反直觉但非常关键的验证要点：

Verify rendered output for both text overflow and panel overlap. A card can pass scrollHeight checks while still being covered by another grid panel.

即：单凭 scrollHeight 检测文本溢出是不够的——一张卡片可能没有文本溢出，却仍被另一个 grid 面板视觉覆盖（例如绝对定位的面板叠压）。因此最终生成后必须对渲染截图同时检查两类问题。这与 SKILL.md 的固定舞台规则与 Mode C 修改规则一致（“After ANY modification, verify: the slide stage remains 16:9, no text overflows its card, no panels overlap, and screenshots look correct at 1280×720 plus one phone viewport”），也与 deck-stage.js 为每张 slide 自动写入的 data-om-validate="no_overflowing_text,no_overlapping_text,slide_sized_text" 验证属性一一对应。

九、与主技能流程的衔接：Phase 2 与 Phase 3 中的 Bold Pack

Bold Template Pack 不是孤立的文件目录，而是 frontend-slides 主流程（SKILL.md）的一个可插拔资源层：

• Phase 2（风格探索）：SKILL.md 规定“如果 bold-template-pack/selection-index.json 存在，就读这个紧凑索引，但此时不读任何 design.md”；预览混合规则、bold 模板选择规则、自定义通配项规则与 preview 真实性规则均在此阶段生效，生成的三个候选标题页保存到 .frontend-slides/slide-previews/；
• Phase 3（生成整幅演示）：如果用户选定的是 bold 模板，读取恰好那一份 design.md，并同时读取 html-template.md、viewport-base.css 与 animation-patterns.md 作为支撑文件；template.html 仅在所选 design.md 缺失关键实现细节时才作为最后手段；
• Phase 5/6（交付与分享）：交付后可选用 scripts/deploy.sh 部署到 Vercel 或 scripts/export-pdf.sh 导出 PDF，Bold Pack 生成的固定 1920×1080 舞台天然兼容导出脚本按 .slide 元素逐页截图的机制。

十、实践要点速查

• 筛选永远从 selection-index.json 开始，用 mood/tone/formality/density/scheme 四组字段压缩候选，best_for/avoid_for 仅作软参考；
• 一次只读一份 design.md（用户选定后），一次只读若干份 preview.md（初筛后），禁止批量读设计文档；
• 预览混合固定为 3 选：1 安全预设 + ≥1 bold 模板 + 1 通配项，并按正式度调整语气；
• 最终 deck 一律固定 1920×1080：把 vw/vh/clamp() 当作比例换算进舞台坐标，整体 transform: scale() 适配视口，letterbox/pillarbox 但不重排内容；
• 完整内联 viewport-base.css，幻灯切换用 .active/.visible + visibility/opacity/pointer-events；
• 预览页必须像真实首屏：任何模板名、slug、路径、流程标签不得上屏；
• 生成后双重验证：既查文本溢出（含 scrollHeight），也查面板相互覆盖；截图像素建议覆盖 1280×720 与手机视口。