Composition Recipes¶

Shared Geometry¶

Read pagesetup(action: "get-settings", session_id: ...) first. Let W and H be the slide dimensions in points. The examples use H=540 and W=960 (16:9) or W=720 (4:3). Horizontal coordinates below are fractions of W; vertical coordinates and font sizes are points at H=540. For a different height, multiply vertical coordinates, heights, and font sizes by H/540, then verify the render. Only the two example sizes have been tested.

• Start with slide(action: "add-blank", ...). Use its returned slide index.
• Content starts at 0.055W; its width is 0.89W.
• Title box: left 0.055W, top 40, width 0.89W, height 75, 32pt bold.
• Examples use Aptos, dark text RGB(28,35,40), and teal rules RGB(0,115,110) on white. For a branded deck, use its approved palette and verify foreground/background contrast.
• Add text with shape(action: "add-text-box", ...), then use the returned shape index for textframe font and color actions. Rules are rectangles with a solid fill and no visible line. All elements remain editable.
• Add speaker notes, export the slide to PNG, and inspect it at its intended size. Check chart labels separately: text-box bounds do not validate chart internals.

Comparison¶

Use for two alternatives evaluated on the same three criteria. Do not imply one option is preferred through unequal widths or inconsistent ordering.

Example: Shared service vs Dedicated team, with Start, Capacity, and Best for in that order on both sides. Keep headings to a few words and each criterion to a short phrase. More alternatives or long paragraphs belong on another slide or in a table. At 4:3, rewrite long labels before reducing the body font.

Chart and Insight¶

Use for one numeric series and one supported takeaway. Keep the chart native, not a screenshot or a collection of hand-drawn bars.

Tested example: chart_type: "bar", categories Q1-Q4, series Active teams, values [12,18,25,34], chart title Active teams, legend hidden. The takeaway is +22 teams, the difference between Q4 and Q1, not a percentage. Interpretation: "Growth continues. Next: verify retention." The source explicitly identifies the data as synthetic.

Use short category labels and no more than four categories for this recipe. More series or dense labels need a full-width chart. Preserve units, relevant baseline, and source context; do not invent a causal explanation from a trend.

Three-Step Timeline¶

Use for three ordered milestones, not a duration-scaled project schedule.

For step i=0,1,2, left is 0.055W + i*0.305W; width is 0.28W.

Example: Weeks 1-2 / Discover / Confirm the need; Weeks 3-4 / Pilot / Validate with users; Week 5 / Launch / Release and monitor. Use one short outcome per milestone. Add a 16pt footer at top 455, height 45, explaining that spacing is not elapsed time. Dependencies, overlapping phases, or more milestones need a different layout; equal spacing would misrepresent a true schedule.

Metric Callout¶

Use for one value that needs a definition and a meaningful comparison.

Example: 18 days, Median time to first result; Previously 24 days; Synthetic cohort: 40 teams, last quarter. Do not omit the unit, denominator, time period, or qualification needed to interpret the number. Multiple competing metrics or a long qualification need a different slide, not several oversized numbers.

Reproduce the Examples¶

CompositionRecipeTests.Recipes_RenderWithContentInsideSlideBounds in the Core test project builds all four examples through public commands at both sizes. It verifies text read-back, COM text bounds, chart category count, and PNG export. All labels and data are authored synthetic examples; no external deck is needed.

On Windows with PowerPoint installed, run from the repository root:

$env:PPTMCP_RECIPE_OUTPUT = Join-Path $env:TEMP 'powerpoint-composition-recipes'
try {
    dotnet test tests/PowerPointMcp.Core.Tests -c Release --filter 'FullyQualifiedName~CompositionRecipeTests' --blame-hang-timeout 5m
} finally {
    Remove-Item Env:PPTMCP_RECIPE_OUTPUT
}

The output contains 720x540 and 960x540 folders, each with recipe-1.png through recipe-4.png in the order above. Without the environment variable, the test deletes its temporary exports. Inspect all eight images after changing fonts, content, or geometry. Passing bounds checks alone is not a visual review.