docs(zh-CN): sync Chinese docs with latest upstream changes (#304)

* docs(zh-CN): sync Chinese docs with latest upstream changes * update --------- Co-authored-by: neo <neo.dowithless@gmail.com>
2026-04-14 05:43:29 +08:00 · 2026-03-03 14:28:27 +08:00
parent adc0f67008
commit ada4cd75a3
114 changed files with 11161 additions and 4790 deletions
--- a/docs/zh-CN/skills/frontend-slides/SKILL.md
+++ b/docs/zh-CN/skills/frontend-slides/SKILL.md
@@ -0,0 +1,195 @@
+---
+name: frontend-slides
+description: 从零开始或通过转换PowerPoint文件创建令人惊艳、动画丰富的HTML演示文稿。当用户想要构建演示文稿、将PPT/PPTX转换为网页格式，或为演讲/推介创建幻灯片时使用。帮助非设计师通过视觉探索而非抽象选择发现他们的美学。
+origin: ECC
+---
+
+# 前端幻灯片
+
+创建零依赖、动画丰富的 HTML 演示文稿，完全在浏览器中运行。
+
+灵感来源于 [zarazhangrui](https://github.com/zarazhangrui) 的作品中展示的视觉探索方法。
+
+## 何时启用
+
+* 创建演讲文稿、推介文稿、研讨会文稿或内部演示文稿时
+* 将 `.ppt` 或 `.pptx` 幻灯片转换为 HTML 演示文稿时
+* 改进现有 HTML 演示文稿的布局、动效或排版时
+* 与尚不清楚其设计偏好的用户一起探索演示文稿风格时
+
+## 不可妥协的原则
+
+1. **零依赖**：默认使用一个包含内联 CSS 和 JS 的自包含 HTML 文件。
+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` 当演示文稿有意借鉴苹果玻璃美学时
+* `e2e-testing` 如果您需要为最终文稿进行自动化浏览器验证
+
+## 交付清单
+
+* 演示文稿可在浏览器中从本地文件运行
+* 每张幻灯片适配视口，无需滚动
+* 风格独特且有意图
+* 动画有意义，不喧闹
+* 尊重减少动效设置
+* 在交付时解释文件路径和自定义点
--- a/docs/zh-CN/skills/frontend-slides/STYLE_PRESETS.md
+++ b/docs/zh-CN/skills/frontend-slides/STYLE_PRESETS.md
@@ -0,0 +1,333 @@
+# 样式预设参考
+
+为 `frontend-slides` 整理的视觉样式。
+
+使用此文件用于：
+
+* 强制性的视口适配 CSS 基础
+* 预设选择和情绪映射
+* CSS 陷阱和验证规则
+
+仅使用抽象形状。除非用户明确要求，否则避免使用插图。
+
+## 视口适配不容妥协
+
+每张幻灯片必须完全适配一个视口。
+
+### 黄金法则
+
+```text
+Each slide = exactly one viewport height.
+Too much content = split into more slides.
+Never scroll inside a slide.
+```
+
+### 内容密度限制
+
+| 幻灯片类型 | 最大内容量 |
+|---|---|
+| 标题幻灯片 | 1 个标题 + 1 个副标题 + 可选标语 |
+| 内容幻灯片 | 1 个标题 + 4-6 个要点或 2 个段落 |
+| 功能网格 | 最多 6 张卡片 |
+| 代码幻灯片 | 最多 8-10 行 |
+| 引用幻灯片 | 1 条引用 + 出处 |
+| 图片幻灯片 | 1 张图片，理想情况下低于 60vh |
+
+## 强制基础 CSS
+
+将此代码块复制到每个生成的演示文稿中，然后在其基础上应用主题。
+
+```css
+/* ===========================================
+   VIEWPORT FITTING: MANDATORY BASE STYLES
+   =========================================== */
+
+html, body {
+    height: 100%;
+    overflow-x: hidden;
+}
+
+html {
+    scroll-snap-type: y mandatory;
+    scroll-behavior: smooth;
+}
+
+.slide {
+    width: 100vw;
+    height: 100vh;
+    height: 100dvh;
+    overflow: hidden;
+    scroll-snap-align: start;
+    display: flex;
+    flex-direction: column;
+    position: relative;
+}
+
+.slide-content {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    max-height: 100%;
+    overflow: hidden;
+    padding: var(--slide-padding);
+}
+
+:root {
+    --title-size: clamp(1.5rem, 5vw, 4rem);
+    --h2-size: clamp(1.25rem, 3.5vw, 2.5rem);
+    --h3-size: clamp(1rem, 2.5vw, 1.75rem);
+    --body-size: clamp(0.75rem, 1.5vw, 1.125rem);
+    --small-size: clamp(0.65rem, 1vw, 0.875rem);
+
+    --slide-padding: clamp(1rem, 4vw, 4rem);
+    --content-gap: clamp(0.5rem, 2vw, 2rem);
+    --element-gap: clamp(0.25rem, 1vw, 1rem);
+}
+
+.card, .container, .content-box {
+    max-width: min(90vw, 1000px);
+    max-height: min(80vh, 700px);
+}
+
+.feature-list, .bullet-list {
+    gap: clamp(0.4rem, 1vh, 1rem);
+}
+
+.feature-list li, .bullet-list li {
+    font-size: var(--body-size);
+    line-height: 1.4;
+}
+
+.grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(min(100%, 250px), 1fr));
+    gap: clamp(0.5rem, 1.5vw, 1rem);
+}
+
+img, .image-container {
+    max-width: 100%;
+    max-height: min(50vh, 400px);
+    object-fit: contain;
+}
+
+@media (max-height: 700px) {
+    :root {
+        --slide-padding: clamp(0.75rem, 3vw, 2rem);
+        --content-gap: clamp(0.4rem, 1.5vw, 1rem);
+        --title-size: clamp(1.25rem, 4.5vw, 2.5rem);
+        --h2-size: clamp(1rem, 3vw, 1.75rem);
+    }
+}
+
+@media (max-height: 600px) {
+    :root {
+        --slide-padding: clamp(0.5rem, 2.5vw, 1.5rem);
+        --content-gap: clamp(0.3rem, 1vw, 0.75rem);
+        --title-size: clamp(1.1rem, 4vw, 2rem);
+        --body-size: clamp(0.7rem, 1.2vw, 0.95rem);
+    }
+
+    .nav-dots, .keyboard-hint, .decorative {
+        display: none;
+    }
+}
+
+@media (max-height: 500px) {
+    :root {
+        --slide-padding: clamp(0.4rem, 2vw, 1rem);
+        --title-size: clamp(1rem, 3.5vw, 1.5rem);
+        --h2-size: clamp(0.9rem, 2.5vw, 1.25rem);
+        --body-size: clamp(0.65rem, 1vw, 0.85rem);
+    }
+}
+
+@media (max-width: 600px) {
+    :root {
+        --title-size: clamp(1.25rem, 7vw, 2.5rem);
+    }
+
+    .grid {
+        grid-template-columns: 1fr;
+    }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+        animation-duration: 0.01ms !important;
+        transition-duration: 0.2s !important;
+    }
+
+    html {
+        scroll-behavior: auto;
+    }
+}
+```
+
+## 视口检查清单
+
+* 每个 `.slide` 都有 `height: 100vh`、`height: 100dvh` 和 `overflow: hidden`
+* 所有排版都使用 `clamp()`
+* 所有间距都使用 `clamp()` 或视口单位
+* 图片有 `max-height` 约束
+* 网格使用 `auto-fit` + `minmax()` 进行适配
+* 短高度断点存在于 `700px`、`600px` 和 `500px`
+* 如果感觉任何内容拥挤，请拆分幻灯片
+
+## 情绪到预设的映射
+
+| 情绪 | 推荐的预设 |
+|---|---|
+| 印象深刻 / 自信 | Bold Signal, Electric Studio, Dark Botanical |
+| 兴奋 / 充满活力 | Creative Voltage, Neon Cyber, Split Pastel |
+| 平静 / 专注 | Notebook Tabs, Paper & Ink, Swiss Modern |
+| 受启发 / 感动 | Dark Botanical, Vintage Editorial, Pastel Geometry |
+
+## 预设目录
+
+### 1. Bold Signal
+
+* 氛围：自信，高冲击力，适合主题演讲
+* 最适合：推介演示，产品发布，声明
+* 字体：Archivo Black + Space Grotesk
+* 调色板：炭灰色基底，亮橙色焦点卡片，纯白色文本
+* 特色：超大章节编号，深色背景上的高对比度卡片
+
+### 2. Electric Studio
+
+* 氛围：简洁，大胆，机构级精致
+* 最适合：客户演示，战略评审
+* 字体：仅 Manrope
+* 调色板：黑色，白色，饱和钴蓝色点缀
+* 特色：双面板分割和锐利的编辑式对齐
+
+### 3. Creative Voltage
+
+* 氛围：充满活力，复古现代，俏皮自信
+* 最适合：创意工作室，品牌工作，产品故事叙述
+* 字体：Syne + Space Mono
+* 调色板：电光蓝，霓虹黄，深海军蓝
+* 特色：半色调纹理，徽章，强烈的对比
+
+### 4. Dark Botanical
+
+* 氛围：优雅，高端，有氛围感
+* 最适合：奢侈品牌，深思熟虑的叙述，高端产品演示
+* 字体：Cormorant + IBM Plex Sans
+* 调色板：接近黑色，温暖的象牙色，腮红，金色，赤陶色
+* 特色：模糊的抽象圆形，精细的线条，克制的动效
+
+### 5. Notebook Tabs
+
+* 氛围：编辑感，有条理，有触感
+* 最适合：报告，评审，结构化的故事叙述
+* 字体：Bodoni Moda + DM Sans
+* 调色板：炭灰色上的奶油色纸张搭配柔和色彩标签
+* 特色：纸张效果，彩色侧边标签，活页夹细节
+
+### 6. Pastel Geometry
+
+* 氛围：平易近人，现代，友好
+* 最适合：产品概览，入门介绍，较轻松的品牌演示
+* 字体：仅 Plus Jakarta Sans
+* 调色板：淡蓝色背景，奶油色卡片，柔和的粉色/薄荷色/薰衣草色点缀
+* 特色：垂直药丸形状，圆角卡片，柔和阴影
+
+### 7. Split Pastel
+
+* 氛围：有趣，现代，有创意
+* 最适合：机构介绍，研讨会，作品集
+* 字体：仅 Outfit
+* 调色板：桃色 + 薰衣草色分割背景搭配薄荷色徽章
+* 特色：分割背景，圆角标签，轻网格叠加层
+
+### 8. Vintage Editorial
+
+* 氛围：诙谐，个性鲜明，受杂志启发
+* 最适合：个人品牌，观点性演讲，故事叙述
+* 字体：Fraunces + Work Sans
+* 调色板：奶油色，炭灰色，灰暗的暖色点缀
+* 特色：几何点缀，带边框的标注，醒目的衬线标题
+
+### 9. Neon Cyber
+
+* 氛围：未来感，科技感，动感
+* 最适合：AI，基础设施，开发工具，关于未来趋势的演讲
+* 字体：Clash Display + Satoshi
+* 调色板：午夜海军蓝，青色，洋红色
+* 特色：发光效果，粒子，网格，数据雷达能量感
+
+### 10. Terminal Green
+
+* 氛围：面向开发者，黑客风格简洁
+* 最适合：API，CLI 工具，工程演示
+* 字体：仅 JetBrains Mono
+* 调色板：GitHub 深色 + 终端绿色
+* 特色：扫描线，命令行框架，精确的等宽字体节奏
+
+### 11. Swiss Modern
+
+* 氛围：极简，精确，数据导向
+* 最适合：企业，产品战略，分析
+* 字体：Archivo + Nunito
+* 调色板：白色，黑色，信号红色
+* 特色：可见的网格，不对称，几何秩序感
+
+### 12. Paper & Ink
+
+* 氛围：文学性，深思熟虑，故事驱动
+* 最适合：散文，主题演讲叙述，宣言式演示
+* 字体：Cormorant Garamond + Source Serif 4
+* 调色板：温暖的奶油色，炭灰色，深红色点缀
+* 特色：引文突出，首字下沉，优雅的线条
+
+## 直接选择提示
+
+如果用户已经知道他们想要的样式，让他们直接从上面的预设名称中选择，而不是强制生成预览。
+
+## 动画感觉映射
+
+| 感觉 | 动效方向 |
+|---|---|
+| 戏剧性 / 电影感 | 缓慢淡入淡出，视差滚动，大比例缩放进入 |
+| 科技感 / 未来感 | 发光，粒子，网格运动，文字乱序出现 |
+| 有趣 / 友好 | 弹性缓动，圆角形状，漂浮运动 |
+| 专业 / 企业 | 微妙的 200-300 毫秒过渡，干净的幻灯片切换 |
+| 平静 / 极简 | 非常克制的运动，留白优先 |
+| 编辑感 / 杂志感 | 强烈的层次感，错落的文字和图片互动 |
+
+## CSS 陷阱：否定函数
+
+切勿编写这些：
+
+```css
+right: -clamp(28px, 3.5vw, 44px);
+margin-left: -min(10vw, 100px);
+```
+
+浏览器会静默忽略它们。
+
+始终改为编写这个：
+
+```css
+right: calc(-1 * clamp(28px, 3.5vw, 44px));
+margin-left: calc(-1 * min(10vw, 100px));
+```
+
+## 验证尺寸
+
+至少测试以下尺寸：
+
+* 桌面：`1920x1080`，`1440x900`，`1280x720`
+* 平板：`1024x768`，`768x1024`
+* 手机：`375x667`，`414x896`
+* 横屏手机：`667x375`，`896x414`
+
+## 反模式
+
+请勿使用：
+
+* 紫底白字的初创公司模板
+* Inter / Roboto / Arial 作为视觉声音，除非用户明确想要实用主义的中性风格
+* 要点堆砌、过小字体或需要滚动的代码块
+* 装饰性插图，当抽象几何形状能更好地完成工作时