Frontend Slides 的 Bold Template Pack 深入指南：渐进式模板读取协议、三选预览混搭与固定 1920×1080 舞台实现契约-平芜编程栈

AI 技能
AI 插件
前端

【免费下载链接】frontend-slides

Create beautiful slides on the web using a coding agent's frontend skills

项目地址：https://gitcode.com/gh_mirrors/fr/frontend-slides

本篇技术指南以 Frontend Slides 仓库中的 bold-template-pack/README.md 为骨架，系统讲解 Bold Template Pack 是如何在不接管"安全预设默认地位"的前提下，把 34 套来自beautiful-html-templates的设计前卫模板注入技能工作流的。读完你将会掌握：agent 侧严格的渐进式文件读取协议（索引 → 预览卡 → 设计文档）、风格发现阶段"1 安全预设 + 至少 1 个 bold 模板 + 1 个 wildcard"的混搭策略、按场合调整基调的判断方法，以及生成最终 deck 时必须遵守的固定舞台实现契约。

Bold Template Pack 是什么：设计体系进技能，但不抢默认地位

frontend-slides是一个面向编码 agent 的演示文稿技能（skill），默认的安全预设集合存放在 STYLE_PRESETS.md 中。而bold-template-pack/目录则是一套可选的、设计前卫的模板包，它把beautiful-html-templates的设计体系移植进来，前提是不让它们成为每次生成 deck 时的默认选项。

这句话是整个包的定位核心：安全预设仍是回退基准，bold 模板是被"渐进式加载"的增强资源——技能先给出轻量索引，用户选中后才加载完整设计文档。这样既避免了每份 deck 都走向同质化，也避免 agent 盲目加载大量无关文件浪费上下文。

从仓库结构看，包内主要包含三类文件：

bold-template-pack/selection-index.json——紧凑的模板元数据索引，34 个模板的筛选入口；
bold-template-pack/templates/<slug>/preview.md——每个模板的轻量"风格卡"，只用于生成标题页预览；
bold-template-pack/templates/<slug>/design.md——被选中模板的完整设计体系文档。

渐进式读取协议：先读索引，再读预览，最后才读设计文档

bold-template-pack/README.md的 "What To Read" 部分给出了 agent 必须严格遵守的六步读取顺序：

先读selection-index.json：这是整个包的唯一入口，任何候选筛选都基于它。
仅凭元数据筛选候选人：只用mood、tone、best_for、avoid_for、formality、density、scheme这七个字段做初筛，不读任何模板文件。
标题页预览只读preview.md：对于筛出的候选人，只读取其对应的preview.md。
用户选定某个 bold 模板后，只读那一个模板的完整design.md。
绝不批量读取包内所有design.md。
除非选中的design.md缺失关键实现细节，否则不读取源模板库中的template.html。

README 还特别强调：完整的源元数据索引不会打进面向用户的技能包中，正常生成流程只能使用selection-index.json。这与 SKILL.md 中的核心原则"渐进式披露（Progressive Disclosure）"完全一致——主SKILL.md是一张工作流地图，支撑文件仅在需要时才按需加载。

这套协议的价值在于上下文效率与决策质量的双重控制：34 个design.md全部读完会消耗海量 token 且淹没注意力，而先看 7 个结构化元数据字段 + 一张预览卡，足以让 agent 和用户一起快速锁定视觉方向。

selection-index.json 数据模型：候选筛选的字段字典

selection-index.json 的结构分为索引级配置与模板条目两层。索引级配置包括：

schema_version: 1、pack_name、source_repo（指向源模板库）、template_count: 34；
usage字段，把 README 的读取协议机器可读化：selection（先读索引）、previews（只读候选的 preview_md）、final_generation（选定后读该模板 design_md）、never（禁止批量读 design.md / 除非设计文档缺关键细节否则不读 template.html）；
frontend_slides_policy，明确固定舞台策略：layout_model: fixed-stage、canvas_width: 1920、canvas_height: 1080、scaling: scale-stage-to-viewport、mobile_behavior为保持 16:9、宁可 letterbox/pillarbox 也不重排内容。

每个模板条目以slug为唯一标识（如neo-grid-bold、broadside、signal、vellum），并携带 README 提到的七个筛选字段：

字段	含义与取值
`name`/`tagline`	模板显示名与一句话概括，用于对话中向用户描述
`mood`	情绪关键词数组，如`editorial`、`playful`、`retro-tech`、`institutional`
`tone`	语气关键词数组，如`graphic`、`punchy`、`literary`、`sober`
`formality`	正式程度：`low`/`medium-low`/`medium`/`medium-high`/`high`
`density`	信息密度：`low`/`medium`/`medium-high`/`high`
`scheme`	色彩方案：`light`/`dark`/`mixed`
`best_for`	推荐场景的散文式描述，作为"软信号"而非行业硬约束
`avoid_for`	明确不合适的场景，用于反向排除
`preview_md`/`design_md`	指向该模板 preview.md 与 design.md 的相对路径

以 bold-template-pack/templates/neo-grid-bold/design.md 对应的索引条目为例：scheme: light、density: high、formality: medium，best_for提到"设计主导的提案、品牌工作、创始人演讲、大会主题演讲，尤其适合数据密集页、对比页与流程页"。这类描述既可以帮助 agent 做场合匹配，也明确给出了排除边界。

三种文件的职责分工：索引筛选、预览卡呈现、设计文档落地

包内三类文档并不是同一信息的三种冗余副本，而是职责各异的三个层次：

selection-index.json：纯元数据，用于"筛选"——agent 据此把 34 个模板缩小到 2～3 个候选人。
preview.md：轻量"风格卡"，用于"呈现"——只够生成一张真实标题页预览。以 bold-template-pack/templates/broadside/preview.md 为例，它包含筛选元数据、视觉快照（"Massive Barlow display type at weight 900 in lowercase"）、预览配料（调色板、字体、签名动作），以及一份"预览规则"清单。
design.md：完整"设计体系参考"，用于"落地"——只有用户真正选定后才会被读取，作为生成整套 deck 的样式配方。

preview.md 中的 "Preview Rules" 部分是一组不可妥协的约束：只能构建一张 1920×1080 的标题页、保留调色板与字型角色、使用用户真实的标题/副标题/上下文（不得复制演示内容）、渲染结果必须像一张真实的首页而非模板选择卡。幻灯片上严禁出现preview、generated from、preview.md、template、preset、Option A/B/C、文件名、路径等内部工作流文字，也严禁出现模板名或 slug（只能写在给用户的对话消息里）。

风格发现阶段的预览混搭：1 安全预设 + 至少 1 个 bold + 1 个 wildcard

Bold Template Pack 并非独立工作流，它嵌入在 SKILL.md 的 Phase 2 风格发现阶段。README 明确了默认的"预览混搭"（Preview mix）：

1 个安全选项：来自STYLE_PRESETS.md；
至少 1 个 bold 选项：来自本包；
1 个 wildcard 选项：可以是本包中的另一个 bold 模板，也可以是 agent 自生成的自定义设计。

SKILL.md 对此做了更细的补充：默认生成 3 张预览，当用户明确点名某个预设或模板时，可以将其作为一个槽位，再围绕它补足剩余槽位。如果 bold 模板匹配较弱，可以用 wildcard 槽位做自定义设计，或回退到另一个安全预设，而不是强行套模板。

这套"1 + 1 + 1"结构的意图是让用户在"保守可读""设计前卫"与"第三重对比"之间做视觉反应：安全预设保证有一个不会出错的基线，bold 模板提供强设计个性，wildcard 则负责拉开对比度或贴合用户的具体场合。

按场合调整混搭基调：正式场与表达场的不同玩法

README 要求 agent 在默认混搭之上按用户场合"调整基调"：

董事会、法务、监管、医疗健康、投资人更新或高度正式的内部 deck：安全选项要做得极度克制，同时选择更安静、更高正式度的 bold 模板；wildcard 应传达"权威且具体"的气质，而不是仅仅装饰。
大胆、编辑式、表达型、实验型或高度设计的 deck：安全选项保留为可读回退，选择一个强势的 bold 模板；wildcard 用于第二个冒险模板，或一个更贴合用户场合与氛围的自定义设计。

从 selection-index.json 的formality字段看，可以给出可落地的对应关系：正式场合优先formality: high的模板，例如signal（深藏蓝画布 + 骨白纸 + 单一哑金点缀）、cartesian（安静暖中性色 + Playfair 衬线）、monochrome（全墨黑白账本风格）、soft-editorial；而表达型场合则可选studio（黑画布 + 电光黄）、broadside（黑画布 + 火焰橙）、peoples-platform（蓝/橙/红三色的海报能量）等formality较低或scheme: dark的选项。

自定义 wildcard 的无 AI 味（No-Slop）美学底线

当 wildcard 采用自定义设计时，README 给出了硬性要求，必须遵守 Frontend Slides 的无 AI 味美学：

有辨识度的字体（distinctive typography）；
一套承诺一致的调色板（a committed palette）；
可识别的布局系统（a recognizable layout system）；
与具体语境相关的视觉创意（a context-specific visual idea）；
固定 16:9 舞台行为（fixed 16:9 stage behavior）；
幻灯片上不得出现 "custom"、"wildcard"、"template"、"preview" 等可见的过程标签。

SKILL.md 对此的进一步解释是：自定义设计要有明确的视觉论点（visual thesis），并且必须可扩展为整套 deck——预览暗示的设计系统要能铺开到章节页、内容页、引用页、对比页和结束页，而不是只有一张好看的首屏。同样地，STYLE_PRESETS.md中的 "DO NOT USE" 清单点明了需要回避的通用 AI 产物：Inter/Roboto/Arial 等泛用字体、#6366f1式通用靛蓝、白底紫色渐变、千篇一律的居中 hero 与卡片网格。

实现契约：design.md 是样式配方，不是可复制的内容

README 的 "Implementation Contract" 是整套约定中最关键的部分，它定义了三种文件的语义边界与最终输出约束。

文件语义：design.md是设计体系参考（design-system reference），必须被当作"样式配方（style recipe）"而非"要复制的内容"；preview.md只是用于生成三个标题页选项的轻量风格卡。

预览即真实：预览幻灯片必须是用户 deck 的真实标题页，不得在页面上渲染模板名、选项标签、文件名、路径、preview.md、"generated from" 或用户需求备注。

最终 deck 的生成规则：

保持单一自包含 HTML 文件——所有 CSS/JS 内联，零依赖；
完整包含viewport-base.css的全部内容；
每张 deck 都生成固定 1920×1080 舞台，并按比例统一缩放到视口——即便源模板原本是视口流式（viewport-fluid）布局也适用；
将源design.md中的vw、vh、clamp()值视为设计比例，翻译成固定 1920×1080 舞台坐标，而不是保留为实时响应式规则；
保留所选模板的字体、调色板、装饰词汇、间距节奏与组件语法；
用户的实际内容优先——模板风格塑造呈现方式，但不得覆盖信息与结构；
同时校验文本溢出与面板重叠——卡片可能通过scrollHeight检查却仍被另一块网格面板遮挡。

这些规则并非空谈，而是与仓库中的实现文件一一对应。例如 SKILL.md 的 Fixed Stage Rules 明令"读取viewport-base.css并把其完整内容加入每份演示"，并禁止用display: none/block切换幻灯片（要用visibility/opacity/pointer-events），还提示 CSS 函数取负必须写成calc(-1 * clamp(...))（浏览器会静默忽略-clamp(...)）。

固定舞台的底层机制：viewport-base.css 与 deck-stage.js

固定 1920×1080 舞台由两个文件共同保证。

viewport-base.css 定义了强制的基础结构：html, body锁定视口并overflow: hidden；.deck-viewport作为全窗口容器；.deck-stage是 1920×1080 的设计画布，transform-origin: 0 0交给 JS 做translate(...) scale(...)；.slide绝对定位堆叠在固定舞台内，visibility: hidden; opacity: 0; pointer-events: none，只有.active/.visible的幻灯片才可见；@media print下每个 slide 以break-after: page按页输出，正好支撑 README/仓库所述的"浏览器打印即得一页一页的 PDF"；末尾还包含prefers-reduced-motion支持。

bold-template-pack/deck-stage.js 则是<deck-stage>自定义元素，负责把 1920×1080 画布统一缩放到视口：_fit()中const s = Math.min(vw / designWidth, vh / designHeight)计算缩放比后对整个画布施加一个transform: scale(s)，任何屏幕上都保持 16:9（允许 letterbox/pillarbox，不重排内容）。它还内置键盘导航（←/→、PgUp/PgDn、Space、Home/End、数字键、R 重置）、移动端三段式点击区、演讲者备注 postMessage、slidechangeCustomEvent 以及打印规则注入。值得注意的是，noscale属性让 PPTX 导出器能以 1:1 作者尺寸做 DOM 捕获——这正是模板 design.md 与 README 反复强调"固定舞台、整体缩放、不做响应式重排"的工程落地。

以 Neo-Grid Bold 为例：一份 design.md 长什么样

为说明design.md的内容密度，可以看 bold-template-pack/templates/neo-grid-bold/design.md。它以 YAML front matter 承载结构化设计令牌（colors、typography、spacing、canvas: 1920×1080、components），随后是散文式设计说明：

网格：每个 slide 都是inset: 40px的 12 列 × 8 行 CSS 网格，单元间距 12px；布局通过grid-column: 4 / span 5; grid-row: 1 / span 5这样的 span 声明完成。
三色面板系统：paper（#F5F4EF）为默认面板、ink（#0A0A0A）为反转块、accent-lemon（#E6FF3D）为信号块；全系统零圆角、零阴影、零渐变（照片占位区除外）。
双字体体系：Space Grotesk 700 全大写负字距承载一切展示文字；JetBrains Mono 大写正字距（0.08–0.12em）承载一切标签、页码、坐标轴。
签名元素：2×2 方块角标/品牌块、<mark>黄色荧光笔强调、<em>黄色变色开关（保持正体）、左下角01 / 12格式页码、yes/part/no 三态对比胶囊。
CJK 中文化指引：中文没有大写概念，展示中文必须用 Noto Sans SC 900 的最重字重来等价传递 Space Grotesk 700 全大写的视觉重量；CJK 字距归零、行高放宽、不做大写变换；<mark>荧光笔机制可直接迁移到中文。