Skip to content

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): trim font stacks, surface per-role families explicitly

hugohe3086a79ea0851
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 3fe2837f..7b546180 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -160,13 +160,15 @@ Built-in library contains 6700+ icons across three libraries:
| 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` | — |
+| **Modern CJK sans** (default) | Tech launches, enterprise reports, most contemporary decks | `"Microsoft YaHei", "PingFang SC", sans-serif` | same as Title | — |
+| **Government / 政务** | Government reports, party-building, formal briefings | `SimHei, "Microsoft YaHei", sans-serif` | `SimSun, serif` | — |
+| **Academic serif** | Research, legal, theses, serious analysis | `Georgia, "Times New Roman", serif` | `"Times New Roman", SimSun, serif` | — |
+| **Editorial display** | Magazine covers, luxury, finance, brand storytelling | `Georgia, SimSun, serif` (Bold/Heavy) | `"Microsoft YaHei", "PingFang SC", sans-serif` | — |
+| **Tech / developer** | Code-focused tech talks, developer docs, API / CLI explainers | `Arial, sans-serif` | same as Title | `Consolas, "Courier New", monospace` |
+| **International English** | English-primary decks, international audiences | `"Helvetica Neue", Arial, sans-serif` | same as Title | — |
+| **Impact / 海报** | Cover headlines, call-to-action, poster-style slides | `Impact, "Arial Black", "Microsoft YaHei", sans-serif` | `"Microsoft YaHei", "PingFang SC", sans-serif` | — |
+
+> **Stack length discipline (soft rule).** 3-4 fonts per stack is enough — more is waste. Converter behavior (see [`drawingml_utils.py parse_font_family`](../scripts/svg_to_pptx/drawingml_utils.py)) only picks the **first** Latin font and the **first** CJK font; everything after is silently dropped in PPTX. macOS-only families (`Songti SC` → SimSun; `Menlo` / `Monaco` → Consolas; `Helvetica` → Arial) are mapped via `FONT_FALLBACK_WIN`, so stacking both the macOS family and its Windows equivalent is redundant. Convention: lead with Windows-preinstalled fonts (Microsoft YaHei / SimSun / Arial / Georgia / Consolas) so PPT viewers see the intended typeface immediately; keep at most **one** macOS-exclusive family (typically `"PingFang SC"`) as a browser-preview nicety.
> **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)
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index f2c4cd79..9641da10 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -86,18 +86,32 @@
**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] |
-| **Emphasis** | [font name] | [font name] | [font name] |
-| **Code** | - | [e.g., JetBrains Mono / Fira Code / Consolas] | [Monaco / monospace] |
-
-**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]`
+Two views on the same font decisions — fill both, keep them consistent:
+
+- **Role breakdown** (below table) — lists the *pieces* for each role: what CJK font, what Latin font, what CSS generic fallback. This is the human-readable design language.
+- **Per-role font stacks** (after the table) — the *ordered* CSS `font-family` strings that actually go into SVG `font-family=""` attributes and into `spec_lock.md`'s `*_family` lines. Order matters because it controls browser character rendering (Latin-led vs. CJK-led) — so this view is the **actual data**, not derivable from the table alone.
+
+| Role | Chinese | English | Fallback tail |
+| ---- | ------- | ------- | ------------- |
+| **Title** | [e.g., `"Microsoft YaHei"`, or `"Microsoft YaHei", "PingFang SC"` for macOS preview nicety] | [e.g., `Georgia`] | [e.g., `serif`] |
+| **Body** | [e.g., `"Microsoft YaHei", "PingFang SC"`] | [e.g., `Arial`] | [e.g., `sans-serif`] |
+| **Emphasis** | [e.g., `SimSun`, or `—` for Latin-only] | [e.g., `Georgia`] | [e.g., `serif`] |
+| **Code** | — | [e.g., `Consolas, "Courier New"`] | [e.g., `monospace`] |
+
+**Per-role font stacks** (CSS `font-family` strings, one per role — arrange the table's pieces in the order your design intends):
+
+- Title: `[Fill in stack, e.g. Georgia, "Microsoft YaHei", serif for Latin-led; or "Microsoft YaHei", "PingFang SC", Georgia, serif for CJK-led]`
+- Body: `[Fill in stack — may be same as Title]`
+- Emphasis: `[Fill in stack, or write "same as Body" to omit the override]`
+- Code: `[Fill in monospace stack, e.g. Consolas, "Courier New", monospace]`
+
+> **Stack ordering — why it matters**: CSS `font-family` falls back font-by-font (not char-by-char with all fonts parallel) — the browser uses the **first installed** font in the stack for everything it can render, and only skips to the next font when that font lacks a glyph for a specific character. So:
+> - `Georgia, "Microsoft YaHei", serif` → Latin characters render in Georgia (elegant serif), CJK characters fall through to Microsoft YaHei. **Use this when Latin typography is the primary design statement** (academic / editorial / Latin-heavy covers).
+> - `"Microsoft YaHei", Georgia, serif` → Everything renders in Microsoft YaHei (including Latin, using YaHei's Latin glyphs — a different design tone). **Use this when the deck is CJK-primary and Latin characters are incidental**.
+>
+> The converter (`drawingml_utils.py parse_font_family`) maps these to PPTX `<a:latin>` / `<a:ea>` typefaces regardless of order — but the browser preview and the SVG's native rendering reflect stack order, so pick the order that matches your design intent.
+
+> **Why two views**: the role breakdown is compact and shows font role assignment at a glance; the stacks carry the ordering information the breakdown can't encode. Keep the fonts consistent between the two — the table's cells should be exactly the fonts that appear in the stacks (in any order).
### Font Size Hierarchy
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index df1afe8e..f85bd65c 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -25,27 +25,30 @@
## typography
- font_family: "Microsoft YaHei", Arial, sans-serif
+- title_family: Georgia, SimSun, serif
+- body_family: "Microsoft YaHei", "PingFang SC", Arial, sans-serif
+- emphasis_family: Georgia, SimSun, serif
+- code_family: Consolas, "Courier New", monospace
- body: 22
- title: 32
- subtitle: 24
- annotation: 14
-> 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.
+> **All five family lines are listed explicitly** so Strategist considers every role when filling this block — easy to forget `code_family` or `emphasis_family` otherwise. In a real project's `spec_lock.md`:
+> - Keep any `*_family` whose role genuinely differs from `font_family`.
+> - **Omit** any `*_family` whose value would equal `font_family` — Executor falls back to `font_family` for missing roles, so writing it twice is noise. (Exception: keep `code_family` even if equal, since it's the conceptually distinct monospace role.)
>
-> **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.
+> `font_family` is the default fallback for roles without an explicit override. Every declared family is a CSS font-stack string.
>
-> **⚠️ 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.
+> **Source of these strings**: they are the *Per-role font stacks* list from `design_spec.md §IV Font Plan` — copy across verbatim. The breakdown table in `design_spec.md` (Chinese / English / Fallback columns) is the human-readable accompaniment; the ordered CSS stack strings live here (and in `design_spec.md`) and must match character-for-character. Stack **order** carries browser-rendering intent (Latin-led vs. CJK-led) that the breakdown table alone cannot encode — see the explainer in `design_spec.md §IV`.
>
-> **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.
+> Sizes (`body` / `title` / etc.) 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`).
>
-> ```
-> - 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
-> ```
+> **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.
>
-> When a `*_family` override is present, Executor MUST use that family for the matching role. When absent, that role falls back to `font_family`.
+> **Stack length discipline.** 3-4 fonts per stack is the sweet spot. Converter only writes the **first** Latin and **first** CJK font into PPTX — everything after is silently dropped. macOS-only families (`Songti SC`, `Menlo`, `Monaco`, `Helvetica`) are auto-mapped to their Windows equivalents via `FONT_FALLBACK_WIN` (see `scripts/svg_to_pptx/drawingml_utils.py`), so stacking both the macOS family and its Windows equivalent is redundant. Lead with Windows-preinstalled fonts (`Microsoft YaHei` / `SimSun` / `Arial` / `Georgia` / `Consolas`); keep at most **one** macOS-exclusive family (typically `"PingFang SC"`) as a browser-preview nicety.
## icons
- library: chunk