frontend-slides

Frontend Slides

建立零依賴、富含動畫效果的 HTML 簡報，完全在瀏覽器中執行。

靈感來自 zarazhangrui 的作品中所展示的視覺探索方法（致謝：@zarazhangrui）。

何時啟用

• 建立演講簡報、提案簡報、工作坊簡報或內部簡報
• 將 .ppt 或 .pptx 投影片轉換為 HTML 簡報
• 改善現有 HTML 簡報的版面、動畫或排版
• 與不知道自身設計偏好的使用者一起探索簡報風格

不可妥協的事項

1. 零依賴：預設使用單一自包含的 HTML 檔案，內嵌 CSS 和 JS。
2. 視口適配是強制的：每張投影片必須完全符合一個視口，且無內部捲動。
3. 展示，而非告知：使用視覺預覽而非抽象的樣式問卷。
4. 獨特的設計：避免通用的紫色漸層、白色背景上的 Inter 字體、樣板化的簡報。
5. 生產級品質：保持程式碼有註解、可存取、響應式且高效能。

在生成之前，請閱讀 STYLE_PRESETS.md 以了解視口安全的 CSS 基礎、密度限制、預設目錄及 CSS 注意事項。

工作流程

1. 偵測模式

選擇一條路徑：

• 新簡報：使用者有主題、筆記或完整草稿
• PPT 轉換：使用者有 .ppt 或 .pptx
• 強化：使用者已有 HTML 投影片並希望改進

2. 探索內容

僅詢問最低需求：

• 目的：提案、教學、會議演講、內部更新
• 長度：短（5-10 張）、中（10-20 張）、長（20 張以上）
• 內容狀態：完成稿、粗略筆記、僅主題

如果使用者有內容，請在設計樣式前要求他們貼上內容。

3. 探索風格

預設使用視覺探索。

如果使用者已經知道想要的預設，則跳過預覽並直接使用。

否則：

1. 詢問簡報應營造何種感覺：印象深刻、充滿活力、專注、啟發靈感。
2. 在 .ecc-design/slide-previews/ 中生成 3 個單張投影片預覽檔案。
3. 每個預覽必須是自包含的，清楚展示排版/色彩/動畫，且投影片內容約在 100 行以內。
4. 詢問使用者要保留哪個預覽，或要混合哪些元素。

在將情緒對應到風格時，請使用 STYLE_PRESETS.md 中的預設指南。

4. 建立簡報

輸出以下其中一種：

• presentation.html
• [presentation-name].html

僅當簡報包含提取的或使用者提供的圖片時，才使用 assets/ 資料夾。

必要的結構：

• 語意化的投影片區段
• 來自 STYLE_PRESETS.md 的視口安全 CSS 基礎
• 用於主題值的 CSS 自訂屬性
• 用於鍵盤、滾輪和觸控導覽的簡報控制器類別
• 用於顯示動畫的 Intersection Observer
• 減少動畫支援

5. 強制視口適配

將此視為嚴格門檻。

規則：

• 每個 .slide 必須使用 height: 100vh; height: 100dvh; overflow: hidden;
• 所有字型和間距必須使用 clamp() 縮放
• 當內容無法容納時，分割成多張投影片
• 絕不透過將文字縮小到可讀大小以下來解決溢出問題
• 絕不允許投影片內出現捲軸

使用 STYLE_PRESETS.md 中的密度限制和強制 CSS 區塊。

6. 驗證

在以下尺寸檢查完成的簡報：

• 1920x1080
• 1280x720
• 768x1024
• 375x667
• 667x375

如果瀏覽器自動化可用，請使用它來驗證沒有投影片溢出，且鍵盤導覽正常運作。

7. 交付

在交接時：

• 刪除暫存預覽檔案，除非使用者想保留它們
• 在適當時使用平台適用的開啟器開啟簡報
• 總結檔案路徑、使用的預設、投影片數量以及簡單的主題自訂點

根據目前作業系統使用正確的開啟器：

• macOS：open file.html
• Linux：xdg-open file.html
• Windows：start "" file.html

PPT / PPTX 轉換

對於 PowerPoint 轉換：

1. 優先使用 python3 搭配 python-pptx 來提取文字、圖片和備註。
2. 如果 python-pptx 不可用，詢問是否要安裝它，或改用手動/匯出為基礎的工作流程。
3. 保留投影片順序、演講者備註和提取的素材。
4. 提取後，執行與新簡報相同的樣式選擇工作流程。

保持轉換跨平台。當 Python 可以完成工作時，不要依賴僅限 macOS 的工具。

實作需求

HTML / CSS

• 使用內嵌 CSS 和 JS，除非使用者明確要求多檔案專案。
• 字體可以來自 Google Fonts 或 Fontshare。
• 偏好氛圍背景、強烈的字型層級和清晰的視覺方向。
• 使用抽象形狀、漸層、網格、噪點和幾何圖形，而非插圖。

JavaScript

包含：

• 鍵盤導覽
• 觸控/滑動導覽
• 滑鼠滾輪導覽
• 進度指示器或投影片索引
• 進入時觸發動畫

可存取性

• 使用語意化結構（main、section、nav）
• 保持對比度可讀
• 支援僅鍵盤導覽
• 尊重 prefers-reduced-motion

內容密度限制

除非使用者明確要求更密集的投影片且可讀性仍可維持，否則使用以下最大值：

投影片類型	限制
標題	1 個標題 + 1 個副標題 + 可選標語
內容	1 個標題 + 4-6 個項目符號或 2 個短段落
功能網格	最多 6 張卡片
程式碼	最多 8-10 行
引言	1 則引言 + 出處
圖片	1 張圖片，受限於視口

反模式

• 沒有視覺識別度的通用新創漸層
• 系統字體簡報，除非是有意為之的編輯風格
• 長篇項目符號牆
• 需要捲動的程式碼區塊
• 在短螢幕上會破版的固定高度內容區塊
• 無效的否定 CSS 函式，如 -clamp(...)

相關 ECC 技能

• frontend-patterns：用於簡報周圍的元件和互動模式
• liquid-glass-design：當簡報有意借用 Apple 玻璃美學時
• e2e-testing：如果需要自動化瀏覽器驗證最終簡報

交付檢查清單

• 簡報可從本機檔案在瀏覽器中執行
• 每張投影片都符合視口，無需捲動
• 風格獨特且有明確意圖
• 動畫有意義而非雜亂
• 尊重減少動畫設定
• 在交接時說明檔案路徑和自訂點