git:20260606.a35fa7d to git:20260608.0b5a87c

+ description: "The third leg of the slide-assistant three-leg relay (picks up after slide-page-splitter, then hands off to the pptx skill for rendering): once it has the SLIDE_PACKET ▸ Pages, it decides page by page \"what is the most effective visual treatment for this page?\" (chart / bullets / diagram / image / comparison / big statement…), and converges each page into a render-ready per-page visual spec SLIDE_PACKET ▸ Visuals, handing it off to the installed pptx skill to render into a .pptx. Trigger proactively when the user hands over a ▸ Pages handoff packet, or says 「挑視覺呈現」「選版式」「決定每頁要用什麼圖」「把分頁變成可算繪的視覺規格」「準備餵 pptx」. Scope boundary: it only does the visual mapping and layout of 'content → layout archetype → pptxgenjs primitive'; it does not rewrite the storyline (that is slide-storyline-designer), does not re-paginate (that is slide-page-splitter), and does not actually generate the .pptx file (that is the pptx skill)."

+ input: "slide-page-splitter's SLIDE_PACKET ▸ Pages handoff packet (already paginated, with each page carrying page number / corresponding beat / page type / title / content points / information density)"

+ process: "For each page, pick the layout using the 'content characteristics → layout archetype' decision rule → map the title and content points to pptxgenjs primitives (addText/bullets/addTable/addChart/addShape/addImage) and write out the layout → human review keep/adjust → hand off"

+ output: "A render-ready per-page visual spec SLIDE_PACKET ▸ Visuals, handed to the installed pptx skill (Create from scratch / pptxgenjs.md) to render into a .pptx"

+ ## Which leg is this

+ The **third leg** of the slide-assistant three-leg relay. The full relay chain is:

+ zynkr-slide (orchestrator, optional) ─ carries SLIDE_PACKET ▸ Brief throughout

+ slide-visual-selector (1.27) ← you are here

+ pptx skill → renders into .pptx

+ **Core idea**: once pagination is done, the content of every page is **already fixed**, and the only key question left is — "what visual treatment for this page lets the audience understand it fastest and remember it best?" A set of figures laid out as a paragraph of text gets skipped; laid out as a bar chart it's understood in one second. Three parallel options written as bullets are easy to muddle together; turned into a two-column comparison table, the differences become visible. This leg makes exactly that judgment for each page, and converges it into a per-page visual spec that the pptx skill can render **directly**.

+ **What it eats**: `SLIDE_PACKET ▸ Pages` (the output of the previous leg, slide-page-splitter, each page carrying `{page number, corresponding beat, page type, title, content points, information density}`).

+ **What it spits out**: `SLIDE_PACKET ▸ Visuals` (render-ready), each page carrying `{page number, title, layout archetype, visual elements, content mapping, layout, design notes}`, with field names matching the relay contract verbatim, handed to the installed pptx skill to render into a `.pptx`.

+ **What it does NOT spit out**: it does not rewrite the storyline, does not re-paginate, does not generate the `.pptx` file itself. It only does the "content → layout archetype → rendering primitive" visual mapping and layout (see ## Limitations).

+ - **Downstream rendering skill (installed)**: the pptx skill at `~/.claude/skills/pptx/`. When this leg hands off, it asks that skill to take the **Create from scratch** path (`Read ~/.claude/skills/pptx/pptxgenjs.md`). The pptx skill replaces the retired #7 open-slide React runtime, so every visual element in ▸ Visuals must map onto a pptxgenjs primitive, so the downstream can render 1:1.

+ - **Rendering-canvas common sense** (keep this in mind when writing layouts; coordinate unit is inches): the pptx skill defaults to `pres.layout = 'LAYOUT_16x9'`; but this leg always describes layouts in **16:9 widescreen ≈ 13.33" × 7.5"** (i.e. pptxgenjs's `LAYOUT_WIDE`, which the downstream uses if it wants a larger canvas), reserving a 0.5" margin. Coordinates only need to be "relative blocks" (e.g. "left half / right half", "top title band / bottom content area"); the exact x/y/w/h is computed by the pptx skill, and this leg does not hardcode pixel-level coordinates.

+ - **Content→visual decision framework**: `./references/visual-decision-framework.md` ── the complete decision logic of "see this kind of content → use this set of building blocks" (content-relationship classification, detection cues, building-block recipes, worked examples, anti-patterns; synthesizing Zelazny's *Say It With Charts* "define the message first, then pick the chart", the Minto Pyramid, and the visualframeworks.com framework catalog). Consult it first when deciding the layout in Step 2.

+ - **Brand visual source (configuration)**: `./references/brand-source.md` ── this skill does **not** ship brand content built in; this file configures where to load your brand visual standards from (color roles, type scale, image rules, logo), and includes a generic schema. When writing "design notes" in Step 3, load the brand per this file; if unconfigured, fall back to neutral defaults.

+ ## Step 1 — Receive the page list (▸ Pages)

+ Read the previous leg's `SLIDE_PACKET ▸ Pages`, and confirm every page carries the full contract fields: `{page number, corresponding beat, page type, title, content points, information density}`, and that the page type uses the contract enum (`title / section / content / data / quote / closing`).

+ If the user **has not provided** ▸ Pages, first ask them to paste it, or go run `slide-page-splitter` first (and further back, `slide-storyline-designer`). Do **not** make up pagination yourself, and do not expand the visual spec ahead of time when there is no ▸ Pages — that would break the field linkage of the relay contract, and the next leg (the pptx skill) can't catch it either.

+ > **If an upstream `SLIDE_PACKET ▸ Brief` is present (produced by `zynkr-slide`)**: first read the "per-leg emphasis ▸ visual (leg 3)" directives and `presentation purpose`, and use them as weights for choosing archetypes and writing design notes (e.g. deep-dive leans toward `data-chart` / `two-column-compare` (including before/after contrasts) to reveal impact; all-hands leans toward `big-statement`, low density, with `section` pages carried by `big-statement` or a title section variant). When `apply brand` is "yes", load the brand per this leg's `./references/brand-source.md`; when "no", use neutral defaults. If the ▸ Brief's "mode" value is express, this leg's human review (Step 4) switches to **non-blocking**: it lists the per-page visual spec and notes that the user can stop it at any time, and if there are no major issues it automatically continues and hands off to pptx for rendering; when the "mode" value is guided, **or there is no ▸ Brief**, keep Step 4's original per-page blocking HITL. The ▸ Brief's visual preferences are still bound by this leg's gatekeeping principles (one main visual per page, only output layout names within the nine-archetype enum, reject charts with no information, kick density overflow back to leg 2). **When there is no ▸ Brief, this leg runs entirely standalone per the original Step 1–5 flow, and none of the above weights apply.**

+ ## Step 2 — Pick a layout per page (content characteristics → archetype)

+ For **each page**, first read its "page type + content points + information density", then use the table below to map it to one **layout archetype**. The layout enum (strictly aligned with the contract):

+ `title / big-statement / bulleted-list / two-column-compare / data-chart / process-diagram / image-led / quote / closing-CTA`.

+ > The table below is the **common-case quick decision rule**. The full "content relationship → building blocks" classification (with detection cues, recipes, worked examples, anti-patterns) is in `./references/visual-decision-framework.md` ── consult it for any page where you're not sure how to choose. Core principle: **define the message first, then pick the form** (same data, different message → different visual).

+ Decision mapping table (content characteristics → layout archetype):

+ | Content characteristic / signal | Choose this archetype | Why |

+ | Page type = `title` (cover: deck name + subtitle + speaker/occasion) | `title` | First impression; whitespace and a big headline, don't cram content |

+ | Page type = `section` (section divider, announcing the next beat) | `big-statement` or `title` (section variant) | A visual breathing point; one line fills the page, helping the audience reorient |

+ | Only **one** impactful conclusion / key number / one-line claim (low information density) | `big-statement` | One point per page; big type is more forceful than a paragraph of text |

+ | 3–6 **parallel, mutually independent** points, no quantification, no need to compare against each other | `bulleted-list` | Bullets are the most direct; more than 6 points means it should go back to the previous leg to be split |

+ | A **contrast** of two subjects (option A vs B, before/after, current vs target, us vs competitor) | `two-column-compare` | Side by side reveals the difference; clearer than stacked bullets |

+ | Has **quantified data**: trend, share, ranking, multi-period comparison (page type is usually `data`) | `data-chart` | Numbers should be "seen", not "read"; see the chart sub-rule below |

+ | **Ordered process / steps / phases / causal chain / timeline** | `process-diagram` | Use nodes and arrows to express order; bullet text can't express flow |

+ | The message is **carried by the image** (product shot, situational photo, schematic, conceptual metaphor) | `image-led` | One right image beats three lines of text; image leads, text supports |

+ | Page type = `quote` (customer testimonial, famous quote, strong endorsement) | `quote` | Quote marks + attribution with whitespace; borrows third-party authority |

+ | Page type = `closing` (call to action, contact info, next steps) | `closing-CTA` | The ending must make "so what now?" explicit; give a single action |

+ `data-chart` chart-type sub-rule (→ the corresponding pptxgenjs `addChart` chart type):

+ | Data intent | chart type | pptxgenjs |

+ | Compare sizes / rankings across categories | bar (`barDir:'col'` vertical columns or `'bar'` horizontal bars) | `addChart(pres.charts.BAR, …)` |

+ | Trend changing over time/sequence | line | `addChart(pres.charts.LINE, …)` |

+ | Composition share of a whole (≤5 categories) | pie / doughnut | `addChart(pres.charts.PIE / DOUGHNUT, …)` |

+ | Pure tabular, need exact per-cell values | not a chart, use a table instead | `addTable(rows, …)` |

+ Gatekeeping principles when deciding:

+ - **One main visual per page**. Pick **one** main archetype per page; at most add supporting elements (title band, page number, one small icon), don't cram two images onto the same page competing for focus.

+ - **The title carries its own conclusion** (following the previous leg's title philosophy). The visual is only there to "act out" that conclusion, not to decorate.

+ - **Reject charts with no information**. If a page has no quantifiable number, don't force in a chart; bullets or big type are more honest.

+ - **Information density overflow = kick it back to the previous leg**. If a page needs >6 bullets or >1 main image to finish saying its point, that's a pagination problem — flag it and ask the user to go back to `slide-page-splitter` to split the page; this leg does not force a fit by shrinking type.

+ - **Don't decorate, do diagram + use color sparingly** (general design principle). If a structural diagram (geometric shapes) can make it clear, don't stuff in a stock image; **the decision color is used at most once per page** (mark only the real decision / CTA), and the accent color is used sparingly. The actual color values come from the brand loaded via `./references/brand-source.md`.

+ ## Step 3 — Map content to rendering primitives + write the layout

+ After picking the archetype, translate each page's "title + content points" into concrete **visual elements**. Every visual element must be able to map 1:1 to a pptxgenjs primitive, otherwise the pptx skill can't render it:

+ | Visual element | pptxgenjs primitive | Typical use |

+ | Text block | `addText(text, {x,y,w,h,fontSize,color,bold,align})` | Title, big-statement claim, quote, caption |

+ | Bullets | `addText([{text, options:{bullet:true, breakLine:true}}, …])` | Each point of a bulleted-list (use `bullet:true`; do **not** type a unicode "•", it produces a double bullet) |

+ | Table | `addTable(rows, opts)` | The contrast of two-column-compare, data needing exact values |

+ | Chart | `addChart(type, data, opts)` | data-chart (BAR / LINE / PIE / DOUGHNUT) |

+ | Shape diagram | `addShape(pres.shapes.RECTANGLE / OVAL / ROUNDED_RECTANGLE / LINE, {…})` | Nodes/connectors of a process-diagram, color blocks, card backgrounds, column dividers |

+ | Image | `addImage({path|data, x,y,w,h})` | image-led main image, icon (icons are converted from react-icons to PNG; the pptx skill handles it) |

+ Then write the **layout** for each page (describe with relative blocks; coordinates are computed by pptx). The layout skeleton of each archetype:

+ - `title`: a big headline at top-center + one subtitle line; speaker/occasion lower down; lots of whitespace. Dark background with light text (covers commonly use a dark background).

+ - `big-statement`: one claim centered or left-aligned in the upper area, largest type; can add a brand-color block / OVAL as a background accent.

+ - `bulleted-list`: title band at top-left; below it, left-aligned `bullet:true` bullets (**not centered**); the right side can leave a schematic image or icon column.

+ - `two-column-compare`: title band + two left/right columns below (two `addTable`s, or two sets of cards `addShape`+`addText`), columns of symmetric width, header filled with brand color.

+ - `data-chart`: title band (the title states the data conclusion) + the main chart `addChart` filling the bottom main area; alongside it you can place a large number callout (`addText` 60–72pt) pointing out the key takeaway.

+ - `process-diagram`: title band + a row/column of nodes (`ROUNDED_RECTANGLE` cards + inner text) connected by `LINE`, evenly divided by the number of steps; numbered 1→N.

+ - `image-led`: a half-page main image (`addImage`, left-half or right-half bleed) + the other half with overlaid text or whitespace; the text block's color contrasts enough with the image.

+ - `quote`: a large quote mark + the quote (italic or big type) centered/left-aligned + small attribution lower down; lots of whitespace.

+ - `closing-CTA`: an explicit single action (`addText` big type) + necessary contact info/QR; dark-background ending echoing the cover, forming a "dark—light—dark" sandwich.

+ Mark the **design notes** per page, applying the brand loaded via `./references/brand-source.md` (use neutral defaults if no brand is configured):

+ - **Background color**: use the brand's "default surface color"; cover / section / closing use the brand's "dark contrast color" as a full-bleed dark background (text flips to the surface color).

+ - **Decision emphasis**: at most one "decision color" per page (CTA / the single decision); the key thinking verb uses the "accent color" (≤ 1 per title).

+ - **Type scale**: give pptx `fontSize` per the brand type scale (title / body / footnote / numbering); use the brand font roles (display / body / numbering / Chinese) for typefaces.

+ - **Chart coloring**: use the brand palette; only the key series gets the decision color; do **not** use Office's default rainbow.

+ - Mark on each page which word / which number to "emphasize". Color values given to pptx always drop the `#` (e.g. `color: "RRGGBB"`).

+ ## Step 4 — Human review (HITL)

+ List the per-page visual spec to the user **numbered** (one summary line per page: `P# | title | archetype | main visual element`), and ask them to confirm page by page, requesting keep / change layout / adjust layout. Key items for the user to review:

+ 1. Whether the layout was chosen correctly (especially judgments like "should this use a chart" or "should this use a comparison table").

+ 2. Whether any page's information density is too high and should actually go back to `slide-page-splitter` to be split.

+ 3. Whether every page's visual elements all map onto a pptxgenjs primitive (nothing "can't be drawn").

+ Before the user signs off on everything, do **not** hand off to the pptx skill for rendering. If changes are large, adjust and then list it again for their review.

+ ## Step 5 — Hand off and save (→ pptx skill renders)

+ After review passes:

+ 1. Save the complete `SLIDE_PACKET ▸ Visuals` into this deck's working subfolder (durable record, the same SLIDE_PACKET as 1.25 / 1.26).

+ 2. **Call the installed pptx skill**: ask it to take the **Create from scratch** path (`Read ~/.claude/skills/pptx/pptxgenjs.md`), with `SLIDE_PACKET ▸ Visuals` as input, and page by page `pres.addSlide()` render each visual element with its corresponding primitive into a `.pptx`, and complete the QA that the pptx skill itself requires (markitdown text check + subagent visual check).

+ 3. Remind the pptx skill: colors and fonts follow the brand loaded via `./references/brand-source.md` (surface-color background, single decision color, brand-palette charts, color values with `#` dropped), and the layout follows the layout this leg gives; use neutral defaults if no brand is configured.

+ Handoff block (render-ready, fields strictly aligned with the contract):

+ SLIDE_PACKET ▸ Visuals (handed to the pptx skill to render into a .pptx)

+ Per-page visual spec (one entry per page):

+ - Page number: P1

+ Title: <this page's title (carries its own conclusion)>

+ Layout archetype: <title / big-statement / bulleted-list / two-column-compare / data-chart / process-diagram / image-led / quote / closing-CTA>

+ Visual elements:

+ - <text block addText> — <content>

+ - <bullets / table addTable / chart addChart{type} / shape diagram addShape / image addImage> — <content/data>

+ Content mapping: <which of ▸ Pages's content points each of these visual elements carries>

+ Layout: <relative-block description, e.g.: title band at top; two left/right columns below; right-half main image…(canvas 16:9 ≈ 13.33×7.5, margin 0.5")>

+ Design notes: <dark/light background, type-scale hierarchy, which word/number to emphasize; colors per brandbook primary/accent color>

+ - Page number: P2

+ …(same structure as above, list every page)

+ — Visual spec confirmed page by page; ready to hand off to the pptx skill (Read pptxgenjs.md, Create from scratch) to render into a .pptx.

+ A render-ready per-page visual spec `SLIDE_PACKET ▸ Visuals`: every page has its layout archetype decided, lists the visual elements that map 1:1 onto pptxgenjs primitives, has its layout and brandbook-based design notes written, and has been reviewed by the user page by page, ready to hand directly to the installed pptx skill to render into a `.pptx`.

+ It only does the visual selection and layout of "content → layout archetype → pptxgenjs rendering primitive". It does **not**:

+ - **Rewrite the storyline**: the presentation goal / core claim / narrative arc belong to the first leg `slide-storyline-designer` (1.25) (▸ Storyline).

+ - **Re-paginate or change what each page says**: that is the second leg `slide-page-splitter` (1.26) (▸ Pages); when a single page's information overflows, it only flags it for return, it does not force a cram.

+ - **Actually generate the `.pptx` file, write pptxgenjs code, or do the final rendering QA**: that is the downstream installed **pptx skill** (`~/.claude/skills/pptx`, Create from scratch / pptxgenjs.md); this leg only hands ▸ Visuals to it.

+