frontend-slides 模板预览卡实战指南：读懂 BlockFrame 的 preview.md 并生成 neobrutalist 标题页-平芜编程栈

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技能仓库中的 BlockFrame 预览卡为研究对象，完整讲解这份"轻量风格卡片"在标题页预览阶段的作用、元数据字段、八色高饱和粉彩色板、签名视觉动作与 CJK 适配规则，并结合 design.md、selection-index.json、deck-stage.js 等源码文件说明其背后的固定 1920×1080 舞台模型。读完本文，你将理解 frontend-slides 的"渐进式披露"模板选择流程，并掌握如何仅凭一份 preview.md 生成一张真实、合规、可复用的 BlockFrame 标题页预览。

一、preview.md 在 frontend-slides 工作流中的角色

BlockFrame 是bold-template-pack（Bold 设计模板包）中 34 个模板之一。模板包的设计目标是：把外部beautiful-html-templates设计系统引入frontend-slides技能，同时不让它们成为每场演示的默认风格（见 bold-template-pack/README.md）。为此，每个模板被拆成两份文档：

文档	用途	阅读时机
preview.md	轻量风格卡片，只用于生成标题页预览	短名单筛选后、用户最终选择前
design.md	完整设计系统规范（recipe）	用户选定该模板后、生成整副 Deck 前

preview.md 开头第一行就写明了自己的定位："Use this small file for title-slide previews only. For final deck generation, read the full design doc listed below."—— 这份小文件只为标题页预览服务，最终成稿必须回到完整设计文档。

这种两级拆分对应 SKILL.md 的渐进式披露原则（Progressive Disclosure）：先读轻量索引（selection-index）与轻量预览卡，把完整 design.md 留到用户做出选择之后，避免在候选阶段读取大量模板规范。同一原则也体现在 selection-index.json 的usage字段中（selection-index.json）：

"usage": { "selection": "Read this compact index first to shortlist bold templates from metadata.", "previews": "For title-slide previews, read only the preview_md files for the shortlisted bold candidates.", "final_generation": "After the user chooses a bold template, read exactly that template design_md before generating the full deck.", "never": "Do not bulk-read templates/*/design.md and do not read template.html unless the selected design.md is missing a critical implementation detail." }

从短名单到成稿的三级阅读链路

结合 SKILL.md 的 Phase 2 / Phase 3 与 bold-template-pack/README.md 的 "What To Read"，完整的阅读流程是：

先读bold-template-pack/selection-index.json，仅依据元数据（mood、tone、best_for、avoid_for、formality、density、scheme）圈定候选模板；
对进入短名单的模板，只读对应候选的preview.md来生成 3 个标题页风格预览（1 个安全预设 + 至少 1 个 Bold 模板 + 1 个 wildcard）；
用户最终选定 BlockFrame 后，才读取且仅读取 block-frame/design.md，据此生成整副 Deck；
不批量读取其它模板的design.md，也不读取template.html（除非所选 design.md 缺失关键实现细节）。

二、Selection Metadata：用元数据做短名单决策

preview.md 的## Selection Metadata一节提供了 BlockFrame 在候选阶段所需的全部决策字段，与 selection-index.json 中"slug": "block-frame"的条目一一对应：

字段	值	决策含义
Slug	`block-frame`	模板唯一标识，也是预览卡/设计卡的文件目录名
Tagline	Neobrutalist deck with pastel-neon color blocks and chunky black borders	一句话风格定位
Mood	bold, playful, graphic, fresh	情感气质关键词，用于对应用户的语气诉求
Tone	confident, graphic, pop, design-led	语言与视觉调性
Formality	medium-low	正式度中低
Density	high	内容密度高（对应 SKILL.md 的 reading-first 风格）
Scheme	light	浅色系方案
Best for	需要 pop-graphic、design-led 感的场合：indie SaaS 发布、代理机构资质展示、创意评审、品牌改版；也适合希望呈现"自信、当代"而非"刻板正式"的科技、金融、研究类演讲	推荐使用场景
Avoid for	需要安静克制或传统分量感的场合（监管披露、正式法律文书）	应回避场景

这套元数据是 Phase 2 "show, don't tell" 的基础：Agent 在不生成任何视觉的情况下，先用结构化字段把模板与用户的目标场合、受众、正式度、密度、明暗偏好对齐（参考 SKILL.md 的 "Bold template selection rules"）。注意best_for只是软信号而非行业硬性过滤——BlockFrame 被明确标注为"科技/金融/研究演讲的意外之选"，说明它允许跨场景使用。

三、Visual Snapshot：五条结构法则与整体气质

preview.md 的## Visual Snapshot用两段文字定义了 BlockFrame 的视觉身份，这两段与 design.md 的## Overview完全一致：

BlockFrame is amaximalist neobrutalist presentation systembuilt on five structural laws: every region has a 4px black border, every elevated element has an 8px hard offset shadow, every corner is square, every accent color is a saturated pastel, and every layout is allowed to be a little bit crooked.

五条结构法则（Five Structural Laws）是整个系统的"宪法"：

每个区域都有 4px 黑色描边（4px solid black border）；
每个被抬升的元素都有 8px 硬偏移阴影（8px hard offset shadow）；
每个角都是方角（every corner is square）；
每个强调色都是高饱和粉彩（every accent color is a saturated pastel）；
每个版式都允许"有点歪"（every layout is allowed to be a little bit crooked）。

系统的"乐趣"恰恰来自这些法则的刻意碰撞：带边框的卡片叠在带边框的卡片上、阴影与阴影堆叠、倾斜的装饰物故意刺破网格。preview.md 的视觉快照还给出风格出处——zine 排版、90 年代复兴贴纸书、当代玩具包装，"大胆、欢乐、略显混乱、绝不胆怯"。

这条视觉快照对预览生成有直接约束：预览页必须同时保留"调色板、字体角色、表面节奏（surface rhythm）、装饰词汇（decorative vocabulary）"四个维度，缺一不可（见本文第六节）。

四、Preview Ingredients：预览卡可直接复用的设计资产

preview.md 的## Preview Ingredients一节列出了生成标题页预览所需的最小编码资产。这一节是"可直接取用"的清单，也是与 design.md 的 token 体系衔接的入口。

4.1 调色板：八色锁定

preview.md 给出了完整八色列表，与 design.md 的colors区块一致：

色名	Hex	角色（依据 design.md Colors / Defaults）
black	`#000000`	结构色：所有描边、主要文字、所有阴影；对比锚点
white	`#FFFFFF`	默认卡片填充、label-pill 与导航按钮底色
offwhite	`#FFFDF5`	暖画布色：默认页面/幻灯片背景
pink	`#FE90E8`	高键糖果洋红：五个粉彩中最饱和
blue	`#C0F7FE`	淡冰蓝：intro 与 stats 表面的"底色"
green	`#99E885`	亮春绿：全表面底色、stripe-block 条纹、图表系列
yellow	`#F7CB46`	CTA 色：按钮、close-frame 阴影、list-number、feature-deco
cream	`#FFDC8B`	暖黄奶油：team/cover 表面、第三图表系列

design.md 强调：粉彩是可互换的角色，不承载固定语义（green 不是"成功"，调色板里根本没有红色）。预览页应遵循默认节奏——封面可用 offwhite/cream 做地面，并让 pastel 以"整面填充"而非"轻量点缀"的方式出现。

4.2 字体角色：Inter 显示声部 + Space Grotesk 标签声部

preview.md 的 Typography 一行写的是 "See full design doc after selection"——具体字阶要回到 design.md。完整的双字体系统（design.md）：

Inter（400–900）：显示/正文/数字声部。headline 用 800–900 字重大写 + 负字距（-0.02 ~ -0.03em）；正文用 500 字重句首大写式（sentence case）；卡片标题用 700 字重大写。
Space Grotesk（400–700）：标签/铬（chrome）声部。label-pill 用 600 字重、13px、0.08em 字距、大写；counter/mono-tag 用 600–700 字重、大写、0.05–0.1em 宽字距。它并非真等宽字体，但几何感 + 宽字距让它读起来像系统的"代码"声部。

design.md 的Typography Scale给出完整 token 表，预览页最常用的是：heading-xl（48–96px，Inter 900，-0.03em，大写）、heading-lg（32–64px，Inter 800）、label（13px，Space Grotesk 600，0.08em 大写）。系统禁止引入第三种字体——Inter + Space Grotesk 就是整个字库。

4.3 签名动作（Signature Moves）

preview.md 明确列出五条签名动作，它们是"非可选"的：

主卡片 4px 纯黑描边，次级铬件 3px——绝不允许更细；
主卡片 8px 硬偏移阴影，次级铬件 4px——纯黑、零模糊；
五粉彩（粉/蓝/绿/黄/奶油）+ 黑 + 白 + 米白，跨表面循环使用；
Inter 800–900 大写负字距是显示声部；Space Grotesk 600 大写 0.08em 字距是标签声部；
处处方角，唯一例外是 stat 卡片上的单个圆形强调点（stat-deco-dot）。

这五条在 design.md 中被落实为borders、shadows、components等 token：

# design.md 中的关键 token（节选） borders: primary: "4px solid {colors.black}" thin: "3px solid {colors.black}" shadows: default: "8px 8px 0px {colors.black}" small: "4px 4px 0px {colors.black}" hover: "6px 6px 0px {colors.black}" close-yellow: "12px 12px 0px {colors.yellow}" close-white: "6px 6px 0px {colors.white}"

design.md 特别强调"描边重量与阴影尺寸强耦合"：4px 描边配 8px 阴影，3px 描边配 4px 阴影；阴影永远是纯黑、零模糊、右下偏移。唯一例外出现在深色收尾面（close-frame）：12px 黄色偏移阴影是全系统唯一的有色阴影，6px 白色阴影用于黑色地面上的 close-btn（见 design.md）。

五、International / CJK Preview Note：中文预览的适配

preview.md 的 CJK 一节非常克制但关键：

If the preview uses Chinese or other CJK text, keep CJK letter-spacing at 0, loosen line-height, and avoid uppercase transforms on CJK runs.
Use the fulldesign.mdCJK section after selection for exact font pairings and script-specific adjustments.

也就是说，预览阶段只需遵守三条硬规则：CJK 字距归零、行高放宽、不做大写变换。具体字体配对与逐项调整在 design.md 的 CJK 章节，要点包括：

推荐中文配对：用思源黑体 Noto Sans SC 替换拉丁字体栈——显示/标题/数字用 900 字重（句首大写式、零字距），卡片标题 700，正文 400–500，标签/计数用 600（不做变换、不加字距）。思源黑体自带与中文字形协调的拉丁字形，混合句可用单一字体族（Strategy A）。
加载方式（design.md 给出的<head>片段）：

<link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@400;500;600;700;900&display=swap" rel="stylesheet">

通用调整：行高增加约 15–25%（正文 1.75–1.85、显示 1.15–1.25）；每个 CJK 语段字距设 0；对中文禁用text-transform: uppercase（CJK 没有大小写）；使用全角中文标点（，。：；！？「」（））；显示级标题结尾不加句号；中英混排用"盘古之白"（BlockFrame 设计系统而非BlockFrame设计系统）；一个句子只用一个字体族，避免浏览器中途切换到 Inter/Space Grotesk。
已知缺口（design.md Known Gaps）：没有 CDN 中文等宽字体来承担 Space Grotesk 的"系统读出声部"，且"大写粗黑"的粗野主义标识在 CJK 中不可复制。因此中文环境下应更依赖结构性元素（倾斜矩形、星爆、条纹块、更多粉彩地面轮换）来补偿。preview.md 的 CJK Note 正是这条策略在预览阶段的落点。

六、Preview Rules：把预览卡变成一张"真标题页"

preview.md 的## Preview Rules是生成预览时的行为契约，共 11 条，可归为四组：

6.1 生成目标（1 条）

Build exactly one title slide at 1920x1080 inside the fixed-stage model.在固定舞台模型中只构建一张1920×1080 的标题页。

6.2 风格保真（2 条）

保留上面定义的调色板、字体角色、表面节奏与装饰词汇；
使用用户的真实标题/副标题/上下文，不得复制演示内容。

6.3 内部文案禁令（3 条，最容易被违反）

页面上禁止出现任何内部工作流文字：preview、generated from、preview.md、template、preset、style option、Option A/B/C、文件名、路径、源文档标签；
禁止在幻灯片上出现模板名或 slug（如 BlockFrame、block-frame），只允许在聊天消息中提及；
禁止把需求备注（desired vibe、audience、内部用途标签）放到幻灯片上，除非用户明确要求这些词出现在 Deck 里。

6.4 可见铬件来源（1 条）

可见的 chrome 只能用真实 Deck 内容：Deck 标题、真实章节标题、日期、作者、公司、页码，或来自用户材料的真实短语。

6.5 信息边界与后续动作（4 条）

生成预览时不读取template.html；
不读取其它模板的design.md；
用户选定本模板后，先读取完整 design.md再生成最终幻灯片。

这组规则与 SKILL.md 的 "Preview authenticity rules (NON-NEGOTIABLE)" 以及 bold-template-pack/README.md 的 "Implementation Contract" 相互印证：预览必须看起来像用户 Deck 的真实第一页，而不是模板选择卡。

七、固定舞台模型：预览页的 1920×1080 落地

preview.md 反复强调的 "fixed-stage model" 不是空话。它对应 frontend-slides 的核心不变式（SKILL.md "Fixed Stage Rules"）与模板包的政策声明：

selection-index.json 的frontend_slides_policy字段写明：canvas_width: 1920、canvas_height: 1080、scaling: scale-stage-to-viewport、mobile_behavior: preserve 16:9 stage; letterbox or pillarbox instead of reflowing slide content；
design.md 的 Fixed-Stage Policy 明确：即使源模板原本使用100vw/100vh/clamp()等视口流式 CSS，生成时也要把那些值当作设计比例翻译成 1920×1080 舞台坐标，而不是保留为响应式规则；并建议使用deck-stage.js或等价的行内缩放器。

预览页与最终 Deck 一样，应基于强制基类 viewport-base.css 构建：.deck-viewport撑满窗口，.deck-stage是固定 1920×1080 的画布（viewport-base.css），.slide以visibility/opacity/pointer-events控制显隐（viewport-base.css），并保留@media print每页一屏的导出能力（viewport-base.css）。

deck-stage.js提供了一个可复用的<deck-stage>Web Component（deck-stage.js）。其默认设计尺寸就是 1920×1080（DESIGN_W_DEFAULT/DESIGN_H_DEFAULT，见 deck-stage.js），_fit()用Math.min(vw/designWidth, vh/designHeight)计算整体缩放并套用transform: scale(s)（deck-stage.js）；noscale属性则让 PPTX 导出器能按作者尺寸渲染。这正对应 design.md 中"整个舞台一个 transform 缩放，先验证文字溢出再验证面板重叠"的要求。

八、从预览卡到完整 Deck：实现契约与验证

当用户从三个预览中选定 BlockFrame 后，Agent 才进入最终生成阶段。此时行为契约切换为 bold-template-pack/README.md 的 "Implementation Contract"：

design.md 是设计系统参考，当作风格配方（style recipe）而非要复制的文案；preview.md 只是标题页的三选一风格卡；
输出保持为单个自包含 HTML 文件，包含viewport-base.css的完整内容；
每副 Deck 都是固定 1920×1080 舞台、整体缩放，即使源模板原本是视口流式的；
保留所选模板的字体、调色板、装饰词汇、间距节奏与组件语法；
用户实际内容优先——模板风格塑造呈现方式，不覆盖信息与结构；
生成后同时验证文字溢出与面板重叠：卡片可能通过scrollHeight检查却仍被另一网格面板遮挡。

design.md 的 token 体系（colors、borders、shadows、typography、spacing、components、canvas）就是实现这份契约的"零件库"。例如，把设计 token 映射成 CSS 变量后，一个符合规范的预览/内容卡片可以这样组织（以下为基于 design.md 公开 token 构造的示意，并非模板源码）：

:root { --ink: #000000; --paper: #FFFFFF; --canvas: #FFFDF5; --pink: #FE90E8; --blue: #C0F7FE; --green: #99E885; --yellow: #F7CB46; --cream: #FFDC8B; --border-primary: 4px solid var(--ink); --border-thin: 3px solid var(--ink); --shadow-default: 8px 8px 0 var(--ink); --shadow-small: 4px 4px 0 var(--ink); } .label-pill { border: var(--border-thin); padding: 6px 16px; background: var(--paper); box-shadow: var(--shadow-small); font-family: 'Space Grotesk', monospace; font-size: 13px; font-weight: 600; letter-spacing: 0.08em; text-transform: uppercase; } .card-elevated { border: var(--border-primary); background: var(--paper); box-shadow: var(--shadow-default); }

标题字号默认取heading-lg（32–64px，Inter 800，大写、-0.02em），封面/英雄页才上heading-xl（48–96px，Inter 900，-0.03em）——这是 design.md 给出的选择原则。若新增大段 CJK 内容，则套用第五节的中文字体与字距规则。

九、常见误用与检查清单

结合 preview.md、design.md 的 Do's and Don'ts 与已知缺口，生成 BlockFrame 预览（以及后续整副 Deck）时建议逐项自检：

检查项	判定标准
舞台尺寸	固定 1920×1080，整体缩放，允许 letterbox/pillarbox，不重新排版
描边与阴影耦合	4px 描边配 8px 阴影，3px 描边配 4px 阴影；纯黑、零模糊
圆角纪律	除 stat-deco dot（12px 圆点）外全部 0px 圆角
字体纪律	Inter 显示一律大写 + 负字距 800–900；Space Grotesk 一律大写 + 0.05–0.1em 字距
色板锁定	只用八色；不新增第六种粉彩（紫/橙/红直接破坏糖果色板）
表面节奏	每张幻灯片轮换 pastel 地面；每个区域以 label-pill 眉题开头
装饰度	每个表面至少一个装饰元素（倾斜矩形、星爆、条纹块、点阵、角括号）
内部文案	页面上无 preview/template/slug/路径/选项标签等字样
CJK 内容	字距 0、行高放宽、无大写变换、中文配对字体
验证	截图检查文字溢出与面板重叠，`scrollHeight`通过不代表不被遮挡

值得注意的另一个"已知缺口"：design.md 声明 Inter 与 Space Grotesk 依赖 Google Fonts 内联@import，无系统字体回退；若字体加载失败，系统会退化为默认字体并失去风格身份。此外，悬停/按下交互假设存在指点设备，:nth-child(odd/even)硬编码了 stat 卡片 ±2deg 倾斜方向，以及 10 点星爆依赖clip-path支持——这些限制在生成与排障时应心中有数。

总之，block-frame/preview.md是一份"小而全"的预览协议：它用元数据帮你决策、用快照与清单帮你锁定视觉资产、用 CJK Note 帮你跨语言保真、用 Preview Rules 帮你守住真实性底线。理解它，就理解了整个 frontend-slides 模板选择与标题页预览机制的运行方式。