promptslide

PromptSlide

使用 AI 编码 Agent 创建幻灯片。每张幻灯片都是使用 Tailwind CSS 设置样式的 React 组件，并内置动画和 PDF 导出功能。

检测模式

检查当前目录中是否已存在 PromptSlide 项目：

grep -q '"promptslide"' package.json 2>/dev/null

• 找到匹配项 → 这是一个现有的 PromptSlide 项目。前往编写幻灯片。
• 未找到匹配项 → 尚无项目。前往创建新演示文稿。

---

创建新演示文稿

步骤 1：了解内容

编写任何代码之前，先询问用户：

1. 这份演示文稿的主题是什么？（主题、关键信息）
2. 受众是谁？（投资者、团队、客户、会议参会者）
3. 需要多少张幻灯片？（建议重点演示文稿采用 5–10 张，详细演示文稿采用 10–15 张）
4. 是否已有准备好的内容？（大纲、要点，还是由 Agent 起草）

根据回答规划幻灯片结构，然后再搭建项目框架。

步骤 2：确定风格方向

编写任何代码之前，先确定视觉方向：

1. 询问是否有品牌指南——包括徽标、颜色、字体。如果有，直接使用。
2. 如果没有品牌指南，从 references/style-presets.md 中推荐 2–3 种预设。简要介绍每种预设（一句话加上氛围），让用户选择或混搭。
3. 如果用户想要自定义风格，询问：偏暗色还是浅色？想要什么氛围？（专业、活泼、戏剧化、科技感）。然后基于预设中的构成要素打造自定义风格。

所选方向决定了步骤 3–4 中的配置：

• 颜色 → src/globals.css（--primary 和其他 CSS 变量）
• 字体 → index.html 中的 <link> + src/theme.ts 中的 fonts
• 布局 → src/layouts/ 中的自定义 React 组件（见下方布局）
• 卡片样式和动画 → 根据方向应用于每张幻灯片

预设只是起点，并非僵化的模板。用户可以更改所有内容——它们都只是 React 组件和 CSS 变量。

步骤 3：搭建项目并启动

npm create slides my-deck -- --yes
cd my-deck
npm install
npm run dev

--yes 标志会跳过交互式提示并采用合理的默认值。将 my-deck 替换为用户想要的名称。开发服务器将在 http://localhost:5173 启动，并支持热模块替换。

步骤 4：配置品牌

编辑 src/theme.ts 中的品牌名称和徽标，并编辑 src/globals.css 中的主题颜色。详情请参阅 references/theming-and-branding.md。

步骤 5：设计思考

编写任何幻灯片代码之前，先确定明确的美学方向，并从整体上规划整份演示文稿。千篇一律、像模板一样的幻灯片还不如不做。

选择方向并贯彻到底

选择鲜明的视觉个性——编辑风、粗野主义、奢华极简、大胆几何、温暖自然——并在整份演示文稿中精准贯彻。关键在于有意识地设计，而不在于追求强烈效果。只要间距和排版完美克制，简约演示文稿也能和大胆繁复的演示文稿一样出色。犹豫不决才会毁掉演示文稿：什么都来一点，却没有任何一种风格贯彻到底。

根据内容设计每张幻灯片

• 这部分内容适合呈现成什么样？ 一个有力的数据值得单独放大呈现。对比内容适合分成两侧。功能列表可以用简洁的排版和留白呈现——不是什么内容都需要卡片。
• 整套幻灯片的节奏如何？ 在信息密集与宽松、深色与浅色、规整与自由之间交替。连续三张白色幻灯片会显得单调。可以用深色的「喘息」页、铺满页面的色块，或非对称布局打破连贯重复的节奏。
• 精彩时刻在哪里？ 每套幻灯片都需要 1–2 张打破常规的页面——放大的数字、大胆的色块，或一句留白充足的短句。这些才是观众会记住的内容。
• 怎样才能让这套幻灯片令人难忘？ 编写代码前先问这个问题。如果答案是「没有」——说明设计方向还不够鲜明。

不要默认采用第一个想到的布局。为每张幻灯片考虑 2–3 种方案，并选择最能传达内容的方案。

编写代码前，先向用户分享设计计划。 简要说明视觉方向、配色策略，以及每张幻灯片的布局方案（例如：「第 3 张：非对称双栏布局，放大的数据置于醒目位置」「第 7 张：深色主视觉页——整套幻灯片中最重要的一页」）。让用户确认或提出调整——不要自行决定后就直接开始制作。

第 6 步：创建幻灯片

从 src/slides/ 中移除演示幻灯片，并清空 src/deck-config.ts，然后按照下方的编写说明操作。

---

编写幻灯片

开始编写幻灯片前

无论是新建还是已有的幻灯片组，在创建幻灯片文件前都要先与用户确认视觉方向。脚手架可能已经配置了用户的主色——未经询问不要覆盖。

编写任何幻灯片代码前，先向用户展示设计计划。 计划应包括：

1. 整体视觉方向——氛围、配色策略，以及主色的使用方式（谨慎使用以突出重点，而非用于每个元素）
2. 每张幻灯片的布局方案——不只是「卡片」，还要说明具体的构图（例如：「非对称分栏布局，左侧放置放大的数字，右侧放置说明」）
3. 哪些幻灯片将作为打破常规的「精彩时刻」
4. 字体选择，以及它为何适合这套幻灯片的个性

为每张幻灯片考虑最适合呈现其内容的方式。设计原则和应避免的反模式，请参阅 references/slide-design-guide.md。

架构

src/
├── layouts/           # Slide layouts — your "master themes", create freely
├── slides/            # Your slides go here
├── theme.ts           # Brand name, logo, fonts
├── deck-config.ts     # Slide order + step counts
├── App.tsx            # Theme provider
└── globals.css        # Theme colors (CSS custom properties)

重要限制

• 幻灯片尺寸：1280×720（16:9）。在演示模式下，内容会自动缩放。
• 语义颜色：使用 text-foreground、text-muted-foreground、text-primary、bg-background、bg-card、border-border——这些会映射到主题的 CSS 自定义属性。
• 图标：从 lucide-react 导入（例如，import { ArrowRight } from "lucide-react"）。

创建幻灯片

每张幻灯片都是一个接收 SlideProps 的 React 组件：

// src/slides/slide-example.tsx
import type { SlideProps } from "promptslide";

export function SlideExample({ slideNumber, totalSlides }: SlideProps) {
  return (
    <div className="bg-background text-foreground flex h-full w-full flex-col p-12">
      <h2 className="text-4xl font-bold">Your Title</h2>
      <div className="flex flex-1 items-center">
        <p className="text-muted-foreground text-lg">Your content</p>
      </div>
    </div>
  );
}

在 src/deck-config.ts 中注册：

import type { SlideConfig } from "promptslide";
import { SlideExample } from "@/slides/slide-example";

export const slides: SlideConfig[] = [{ component: SlideExample, steps: 0 }];

布局（母版主题）

布局是 src/layouts/ 中用于包裹幻灯片内容的 React 组件。它们控制结构（页眉、页脚、背景、内边距），最接近传统工具中的「母版幻灯片」。修改一次布局，所有使用该布局的幻灯片都会随之更新。

每套幻灯片创建 2–4 种布局，以丰富视觉变化。

脚手架项目包含作为起始布局的 SlideLayoutCentered。可以自由创建新布局——它们只是 React 组件。用户可以自定义内边距、背景、页眉样式，也可以添加全新的结构模式。

动画

使用 <Animated> 实现点击逐步显示，使用 <AnimatedGroup> 实现交错显示。可用的动画：fade、slide-up、slide-down、slide-left、slide-right、scale。

重要规则：

• deck-config.ts 中的 steps 值必须等于该幻灯片使用的最高 step 数。steps: 0 表示不使用动画。
• <Animated> 会渲染一个包装 <div>。在 grid 或 flex 容器中使用时，必须通过 <Animated> 的 className 传入布局类（h-full、w-full、col-span-*），不能只传给内部子元素，否则包装元素会收缩并破坏布局。

完整动画 API 请参阅 references/animation-api.md。

样式限制（PDF 兼容性）

以下规则可确保幻灯片在屏幕上和导出为 PDF 后的效果一致：

• 不使用模糊效果：Chromium 的 PDF 处理流程会直接丢弃 filter: blur() 和 backdrop-filter: blur()
• 不使用渐变：bg-gradient-to-* 和径向渐变的渲染效果不一致，请改用带透明度的纯色（例如 bg-primary/5、bg-muted/20）。如果需要柔和的径向辉光效果，项目提供了 /public/images/glow-white.png，可将其作为绝对定位的图像放置——详情请参阅主题设置参考。
• 不使用阴影：box-shadow（包括 shadow-sm、shadow-lg、shadow-2xl）无法正确导出为 PDF，请改用边框或背景色调（例如 border border-border、bg-white/5）

有关内容密度规则、设计原则和视觉反模式，请参阅 references/slide-design-guide.md。

视觉验证

创建或修改幻灯片后，可以截取屏幕截图，直观验证其渲染效果是否正确。有关 promptslide to-image 命令和工作流，请参阅 references/visual-verification.md。

注释（用户反馈）

用户可以在浏览器中点击幻灯片元素留下注释——附加到特定 DOM 元素的文本反馈。注释存储在项目根目录下的 annotations.json 中。

读取注释

开始工作前，请检查是否有注释：

cat annotations.json 2>/dev/null

每条注释包含：

• slideIndex — 幻灯片索引（从 0 开始，与 deck-config.ts 中的顺序一致）
• slideTitle — 易于理解的幻灯片名称
• target.selector — 指向幻灯片内该元素的 CSS 选择器
• target.textContent — 目标元素的文本内容
• target.dataAnnotate — 如果元素具有 data-annotate 属性，则为稳定标识符
• body — 用户反馈
• status — "open" 或 "resolved"

处理注释

处理完反馈后，将注释的 status 更新为 "resolved"，并可选添加 resolution 说明所做的更改。直接编辑 annotations.json。

添加 data-annotate 属性

创建幻灯片时，请为关键元素（标题、功能卡片、统计信息块）添加 data-annotate="descriptive-name"，使注释在编辑后更稳定：

<h2 data-annotate="main-title" className="text-4xl font-bold">Title</h2>
<div data-annotate="feature-card-1" className="rounded-2xl bg-card p-6">...</div>

发布元数据

完成所有幻灯片的编写后，使用 deckMeta（标题、描述、3–6 个标签）和每张幻灯片的 meta 条目（标题、标签、章节）更新 .promptslide-lock.json 中 items 下的内容。这些内容会在用户运行 promptslide publish 时作为预填默认值。请先读取现有锁定文件，再进行合并——不要覆盖其他字段。