ppt-master 可视化模板编写指南Chart 与 Table 模板库的中性预览合同、结构规则与验证流程【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master本文基于 ppt-master 仓库中的维护者指南VISUALIZATION_TEMPLATE_AUTHORING.md展开系统讲解templates/charts/与templates/tables/两个 Visualization catalog family 的编写合同模板的所有权边界、中性预览规范、语义压缩要求、data-pptx-bounds分组约定、Native Chart/Table 替换标记以及占位内容注册与迁移边界。读完后你将能够独立编写或修改一个符合该库结构合同、可通过svg_quality_checker.py与visualization_recall.py validate双验证的可视化模板并理解“Structure 是方法而非目录”“Visualization 不是 Layout”这两条贯穿全库的设计决策。1. 文档定位与两条硬规则templates/charts/和templates/tables/共同组成 ppt-master 的 page-local Visualization 模板库。模板只负责数据编码或单元格关系不负责最终项目风格它们必须保持源码可读、独立可渲染并允许 Executor 根据项目 Design Spec 与spec_lock.md重做字体、配色和装饰。先给出 family 判定表这是后续一切编写决策的分流依据分类定义判定边界chart数值驱动的可视化数值、类别、时间、权重或持续时间决定 mark 的位置、长度、面积、角度、字号或连接宽度table行 × 列事实网格行头与列头共同寻址一个单元格事实合并、对齐和边界保持该交点关系在此之上文档确立了两条贯穿全文的硬规则Structure 是一种方法不是目录。定性顺序、层级、角色、分区和关系由 executor-structure.md 在当前页面现场构形不登记固定structure/key、SVG roster 或 index。Default 和 Quick 路径都先判断页面真实信息模型需要定性拓扑时都必须采用这套 Structure 方法。删除 catalog 只删除固定示例不删除 Quick 或 Default 的 Structure 能力。Visualization 不是 Layout。Chart/Table 模板和运行时 Structure 都不拥有data-pptx-master、data-pptx-layout、data-pptx-layer或data-pptx-placeholder。跨页 Master/Layout、page type、slot geometry 和 placeholder 合同属于 layouts/ 或 decks/ workspace两者共存时仅由 Layout 覆盖 Deck 的结构分段。2. 上游规范不重复定义第二套 SVG 规范本指南只定义 Chart/Table 两个 catalog family 的结构与中性预览合同。通用 SVG 语法、效果、原生数据接口和 PowerPoint 结构分别由以下权威文件定义冲突时一律以上游为准合同权威文件通用 SVGshared-standards.md效果与兼容输入svg-effects.mdNative Chart/Tablenative-data-interface.md画布格式canvas-formats.md这条规则的实操意义是编写模板时不要在模板文件内“就地发明”语法细节所有语法争议回到上表四个文件裁决。3. 所有权边界3.1 作者合同与项目消费所有权划分只约束库内单个模板工件的维护不把工件变成项目页面的布局锁单个 Visualization 模板的作者合同项目页面决策拥有该工件的 family 与相应信息模型最终采用的页面级结构、类型与几何该工件内的数据映射或单元格关系项目字体、字号、调色板与品牌色该工件的示例骨架和阅读顺序实际分组、框架数量、项目数量、组合方式与容量适配必要的状态与语义区分页面背景、页头、页脚和品牌 chrome独立预览所需的中性样式最终强调策略与页面级视觉层级由此派生两条硬规则编写完整性维护某个库模板时必须保持该模板自身的 family 与信息模型Chart 的数值映射、Table 的行 × 列事实网格。若修改结果属于定性关系拓扑不新增第三类模板而由 runtime Structure 方法构建若仍属于另一 catalog family应登记到正确 family不能保留错误标签。最终视觉样式来自使用它的项目而不是模板的示例审美。灵活的项目引用Executor 选中的family/key仍只是灵活的页内引用。Default 的 §IX 或 Quick 的页面决策拥有最终结构选中引用不会锁死页面的可视化类型、几何、分组数、项目数或组合方式。项目若实际采用某一信息模型必须保持其真实数据与关系准确仅有引用本身不构成页面结构权威。3.2 保留判断对模板里的每个视觉元素按顺序判断判断处理删除后会改变数据含义、关系、状态或阅读顺序保留删除后会弱化分组、层级、边界或文本容量保留结构表达只简化不承载信息的样式层只让示例显得更精致、立体、品牌化或“高级”作为简化候选通过文本与前后渲染核对后再删除只对某个项目风格成立交给 Executor 重建默认——信息优先优先使用清楚的线、面、标签和留白装饰不能成为理解信息的前提语义需要时可以覆盖。3.3 保真优先先保真再瘦身三条硬规则约束模板瘦身行为先保真再瘦身瘦身不得改写或删除原有可见标题、标签、说明、数值、单位、状态、来源、顺序、容量和关系。占位内容保持原文只有明确重复的信息可以删除并记录理由。显式迁移例外经明确批准的 family/key 合并、重组或退役可以用中性占位内容重建 canonical SVG或移除不再存活的工件——这不是普通模板瘦身。迁移必须在第 8 节记录 catalog 边界和仍可读取的 legacy 语义未列入批准迁移的模板仍受逐字保真约束。保留结构框架框线、底色、分隔、标签页或面板只要表达真实的信息单元、父子层级、阶段范围、绘图区或输出区就属于结构。可以减少叠加效果但不得为了 token 数字把有效层级压平。禁止通过改写压缩不用缩写、概括、换词或删句降低 token。体积优化只能来自属性继承、重复样式合并和非语义效果简化不来自内容编辑。4. 中性预览4.1 独立可渲染硬规则每个模板保持完整svg、viewBox0 0 1280 720和一个直接的白色全画布背景使文件无需外部样式即可打开审阅svg xmlnshttp://www.w3.org/2000/svg viewBox0 0 1280 720 width1280 height720 font-family-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, Microsoft YaHei, sans-serif rect width1280 height720 fill#FFFFFF/ !-- semantic content -- /svg白色背景是预览基线不是项目背景指令Executor 必须按当前页面风格处理最终背景。这一要求可以直接在现有模板中得到验证例如 line_chart.svg 第 1–8 行完整遵循了该骨架viewBox、系统字体栈、白色背景 rect、带data-pptx-bounds的header组。4.2 中性参考色以下色值只保证模板独立展示时清晰它们不是最终项目调色板角色中性参考值使用边界主文本#0F172A标题、关键值正文#475569描述、图例次文本#64748B轴标签、辅助说明弱线#CBD5E1/#E2E8F0网格、边界、分隔参考强调#2563EB第一系列、当前状态或结构焦点正向语义#059669仅表示上升、完成、达标负向语义#E11D48仅表示下降、异常、未达标警示语义#D97706仅表示风险或待处理硬规则多系列数据必须可区分正负、完成/计划等语义状态必须可辨认。颜色承担这些信息时保留颜色只承担装饰时移除。禁止固定目录调色板不要求每个卡片、步骤或能力点使用不同 Tailwind hue项目配色不从模板示例反向推导。4.3 页面 chrome元素模板行为标题/副标题可用简短占位文本展示层级和可用空间不附带装饰条、徽章或品牌图形数据来源仅当该可视化结构需要来源/脚注槽时保留不是每个模板的固定页脚页码、Logo、部门名省略进度徽章、状态胶囊只有状态本身属于信息时保留移除纯装饰外壳5. 装饰与效果5.1 减少冗余效果默认原则是“一种清楚的处理方式”结构需要深度时可以覆盖中性模板避免阴影、发光、纹理、渐变和多层框同时叠加只保留能帮助读者识别真实边界、重叠或空间关系的最少效果。效果默认允许条件阴影/filter有描边或底色已能分组时省略重叠、浮层或空间深度本身属于结构渐变只承担审美时可换成实色连续色阶、流量、深度面或方向确实承载编码透明光晕省略透明度本身编码范围或不确定性圆角卡片保留真实信息单元的一层边界圆角值与最终外观由项目适配图标底板非默认需要明确图标槽位或状态边界硬规则划定了“哪些视觉效果属于信息”Heatmap 色阶、Sankey 流量宽度、系列区分、Isometric 面向关系和真实模块边界属于信息编码或结构而普通卡片阴影、气泡高光、无含义色带和不承担顺序的大号淡色编号通常不属于——但删除前仍需确认没有弱化层级。5.2 容器克制硬规则每个真实信息单元保留至少一种清楚的边界表达——留白、分隔线、描边或底色。通常只需一种父级区域与子级内容确实表达两个层级时可以保留两层。不要同时叠加无语义的描边、阴影、渐变和多层圆角框。参考说明不是约束项目最终可能采用强装饰风格那是 Executor 根据 Design Spec 重建的项目决策不是共享模板的默认形态。6. 源码可读性与体积6.1 语义压缩硬规则缩小模板时保留正常换行、缩进、语义id和必要分区注释。压缩目标是减少重复信息不是把 XML 变成一行。具体做法做法要求字体继承公共font-family放在根svg局部差异放在清楚的父g属性继承同组重复的fill、stroke、字号或锚点提升到父组根节点不放 paint注释保留结构、语义和机器标记删除色名、营销解释和重复说明文本普通单行直接写在text只有多 run/多行需要tspan坐标页面坐标从写入时就使用必要精度质量检查只读验证不在之后改写ID使用chart-area、series-1、card-1等结构名称避免示例业务名6.2 禁止的压缩以下做法被明确禁止单行 minify、随机缩写 ID 或删除结构注释为省字符把核心构图拆成难以追踪的深层symbol/use图把模板必要信息藏进外部 CSS、脚本或未登记依赖用 Base64、压缩字符串或生成器说明替代可读的可视几何。静态同文档use只在重复原语保持清晰、且满足上游条件合同时使用它不是默认瘦身手段。6.3 文本可读性角色中性范围页面标题30–36700–800区域标题18–24600–700正文/标签13–16图注/轴刻度12–14硬规则所有文本font-size 12使用有限无单位数值。需要成为一个 PowerPoint 文本框的多格式逻辑行使用一个text加非定位tspan独立文本框使用独立text。7. SVG 分组与边界7.1 语义分组硬规则使用描述性顶层g id表达页面级逻辑单元Header、Chart、Legend、Card Grid、Process 等不要为每条文字、图标或数据点建立一个直属根组。顶层组典型内容header标题与副标题chart-area/ replacement carrierChart 的轴、数据系列、标签、必要 metadatalegend系列或状态说明table-area/ replacement carrierTable 的行、列、单元格和必要 metadatatable-notes来源、口径或脚注禁止工作区元数据两个 catalog family 都不得写入 Master/Layout/placeholder 所有权标记。运行时 Structure 即使占满整个1280×720画布也仍是 Slide-local 构形不会因此成为 Layout workspace。7.2data-pptx-bounds硬规则每个可见直属根g都声明正数、根坐标系的data-pptx-boundsx y width height。即使该组已有 native chart/table frame也保留 boundsg idheader>!-- chart-plot-area: 140,150,1160,550 --Pie、Donut、Radar 使用对应中心和半径格式。该注释是工具输入不得作为“清理注释”删除。以 line_chart.svg 为例chart-plot-area: 140,150,1160,550正好落在网格与坐标轴之后、第一个数据系列之前——这正是合同规定的唯一合法位置。Catalog 模板本身只有一个主 Chart可保留上述 unscoped marker 与idchartArea。Executor 在项目页面组合多个已验证 Chart 对象时改用 executor-chart.md 定义的 semantic object key 和 scoped marker不能在同一 SVG 中复制多个chartAreaid。8.2 Native Chart/Table 替换标记硬规则只有 native-data-interface.md 支持的真实 Chart 或纯文本 Table 使用 replacement marker。JSON metadata 与可见 fallback 必须表达同一份数据。运行时构建的 Structure 永远不使用 Chart/Table replacement marker。g idline-chart >line_chart: { summary: Pick for 1-3 time-series on a continuous axis showing direction. Skip if cumulative volume matters (use area_chart). }summary保留Pick for ... Skip if ...句式供可选的机器召回诊断使用规划主路径不读取这些记录。两份 index 的meta.summaryGrammar都把它固化为机器合同Pick for content shape scale. Skip if reason → alternative。Chart 与 Table 的规划词汇表必须完整列出各自同一组 canonicalfamily/key只说明信息关系不写 SVG 实现、布局参数或选择结论。硬规则key与同 family 文件名一致meta.total与该 family catalog 数量一致当前 charts_index.json 中meta.total为 33tables_index.json 中为 6每份 planning vocabulary 与 owning index 的成员集合必须精确一致。除此以外不要建立跨 family 的第二份成员清单。summary的句式不是风格偏好而是召回算法的输入格式。从 visualization_recall.py 的_score_candidate实现看工具用正则skip (?:if|for)把 summary 切分为 pick 子句与 skip 子句tag 命中 key/pick 子句分别记正分20/14/9/5命中 skip 子句记负分12/6也就是说Pick for / Skip if句式直接决定了召回诊断的正负证据。该工具只读这两份 index 并维护不了第二份索引详见 visualization-recall.md。10. 迁移边界本指南是新建和修改 Chart/Table 模板的目标合同。当前两个 catalog family 共39 个 SVGChart 33 个、Table 6 个。各 live index 是成员清单的唯一权威Structure 不再有固定 SVG roster、index 或 canonical key。硬规则——拓扑由现场生成不从目录召回从来源 deck 吸收的是 Shape grammar 和构形思维而不是页面示例清单。先还原顺序、层级、分组、分区、连接、交叠等真实关系再由executor-structure.md使用区域、节点、主轴、连接、标签与装饰等角色现场组合。Default 在 §IX 描述该关系Quick 在当前上下文作同一判断两条路径都不依赖structure/key或固定 SVG不能因 Quick 跳过 §VII/lock 就跳过 Structure 载体判断。已批准的图表容量迁移规范 key已批准边界兼容处理gauge_chart2026-08-10中性预览从三个并列 Gauge 重组为一个有界域、明确目标或阈值的 KPI多个同级 KPI 改用bullet_chart或progress_bar_chartcanonical key 保持不变旧三指标示例不再作为可读取容量合同无需 alias规范 Table 集合规范 key核心信息关系record_table每行一条记录、每列一个稳定字段metric_table实体与 KPI 的交点承载度量、变化、状态或 cell 内微图形comparison_matrix行维度与列方案的交点承载文本、精确值或异构事实feature_matrix能力与方案的交点承载支持、不支持、部分支持或例外状态rating_matrix评价维度与方案的交点使用同一套序数等级hierarchical_table分组或缩进行、明细与小计/总计形成层级网格硬规则——先判定语义分类再看物理对象PowerPoint 中的物理 Table 对象不自动属于tablefamily。只有行头与列头的交点可寻址为一个事实时才是 Table日期或持续时间决定x/width的排期是chart/gantt_chart阶段与泳道只表达定性活动位置时由 runtime Structure 构建。这条规则与 family 判定表首尾呼应也是gantt_chart从旧project_schedule_table迁移到 chart family 的依据。规范目录别名只服务旧page_charts读取不是新模板命名候选规范引用旧版裸 keytable/record_tablebasic_tabletable/metric_tableconsulting_tabletable/comparison_matrixcomparison_tabletable/feature_matrixfeature_matrix_tabletable/rating_matrixharvey_balls_tabletable/hierarchical_tablefinancial_statement_tablechart/gantt_chartproject_schedule_table上述别名与两份 index 的aliases字段一一对应tables_index.json的aliases覆盖了前六个裸 keycharts_index.json的aliases覆盖project_schedule_table → gantt_chart。新文档、§VII 和page_visualizations只写 canonicalchart|table/key。此前 36 个 canonical Structure bare key 只在旧page_charts读取时保留为legacy-structure-intent它没有 canonical SVG、path 或 reference不参与 recall也不能写入新 §VII/lock消费方把该意图投影为定性关系提示再交给 runtime Structure 构形不得把它伪装成仍存活的模板。迁移收尾还有一条硬规则修改一个仍属 canonical 的模板时先冻结可见文本、数据和结构层级再简化确认无语义的效果、补齐直属根 bounds并完成文本差异、独立渲染与双路线验证。经本节明确登记的 catalog 合并/重组/退役不要求保留旧示例文案除此之外未经说明的文本删除、改写或结构边界丢失都会阻断变更。11. 检查清单11.1 结构与可读性SVG 独立可渲染viewBox为0 0 1280 720。源码有正常缩进、语义 ID 和必要结构注释。原有可见文本、数值、单位、来源、状态和关系保持不变删除项只有审核过的重复信息。真实信息单元、父子层级、阶段范围和输出区仍有清楚边界。每个可见直属根g有准确的data-pptx-bounds嵌套组不滥加 bounds。模板只保留结构、数据编码和必要中性预览。字体在根或清楚父组继承文本字号不小于 12。11.2 风格归属无固定项目调色板、品牌字体或品牌 chrome。纯装饰效果已减少但没有以“去装饰”为由删除结构框线或压平层级。颜色差异确实表达 series、state、positive/negative 等语义。标题、副标题和来源只用于展示必要结构或容量。11.3 分类与 PowerPoint分类判定正确Chart 为数值驱动、Table 为行 × 列事实网格定性拓扑退出 catalog 并由 runtime Structure 构建。Chart/Table 模板不含 Master/Layout/layer/placeholder ownership metadata。Calculator-supported Chart 保留准确chart-plot-area标记。Eligible Chart/Table 的 metadata 与可见 fallback 数据一致。默认 Shape-first 导出通过。存在 replacement marker 时显式 native Chart/Table 导出通过。svg_quality_checker.py无 errorwarning 已人工判断。11.4 目录新模板只登记到 owning family indexindex object、meta.total与 SVG roster 一致。修改 key/summary 后通过visualization_recall.py validate和 recall 烟测。前后可见文本差异已审阅非重复内容没有意外丢失或改写。前后渲染对比确认结构仍可读。记录 bytes/tokens 变化但不以牺牲源码可读性换取数字。12. 验证命令指南为每次变更规定了两条机器验证命令# 单文件 SVG 合同 python3 skills/ppt-master/scripts/svg_quality_checker.py \ skills/ppt-master/templates/family-directory/key.svg \ --canonical-authoring # Canonical family/key python3 skills/ppt-master/scripts/visualization_recall.py validate \ family/key两条命令的作用边界不同svg_quality_checker.py负责单文件的 SVG 合同检查独立可渲染、bounds、文本字号等。作者态必须已紧凑——Checker 只读验证不在检查后重写这与第 6 节“坐标在写入时就使用必要精度”的硬规则是同一条约束的两端。visualization_recall.py validate负责引用解析它只读地把family/key解析到登记的 SVG全部解析成功时退出码为0否则为1--legacy-bare开关仅用于验证旧page_charts映射中的未限定裸 key且每个 key 必须唯一解析见 visualization_recall.py 的参数定义。最终验证要求修改后至少完成XML 解析、独立 SVG 渲染、Checker、默认 Shape-first 导出以及 marker 模板的 native Chart/Table 导出——即 Shape 路线与 native 路线双验证两条路线都必须可验证后才能提交变更。13. 总结这套编写指南的核心思想可以概括为三层分离模板层只承诺信息模型与中性预览family、数据映射、data-pptx-bounds、chart-plot-area项目层拥有全部视觉风格配色、字体、chrome、背景方法层Structure不落在目录里而落在 Executor 的现场判断中。39 个 canonical SVG 的存活合同是“源码可读、独立可渲染、保真优先、Shape-first、双路线可验证”任何瘦身或迁移都必须先冻结可见文本与结构层级再以属性继承和非语义效果简化换取体积并以第 11 节检查清单和两条验证命令收口。掌握这份合同后你可以直接上手扩展charts/或tables/任一 family或在维护现有模板时不破坏其 canonical 语义。【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考