html-slides 完整教學

Claude Code Skill：用自然語言描述需求，自動產出可直接瀏覽器開啟的單檔 HTML 簡報。

1. 專案定位

1.1 這個專案解決什麼問題？

做簡報最常見的瓶頸不是內容不夠，而是「排版太花時間」和「工具學習成本太高」。PowerPoint 要調字型、對齊、配色；Marp 或 reveal.js 要懂 markdown 或前端框架。html-slides 的核心主張是：你只需要用自然語言說出需求，Claude Code 就幫你完成從草案到成品的全流程。

html-slides 是一個 Claude Code skill，安裝後會賦予 Claude 一套完整的簡報製作知識：6 種視覺風格、22 種頁面版型、草案優先工作流、教學活動設計節奏、QA 自我驗收機制。使用者不需要懂 HTML/CSS，只需要在 Claude Code 中描述目的、受眾、風格偏好，Claude 就會按照 skill 內建的規範逐步產出。

1.2 產出成品是什麼？

一個 .html 檔案。用 Chrome/Safari/Edge 雙擊開啟就能全螢幕播放，鍵盤左右鍵翻頁。不需要安裝任何東西、不需要網路連線、不需要建置工具。

1.3 目標使用族群

2. 安裝指南

2.1 前置需求

• Claude Code：需要已安裝並可正常使用 Claude Code CLI
• 瀏覽器：Chrome、Safari 或 Edge（用來開啟成品）
• 不需要：Node.js、npm、Python、任何建置工具

2.2 全域安裝（所有專案可用）

1git clone https://github.com/gatelynch/html-slides.git ~/.claude/skills/html-slides

安裝後，在 Claude Code 中提到「做簡報」、「HTML 簡報」、「slide deck」就會自動啟動此 skill。

2.3 專案內安裝（僅該專案可用）

1git clone https://github.com/gatelynch/html-slides.git <你的專案>/.claude/skills/html-slides

2.4 快速驗證

安裝後在 Claude Code 中輸入：

1幫我做一份 3 頁的自我介紹簡報，Clean 風格。

如果 Claude 開始詢問目的與受眾，表示 skill 已成功載入。

3. 核心架構解析

3.1 系統架構圖

graph TD
    subgraph 使用者輸入
        A[自然語言描述需求]
    end

    subgraph Claude Code + html-slides Skill
        B[SKILL.md
工作流程引擎]
        C[references/
設計規範庫]
        D[assets/templates/
base-deck.html]
    end

    subgraph 設計規範庫 references/
        C1[outline-format.md
草案格式]
        C2[deck-patterns.md
22 種版型]
        C3[style-system.md
6 種風格 + CSS token]
        C4[teaching-patterns.md
教學版型設計]
        C5[qa-checklist.md
QA 檢查清單]
        C6[github-pages.md
發布指引]
    end

    subgraph 產出
        E[草案 markdown
逐頁重點]
        F[成品 HTML
單檔簡報]
    end

    A --> B
    B --> C
    B --> D
    C --> C1 & C2 & C3 & C4 & C5 & C6
    B --> E
    E -->|使用者確認| F
    D -->|模板基礎| F

    style B fill:#2563eb,color:#fff
    style F fill:#16a34a,color:#fff

3.2 關鍵設計決策

為什麼是單檔 HTML？

單檔 HTML 是最可攜帶的簡報格式。一個 .html 檔可以用任何瀏覽器開啟、離線播放、email 附件寄送、GitHub Pages 發布。不需要安裝 runtime、不需要 npm install、不需要啟動 dev server。

為什麼強制草案優先？

在 HTML 生成前先寫一份逐頁 markdown 草案，是為了把「頁序、版型、每頁重點」的討論成本降到最低。修改一行 markdown 比修改一段 HTML 便宜得多。這個決策在 commit 3ae5b5c 中被正式加入。

為什麼用 CSS token 而不是直接寫死顏色？

10 個 CSS 自訂屬性（--bg-primary、--accent 等）讓 22 種版型可以在 6 種風格之間自由切換，不需要為每種風格重寫版型樣式。這是整個系統的可維護性基礎。

3.3 CSS Token 系統

 1:root
 2├── --bg-primary      → 頁面背景色
 3├── --text-primary    → 主要文字色
 4├── --text-secondary  → 輔助文字色
 5├── --accent          → 強調色（按鈕、重點數字、當前步驟）
 6├── --accent-dim      → 淡化強調色（背景標記）
 7├── --surface         → 卡片 / 面板背景色
 8├── --border          → 邊框色
 9├── --on-accent       → 強調色上的文字色
10├── --font-title      → 標題字型
11└── --font-body       → 內文字型

六種風格只需覆寫這 10 個變數，所有版型自動套用新配色。

4. 使用方式詳細說明

4.1 完整工作流程（四個階段）

階段一：問清楚

Claude 會確認以下資訊（已提供的就不會重複問）：

1. 簡報目的與受眾
2. 內容是完整素材、粗略大綱，還是只有主題
3. 預計講多久、需要幾頁
4. 想要哪種風格（未指定則用 Clean）
5. 是否需要講者備註
6. 是否有圖片或資產要放入
7. 是否需要發布到 GitHub Pages

教學簡報額外確認：現場是講述/討論/實作、學習者先嘗試或先看範例、活動的輸入/任務/產出/時間。

階段二：給草案

Claude 產出一份 markdown 草案，每頁一個區塊：

 1## 1. Cover — 把工具用成可教的流程
 2- 重點：一句承諾；今天會帶走一套可重複的方法
 3- 備註：開場用一句話說明今天會完成什麼
 4
 5## 2. Agenda — 今天的路徑
 6- 重點：看見問題 / 做一次任務 / 帶走流程
 7
 8## 3. Activity — 請幫導師回覆一則訊息
 9- 情境：家長對換座位不滿，傳來情緒強烈的訊息
10- 任務：寫一版 120 字以內回覆
11- 時間：個人 4 分鐘 + 小組比較 3 分鐘
12- 產出：一段可直接傳出的訊息
13- 討論：哪一句最能降溫？

使用者在這個階段可以增刪頁面、調整順序、改版型、補內容。

階段三：生成簡報

草案確認後，Claude 根據 base-deck.html 模板生成完整 HTML。每個草案區塊轉成一個 <section class="slide">。

階段四：自我驗收

Claude 在宣稱完成前，主動攤開兩份東西：

• 逐頁清單：列出每頁的版型、標題、核心訊息
• 成功標準自評：一頁一畫面、不依賴捲動、風格一致、CSS token 一致等

4.2 常用指令範例

4.3 播放操作

4.4 風格選擇指南

5. 應用場景

5.1 教育現場

html-slides 最大的差異化在於教學版型。傳統簡報工具把教學簡報當成「內容的容器」，html-slides 把它當成「活動的載體」。

10 種教學版型對應不同的教學節奏：

建議的教學節奏：給情境 → 讓學生嘗試 → 互相比較 → 揭示範例 → 討論為什麼有效。

5.2 企業報告

用 12 種通用版型組合：Cover → Agenda → Stat → Two-column → Feature Grid → Process → Timeline → Chart → Closing。Clean 風格最適合正式場合。

5.3 技術分享

Lab 風格 + Code 版型 + Prompt Lab 版型 + Comparison 版型。適合展示程式碼片段、prompt 實驗、工具比較。

5.4 故事型演講

Story 風格 + 大圖背景 + Quote 版型 + Before/After 版型。少字、沉浸、以照片和案例推進敘事。

6. 資安掃描報告

6.1 掃描範圍

對 gatelynch/html-slides repo 執行以下掃描：

• 原始碼中的危險函數呼叫（eval、exec、fetch、XMLHttpRequest）
• 機密資訊（密碼、API key、token）
• 憑證檔案（.env、.key、.pem）
• 外部 URL 依賴

6.2 掃描結果

6.3 風險評估

整體風險等級：低

html-slides 是純靜態 HTML 模板，不包含後端邏輯、不連線外部服務、不存取使用者資料。產出的簡報檔案也是自包含的靜態 HTML，不會執行任何網路請求。

唯一需注意的是：如果使用者在簡報中嵌入外部圖片或 script，那是使用者自行加入的內容，不在 skill 本身的風險範圍內。

7. FAQ

Q1：html-slides 和 Marp / reveal.js / Slidev 有什麼不同？

html-slides 不是一個簡報框架，而是一個 Claude Code skill。Marp/reveal.js/Slidev 需要使用者手動撰寫 markdown 或 code，html-slides 讓使用者用自然語言描述需求，由 Claude 完成全部生成工作。產出是純 HTML，不依賴任何 runtime。

Q2：可以自訂風格嗎？

可以。六種風格各自只是覆寫 10 個 CSS 變數。你可以在 base-deck.html 的 <style> 區塊中新增一組 body.style-yourname { ... } 來定義新風格。

Q3：簡報可以離線播放嗎？

可以。只要圖片跟著 .html 一起帶走（放在相鄰的 assets/ 資料夾），就能完全離線播放。

Q4：可以發布到網路嗎？

可以。skill 內建 GitHub Pages 發布指引。把 index.html 和 assets/ 推到 GitHub repo，開啟 GitHub Pages 即可。

Q5：一份簡報可以混用多種風格嗎？

不建議。設計規範明確指出「一份簡報只選一種主風格」，以維持視覺一致性。必要時可以做少數深色封面頁，但不要混成多套品牌。

Q6：頁面內容太多怎麼辦？

拆頁。skill 的核心原則是「一頁一個核心訊息」、「頁面不可依賴內部捲動」。內容超出時優先拆頁，不要縮小字體。

Q7：支援講者備註嗎？

支援。使用 data-note 屬性存放每頁的講者提示。是否顯示、如何顯示由使用者決定。

Q8：草案可以跳過嗎？

可以。在指令中加上「不用草案，直接出 HTML」即可跳過第二階段。但建議對重要簡報保留草案流程。

8. 進階技巧

8.1 版型組合節奏

避免連續使用同一種版型超過兩頁。建議的節奏模式：

1Cover → Agenda → Stat → Two-column → Activity → Reveal →
2Feature Grid → Process → Comparison → Reflection → Closing

8.2 教學活動階梯設計

同一情境延伸多個活動時，讓每個活動像階梯：

1. 活動一：先處理最表層任務
2. 活動二：加入限制、判準或角色差異
3. 活動三：要求學習者修改、評估或重設計

8.3 響應式字級系統

html-slides 使用 clamp() 讓文字自適應螢幕尺寸：

8.4 動畫使用原則

• 動畫距離小、時間短，避免彈跳、旋轉、過度模糊
• 一頁最多一個主要進場動作，其餘元素淡入即可
• 必須支援 prefers-reduced-motion
• Loop 動畫只放在小型裝飾元素，不放在文字
• 可依場合省略所有動畫

8.5 內容密度上限

9. 整合進其他工作流

9.1 與 AIKT 整合

html-slides 產出的 HTML 簡報可以透過以下方式整合進 AI Knowledge Template 工作流：

• 作為 paper-tutorial 的簡報輸出：研究論文教學除了 plain HTML 報告外，可用 html-slides 產出精華 slides
• 作為 company-intel 的簡報輸出：盡職調查報告轉成會議簡報
• 作為 video-to-tutorial 的補充：影片教學的重點摘要 slides

9.2 與 GitHub Pages 整合

1. 將 index.html 和 assets/ 推到 GitHub repo
2. 在 repo Settings → Pages 開啟 GitHub Pages
3. 簡報即可透過 https://<user>.github.io/<repo>/ 存取

9.3 與 kami 的差異

10. 重點摘要 Checklist

• html-slides 是 Claude Code skill，不是簡報框架
• 安裝方式：git clone 到 ~/.claude/skills/html-slides
• 產出：單檔 .html，瀏覽器雙擊即可播放
• 工作流：問清楚 → 給草案 → 生成 HTML → 自我驗收
• 6 種風格：Clean / Workshop / Notebook / Story / Lab / Dark
• 22 種版型：12 通用 + 10 教學
• CSS token 系統：10 個自訂屬性控制全部風格
• 教學版型強調「活動設計」而非「內容堆疊」
• 翻頁支援水平 / 垂直兩種模式（按 V 切換）
• 無外部依賴，完全離線可用
• 資安風險：低（純靜態 HTML，無後端、無網路請求）

11. 進一步閱讀