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(image-layout): add narrative-intent layer, gate ratio table to side-by-side

hugohe3d8f64be18647
diff --git a/skills/ppt-master/references/image-layout-spec.md b/skills/ppt-master/references/image-layout-spec.md
index 4a2658ce..690810cb 100644
--- a/skills/ppt-master/references/image-layout-spec.md
+++ b/skills/ppt-master/references/image-layout-spec.md
@@ -1,28 +1,32 @@
> See shared-standards.md for common technical constraints.
-# Image Layout Specification (Mandatory)
+# Image Layout Specification
-Layout rules for pages containing images. Both the Strategist planning phase and Executor generation phase must follow these rules.
+Layout rules for pages where the image is placed **side-by-side with body text** as a container block. Both the Strategist planning phase and Executor generation phase must follow these rules when the image's narrative intent is *side-by-side*.
-**Core principle: Calculate layout based on the image's original aspect ratio, ensuring the image is displayed completely without excess whitespace or cropping.**
+**Core principle (side-by-side): Calculate container layout based on the image's original aspect ratio, ensuring the image is displayed completely without excess whitespace or cropping.**
+
+> **Scope note.** This spec applies to the *side-by-side* image intent — the most common case for content pages. For other intents (hero / full-bleed, atmosphere / background layer, accent / inline), container ratio alignment is not a constraint; see `references/strategist.md` §h "Image narrative intent" for how to decide between them. Hero and atmosphere intents intentionally use full-bleed placement (image fills canvas, cropping is expected); the ratio→split table below does NOT apply to them.
---
## Layout Decision Flow
```
-1. Get image original dimensions → Calculate ratio (width/height)
-2. Select layout type based on ratio
-3. Calculate maximum display size for the image
-4. Allocate remaining space for text area
-5. Fill results into the Design Specification's image resource list
+1. Decide narrative intent (hero / atmosphere / side-by-side / accent) — see strategist.md §h
+2. If intent = side-by-side: continue below. Otherwise: compose per narrative; this spec does not apply.
+3. Get image original dimensions → Calculate ratio (width/height)
+4. Select layout type based on ratio
+5. Calculate maximum display size for the image
+6. Allocate remaining space for text area
+7. Fill results into the Design Specification's image resource list
```
**When to execute**: If the image approach includes "B) User-provided", after the Strategist completes the Eight Confirmations and before content analysis and outlining, the scan must be run and the image resource list populated.
---
-## Layout Type Selection (Mandatory)
+## Layout Type Selection (side-by-side intent)
| Image Ratio | Layout Type | Image Position | Description |
|-------------|-------------|----------------|-------------|
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 7118e895..ea405235 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -205,17 +205,28 @@ Selection principle: Font size is based on **content density**, not design style
| Diagram | Flowcharts, architecture diagrams, concept relationship maps |
| Decorative pattern | Partial decoration, textures, borders, divider elements |
-**Image-layout alignment principles** (detailed calculation rules in `references/image-layout-spec.md`):
+**Image narrative intent** (decide this *before* consulting the ratio table — it determines whether the image even lives in a container):
-| Image Ratio | Recommended Layout |
-|-------------|-------------------|
+| Intent | Form | When to use |
+|--------|------|-------------|
+| **Hero / full-bleed** | Image fills the canvas (or a dominant zone); title / caption floats over with a gradient or opacity overlay for legibility | Covers, chapter dividers, `breathing` impact pages — when the image *is* the message, not a companion to body copy |
+| **Atmosphere / background layer** | Image sits behind content as a low-contrast backdrop (reduced opacity or dark overlay); content reads against the treated layer | Section backgrounds, mood-setting pages — when the image sets tone but text carries the information |
+| **Side-by-side** | Image and text occupy adjacent blocks as coequal units — the ratio table below governs container sizing in this case | Most content pages — when image and explanation need to be read together |
+| **Accent / inline** | Small image tucked next to related text as an illustrative element, not a container; no forced ratio matching | Supporting visuals, spot illustrations, small diagrams explaining a term |
+
+> Intent is driven by **what the image is doing narratively**, not by image ratio. The same 16:9 photo can be a hero on one page and a side-by-side block on the next depending on the page's purpose. Do not default every image-bearing page to side-by-side.
+
+**Side-by-side ratio alignment** (consult only when the chosen intent is *side-by-side*; detailed calculation rules in `references/image-layout-spec.md`):
+
+| Image Ratio | Recommended Container Layout |
+|-------------|-----------------------------|
| > 2.0 (ultra-wide) | Top-bottom split, top full-width |
| 1.5-2.0 (wide) | Top-bottom split |
| 1.2-1.5 (standard landscape) | Left-right split |
| 0.8-1.2 (square) | Left-right split |
| < 0.8 (portrait) | Left-right split, image on left |
-Core logic: The layout container's aspect ratio must closely match the image's original ratio. Never force a wide image into a square container or a portrait image into a narrow horizontal strip.
+Core logic (side-by-side only): the container's aspect ratio must closely match the image's original ratio. Never force a wide image into a square container or a portrait image into a narrow horizontal strip. For hero / atmosphere / accent intents, ratio alignment is not a constraint — composition is governed by the page's narrative, not the image's numeric ratio.
> **Portrait canvases** (Xiaohongshu, Story): Layout rules differ — top-bottom is preferred for most ratios since left-right columns become too narrow. See "Portrait Canvas Override" in `references/image-layout-spec.md`.