Frontend Slides:让不会设计的人靠看三份真实预览挑出自己审美的零依赖 HTML 幻灯片 skill
zarazhangrui/frontend-slides
zarazhangrui/frontend-slides 是一个 coding-agent skill,MIT,主语言 JavaScript,29,716★ / 2,326 forks,仓库描述一句话:「用 coding agent 的前端能力在网页上做漂亮的幻灯片」。它的设计主张是 README 第一条 Philosophy——你不需要是设计师也能做出好看的东西,你只需要对看到的东西有反应。这句话决定了整套架构:绝大多数 PPT 类 prompt 集合让你先描述风格(「简约」「科技感」「商务」),而 SKILL.md 明确否掉这条路,Phase 2 叫 Style Discovery,原话是「大多数人无法用语言描述自己的设计偏好」,所以默认体验永远是视觉对比——先生成三份单页 HTML 预览自动打开让你挑,还专门写了「不要问用户是否想要选项或预设选择器」。三份预览的配比是硬规则:1 个安全预设(STYLE_PRESETS.md 的 12 个精选,按气质分暗色 Bold Signal / Electric Studio / Creative Voltage / Dark Botanical、亮色 Notebook Tabs / Pastel Geometry / Split Pastel / Vintage Editorial、特化 Neon Cyber / Terminal Green / Swiss Modern / Paper & Ink)+ ≥1 个 bold 模板(bold-template-pack 的 34 套设计系统,来自作者另一个仓库 beautiful-html-templates,每个配三张真实截图)+ 1 个 wildcard(第二个 bold 模板或 agent 自研定制设计,brief 里有比模板更锋利的机会时用这一格)。产物形态是零依赖单 HTML 文件,CSS/JS 全内联,没有 npm、构建工具与框架,理由写得实在:「依赖就是负债,一个 HTML 文件十年后还能打开,2019 年的 React 项目呢」。渐进披露是 token 工程:agent 先只读带 mood / tone / best_for / avoid_for / formality / density / scheme 字段的 selection-index.json,入围后读候选的 preview.md,只有用户最终选定那一个才读它的完整 design.md,并明确「除非缺关键实现细节否则不要读也不要抄 template.html」。它有一条被标成 NON-NEGOTIABLE 的预览真实性规则——每份风格预览必须看起来像用户 deck 的真实第一页而不是诊断卡,页面上不许出现 preview / template / preset / Option A-B-C / 文件名与路径,也不许把「sharp and provocative」这类需求备注当内容渲染。第 5 条核心原则同样 NON-NEGOTIABLE:固定 1920×1080 画布整体等比缩放,手机上也保持 16:9,可以 letterbox 不可以 re-layout;配套约束逐条对应真实 bug(必须内联 viewport-base.css 全文、页面显隐只能用基于 visibility / opacity / pointer-events 的.active /.visible 而禁用 display:none、clamp 只用于舞台之外、不许直接对 CSS 函数取负要写 calc(-1 * clamp(...))、必须带 prefers-reduced-motion)。反 AI slop 那节用第二人称直接对 agent 说话,点名要避开的收敛倾向包括 Inter / Roboto / Arial、白底紫色渐变、可预测布局,最狠一句是「你仍然会跨多次生成收敛到常见选择上(比如 Space Grotesk),避免它」。验收标准很专业:生成后要在浏览器渲染截图里同时验证内容溢出与面板重叠,只查 scrollHeight 不够,因为 grid 面板可能在视觉上互相覆盖。六个 Phase 覆盖新建、PPTX 转换(extract-pptx.py)、增强既有 HTML 三种模式与低密度、高密度两档,产物自带内联编辑(按 E 进编辑、Ctrl+S 保存),Phase 6 给出 deploy.sh(Vercel)与 export-pdf.sh(Playwright,–compact 改按 1280×720 渲染通常减 50–70%)的运维坑位。我们未安装该 plugin、未跑出真实 deck,记为待复现。
我们的判断12 个安全预设 + 34 套 bold 模板 + 一条「三份预览必须像真实第一页」的 NON-NEGOTIABLE 规则,把选风格的主路径从「描述」改成「看」——这是给不会设计的人用的产品决定,不是模板堆料。另外两条值得抄进任何生成式 UI 流程:固定 1920×1080 舞台换排版确定性,以及验收必须看渲染截图查溢出与面板遮挡(只查 scrollHeight 抓不到 z 轴覆盖)。我们未安装跑出成品,记为待复现。
/plugin marketplace add https://github.com/zarazhangrui/frontend-slides 然后 /plugin install frontend-slides@frontend-slides它解决的到底是什么问题
zarazhangrui/frontend-slides 是一个 coding-agent skill，MIT，主语言 JavaScript，29,716 stars / 2,326 forks。它的一句话定位写在仓库描述里：「用 coding agent 的前端能力在网页上做漂亮的幻灯片」。但真正的设计主张是它给不会设计的人用的——README 第一条 Philosophy 就是「你不需要是设计师也能做出好看的东西，你只需要对看到的东西有反应」。
这句话决定了整套架构。绝大多数 PPT 类 prompt 集合的做法是让你先描述风格（「简约」「科技感」「商务」），而 SKILL.md 明确否掉了这条路：Phase 2 叫 Style Discovery，原话是「大多数人无法用语言描述自己的设计偏好」，所以默认体验永远是视觉对比——先生成三份单页 HTML 预览，自动打开，让你挑，而不是问你「要不要看看风格选项」。它甚至专门写了「不要问用户是否想要选项或预设选择器」。
产物形态也定了调：零依赖单 HTML 文件，CSS/JS 全内联，没有 npm、没有构建工具、没有框架。Philosophy 第二条给的理由很实在——「依赖就是负债，一个 HTML 文件十年后还能打开，2019 年的 React 项目呢？祝你好运」。
三份预览的配比是被写死的规则
这是它最值得抄走的一处产品设计。预览不是随便生成三个，配比有硬约束：
| 槽位 | 来源 | 作用 |
|---|---|---|
| 1 个安全预设 | STYLE_PRESETS.md 里的 12 个精选预设 | 可读性兜底，保守/高风险场合要「特别克制」 |
| ≥1 个 bold 模板 | bold-template-pack/selection-index.json 里的 34 套设计系统 | 把设计感拉出来，让用户有东西可反应 |
| 1 个 wildcard | 第二个 bold 模板 或 agent 自研的定制设计 | 制造最强对比；brief 里有比模板更锋利的机会时，用这一格自由设计 |
12 个安全预设按气质分三组：暗色的 Bold Signal（自信高冲击）、Electric Studio（干净专业的分屏）、Creative Voltage（复古现代 + 电光蓝霓虹）、Dark Botanical（优雅暖调）；亮色的 Notebook Tabs（编辑感、纸面配彩色标签页）、Pastel Geometry（亲和、竖排胶囊）、Split Pastel（双色竖分）、Vintage Editorial（机智、几何形）；特化的 Neon Cyber（粒子背景霓虹）、Terminal Green（黑客终端）、Swiss Modern（包豪斯几何）、Paper & Ink（首字下沉、拉引语）。SKILL.md 还给了「情绪 → 建议预设」的对照表：想显得有分量选 Bold Signal / Electric Studio / Dark Botanical，想让人兴奋选 Creative Voltage / Neon Cyber / Split Pastel，想冷静聚焦选 Notebook Tabs / Paper & Ink / Swiss Modern，想打动人选 Dark Botanical / Vintage Editorial / Pastel Geometry。
34 个 bold 模板来自作者的另一个仓库 beautiful-html-templates，README 给每个模板配了三张真实截图。我们数了一遍名字：Soft Editorial（Cormorant Garamond 衬线配暖纸与鼠尾草/腮红/柠檬）、Editorial Forest、Pin & Paper、Sakura Chroma、Stencil & Tablet、Cobalt Grid、Vellum、Emerald Editorial、Neo-Grid Bold、Editorial Tri-Tone、Creative Mode、Monochrome、People's Platform、Pink Script — After Hours、8-Bit Orbit、BlockFrame、Blue Professional、Bold Poster、Broadside、Capsule、Cartesian、Coral（奶油珊瑚配近黑 + 超大 Bebas Neue）、Daisy Days（手绘雏菊彩虹）、Grove、Mat（中世纪现代 + 木色调）、Playful（Syne 显示字体的独立发布感）、Raw Grid（新粗野主义、粗边框错位阴影）、Retro Windows（Windows 95 灰色标题栏 + MS Sans Serif）、Retro Zine（米纸绿accent + riso 印刷感）、Scatterbrain（便利贴 + Caveat 手写）、Signal（深海军蓝 + 单一哑金）、Studio（黑底电黄）、Biennale Yellow（荷兰编辑海报感）、Long Table（暖奶油锈红 supper-club）。
配套的渐进披露做得很干净，这是 token 工程而非风格工程：agent 先只读紧凑的 selection-index.json（里面带 mood/tone/best_for/avoid_for/formality/density/scheme 字段供匹配），入围后才读那几个候选的小 preview.md 卡片做标题页预览，只有用户最终选定那一个模板，才读它的完整 design.md。SKILL.md 还专门写了「除非选定的 design.md 缺关键实现细节，否则不要读也不要抄 template.html」。
预览真实性：一条被标成 NON-NEGOTIABLE 的规则
这一节暴露了作者踩过什么坑。规则是：每份风格预览必须看起来像用户 deck 的真实第一页，而不是一张诊断卡。禁止在幻灯片上渲染任何内部流程字样——不许出现 preview、generated from、preview.md、template、preset、style option、Option A/B/C、文件名、路径、来源文档标签；不许把模板名或 slug 印在页面上（模板名只能出现在给用户看的消息里）；也不许把用户的需求备注当内容渲染上去，比如「sharp and provocative」「safe option」「bold option」「for internal sharing」「audience: ...」。
需要页面 chrome 时，只准用真实 deck 的 chrome：deck 标题、章节标题、日期、作者、公司、页码，或者用户素材里真实存在的一句话。打开预览前还要再检查一遍可见文本，发现内部元数据就改掉。自研 wildcard 那条还多一句：不许在页面上渲染 custom、wildcard、AI-generated 或任何设计流程标签。
这条规则的价值超出 PPT 本身：它是「生成物里不许泄漏脚手架」的一般化。用户看到的应该是成品，不是 agent 的工作过程。任何做生成式 UI 的团队都该把它抄走。
固定 1920×1080 舞台：五条工程不变量
第 5 条核心原则被标成 NON-NEGOTIABLE：每份 deck 都在一个固定的 1920×1080 画布里写作，整体等比缩放到视口，手机上也必须保持 16:9，不许为了适配设备把内容重新排版。可以 letterbox / pillarbox（黑边），不可以 re-layout。这条和大多数「响应式幻灯片」库正好相反，但它换来的是排版确定性：设计尺寸就是最终尺寸。
配套的技术约束写得非常具体，每一条都对应一个真实 bug：
| 规则 | 不这么做会怎样 |
|---|---|
生成时必须读 viewport-base.css 并把全文放进 <style> | 舞台缩放与页面切换的基础 CSS 缺失，整份 deck 的适配行为不可预测 |
页面显隐只能用 viewport-base.css 里基于 visibility/opacity/pointer-events 的 .active/.visible，禁止 display:none/display:block | 后面的布局类（如 .slide-content { display: flex; }）会覆盖它，结果所有页面同时可见 |
clamp() 只用于舞台之外的非幻灯片 UI，或完整舞台不现实的小预览 | 舞台内用流式单位就等于放弃了固定设计尺寸 |
不许直接对 CSS 函数取负（-clamp()/-min()/-max()），要写 calc(-1 * clamp(...)) | 浏览器静默忽略，不报错，值直接失效 |
必须带 prefers-reduced-motion 支持 | 无障碍缺失 |
字体也是硬约束：只用 Fontshare 或 Google Fonts，永远不用系统字体。代码质量要求写在 Phase 3：每个区块都要有清晰的 /* === SECTION NAME === */ 注释块，并加详细注释解释每一段——对应 Philosophy 第四条「注释是一种善意，代码应该能向未来的你自我解释」。
反 AI slop：把「模型会收敛」写成显式对抗目标
Design Aesthetics 那一节用的是第二人称，直接对 agent 说话：「你会倾向于收敛到通用的、'在分布上'的输出，在前端设计里这就是用户所说的 AI slop 审美」。然后列出要避开的四件事：过度使用的字体族（Inter、Roboto、Arial、系统字体）、陈词滥调的配色（尤其是白底紫色渐变）、可预测的布局与组件模式、缺乏场景特征的模板化设计。
最狠的一句是：「你仍然会跨多次生成收敛到常见选择上（比如 Space Grotesk），避免它，跳出盒子思考是关键的」。它连「模型换了字体但换成了另一个大家都用的字体」这种二阶收敛都点出来了。正面要求则是四条：字体要美、独特、有意思；配色要committed（CSS 变量保持一致性，主色配锐利强调色胜过胆怯的均匀调色，可以从 IDE 主题与文化审美里取灵感）；动效优先 CSS-only，聚焦在高影响力时刻（一次编排良好的错峰入场比一堆零散微交互更讨喜）；背景要造氛围与层次，不要默认纯色。
这套「承认模型有收敛倾向 → 把倾向点名列举 → 要求刻意偏离」的写法，比单纯说「要有创意」有效得多，我们在 guizang-ppt-skill 里没看到同等强度的自我对抗条款。
工作流：六个 Phase，两种密度
Phase 0 先判模式：A 新建（走 Phase 1）、B PPTX 转换（直接跳 Phase 4）、C 增强既有 HTML（读完、理解、再改）。Mode C 单列了修改规则，因为固定舞台下「加内容」是最大的风险：加内容前先数现有元素并对照密度上限；加图片必须先塞进 1920×1080 画布，页面已满就拆成两页；加文本每页最多 4–6 条 bullet，超了拆续页；任何修改之后都要验证舞台仍是 16:9、文字没溢出卡片、面板没重叠，并且在 1280×720 加一个手机视口下截图确认；如果修改会导致溢出，主动拆分并告知用户，不要等人来问。
Phase 1 要求四个问题一次问完（有原生结构化提问 UI 就用，没有就在一条消息里编号列出）：用途（pitch deck / 教学 / 大会演讲 / 内部汇报）、篇幅（5–10 / 10–20 / 20+）、内容就绪度（全有 / 粗笔记 / 只有主题）、密度。并明确写了「Phase 1 不要问内联编辑」——用户不该在看到草稿前就被要求选编辑行为，内联编辑默认给，除非用户明确要锁定/只导出。
密度这一问是它比普通模板多的一个维度，直接影响页数、字号比例、每页文字量与布局密度：
| 密度模式 | 适合 | 设计行为 |
|---|---|---|
| 低密度 / 演讲者主导 | 公开演讲、keynote 式分享、现场讲解 | 一页一个观点，大字，强层级，大量留白，最多 1–3 条 bullet，需要就加页数 |
| 高密度 / 阅读优先 | 报告、发放材料、异步评审、内部详档 | 页面自足，结构化网格/表格/注释，4–8 条 bullet 或 4–6 张卡片，紧凑但仍有意图 |
基线限制两种模式都适用：不滚动、不溢出、面板不重叠、字号不小于舒适阅读尺寸。内容超出选定密度时拆成更多页，而不是缩到挤成一团。需求混合时选更接近的那一档，不许发明中间档：现场说服默认低密度，异步流转或详细评审默认高密度。
如果用户给了图片文件夹，Step 1.2 是四步：扫描列出所有图片 → 用 agent 的图像理解能力逐张看（读不了图就退回文件名/元数据，必要时才问）→ 逐张评估「是什么 / USABLE 还是 NOT USABLE（附理由）/ 代表什么概念 / 主色」→ 与大纲共同设计。最后一条写得很重：这不是「先排页再塞图」，而是从一开始就围绕文字和图片一起设计（例如 3 张截图 → 3 页功能页，1 个 logo → 标题页/收尾页）。若识别出可用 logo，Phase 2 的三份预览里都要 base64 内嵌进去——让用户看到自己的品牌被三种风格各自演绎。
验证：scrollHeight 不够，必须看渲染截图
Phase 3 选定 bold 模板后，要把它的 design.md 当「设计配方」用：保留字体、调色、装饰语汇、间距节奏与组件语法；无论源模板原本用 deck-stage.js 还是流式 CSS，最终产物一律是固定 1920×1080 舞台等比缩放；design.md 里的视口流式数值要当成设计比例翻译成舞台坐标，不能在成品里保留成实时 reflow 规则；输出仍是单个自包含文件；不许照抄演示内容或过度模仿源模板。
关键的一句是验收标准：生成之后要在浏览器渲染截图里同时验证内容溢出与面板重叠，只查 scrollHeight 不够，因为 grid 面板可能在视觉上互相覆盖。这是很专业的判断——overflow 检查抓不到 z 轴上的遮挡，而遮挡恰恰是固定尺寸舞台里最常见的翻车方式。选了自研 wildcard 时规则平行：把那份预览的 CSS 与布局当配方，向全 deck 扩展，不许在用户选定定制方向后再切回预设或 bold 模板，缺失的版式从同一系统里设计而不是从别的风格里搬。
没有图片时，CSS 生成的视觉元素（渐变、形状、图案）是一等公民路径而不是降级方案。
转换、交付与分享
Phase 4 的 PPTX 转换跑 python scripts/extract-pptx.py <input.pptx> <output_dir>（需要 python-pptx），把提取出的标题、内容摘要与图片数量先给用户确认，再进 Phase 2 选风格，最后生成 HTML 时保留全部文字、图片（放 assets/）、页面顺序，演讲者备注转成 HTML 注释保留。
Phase 5 交付要做四件事：删掉 .frontend-slides/slide-previews/、用 open 打开、告诉用户文件位置/风格名/页数/导航方式（方向键、空格、启用了就支持滑动点按）/怎么改（:root CSS 变量改颜色、字体链接改字体、.reveal 类改动效），以及产物自带内联编辑：鼠标移到左上角或按 E 进编辑模式，点任意文字直接改，Ctrl+S 保存。
Phase 6 是可选分享，两条路都给了非常具体的运维细节：
| 路径 | 脚本 | 坑与对策（README/SKILL 原文） |
|---|---|---|
| 部署到公网 URL | scripts/deploy.sh（Vercel 免费档） | 脚本能自动识别 src="..." 引用的本地资源，但 CSS background-image 或非常规路径可能漏掉，所以部署后必须打开 URL 逐张确认图片；素材多时优先部署整个文件夹而不是单文件；文件名带空格能用但 Vercel URL 会编成 %20，图片仍裂就改成连字符；重复部署覆盖同一个 URL，不用重发链接；首次使用会带着走注册与 vercel login |
| 导出 PDF | scripts/export-pdf.sh（Playwright） | 无头浏览器按 1920×1080 逐页截图再合成，动效与交互不保留（静态快照，要提前告知用户）；首次运行要下载约 150MB 的 Chromium，慢 30–60 秒；脚本靠查询 .slide 找页面，外部创建的 HTML 用了别的类名会报「0 slides found」；图片必须能用 HTTP 加载（脚本会起本地 server 服务 HTML 的父目录，所以相对路径可用，绝对文件系统路径不行）；18 页能出约 20MB PDF，超过 10MB 就问用户要不要压，--compact 改按 1280×720 渲染，通常减 50–70% 而视觉差异很小 |
另外仓库自带一条 YouTube 走查教程（372Iksaz8b0），以及一份「用这个 skill 做出的、讲这个 skill 的 deck」作为自证。
安装方式与运行时适配
Claude Code 走自定义 marketplace source，两条命令必须分成两条消息发，不能一次粘进 prompt：
/plugin marketplace add https://github.com/zarazhangrui/frontend-slides
/plugin install frontend-slides@frontend-slidesREADME 特别提醒要用 HTTPS URL：写成 zarazhangrui/frontend-slides 短格式可能让 Claude Code 去试 SSH，如果 GitHub 不在 known_hosts 里就会失败。装好后调用名是 /frontend-slides:frontend-slides（Claude Code 把 plugin 安装的 skill 命名成 /plugin-name:skill-name）；手工拷进 ~/.claude/skills/frontend-slides 的独立 skill 不带命名空间，直接 /frontend-slides。
其他 agent（README 点名 Codex、Kimi Code、OpenCode、Gemini CLI 或其他本地 coding agent）的路径是：把仓库链接发给它，让它从 SKILL.md 开始，只按需加载引用到的支持文件（STYLE_PRESETS.md、viewport-base.css、html-template.md、animation-patterns.md、bold-template-pack/、scripts/）。有文件系统权限的 agent 还能替你装到本地 skills 目录；没有的话当场按 SKILL.md 走也行。硬性前提只有一个：本地 coding agent，有文件系统访问权，能跑 shell 命令。
架构：一张表说明渐进披露
| 文件 | 作用 | 何时加载 |
|---|---|---|
SKILL.md | 核心工作流与规则 | 总是（skill 被调用时） |
STYLE_PRESETS.md | 12 个精选视觉预设 | Phase 2 选风格 |
bold-template-pack/selection-index.json | 34 个 bold 模板的紧凑元数据 | Phase 2 选风格 |
bold-template-pack/templates/*/preview.md | 入围候选的小风格卡 | Phase 2 入围之后 |
bold-template-pack/templates/*/design.md | 选定模板的完整设计系统 | Phase 3 用户选定之后（只读这一个） |
viewport-base.css | 强制的固定舞台 CSS | Phase 3 生成（全文内联） |
html-template.md | HTML 结构与 JS 特性 | Phase 3 生成 |
animation-patterns.md | 动画参考与「效果 → 感受」对照 | Phase 3 生成 |
scripts/extract-pptx.py | PPTX 内容提取 | Phase 4 转换 |
scripts/deploy.sh / scripts/export-pdf.sh | 部署 Vercel / 导出 PDF | Phase 6 分享 |
作者自己概括这套结构是「先给 agent 一张地图，再按当前选择只揭示需要的那几个文件」。维护用的源元数据与再生成辅助文件被刻意放在用户可见的 skill 包之外，普通用户不需要它们。
在 agientry 里的位置
我们把它收在 Agent Skills 的 documents（文档与演示）域，runtime 标 claude-code 与 codex——前者是原生 plugin 安装路径，后者是 README「Other Coding Agents」段落点名的第一档；OpenCode、Gemini CLI、Kimi Code 走的是「读 SKILL.md」这条通用路径，我们没有单独标注，因为它们不是这个仓库的适配目标而是普适兜底。
它和 op7418/guizang-ppt-skill 是同一赛道的两种答案，值得放在一起看：frontend-slides 押注发现——让不会设计的人通过看三份真实预览找到自己的审美，模板池大（12 预设 + 34 bold 模板），自研 wildcard 给自由留了口子，验收靠渲染截图人眼核对；guizang 押注约束——两套类名互不通用的视觉系统、22 个锁定版式、三个校验器与一条按 px 分级的修正阶梯，还内置了带排练计时的本地演讲者模式。需要快速试出视觉方向、或把既有 PPTX 转成网页的，选 frontend-slides；做严肃线下演讲、要演讲者模式与可脚本校验的一致性的，选 guizang。
诚实交代验证边界：本篇全部结论来自通读 README.md（594 行，含 34 个 bold 模板的完整清单与部署/导出注意事项）与 SKILL.md（380 行，含五条核心原则、固定舞台规则、六个 Phase 与渐进披露表）原文。我们没有安装该 plugin、没有跑出一份真实 deck、没有验证 extract-pptx.py 对复杂 PPTX 的还原度，也没有实测 --compact 的实际压缩比与 34 个 bold 模板在真实内容下的表现，均记为待复现。