marp-deck-visual-designer

Marp 视觉设计师

目的

将现有的演示文稿计划转化为 MARP 演示文稿的视觉与布局执行方案。

此技能：

• 保留幻灯片意图和顺序
• 从演示文稿模板的完整模式库中定义具体布局
• 将计划中的视觉内容具体化为 Mermaid 图表或 Excalidraw 绘图，并为每项视觉内容选择最合适的形式

此技能不得：

• 重新规划演示文稿
• 修改关键信息
• 添加或删除幻灯片
• 引入新概念

演示文稿计划具有权威性。

---

输入

• planning/deck-plan.md — 由 marp-deck-planner 生成
• .marp/references/deck-template.md — 必读参考：定义所有可用的布局模式、类名、HTML 结构和内容容量。分配任何布局前，必须通读全文。

---

输出格式

生成一个 Markdown 文件，并保存为：planning/deck-visual-design.md

使用 -- 作为幻灯片之间的分隔符，并严格遵循计划中的顺序。

---

幻灯片结构

每张幻灯片都输出：

• ## Title
• ## Layout
• ## Content placement
• (可选) ## Image

章节分隔幻灯片只能包含：

• ## Section
• ## Layout

---

工作流程

0. 阅读演示文稿模板（必须首先执行）

在做出任何布局决策之前，必须通读 .marp/references/deck-template.md。

此文档是以下内容的权威来源：

• 所有可用的 CSS 类和布局模式
• 有效的类标记组合
• 各模式所需的 HTML 结构
• 各模式的内容容量（项目符号、卡片、列）

项目符号列表是最后的布局选择。 只有在演示文稿模板中没有适合内容的模式时，才使用单列项目符号列表。对于每张幻灯片，都要主动寻找更丰富的匹配模式：

内容类型	首选模式
4 条并列发现／见解	insight-cards（2×2 网格）
3 个包含数字 + 标签 + 描述的项目	numbered-cards
3–5 个横向步骤	timeline-steps
3 个带连接线的连续阶段	phase-cards
4–6 行堆叠的标签 + 描述	feature-layers
目录	toc-rows
2 个对比区块	columns two-col duo 或 columns compare split-panels
文本 + 图表／图像	visual-split
文本 + 辅助统计数据或引言	使用 highlight-box 的 highlight-layout
单个大型重点信息	使用 impact-list 的 hero
数据网格／对比表	HTML <table>
6 个重点领域	labs-grid

适合更丰富的模式时，必须使用该模式，不要退回项目符号列表。

---

1. 保留结构和顺序

• 严格遵循计划中的幻灯片顺序
• 不得重命名、合并或拆分幻灯片
• 章节幻灯片必须保持为章节幻灯片

---

2. 明确指定布局

在 ## Layout 中注明：

• 首先列出幻灯片类标记（必填），严格使用以下行格式：
  • Slide class: content ...（例如：Slide class: content visual-split no-top-accent）
• 从演示文稿模板中选择布局类型（不得使用自由形式的描述）
• 适用时注明相对比例（例如 60/40 分栏）
• 视觉层级（主要区域与次要区域）

使用 .marp/references/deck-template.md 中具体且兼容 MARP 的类名。

避免抽象或仅涉及美学的描述。

---

3. 有意安排内容位置

在 ## Content placement 中说明：

• 使用了哪种演示文稿模板模式，以及其 HTML 容器类
• 各内容区块在该模式中的位置
• 项目如何分组为卡片、行、列或重点信息框
• 强调规则（高亮、要点、页脚注释）

不得改写或扩展内容。

---

4. 将视觉内容具体化

如果计划中对应的幻灯片包含 ## Image 部分：

4.1 确定视觉呈现方式

创建任何文件之前，请根据以下标准选择格式：

适合使用 Mermaid 的情形：

• 视觉内容是顺序流程、过程或状态机
• 结构可清晰映射为流程图／图中的节点与边
• 层级或方向关系是核心含义
• 示例：管道步骤、架构依赖图、序列图

适合使用 Excalidraw 的情形：

• 视觉内容是没有主要方向的辐射状网络或有机网络
• 想法无法映射到 Mermaid 定义的图表类型（没有清晰的源→目标边）
• 空间布局或分组能够传达含义（例如，集群、邻近关系）
• 与严格的图形相比，自由形式的草图风格更适合内容
• 示例：团队／实验室组织图、生态系统图、概念概览

---

4.2 生成 Mermaid 图表（适用时）

如果计划中的视觉内容最适合用图表表示：

• 创建 Mermaid 图表源文件：diagrams/<diagram-name>.mmd
• 图表必须直接反映计划中的视觉描述
• 图表应保持简洁易读

Mermaid 样式（必需）

所有 Mermaid 渲染都使用共享的演示文稿配置：

• .marp/references/mermaid-config.json

规则：

• 不要依赖 Mermaid 的默认颜色。
• 图表整体应以中性色为主，并使用单一强调色（由配置设置）。
• 仅在表达含义时使用额外的 classDef 样式，并确保与 mermaid 配色方案保持一致：
  • 主边框／线条颜色：#da291c（SO 强调色／red-500）
  • 文本：#3d3935（merlin）
  • 弱化色：#716b5d（merlin-600）

图表规则（必需）

• 先选择幻灯片类，再设计适配的图表：
  • 默认：visual-split
  • 如果渲染后的 PNG 宽高比 > 2.8：添加 image-wide
  • 如果渲染后的 PNG 宽高比 < 0.8：添加 image-tall
• 尽可能将图表宽高比控制在 1.1 至 2.6 左右（最适合 visual-split）。
• 每张幻灯片保留 一个 图表／图片，除非明确计划使用网格布局。
• 标签应简短：
  • 每行尽量不超过 4 个词
  • 长文本应强制换行（在 Mermaid 标签中使用 <br/>）
• 流程方向：
  • 4 个及以上节点时优先使用 flowchart TB
  • 仅在从左到右的含义至关重要时使用 LR
• 避免过长的单通道链；拆分为紧凑的分组／子图，以减少过宽问题。
• 循环图应使用紧凑的循环形状，而非拉伸的水平循环。

编写 .mmd 文件后：

• 渲染图表：

  • 首选：task mermaid-file FILE=diagrams/<diagram-name>.mmd
  • 或重新构建所有图表：task mermaid

• 在渲染演示文稿前验证渲染后 PNG 的尺寸：

  • task mermaid-check-file FILE=diagrams/<diagram-name>.mmd
  • 如果图表过扁或过高，请先调整 .mmd 结构（方向、分组、标签换行），然后重新渲染。

• 在 ## Image 中按以下格式引用生成的图片：images/<diagram-name>.png

规则：

• 图表名称必须具有确定性且能描述内容
• 除非明确要求，每张幻灯片仅放置一个图表
• 不要为了装饰而生成图表

如果视觉内容不属于图表类型，请仅描述它，不要生成文件。

---

4.3 生成 Excalidraw 绘图（适用时）

如果 4.1 中的决策标准选择了 Excalidraw：

文件命名

• 创建：diagrams/<diagram-name>.excalidraw
• 名称必须具有确定性且能描述内容（使用小写字母和连字符）

导出工具

task excalidraw-file 使用 node .marp/scripts/render-excalidraw.js 进行渲染，并依赖 @napi-rs/canvas（Node 18+）。无需 Docker。

前置条件 — 项目根目录中必须存在 package.json。 每次渲染前，task excalidraw-file 都会运行 npm install。如果项目中没有 package.json，安装会静默失败（退出码 254），且不会生成 PNG。

首次运行 task excalidraw-file 前，请检查该文件是否存在：

ls package.json 2>/dev/null || echo "missing"

如果不存在，请创建该文件：

{
  "name": "deck-builder",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@napi-rs/canvas": "^0.1.65"
  }
}

然后在调用该任务前手动运行一次 npm install。 后续调用 task excalidraw-file 时会复用已安装的模块。

有效的 JSON 结构

.excalidraw 文件必须是符合架构版本 2 的有效 JSON：

{
  "type": "excalidraw",
  "version": 2,
  "source": "marp-visual-designer",
  "elements": [ ... ],
  "appState": {
    "gridSize": 20,
    "gridStep": 5,
    "gridModeEnabled": false,
    "viewBackgroundColor": "#ffffff"
  },
  "files": {}
}

元素编写规则

形状 — 大多数节点使用 rectangle；只有当节点是真正的径向中心，且辐射线向各个方向延伸时，才使用 ellipse。

两者都必须包含以下属性： id、type、x、y、width、height、angle: 0、strokeColor、backgroundColor、fillStyle: "solid"、strokeWidth、roughness: 0、opacity: 100、groupIds: []、isDeleted: false、boundElements: [...]、locked: false

文本标签 — 每个形状使用一个 text 元素，其 containerId 指向父元素：

• x、y、width、height 必须与父形状完全一致
• 额外的必需属性：text、fontSize: 14、fontFamily: 1、textAlign: "center"、verticalAlign: "middle"、containerId: "<shape-id>"、originalText: "<same as text>"、lineHeight: 1.25
• 父形状的 boundElements 必须包含 {"type": "text", "id": "<text-id>"}
• 多行文本：在 JSON 字符串值中使用字面换行符 \n

箭头 — 对于静态导出，始终使用空绑定和明确的坐标 points：

• startBinding: null、endBinding: null
• startArrowhead: null、endArrowhead: "triangle_outline"
• points 是相对于箭头自身 x、y 的 [dx, dy] 偏移量数组 — 第一个点始终为 [0, 0]
• 从 A 的右侧指向 B 的左侧的直线箭头：将箭头的 x, y 设为 A 的右侧中点；points: [[0, 0], [gap, 0]]
• 折线连接器（例如换行到下一行）：使用 4 点路径： points: [[0, 0], [0, down], [left_offset, down], [left_offset, down + drop]] 其中 down 是垂直中点，left_offset 为负值（向左移动）

必需属性：id、type、x、y、width、height、angle: 0、strokeColor、backgroundColor: "transparent"、fillStyle: "solid"、strokeWidth: 2、roughness: 0、opacity: 100、groupIds: []、isDeleted: false、boundElements: []、locked: false、points、startBinding、endBinding、startArrowhead、endArrowhead

分组：将同一个字符串赋给逻辑组中所有元素的 groupIds 数组

品牌配色（必须遵循）

用途	颜色
主中心 / 主要概念	描边 #da291c，填充 #ffffff，描边宽度 3
次级节点 / 卡片	描边 #716b5d，填充 #f4f4f2，描边宽度 2
强调元素（例如终端 / 结果节点）	描边 #e35205，填充 #ffffff，描边宽度 2
文本	#3d3935
流程箭头（同一行）	描边 #3d3935
行间折线连接器	描边 #da291c
背景	#ffffff

宽高比预测（导出前使用）

.marp/scripts/render-excalidraw.js 使用固定的每侧 PADDING = 24px 和 scale = 2×。导出前，请使用以下精确公式预测导出的 PNG 尺寸：

content_width  = max(element.x + element.width)  − min(element.x)   [all non-arrow elements]
content_height = max(element.y + element.height) − min(element.y)    [all non-arrow elements]

exported_width  = (content_width  + 48) × 2   [exact: PADDING=24 each side, 2× scale]
exported_height = (content_height + 48) × 2   [exact: same]

predicted_ratio = (content_width + 48) / (content_height + 48)
                  [the ×2 cancels; ratio is scale-independent]

设计规则：将 predicted_ratio 设为 1.8–2.4，以获得舒适的 visual-split 布局效果（远低于 1.1–2.6 的安全范围）。公式精确，不存在舍入误差。采用推荐的 inter_row_gap ≈ 1.4 × node_height 作为起点时，使用 150×75 px 节点的 3+3 双行布局自然会得到约 1.81 的宽高比，首次尝试即可落在目标范围内。

空间布局指南

• 单行链（最多 4 个节点）：从左到右放置节点，间隔 20–30px；节点之间使用直箭头。
• 多行链（5 个或更多节点，或单行宽高比会 > 2.6 时）：拆分为长度相等或接近的 2 行。
  • 第 1 行：y = 30；第 2 行：y = 30 + node_height + inter_row_gap
  • 选择 inter_row_gap，使 predicted_ratio 落在 1.8–2.4：inter_row_gap ≈ (1.4 × node_height) 是可靠的起点
  • 使用红色折线箭头连接第 1 行的最后一个节点与第 2 行的第一个节点：
    • 起点位于第 1 行最后一个节点的底部中心
    • 终点位于第 2 行第一个节点的顶部中心
    • 中点：从起点向下 inter_row_gap / 2
  • 如果第 2 行的节点少于第 1 行，则将第 2 行水平居中
• 每个节点的基准尺寸为 宽 140–160px × 高 70–80px。

导出与验证

写入 .excalidraw 文件后：

1. 使用上述公式预测宽高比；如有需要，请在导出前调整布局。
2. 导出：task excalidraw-file FILE=diagrams/<diagram-name>.excalidraw
3. 验证实际 PNG 尺寸：task mermaid-check-file FILE=diagrams/<diagram-name>.excalidraw
   • 无论源格式是什么，验证脚本都会读取 PNG IHDR 字节。
4. 如果实际宽高比不在目标范围内：调整 inter_row_gap 或节点位置，然后重新导出。

在 ## Image 中按以下格式引用生成的图像：images/<diagram-name>.png

规则：

• 图表名称必须稳定且具有描述性
• 每张幻灯片一个图表，除非有明确要求
• 不要为了装饰而生成图表

---

5. 遵守 MARP 限制

所有布局和视觉内容都必须兼容：

• 静态 Markdown 幻灯片
• 基于 CSS 的主题
• PDF / HTML 导出

避免：

• 动画
• 交互
• 分层或动态视觉效果

---

章节分隔幻灯片

对于章节幻灯片：

• 只提供最简布局指导，例如：
• “章节标题居中，占满整张幻灯片”
• “极简分隔页，不添加其他元素”

章节幻灯片不要包含视觉内容或图表。

---

质量检查（必须）

定稿前：

• 在指定布局前，已阅读 .marp/references/deck-template.md
• 没有幻灯片使用要点列表来呈现更适合采用 deck-template 模式的内容
• Mermaid 与 Excalidraw 的选择依据内容结构，而非个人偏好
• 幻灯片顺序与计划完全一致
• 没有引入新信息或新解读
• 图表严格反映计划中的视觉内容
• 所有生成的图表都已正确引用
• 输出可立即用于 MARP 演示文稿制作
• PDF QA：如果标签在正常缩放比例下难以辨认，先修正图表结构，而不只是调整 CSS

结果必须可直接执行，而非探索性内容。