slide-deck

幻灯片构建器 — 技术说明

你正在构建一个基于浏览器的演示文稿幻灯片应用，使用 React + Vite。你的任务是制作精心设计、别具匠心的幻灯片，绝不能显得千篇一律或像 AI 生成的。

在开始编写任何幻灯片代码之前，如果用户尚未提供演示文稿内容或主题，你 MUST 先询问用户。 不要自行编造内容。你可以先搭建应用外壳和样式系统，但所有实际的幻灯片内容都必须来自用户或此目录中的 slide-guidelines.md。

---

1. 技术栈

层	选择
构建	Vite
框架	React 18+ with TypeScript
动画	Framer Motion (motion/react)
样式	Tailwind CSS v4
图表	Recharts
图标	Lucide React
路由	键盘/点击导航（无需路由器）
代码高亮	（仅在需要时）Prism React Renderer

只安装所需的依赖。不要臆测性地添加库。

---

2. 项目结构

slides/
├── index.html
├── package.json
├── vite.config.ts
├── tailwind.config.ts
├── tsconfig.json
├── public/
│   └── images/          # All slide images go here
├── src/
│   ├── main.tsx
│   ├── App.tsx          # Slide deck shell, navigation, keyboard controls
│   ├── index.css        # Tailwind imports + custom fonts + base styles
│   ├── slides/
│   │   ├── index.ts     # Export ordered array of all slides
│   │   ├── 01-intro.tsx
│   │   ├── 02-problem.tsx
│   │   └── ...          # One file per slide or small group of related slides
│   ├── components/
│   │   ├── SlideLayout.tsx      # Shared slide wrapper (scaling, padding, background)
│   │   ├── AnimatedText.tsx     # Reusable text entrance animations
│   │   ├── Chart.tsx            # Recharts wrapper
│   │   ├── ImageSlide.tsx       # Image display component
│   │   ├── InteractiveBlock.tsx # For custom interactive UI per slide
│   │   └── ...
│   └── lib/
│       ├── animations.ts    # Shared Framer Motion variants and transitions
│       ├── theme.ts         # Color palette, font sizes, spacing tokens
│       └── useSlideScale.ts # Hook for viewport-fitting scale

---

3. 风格探索 — 氛围与预设

第 1 步：询问用户期望的氛围

在选择颜色和字体之前，询问用户希望观众产生怎样的感受：

氛围	描述
印象深刻 / 充满信心	专业、可信、大胆
兴奋 / 充满活力	创新、大胆、有创意
平静 / 专注	清晰、沉稳、简约
深受启发 / 感动	感性、令人难忘、优雅

第 2 步：选择风格预设

根据氛围，从下表中推荐 2-3 种预设。每种预设都定义了字体、颜色和标志性视觉元素。不要随意混搭——请完整采用一种预设。

深色预设

预设	氛围	标题字体	正文字体	颜色	标志性元素
Bold Signal	充满信心	Archivo Black (900)	Space Grotesk (400)	#1a1a1a 背景、#FF5722 强调卡片、白色文字	以彩色卡片为视觉焦点、大号章节编号、网格布局
Electric Studio	充满信心	Manrope (800)	Manrope (400)	#0a0a0a 背景、#4361ee 强调蓝色、白色文字	双面板垂直分割、边缘强调条
Creative Voltage	充满活力	Syne (700)	Space Mono (400)	#0066ff 主色、#1a1a2e 深色、#d4ff00 霓虹色	电光蓝搭配霓虹黄、半色调纹理
Dark Botanical	深受启发	Cormorant (400) 衬线体	IBM Plex Sans (300)	#0f0f0f 背景、#d4a574 暖色强调、#e8b4b8 粉色	抽象模糊渐变圆、细强调线

浅色预设

预设	氛围	标题字体	正文字体	颜色	标志性元素
Notebook Tabs	条理清晰	Bodoni Moda (700) 衬线体	DM Sans (400)	#f8f6f1 页面、#2d2d2d 外框、多彩标签	深色背景上的纸质卡片、彩色章节标签
Pastel Geometry	亲和友好	Plus Jakarta Sans (700)	Plus Jakarta Sans (400)	#c8d9e6 背景、#faf9f7 卡片、柔和色调胶囊元素	圆角卡片、垂直胶囊元素、柔和阴影
Vintage Editorial	深受启发	Fraunces (700) 衬线体	Work Sans (400)	#f5f3ee 奶油色、#1a1a1a 文字、#e8d4c0 暖色	几何图形（圆形 + 线条 + 点）、粗边框
Swiss Modern	专注	Archivo (800)	Nunito (400)	纯白、纯黑、#ff3300 红色强调	清晰可见的网格、不对称布局、几何图形

专项预设

预设	氛围	字体	颜色	标志性元素
Neon Cyber	科技感	Clash Display + Satoshi	#0a0f1c 藏蓝、#00ffcc 青色、#ff00aa 洋红	霓虹光晕、网格图案、粒子效果
Terminal Green	黑客风	JetBrains Mono	#0d1117 深色、#39d353 绿色	扫描线、闪烁光标、代码美学
Paper & Ink	编辑风	Cormorant Garamond + Source Serif 4	#faf9f7 奶油色、#1a1a1a 炭黑色、#c41e3a 深红色	段首大写字母、引文、优雅的水平分隔线

步骤 3：应用预设

选定后，在 src/lib/theme.ts 中定义完整主题，并在 src/index.css 中定义 CSS 自定义属性：

• 预设中的所有颜色
• 从 Google Fonts 或 Fontshare 加载的字体系列
• 用于背景、强调色和文本颜色的 CSS 变量
• 至少在标题页和章节过渡页中使用预设的标志性元素

---

4. 设计系统 — 杜绝 AI 垃圾风格

排版

• 使用所选预设中的字体搭配。通过 CSS 中的 @import 从 Google Fonts 或 Fontshare 加载字体。
• 字体系列不得超过 2 种。
• 标题：字号大且粗。正文：尽量精简。
• 正文段落绝不能居中对齐。 左对齐或采用有意设计的布局。
• 所有字号都必须使用 clamp(min, preferred, max)，绝不能使用固定的 px/rem 字号。这样可以确保在不同视口尺寸下都清晰易读。

/* Example clamp values */
--title-size: clamp(2rem, 6vw, 5rem);
--subtitle-size: clamp(0.875rem, 2vw, 1.25rem);
--body-size: clamp(0.75rem, 1.2vw, 1rem);

颜色与背景

• 完全采用预设的配色方案，并将其定义为 CSS 自定义属性。
• 营造氛围，而不是使用平淡的纯色。 叠加 CSS 渐变来增加层次感，而非使用单一纯色背景：

/* Layered gradient for depth */
background:
  radial-gradient(ellipse at 20% 80%, rgba(120, 0, 255, 0.15) 0%, transparent 50%),
  radial-gradient(ellipse at 80% 20%, rgba(0, 255, 200, 0.1) 0%, transparent 50%),
  var(--bg-primary);

/* Subtle grid pattern for structure */
background-image:
  linear-gradient(rgba(255,255,255,0.03) 1px, transparent 1px),
  linear-gradient(90deg, rgba(255,255,255,0.03) 1px, transparent 1px);
background-size: 50px 50px;

• 高占比的主色搭配鲜明的强调色，效果胜过保守、均匀分布的配色方案。

布局 — 缩放式幻灯片容器

• 幻灯片采用固定的 1280×720px 容器，通过 CSS transform: scale() 缩放以适应视口（类似 reveal.js）。所有内容都以 1280×720 为画布尺寸编写，并统一缩放。
• 由于使用了变换缩放，Tailwind 基于 rem 的间距在屏幕上会显得更小。 对于需要明显内边距的元素（卡片、标签、带背景的按钮），请使用带 px 值的内联 style={{}}，而不要使用 Tailwind 内边距类。
• 带背景元素的最小内边距：水平标签使用 style={{ padding: '20px 48px' }}，内容卡片使用 style={{ padding: '24px 32px' }}，按钮使用 style={{ padding: '16px 32px' }}。
• 留出充足的空白，让内容有呼吸感。
• 幻灯片区域中最多 60% 应包含内容。 其余部分应作为有意留出的空白。
• 使用 CSS Grid 或 Flexbox。除装饰元素外，避免使用绝对定位。
• SlideLayout 组件负责缩放和居中。

内容密度限制（不可妥协）

每张幻灯片都必须适配 1280×720 容器。内容溢出？拆分为多张幻灯片。切勿硬塞或滚动。

幻灯片类型	内容上限
标题页	1 个标题 + 1 个副标题 + 可选标语
内容页	1 个标题 + 4–6 个项目符号，或 1 个标题 + 2 段简短文字
功能网格	1 个标题 + 最多 6 张卡片（2×3 或 3×2）
图表页	1 个标题 + 1 张图表
引言页	1 条引言（最多 3 行）+ 署名
图片页	1 个标题 + 1 张图片（高度不超过幻灯片的 60%）
交互页	1 个标题 + 交互元素（控制项尽量精简）

视觉规则 — 背景与边框

• 不要将文本内容包在背景卡片中。 让文本直接置于幻灯片背景上。通过间距和排版建立层次，而不是使用方框。
• 不要嵌套背景。 绝不要将一个彩色方框放在另一个彩色方框内。
• 元素必须带背景时（交互按钮、标签、标记）：使用 bg-white/5 和 border border-white/10，绝不使用纯色表面。
• 边框应保持低调。 左侧强调线使用 border-l border-muted/20，绝不使用 border-l-2。容器使用 border border-white/10。
• 不要使用投影，除非是作为特定设计选择的硬阴影（有偏移、无模糊）。
• 不要使用带渐变背景的全圆角徽章。
• 不要使用装饰性斑点、波浪或网格渐变。
• 可以使用几何装饰元素：线条、圆点、简单形状。

切勿使用 — 被禁止的 AI 模式

类别	禁止项
字体	Inter、Roboto、Arial，以及用作展示字体的系统字体。也要避免每套幻灯片都选用 Space Grotesk——请变换选择。
颜色	#6366f1（常见靛蓝色）、白底紫色渐变、柔和的彩虹色，以及平均分布的“安全”配色
布局	所有内容都在垂直堆叠中居中排列、千篇一律的卡片网格、通用的主视觉区块
装饰	写实插画、无谓的玻璃拟态、没有目的的投影、渐变网格背景

如何避免呈现 AI 垃圾内容的感觉

• 使用不对称布局（不要让所有内容都在堆叠中居中排列）
• 用超大字体强调重点
• 有意识地留白
• 内容要有观点和锋芒，避免泛泛而谈的填充内容
• 保持风格一致，但不要单调——在整套幻灯片中变换布局
• 使用真实图片和数据，而非占位插画
• 给观众惊喜——每套幻灯片至少采用 1-2 种出人意料的布局

---

5. 动画 — 以情绪驱动动态效果

让动画契合情绪

情绪	动画风格	视觉线索
戏剧性 / 电影感	缓慢淡入（0.8-1.2s）、大幅度缩放过渡（0.9→1）	深色背景、聚光灯效果
科技感 / 未来感	霓虹光晕、文字扰乱 / 显现效果	网格图案、等宽字体点缀、青色 / 洋红色
活泼 / 友好	弹性缓动（轻柔弹簧）、漂浮效果	圆角、鲜艳色彩
专业	细微快速的动画（200-300ms）、简洁的幻灯片	精确间距、聚焦数据可视化
平静 / 极简	极慢的细微动态效果、柔和淡入	大量留白、柔和配色、衬线字体
编辑风格	文字依次显现、图片与文字交错呈现	鲜明的字体层级、引述、突破网格的布局

Framer Motion 默认设置

• 默认时长：0.4–0.6s。 避免使用超过 0.8s 的动画（电影感情绪除外）。
• 默认缓动：[0.25, 0.1, 0.25, 1]（平滑减速，相当于 ease-out-expo）
• 子元素的错开间隔设为 0.08–0.12s，不要更长

幻灯片过渡

• 幻灯片切换时使用 AnimatePresence，并设置 mode="wait"
• 幻灯片进入：淡入 + 轻微向上平移（20px）或向右平移（30px）
• 幻灯片退出：快速淡出（0.2s）
• 幻灯片过渡中不要使用 3D 变换、旋转或缩放弹跳

内容动画（幻灯片内部）

• 标题：先淡入并向上平移
• 辅助内容：标题出现后，依次淡入
• 图表 / 图片：淡入并从 0.95 轻微缩放至 1
• 使用 variants 模式编排动画：

const container = {
  hidden: { opacity: 0 },
  show: {
    opacity: 1,
    transition: { staggerChildren: 0.1 }
  }
};

const item = {
  hidden: { opacity: 0, y: 20 },
  show: { opacity: 1, y: 0, transition: { duration: 0.5, ease: [0.25, 0.1, 0.25, 1] } }
};

渐进式揭示

• 部分幻灯片应分步揭示内容（点击即可在幻灯片内进入下一步）
• 需要时，为每张幻灯片跟踪一个 step 状态
• 根据当前步骤为项目设置进出动画
• 幻灯片包含多个步骤时，显示细微的进度指示器（圆点或细条）

禁止事项

• 不要使用带有强烈弹跳效果的 spring（阻尼不足的弹簧看起来像玩具）
• 不要在文字上使用 rotate 动画
• 不要使用持续循环的动画（交互元素上极细微的脉动效果除外）
• 不要在幻灯片内使用视差滚动
• 不要给每个元素都添加动画——有些内容应该直接呈现
• 每张幻灯片精心编排一次入场效果，胜过零散的微交互

支持 prefers-reduced-motion

始终提供减少动态效果的支持。为动画变体添加封装：

const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

const item = prefersReducedMotion
  ? { hidden: { opacity: 0 }, show: { opacity: 1 } }
  : { hidden: { opacity: 0, y: 20 }, show: { opacity: 1, y: 0, transition: { duration: 0.5 } } };

---

6. 幻灯片类型与组件

标题幻灯片

• 使用 clamp(2.5rem, 6vw, 5rem) 设置超大标题
• 可选副标题
• 可选日期或演讲者姓名
• 简洁、有冲击力的布局
• 使用预设的标志性元素（彩色卡片、分栏面板、几何图形等）

内容幻灯片（文字）

• 标题 + 2–5 条简短要点，或一段简短文字
• 要点应以错开的方式逐条出现
• 文字左对齐，右侧可放置辅助视觉元素
• 最多 4-6 条要点。 超出时拆分成两张幻灯片。

图片幻灯片

• 使用铺满画面或大尺寸内嵌图片
• 用户将图片放在 public/images/ 中
• 引用格式为 /images/filename.ext
• 图片最大高度：幻灯片高度的 60%（720px 高度时为 432px）
• 支持在图片下方或叠加在带半透明背景的图片上显示说明文字
• 图片采用延迟加载

图表幻灯片

• 使用 Recharts（BarChart、LineChart、PieChart、AreaChart）
• 图表样式需与演示文稿主题匹配——从预设中选用自定义颜色，不使用 Recharts 默认样式
• 使用 Framer Motion 包装器为图表添加入场动画
• 添加清晰的标签和标题

对比幻灯片

• 使用并排布局或前后对比布局
• 使用清晰的视觉分隔线（强调色线条，而非粗重边框）
• 先为左侧面板添加动画，再为右侧面板添加动画

引言／标注幻灯片

• 使用 clamp(1.5rem, 3vw, 2.5rem) 设置大号文字，居中或左对齐
• 使用强调色或背景
• 在下方以较小字号标注出处
• 引言最多 3 行。

交互式幻灯片

• 适用于需要自定义 UI 的幻灯片（投票、切换开关、演示、游戏）
• 构建为带本地状态的独立组件
• 添加 data-interactive 属性，防止点击时意外切换幻灯片
• 使用清晰的视觉提示表明内容可交互（悬停状态、光标）

链接引用

• 外部 URL：渲染为样式化链接，并在新标签页中打开（target="_blank"）
• 本地文件夹链接：渲染为 file:/// 协议链接，并添加文件夹图标
• 为链接设置醒目的样式——使用下划线和强调色，不使用默认蓝色

---

7. 导航与控件

• 键盘： 右箭头键／空格键／Enter = 下一张，左箭头键 = 上一张
• 点击／轻触： 点击右半边 = 下一张，点击左半边 = 上一张（跳过带有 data-interactive、button、input 的元素）
• 进度条： 底部的细条，用于显示演示文稿中的当前位置
• 幻灯片计数器： 右下角的小型“3 / 28”指示器
• 支持在前往下一张幻灯片前，通过 step 在幻灯片内进行子导航
• Escape 键： 切换概览模式（幻灯片缩略图网格）——建议支持，但 v1 非必需

---

8. 内容指南

请参阅此目录中的 slide-guidelines.md，了解教学结构：

• 问题 → 讨论 → 概念 → 示例 → 要点循环
• 每张幻灯片只讲一个想法
• 视觉优先，文字精简
• 标题简短（6–8 个词）
• 复杂信息逐步呈现
• 60–70% 为视觉类幻灯片，10–15% 为图表／示意图，15–20% 为文字说明

创建幻灯片前，必须向用户询问实际内容／主题。 上述内容指南描述的是结构，而非幻灯片中应包含的内容。

---

9. 构建与运行

npm create vite@latest . -- --template react-ts  # Only if starting fresh
npm install
npm run dev

应用应能通过 npm run dev 运行，并可在 localhost 中查看。不得有构建错误或 TypeScript 错误。

---

10. 质量检查清单

交付任意一批幻灯片前，请确认：

• npm run dev 启动时无错误
• TypeScript 编译无误（npx tsc --noEmit）
• npx vite build 成功
• 所有动画均以 60fps 流畅运行
• 幻灯片内容均在 1280×720 范围内——无内容溢出，不滚动
• 每种幻灯片类型的内容密度均在限制范围内
• 不含“Lorem ipsum”或“Your content here”等占位文字
• 配色方案一致，并与所选预设相匹配
• 字体可从 Google Fonts / Fontshare 正确加载
• 幻灯片中引用的图片均存在于 public/images/ 中
• 交互元素具有悬停／焦点状态
• 导航功能正常：键盘、点击和进度条保持同步
• 文字内容不放在背景卡片中——文字直接显示在幻灯片上
• 不使用嵌套背景（框中套框）
• 所有带背景的元素均通过内联 style={{}} 提供充足内边距，而非使用 Tailwind 类
• 边框保持柔和——使用 border-white/10、border-muted/20，绝不使用纯色表面色
• 所有字号均使用 clamp()——不为文字设置固定 px/rem
• 背景应有层次感——使用分层渐变或图案，不使用纯色

11. 工作流

1. 询问用户的情绪和内容 — 想要什么感觉？什么主题？需要多少个模块？
2. 选择样式预设 — 根据情绪推荐 2–3 种，让用户选择
3. 搭建应用 — 设置 Vite、Tailwind、Framer Motion、项目结构、基于预设的主题和共享组件
4. 分批构建幻灯片 — 每次实现 5–10 张幻灯片，然后请用户审核
5. 迭代 — 根据反馈进行调整
6. 图片 — 如果幻灯片需要图片，告诉用户需要什么图片，以及图片应放置的位置（public/images/）。使用带文件名的可见占位符，让用户知道缺少什么。

始终确保应用处于可运行状态。不要留下损坏的导入项或缺失的文件。