ui-ux-pro-max-skill Slides 技能 HTML 幻灯片模板详解：设计令牌、16:9 锁定、Chart.js 与导航脚本实现

2026-09-04 23:04:54作者：柏廷章Berta

本文以 ui-ux-pro-max-skill 仓库中 Slides 技能的知识库文档 html-template.md 为主体，完整拆解该技能为“战略性 HTML 演示文稿”提供的单文件幻灯片模板：设计令牌如何注入、16:9 画布如何在任意视口下锁定、Chart.js 图表如何嵌入、导航与进度条脚本如何工作。读完本文，你可以直接复制该模板产出自包含、可响应式、品牌一致的演示页，并理解它与仓库中 design-system 技能的令牌生成、校验脚本之间的配合关系。

模板在 Slides 技能中的位置

Slides 技能定义在 SKILL.md，其 frontmatter 声明了技能元信息与路由规则：

name: slides
description: Create strategic HTML presentations with Chart.js, design tokens, responsive layouts, copywriting formulas, and contextual slide strategies.
argument-hint: "[topic] [slide-count]"

该技能采用“子命令 + 知识库”结构：解析 $ARGUMENTS 的第一个词作为子命令（目前只有 create），然后加载对应参考文档执行。知识库共四个参考文档：

主题	文件
Layout Patterns	references/layout-patterns.md
HTML Template	references/html-template.md
Copywriting Formulas	references/copywriting-formulas.md
Slide Strategies	references/slide-strategies.md

本文聚焦的 html-template.md 是其中“骨架级”的文档——它提供完整的 HTML 结构、导航脚本、Chart.js 集成、动画类与 CSS 变量速查表；其余文档分别负责布局选型、文案公式与页面策略。

Base Structure：完整的自包含幻灯片页面

模板的核心承诺是：一个 HTML 文件即一套完整幻灯片，无需构建工具、无需外部 CSS 文件。官方给出的完整基础结构如下（代码完整保留自原文档）：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Presentation Title</title>
    <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js"></script>
    <style>
        /* Paste embed-tokens.cjs output here */
        :root {
            --color-primary: #FF6B6B;
            --color-background: #0D0D0D;
            /* ... more tokens */
        }

        /* Base slide styles */
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body {
            background: var(--color-background);
            color: #fff;
            font-family: var(--typography-font-body, 'Inter', sans-serif);
            overflow: hidden;
        }

        /* 16:9 Aspect Ratio Container (desktop) */
        .slide-deck {
            position: relative;
            width: 100vw;
            height: 100vh;
            overflow: hidden;
        }

        @media (min-width: 769px) {
            .slide-deck {
                /* Lock to 16:9 — letterbox if viewport ratio differs */
                max-width: calc(100vh * 16 / 9);
                max-height: calc(100vw * 9 / 16);
                margin: auto;
                position: absolute;
                inset: 0;
            }
        }

        .slide {
            position: absolute;
            width: 100%; height: 100%;
            display: flex;
            flex-direction: column;
            justify-content: center;
            align-items: center;
            text-align: center;
            padding: 60px;
            opacity: 0;
            visibility: hidden;
            transition: opacity 0.4s;
            background: var(--color-background);
            overflow: hidden; /* Prevent content overflow */
        }

        .slide.active { opacity: 1; visibility: visible; }

        /* Slide inner wrapper — constrains content within safe area */
        .slide-content {
            width: 100%;
            max-width: 100%;
            max-height: 100%;
            overflow: hidden;
            display: flex;
            flex-direction: column;
            justify-content: center;
            align-items: center;
            gap: 16px;
        }

        /* Typography */
        h1, h2 { font-family: var(--typography-font-heading, 'Space Grotesk', sans-serif); }
        .slide-title {
            font-size: clamp(32px, 6vw, 80px);
            background: var(--primitive-gradient-primary, linear-gradient(135deg, #FF6B6B, #FF8E53));
            -webkit-background-clip: text;
            -webkit-text-fill-color: transparent;
            line-height: 1.1;
        }

        /* ===== RESPONSIVE BREAKPOINTS ===== */

        /* Tablet (portrait) */
        @media (max-width: 768px) {
            .slide { padding: 32px 24px; }
            .slide-title { font-size: clamp(28px, 5vw, 48px); }
            h2 { font-size: clamp(20px, 4vw, 32px); }
            p, li { font-size: clamp(14px, 2.5vw, 18px); }
        }

        /* Mobile */
        @media (max-width: 480px) {
            .slide { padding: 24px 16px; }
            .slide-title { font-size: clamp(22px, 6vw, 36px); }
            h2 { font-size: clamp(18px, 4.5vw, 28px); }
            p, li { font-size: clamp(12px, 3vw, 16px); }
            .nav-controls { bottom: 16px; gap: 12px; }
            .nav-btn { width: 32px; height: 32px; font-size: 14px; }
        }

        /* Navigation */
        .progress-bar {
            position: fixed;
            top: 0; left: 0;
            height: 3px;
            background: var(--color-primary);
            transition: width 0.3s;
            z-index: 1000;
        }
        .nav-controls {
            position: fixed;
            bottom: 30px;
            left: 50%;
            transform: translateX(-50%);
            display: flex;
            align-items: center;
            gap: 20px;
            z-index: 1000;
        }
        .nav-btn {
            background: rgba(255,255,255,0.1);
            border: none;
            color: #fff;
            width: 40px; height: 40px;
            border-radius: 50%;
            cursor: pointer;
            font-size: 18px;
        }
        .nav-btn:hover { background: rgba(255,255,255,0.2); }
        .slide-counter { color: rgba(255,255,255,0.6); font-size: 14px; }
    </style>
</head>
<body>
    <!-- Progress Bar -->
    <div class="progress-bar" id="progressBar"></div>

    <!-- Slide Deck Container (16:9 on desktop) */
    <div class="slide-deck">

    <!-- Slides -->
    <div class="slide active">
        <div class="slide-content">
            <h1 class="slide-title">Title Slide</h1>
            <p>Subtitle or tagline</p>
        </div>
    </div>

    <!-- More slides... (always wrap content in .slide-content) -->

    </div><!-- /.slide-deck -->

    <!-- Navigation -->
    <div class="nav-controls">
        <button class="nav-btn" onclick="prevSlide()">←</button>
        <span class="slide-counter"><span id="current">1</span> / <span id="total">9</span></span>
        <button class="nav-btn" onclick="nextSlide()">→</button>
    </div>

    <script>
        let current = 1;
        const total = document.querySelectorAll('.slide').length;
        document.getElementById('total').textContent = total;

        function showSlide(n) {
            if (n < 1) n = 1;
            if (n > total) n = total;
            current = n;
            document.querySelectorAll('.slide').forEach((s, i) => {
                s.classList.toggle('active', i === n - 1);
            });
            document.getElementById('current').textContent = n;
            document.getElementById('progressBar').style.width = (n / total * 100) + '%';
        }

        function nextSlide() { showSlide(current + 1); }
        function prevSlide() { showSlide(current - 1); }

        document.addEventListener('keydown', (e) => {
            if (e.key === 'ArrowRight' || e.key === ' ') { e.preventDefault(); nextSlide(); }
            if (e.key === 'ArrowLeft') { e.preventDefault(); prevSlide(); }
        });

        document.addEventListener('click', (e) => {
            if (!e.target.closest('.nav-controls')) nextSlide();
        });

        showSlide(1);
    </script>
</body>
</html>

模板中有几个值得逐条理解的关键设计决策：

1. 16:9 画布锁定（letterbox）。桌面端（min-width: 769px）下 .slide-deck 用两条 CSS 数学公式把容器“锁死”为 16:9：

max-width: calc(100vh * 16 / 9)：以视口高为基准换算允许的最大宽度；
max-height: calc(100vw * 9 / 16)：以视口宽为基准换算允许的最大高度。

再配合 position: absolute; inset: 0; margin: auto; 居中，无论浏览器窗口是超宽屏还是竖长窗口，幻灯片画布都保持 16:9，多余区域呈现为黑边（letterbox）。这保证了演示内容在任何显示器上的排版一致性。移动端则退化为全视口铺满，通过断点调整内边距与字号（见下文）。

2. 幻灯片切换采用“叠放 + 淡入”模型。所有 .slide 都是 position: absolute 铺满画布并默认 opacity: 0; visibility: hidden，只有携带 .active 类的那一张可见，切换由 transition: opacity 0.4s 提供淡入淡出。相比横向平移方案，该模型实现简单、天然支持任意页码跳转，且不会因内容宽度不同产生横向滚动。

3. .slide-content 安全区包装。文档特别注明“always wrap content in .slide-content”：该包装层用 flex 居中内容、以 gap: 16px 控制块间距，并用 overflow: hidden 防止内容溢出到导航控件区域。.slide 自身的 overflow: hidden 则是第二道保险。

4. 标题使用渐变文字。.slide-title 通过 background-clip: text 把 --primitive-gradient-primary 渐变“裁剪”成文字填充色，字号用 clamp(32px, 6vw, 80px) 在 32px 到 80px 之间随视口弹性伸缩，避免在笔记本与大屏之间出现过大或过小的标题。

5. 令牌兜底值。注意 var(--typography-font-body, 'Inter', sans-serif) 这类写法：每个关键令牌都带了 CSS 变量回退值（回退栈第二参数是字面量），意味着即使忘记粘贴 :root 令牌块，页面也不会退化成浏览器默认外观——这是“自包含模板”鲁棒性的关键细节。

设计令牌注入：embed-tokens.cjs 的工作方式

模板 <style> 块首行的注释 /* Paste embed-tokens.cjs output here */ 指明了令牌来源。仓库中该工具位于 design-system 技能目录下，即 embed-tokens.cjs，其文件头注释写明用途：“Reads design-tokens.css and outputs embeddable inline CSS. Use when generating standalone HTML files (infographics, slides, etc.)”，支持三种调用方式：

node embed-tokens.cjs           # 输出完整 :root 令牌 CSS
node embed-tokens.cjs --minimal # 仅输出幻灯片/信息图常用令牌
node embed-tokens.cjs --style   # 额外包裹 <style> 标签

从源码看（embed-tokens.cjs），它的工作流程是：

从当前目录逐级向上查找 assets/design-tokens.css（findProjectRoot），找不到则报错退出——这是该工具的运行前提：项目根目录必须已存在由 design-system 技能生成的 assets/design-tokens.css；
用正则 /:root\s*\{([^}]+)\}/g 提取所有 :root 块中的 --变量: 值; 声明；
--minimal 模式下按 MINIMAL_TOKENS 白名单过滤，只保留幻灯片高频使用的令牌前缀，例如：

const MINIMAL_TOKENS = [
  '--primitive-spacing-',
  '--primitive-fontSize-',
  '--primitive-fontWeight-',
  '--primitive-lineHeight-',
  '--primitive-radius-',
  '--primitive-shadow-glow-',
  '--primitive-gradient-',
  '--primitive-duration-',
  '--color-primary',
  '--color-secondary',
  '--color-accent',
  '--color-background',
  '--color-surface',
  '--color-foreground',
  '--color-border',
  '--typography-font-',
  '--card-',
];

去重后输出 :root { ... } 块，--style 时再包一层 <style> 标签，方便直接粘贴进 HTML。

这套命名（--color-primary、--primitive-gradient-、--typography-font- 等）对应仓库中三层令牌架构：Primitive（原始值）→ Semantic（语义别名）→ Component（组件级），详见 token-architecture.md。模板 CSS 变量速查表里出现的 --primitive-gradient-primary（Primitive 层）、--color-primary（Semantic 层）、--typography-font-body（跨层字体令牌）正好是这三层命名的实例。令牌本身的生成则由 generate-tokens.cjs 从符合 W3C DTCG 格式的 JSON 完成，JSON 结构可参考模板文件 design-tokens-starter.json（如 "blue": { "600": { "$value": "#2563EB", "$type": "color" } }）。

需要说明的是：slides 技能模板走的是内联令牌路线（把 :root 直接贴进文件，得到真正的单文件演示），而 design-system 技能的另一条生产线 generate-slide.py 生成的幻灯片则是通过 <link rel="stylesheet" href="{tokens_css_path}"> 外链 design-tokens.css。两者共享同一套令牌命名，但交付形态不同——前者适合分发单文件，后者适合令牌需要集中维护的项目。

响应式断点参数速查

原文档在模板中内嵌了两级响应式断点，整理成表如下（数值均直接取自模板 CSS）：

属性	桌面（>768px）	平板竖屏（≤768px）	手机（≤480px）
`.slide` padding	`60px`	`32px 24px`	`24px 16px`
`.slide-title` 字号	`clamp(32px, 6vw, 80px)`	`clamp(28px, 5vw, 48px)`	`clamp(22px, 6vw, 36px)`
`h2` 字号	由页面内容决定	`clamp(20px, 4vw, 32px)`	`clamp(18px, 4.5vw, 28px)`
`p, li` 字号	由页面内容决定	`clamp(14px, 2.5vw, 18px)`	`clamp(12px, 3vw, 16px)`
`.nav-controls` 位置/间距	`bottom: 30px; gap: 20px`	同桌面	`bottom: 16px; gap: 12px`
`.nav-btn` 尺寸	`40px` 圆钮 / 18px 字号	同桌面	`32px` 圆钮 / 14px 字号

移动端断点还顺手缩小了导航控件，避免小屏上 40px 按钮占位过大。

导航脚本与进度条

模板内置的 JavaScript 共约 30 行，承担四项职责：

页码计算：total 通过 document.querySelectorAll('.slide').length 动态得出，写入 #total；因此增删幻灯片不需要改脚本，只需保持 .slide 类名一致。
showSlide(n) 核心函数：先做边界钳制（n < 1 归 1、n > total 归 total），再遍历所有 .slide，用 classList.toggle('active', i === n - 1) 精确点亮目标页，同时更新计数器与进度条宽度 n / total * 100%。
键盘支持：ArrowRight 与空格触发下一页（均 preventDefault 防止空格滚动），ArrowLeft 触发上一页。
点击翻页：全局 click 监听中，凡点击目标不在 .nav-controls 内的区域都视为“前进一页”，模拟常见的演示手势；点击导航按钮本身则走按钮的 onclick 而不重复触发。

.progress-bar 是固定在视口顶部的 3px 色带（颜色取自 --color-primary），以 width 0.3s 过渡跟随翻页——它脱离 .slide-deck 的 16:9 锁定直接 position: fixed，因此无论画布是否 letterbox，进度条都贴满窗口上边缘。

Chart.js 集成

模板在 <head> 中以 UMD 方式引入 Chart.js 4.4.1，图表嵌入的标准写法（完整保留自原文档）：

<div class="chart-container" style="width: min(80%, 600px); height: clamp(200px, 40vh, 350px);">
    <canvas id="revenueChart"></canvas>
</div>

<script>
new Chart(document.getElementById('revenueChart'), {
    type: 'line', // or 'bar', 'doughnut', 'radar'
    data: {
        labels: ['Sep', 'Oct', 'Nov', 'Dec'],
        datasets: [{
            label: 'MRR ($K)',
            data: [5, 12, 28, 45],
            borderColor: '#FF6B6B',
            backgroundColor: 'rgba(255, 107, 107, 0.1)',
            borderWidth: 3,
            fill: true,
            tension: 0.4
        }]
    },
    options: {
        responsive: true,
        maintainAspectRatio: false,
        plugins: { legend: { display: false } },
        scales: {
            x: { grid: { color: 'rgba(255,255,255,0.05)' }, ticks: { color: '#B8B8D0' } },
            y: { grid: { color: 'rgba(255,255,255,0.05)' }, ticks: { color: '#B8B8D0' } }
        }
    }
});
</script>

几个配合模板体系的关键点：

容器尺寸用 min() 与 clamp() 双重约束：宽度 min(80%, 600px) 保证图表在桌面不超宽、在小屏占满可用空间；高度 clamp(200px, 40vh, 350px) 让图表纵向跟随视口。
maintainAspectRatio: false + responsive: true 是必须组合：Chart.js 默认 1:1 画布会撑破幻灯片的弹性布局，关闭比例锁定后画布才会精确贴合 .chart-container 的 clamp 高度。
暗色主题适配：网格线用 5% 透明度的白、刻度文字用 #B8B8D0 灰紫，与模板 #0D0D0D 级深色背景协调。type 支持 line/bar/doughnut/radar 四类，覆盖演示文稿最常见的数据形态。
从仓库其他幻灯片资料看，slide-charts.csv 提供了图表类型的选型知识库，可配合本文模板使用。

动画类库

原文档提供了四个开箱即用的动画类（完整保留）：

/* Fade Up */
.animate-fade-up {
    animation: fadeUp 0.6s ease-out forwards;
    opacity: 0;
}
@keyframes fadeUp {
    from { opacity: 0; transform: translateY(30px); }
    to { opacity: 1; transform: translateY(0); }
}

/* Count Animation */
.animate-count { animation: countUp 1s ease-out forwards; }

/* Scale */
.animate-scale {
    animation: scaleIn 0.5s ease-out forwards;
}
@keyframes scaleIn {
    from { opacity: 0; transform: scale(0.9); }
    to { opacity: 1; transform: scale(1); }
}

/* Stagger Children */
.animate-stagger > * {
    opacity: 0;
    animation: fadeUp 0.5s ease-out forwards;
}
.animate-stagger > *:nth-child(1) { animation-delay: 0.1s; }
.animate-stagger > *:nth-child(2) { animation-delay: 0.2s; }
.animate-stagger > *:nth-child(3) { animation-delay: 0.3s; }
.animate-stagger > *:nth-child(4) { animation-delay: 0.4s; }

用法要点：

.animate-fade-up 与 .animate-scale 都是“初始隐藏 + forwards 保留终态”模式，分别用于元素从下方 30px 上浮入场、以 0.9 倍缩放入场；
.animate-stagger 作用于父容器，通过 :nth-child 给子元素 0.1s 递增延迟，一行类名即可让一组卡片/列表项依次入场，适合“指标卡四连排”这类幻灯片；
所有动画时长（0.5s/0.6s/1s）与缓动（ease-out）刻意保持克制，符合演示场景“快速入场、不干扰阅读”的要求。

背景图幻灯片

原文档给出的背景图方案是“绝对定位图片 + 渐变遮罩 + 内容提升层级”三件套（完整保留）：

<div class="slide slide-with-bg" style="background-image: url('https://images.pexels.com/...')">
    <div class="overlay" style="background: linear-gradient(135deg, rgba(13,13,13,0.9), rgba(13,13,13,0.7))"></div>
    <div class="content" style="position: relative; z-index: 1;">
        <!-- Slide content -->
    </div>
</div>

要点：遮罩用 135° 线性渐变把深色背景从 90% 透明度过渡到 70%，既保证文字对比度又保留图片的明暗层次；.content 通过 position: relative; z-index: 1 抬到遮罩之上。背景图来源在仓库工具链中是允许的外部域名（见后文校验器的白名单），仓库 fetch-background.py 即为幻灯片背景图提供抓取支持。

CSS Variables 速查表

原文档附带的令牌用途表（完整保留），制作幻灯片时按需取用：

Variable	Usage
`--color-primary`	Brand primary (CTA, highlights)
`--color-background`	Slide background
`--color-secondary`	Secondary elements
`--primitive-gradient-primary`	Title gradients
`--typography-font-heading`	Headlines
`--typography-font-body`	Body text

令牌纪律：生成器与校验器的源码级佐证

slides 技能的模板定义了“应该长什么样”，design-system 技能的脚本则定义了“怎么保证令牌被正确使用”。两者共同构成这套体系的工程闭环。

generate-slide.py：严格令牌模板的批量生成。generate-slide.py 文件头明确写着约束：“ALL styles MUST use CSS variables from design-tokens.css / NO hardcoded colors, fonts, or spacing allowed”。它内置一份与本文模板同源的 SLIDE_TEMPLATE（16:9 aspect-ratio 容器、.slide-title 渐变标题、.card/.btn 组件令牌、纯 CSS 柱状图等），并提供七类幻灯片生成器（title/problem/solution/metrics/chart/testimonial/cta，映射于 SLIDE_GENERATORS 字典）。其 CLI 参数为：

python generate-slide.py --demo                  # 生成演示 deck（覆盖全部幻灯片类型）
python generate-slide.py --json slides.json -o out.html   # 由 JSON 数据驱动生成

值得注意的是它对用户输入做了两层防护：_e() 用 html.escape 转义所有嵌入值；_safe_url() 只放行 http://、https://、#、/ 四类 scheme 并显式注释“防止 javascript: URI 注入（CWE-79）”。这说明该生成器面向的是外部数据驱动的批量产出场景。

html-token-validator.py：令牌合规校验。html-token-validator.py 对产出的 HTML 资产做合规检查，用法：

python html-token-validator.py                    # 校验全部 HTML 资产
python html-token-validator.py --type slides      # 只校验幻灯片
python html-token-validator.py path/to/file.html  # 校验指定文件
python html-token-validator.py --colors          # 打印令牌中的品牌色

其校验规则（见源码 FORBIDDEN_PATTERNS 与 validate_html）包括：

必须存在 design-tokens.css 引用，否则报 Missing design-tokens.css import；
禁止在 <style> 或内联 style 中出现硬编码 hex/rgb/rgba/hsl 颜色与硬编码字体；
白名单例外：<script> 块内的颜色（Chart.js 需要字面色）、外部资源域名（pexels.com、unsplash.com、googleapis.com 等，对应 ALLOWED_EXCEPTIONS）、品牌色透明变体（ALLOWED_RGBA_PATTERNS，因 CSS 无法对变量直接加透明度而允许从品牌色派生的 rgba）；
统计 var(--color-、var(--primitive-、var(--typography-、var(--card-、var(--button- 五类令牌引用，少于 5 处给出“Low token usage”警告。

另外，slide-token-validator.py 是一个遗留包装器，内部直接 subprocess 转发到统一校验器并固定 --type slides，新用法应直接使用统一校验器。这里也体现了一个适用前提：该校验器的第 1 条规则针对的是外链 design-tokens.css 的生成产物；slides 技能这种内联 :root 的自包含单文件并不引用该文件，若直接套用此校验器需理解其规则语义（它同时会扫描 <script> 内颜色并放行）。

使用建议与适用前提

结合文档与仓库源码，落地该模板时需要注意以下前提与边界：

令牌注入是可选但推荐的第一步。模板自带 :root 示例值（#FF6B6B / #0D0D0D / 橙红渐变）与 var() 兜底值，不贴令牌也能直接跑；但若要品牌一致，应先由 generate-tokens.cjs 产出 assets/design-tokens.css，再用 embed-tokens.cjs --minimal 提取令牌块替换示例 :root。--minimal 白名单（embed-tokens.cjs 中的 MINIMAL_TOKENS）恰好覆盖了本文模板用到的颜色、字体、间距、圆角、渐变、时长等前缀。
模板定位是“骨架”而非“内容”。单页内容布局应配合 layout-patterns.md 的版式库、slide-strategies.md 的页面策略与 copywriting-formulas.md 的文案公式使用；design 技能下还有一份同主题的 slides-html-template.md 副本，跨技能引用时内容一致。
Chart.js 依赖运行时网络。模板通过 CDN 引入 chart.umd.min.js，离线场景需自行替换为本地副本；不展示图表的幻灯片页可以删除该 <script> 行以进一步精简。
验证产物时区分两条生产线。批量生成 deck 走 generate-slide.py（外链令牌 + 校验器可查），手工精修的单文件演示走本文模板（内联令牌 + 自包含）。两者的共同底线是同一套三层令牌命名——这正是 token-architecture.md 中 --{category}-{item}-{variant}-{state} 命名约定的价值：换主题只改 Semantic 层，模板 CSS 一行不动。