AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
refactor(typography): open font family + size, add PPT-safe discipline
hugohe39c30c08577d8
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex 426d43ca..d8004b06 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -50,7 +50,8 @@ Must output confirmation including: canvas dimensions, body font size, color sch- Color values (fill / stroke / stop-color) MUST come from `colors` in `spec_lock.md`- Icons MUST come from the `icons.inventory` list; icon library MUST equal `icons.library`-- Font family MUST equal `typography.font_family`; font sizes MUST match one of `typography.*` values+- Font family MUST come from the `typography` block: use the role-specific override (`title_family` / `body_family` / `emphasis_family` / `code_family`) if declared for that role, otherwise fall back to `font_family`.+- Font sizes follow a **ramp anchored on `typography.body`**, not a closed menu. The slots listed in `spec_lock.md typography` (`title` / `subtitle` / `annotation` / any project-specific additions like `cover_title` / `hero_number`) are common anchors — use them directly when they fit. Executor MAY use an intermediate size (e.g., 40px hero number, 13px chart annotation, 72px cover headline) when the role calls for it, **provided** the size's ratio to `body` falls within the corresponding role's band in the design-spec ramp table (see `design_spec_reference.md §IV — Font Size Hierarchy`, also mirrored in `design_spec.md §IV` per project). Sizes outside every ramp band are still forbidden — surface the need and extend the lock instead of inventing one-off values.- Images MUST reference files listed under `images`; no invented filenamesIf a page genuinely needs a value not in `spec_lock.md`, stop and surface it — do not silently invent one. Either request the user to extend the lock, or revise the page to stay within it.diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex ea405235..4c187ceb 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -134,31 +134,73 @@ Built-in library contains 6700+ icons across three libraries:### g. Typography Plan Confirmation (Font + Size)-#### Font Presets+#### Font Combinations-| Scenario | Preset | Title | Body | Emphasis |-|----------|--------|-------|------|----------|-| Modern business, tech | P1 | Microsoft YaHei / Arial | Microsoft YaHei / Calibri | SimHei |-| Government documents, reports | P2 | SimHei | SimSun / Times | SimSun |-| Culture, arts, humanities | P3 | KaiTi / Georgia | Microsoft YaHei | SimHei |-| Traditional, conservative | P4 | SimSun | Microsoft YaHei / Arial | SimSun |-| English-primary | P5 | Arial / Impact | Calibri / Georgia | Arial Black |+> **Starting points, not a menu.** Each row below is one common direction — pick the closest match and adapt, or propose a new combination when the content tone calls for it. Per-role assignment is expected: `title` / `body` / `emphasis` / `code` may each use a different family. A deck is not required to stick to one family throughout.+>+> **⚠️ PPT-safe font discipline (HARD rule).** PPTX stores a single `typeface` per text run — there is no runtime fallback stack. On a machine that lacks the declared font, PowerPoint substitutes with its own default (typically Calibri), breaking the design. Therefore every CSS `font-family` stack declared in the spec MUST end with a cross-platform pre-installed font:+> - CJK-capable stacks → end with `"Microsoft YaHei", sans-serif` (sans) or `SimSun, serif` (serif)+> - Latin-only stacks → end with `Arial, sans-serif` or `"Times New Roman", serif`+> - Monospace stacks → end with `Consolas, "Courier New", monospace`+>+> Any stack that *leads* with a non-pre-installed font (Inter / HarmonyOS Sans / any Google Fonts family / any brand-specific typeface like McKinsey Bower) is only acceptable when the Design Spec explicitly notes "requires the target machine to have this font installed, or the PPTX to embed it." Never leave a non-safe font as the final fallback.++**Cross-platform pre-installed reference** (Windows + Mac out of the box):++| Category | Safe families |+|----------|--------------|+| CJK sans | Microsoft YaHei, SimHei, PingFang SC, Heiti SC |+| CJK serif | SimSun, FangSong, KaiTi, Songti SC, STSong |+| Latin sans | Arial, Calibri, Segoe UI, Verdana, Helvetica, Helvetica Neue |+| Latin serif | Times New Roman, Georgia, Cambria, Times, Palatino |+| Monospace | Consolas, Courier New, Menlo, Monaco |+| Display | Impact, Arial Black |++**Seed combinations** (all stacks are PPT-safe — end on pre-installed fonts):++| Direction | Typical scenarios | Title stack | Body stack | Code stack |+|-----------|-------------------|-------------|------------|------------|+| **Modern CJK sans** (default) | Tech launches, enterprise reports, most contemporary decks | `"PingFang SC", "Microsoft YaHei", sans-serif` | same as Title | — |+| **Government / 政务** | Government reports, party-building, formal briefings | `SimHei, "Microsoft YaHei", sans-serif` | `SimSun, "Songti SC", serif` | — |+| **Academic serif** | Research, legal, theses, serious analysis | `Georgia, "Times New Roman", serif` | `"Times New Roman", "Songti SC", SimSun, serif` | — |+| **Editorial display** | Magazine covers, luxury, finance, brand storytelling | `Georgia, "Times New Roman", "Songti SC", serif` (Bold/Heavy) | `"PingFang SC", "Microsoft YaHei", sans-serif` | — |+| **Tech / developer** | Code-focused tech talks, developer docs, API / CLI explainers | `Arial, Helvetica, sans-serif` | same as Title | `Consolas, Menlo, Monaco, "Courier New", monospace` |+| **International English** | English-primary decks, international audiences | `"Helvetica Neue", Helvetica, Arial, sans-serif` | same as Title | — |+| **Impact / 海报** | Cover headlines, call-to-action, poster-style slides | `Impact, "Arial Black", "Microsoft YaHei", sans-serif` | `"PingFang SC", "Microsoft YaHei", sans-serif` | — |++> **Directions that require font installation or embedding** (NOT in the safe seed table above):+> - **Retro / pixel** — Press Start 2P / VT323 / Silkscreen (not pre-installed on any OS; degrades to a wildly different font without install)+> - **Rounded friendly** — Nunito / Quicksand / M PLUS Rounded / OPPO Sans (no true cross-platform rounded pre-installed; closest safe substitutes are `Trebuchet MS` / `Verdana` but they are not truly rounded)+> - **Modern web sans** — Inter / HarmonyOS Sans / Source Han Sans / Noto Sans (not pre-installed; viewers without the font see Calibri)+> - **Brand-specific typography** — McKinsey Bower, Anthropic house fonts, corporate VI typefaces+>+> Only declare these when the deck runs on controlled machines (all viewers install the font first) or when the PPTX embeds the font. Always note the constraint in the Design Spec.+>+> **Guidance for the Strategist**: state the intended direction in one phrase (e.g., "modern CJK sans"), then list the actual families per role in the design spec. The spec is the source of truth; the table above is only a quick pick.++#### Font Size Ramp (all sizes in px)-#### Font Size Baseline (all sizes in px)+> **Ramp discipline, not a fixed menu.** Every size in the deck is derived from the `body` baseline as a ratio. The `spec_lock.md typography` block declares `body` as the anchor plus whichever common slots this deck actually uses (`title` / `subtitle` / `annotation` by default; add `cover_title` / `hero_number` / `chart_annotation` etc. when the content calls for them). Executor may use intermediate sizes during generation as long as the size's ratio to `body` lands within the corresponding role's band below — the list is a ramp, not an allowed-values enumeration.-Selection principle: Font size is based on **content density**, not design style.+Selection principle: Baseline choice is driven by **content density**, not design style.| Content Density | Points per Page | Body Baseline | Suitable Scenarios ||----------------|----------------|---------------|-------------------|| Relaxed | 3-5 items | 24px | Keynote-style, training materials || Dense | 6+ items | 18px | Data reports, consulting analysis |-| Level | Ratio | 24px Baseline | 18px Baseline |-|-------|-------|---------------|---------------|-| Cover title | 2.5-3x | 60-72px | 45-54px |+| Level | Ratio to body | 24px baseline | 18px baseline |+|-------|---------------|---------------|---------------|+| Cover title (hero headline) | 2.5-5x | 60-120px | 45-90px |+| Chapter / section opener | 2-2.5x | 48-60px | 36-45px || Page title | 1.5-2x | 36-48px | 27-36px |+| Hero number (consulting KPIs) | 1.5-2x | 36-48px | 27-36px |+| Subtitle | 1.2-1.5x | 29-36px | 22-27px || **Body** | **1x** | **24px** | **18px** |-| Annotation | 0.75x | 18px | 14px |+| Annotation / caption | 0.7-0.85x | 17-20px | 13-15px |+| Page number / footnote | 0.5-0.65x | 12-16px | 9-12px |++> Executor may pick any px value within a role's band (e.g., 40px hero number, 13px chart annotation, 72px cover headline) without having to pre-declare every intermediate value in `spec_lock.md`. Values outside **every** band remain forbidden — those need the lock extended first.### h. Image Usage Confirmation@@ -388,7 +430,7 @@ The Strategist should make professional judgments on the template basis generate| I. Project Information | Project name, canvas format, page count, style, audience, scenario, date || II. Canvas Specification | Format, dimensions, viewBox, margins, content area || III. Visual Theme | Style description, light/dark theme, tone, color scheme (with HEX table), gradient scheme |-| IV. Typography System | Font plan (P1-P5), font size hierarchy (H1-Code, 7 levels) |+| IV. Typography System | Font plan (per-role families — title / body / emphasis / code), font size hierarchy || V. Layout Principles | Page structure (header/content/footer zones), layout pattern library (combine/break as content demands), spacing spec || VI. Icon Usage Spec | Source description, placeholder syntax, recommended icon list || VII. Visualization Reference List | Visualization type, reference template path, used-in pages, purpose |diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.mdindex 692acac6..ad26691b 100644--- a/skills/ppt-master/references/template-designer.md+++ b/skills/ppt-master/references/template-designer.md@@ -89,7 +89,7 @@ When creating a global template, a `design_spec.md` must be generated, containinTemplates must strictly follow the finalized template brief and the generated `design_spec.md`:- **Canvas dimensions**: viewBox matches the design spec- **Color scheme**: Uses primary, secondary, and accent colors from the spec-- **Font plan**: Uses font presets from the spec+- **Font plan**: Uses the per-role font families declared in the spec- **Layout principles**: Margins and spacing conform to the specIf PPTX import output exists:diff --git a/skills/ppt-master/scripts/update_spec.py b/skills/ppt-master/scripts/update_spec.pyindex 1c0be6d8..3da6e92a 100755--- a/skills/ppt-master/scripts/update_spec.py+++ b/skills/ppt-master/scripts/update_spec.py@@ -4,19 +4,21 @@Examples:python3 update_spec.py <project_path> primary=#0066AApython3 update_spec.py <project_path> colors.text=#111111- python3 update_spec.py <project_path> typography.font_family='"Inter", Arial, sans-serif'+ python3 update_spec.py <project_path> typography.font_family='"PingFang SC", "Microsoft YaHei", sans-serif'v2 scope:- `colors.*` — HEX value replacement across svg_output/*.svg (case-insensitive match).- `typography.font_family` — replaces the inner value of every `font-family="..."`- / `font-family='...'` attribute in svg_output/*.svg.+ / `font-family='...'` attribute in svg_output/*.svg. This is a global replace:+ every text element becomes the new family, regardless of role.Bare `key=value` (no dot) is treated as `colors.key=value` for backward compat.-Other keys (typography sizes, icons, images, canvas, forbidden) are intentionally-NOT supported — they involve attribute-scoped or semantic replacements whose-risk/benefit does not warrant bulk propagation. Edit spec_lock.md and the-affected SVGs by hand, or re-author the pages.+Other keys (typography sizes, per-role `typography.*_family` overrides, icons,+images, canvas, forbidden) are intentionally NOT supported — they involve+attribute-scoped or semantic replacements whose risk/benefit does not warrant+bulk propagation. For per-role family changes, edit spec_lock.md and re-author+the affected pages."""from __future__ import annotationsdiff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.mdindex 8c7d9053..f2c4cd79 100644--- a/skills/ppt-master/templates/design_spec_reference.md+++ b/skills/ppt-master/templates/design_spec_reference.md@@ -80,37 +80,45 @@### Font Plan-> Strategist should select a font preset based on content characteristics, or customize the font combination-> Preset descriptions: P1=Modern business/tech | P2=Government docs | P3=Culture/arts | P4=Traditional/conservative | P5=English-primary+> **Per-role families are expected, not optional.** Title / Body / Emphasis / Code may each use a different family — for example, a display serif for titles paired with a geometric sans for body. A deck is not required to stick to one family throughout. See [strategist.md §g — Font Combinations](../references/strategist.md) for common starting directions; you are free to propose a combination not in that list.+>+> **⚠️ PPT-safe stack discipline (HARD rule).** PPTX stores a single `typeface` per text run — no runtime fallback. Every stack below MUST end with a cross-platform pre-installed font (`"Microsoft YaHei", sans-serif` / `SimSun, serif` / `Arial, sans-serif` / `"Times New Roman", serif` / `Consolas, "Courier New", monospace`). Stacks that lead with a non-pre-installed font (Inter / Google Fonts families / brand typefaces) are only allowed when this spec explicitly notes the font-install or font-embedding requirement.-**Recommended preset**: [Fill in preset code]+**Typography direction**: [Fill in one phrase, e.g., "modern CJK sans" / "academic serif" / "brand-specific: McKinsey Bower (requires font install)"]| Role | Chinese | English | Fallback || ---- | ------- | ------- | -------- || **Title** | [font name] | [font name] | [font name] || **Body** | [font name] | [font name] | [font name] |-| **Code** | - | Consolas | Monaco || **Emphasis** | [font name] | [font name] | [font name] |+| **Code** | - | [e.g., JetBrains Mono / Fira Code / Consolas] | [Monaco / monospace] |-**Font stack**: `[Fill in CSS font-family string]`+**Per-role font stacks** (CSS `font-family` strings — one per role if they differ, or a single stack if all roles share the same family):+- Title: `[Fill in]`+- Body: `[Fill in — may be the same as Title]`+- Emphasis: `[Fill in or "same as Body"]`+- Code: `[Fill in — typically a monospace stack]`### Font Size Hierarchy-> **Design principle**: Use body font size as baseline (1x), derive other levels proportionally-> **Unit convention**: Use px uniformly (SVG native unit) to avoid pt/px conversion errors-> **Selection principle**: Font size is based on **content density**, not design style+> **Ramp discipline, not a fixed menu.** The `body` baseline is the single anchor; every other size is a ratio of it. The table below is a **ramp** — each row gives the allowed ratio band for that role, and Executor may pick any px value inside the band during generation (e.g., 40px hero number, 13px chart annotation, 72px cover headline) without having to pre-declare every intermediate value in `spec_lock.md`.+> **Unit convention**: Use px uniformly (SVG native unit) to avoid pt/px conversion errors.+> **Baseline selection**: Drive by **content density**, not design style.**Baseline**: Body font size = [fill in]px (choose 18-24px based on content density)-| Purpose | Ratio | 24px baseline (relaxed) | 18px baseline (dense) | Weight |-| ------- | ----- | ---------------------- | -------------------- | ------ |-| Cover title | 2.5-3x | 60-72px | 45-54px | Bold |-| Chapter title | 2-2.5x | 48-60px | 36-45px | Bold |-| Content title | 1.5-2x | 36-48px | 27-36px | Bold |+| Purpose | Ratio to body | 24px baseline (relaxed) | 18px baseline (dense) | Weight |+| ------- | ------------- | ---------------------- | -------------------- | ------ |+| Cover title (hero headline) | 2.5-5x | 60-120px | 45-90px | Bold / Heavy |+| Chapter / section opener | 2-2.5x | 48-60px | 36-45px | Bold |+| Page title | 1.5-2x | 36-48px | 27-36px | Bold |+| Hero number (consulting KPIs) | 1.5-2x | 36-48px | 27-36px | Bold || Subtitle | 1.2-1.5x | 29-36px | 22-27px | SemiBold || **Body content** | **1x** | **24px** | **18px** | Regular |-| Annotation | 0.75-0.85x | 18-20px | 14-15px | Regular |-| Page number/date | 0.55-0.65x | 13-16px | 10-12px | Regular |+| Annotation / caption | 0.7-0.85x | 17-20px | 13-15px | Regular |+| Page number / footnote | 0.5-0.65x | 12-16px | 9-12px | Regular |++> Sizes outside **every** band remain forbidden — surface the need and extend `spec_lock.md typography` (e.g., add `cover_title: 96`) rather than invent a one-off value.> **Tip**: Dense content (6+ points per page) use 18px; relaxed content (3-5 points per page) use 24pxdiff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.mdindex c19d6131..df1afe8e 100644--- a/skills/ppt-master/templates/spec_lock_reference.md+++ b/skills/ppt-master/templates/spec_lock_reference.md@@ -1,5 +1,7 @@# Execution Lock+> **⚠️ This file is a REFERENCE skeleton for Strategist — do NOT copy it verbatim into a project.** When producing `<project_path>/spec_lock.md`, emit only the structural `##` sections with their filled-in `-` data lines. Do NOT carry over any `>` blockquote guidance, callout boxes, HARD-rule notes, or `> ```code fence` override examples from this file — those are author-time guidance for Strategist, not runtime data. The output is a machine-readable contract; every line must be parseable data.+>> Machine-readable execution contract. Executor MUST `read_file` this before every SVG page. Values NOT listed here must NOT appear in SVGs. For design narrative (rationale, audience, style), see `design_spec.md`.>> After SVG generation begins, this file is the canonical source for color / font / icon / image values. Modifications should go through `scripts/update_spec.py` so both this file and the generated SVGs stay in sync.@@ -23,12 +25,27 @@## typography- font_family: "Microsoft YaHei", Arial, sans-serif+- body: 22- title: 32- subtitle: 24-- body: 22- annotation: 14-> Sizes are in px, matching SVG native units. `font_family` is a CSS font-stack string.+> Sizes are in px, matching SVG native units. `body` is the **required baseline anchor** — every other size in the deck is derived as a ratio of it (see ramp table in `design_spec_reference.md §IV`). `font_family` is a CSS font-stack string — used as the default family for every text role unless overridden below.+>+> **Size slots are anchors, not a closed menu.** The common slots (`title` / `subtitle` / `annotation`) cover frequent cases. Add role-specific slots (e.g. `cover_title: 72`, `hero_number: 48`, `chart_annotation: 13`) when a deck genuinely needs them — this is expected for cover-heavy decks, consulting-style hero numbers, and information-dense pages. Executor may use intermediate sizes as long as the size's ratio to `body` sits within the corresponding role's band in the ramp table.+>+> **⚠️ PPT-safe stack discipline (HARD rule).** PPTX stores one `typeface` per text run; there is no runtime fallback. Every stack here MUST end with a cross-platform pre-installed font: `"Microsoft YaHei", sans-serif` / `SimSun, serif` / `Arial, sans-serif` / `"Times New Roman", serif` / `Consolas, "Courier New", monospace`. Non-pre-installed fonts (Inter / Google Fonts / brand typefaces) may lead the stack only when the Design Spec explicitly notes the font-install or font-embedding requirement.+>+> **Optional per-role family overrides** — add only when a role needs a family different from the default (e.g., a display serif for titles while body stays a geometric sans). Omit any override that is not needed.+>+> ```+> - title_family: Georgia, "Times New Roman", "Songti SC", serif+> - body_family: "PingFang SC", "Microsoft YaHei", sans-serif+> - emphasis_family: same as body (omit if identical)+> - code_family: Consolas, Menlo, Monaco, "Courier New", monospace+> ```+>+> When a `*_family` override is present, Executor MUST use that family for the matching role. When absent, that role falls back to `font_family`.## icons- library: chunk