pptx-slide-specification

name	pptx-slide-specification
description	Author or repair coordinate-explicit JSON specifications for editable PPTX decks.

PPTX Slide Specification

Use this skill when writing or repairing a coordinate-explicit JSON deck spec.

Author final coordinates directly in layout_tree; plugin scripts will not choose layouts, measure browser boxes, or shrink text to fit. Split dense material across slides rather than relying on tiny fonts.

Workflow

1. Define slide messages, design context, and slide size.
2. Create each slide with id, title, and complete layout_tree.
3. Place groups and objects with final inch bboxes, z-order, and styles.
4. Add at least one style-derived layout_design element on normal content slides.
5. Audit collisions, density, font sizes, and default-theme failures.

Deck Shape

• Return a JSON object with top-level slides; use stable readable IDs such as s01_overview.
• Use top-level summary for audit metadata. Newly generated decks require summary.design_context unless a user-provided brand guide or reference PPTX is documented as the primary style source.
• Record design profile IDs, source URLs, and license IDs in summary.design_context when using design references.
• Use render_mode: "layout" or omit it for generated decks. OOXML mode is only for extracted specs with ooxml_elements.
• Every generated slide must include layout_tree; do not rely on shorthand layout specs.
• Production decks must also include summary.layout_policy and summary.accessibility. They define the usable content region and document language before the PPTX is built.

Production Metadata

Use this compact form for production decks. Values may change for a different slide size or an approved design system, but all values must be explicit.

{
  "summary": {
    "layout_policy": {
      "safe_margin": 0.5,
      "content_bottom": 6.7,
      "footer_top": 6.85,
      "minimum_gap": 0.12
    },
    "accessibility": {
      "language": "en-US",
      "presentation_title": "Quarterly operating review"
    }
  }
}

content_bottom must be lower than footer_top. Content objects must end at or above content_bottom. Footer objects may use the space from footer_top to the slide edge. A footer never overlaps content.

Slide Fields

• Each generated slide must include id, title, and layout_tree.
• Production slides must include accessibility.reading_order, an ordered list of meaningful object IDs. The order must follow the intended reading sequence.
• Use hidden: true only for appendix/reference slides that should remain in the PPTX package but not appear during normal presentation.
• Do not use pattern, layout_pattern, composition.pattern, layout, sections, bullets, objects, or theme as render-time shorthand. Decide all positions, sizes, z-order, colors, font sizes, and relationships in the JSON before rendering.
• Do not overfill a slide: prefer three to five major content groups.
• Do not ship default python-pptx-looking slides: plain white background, Calibri-only text, default theme colors, and bullet-only layouts are design failures unless explicitly requested.

Layout Tree

• Required keys: slide_size (width, height in inches), root_group_id, groups keyed by ID, and objects keyed by ID.
• groups and objects are id-keyed maps; object_ids/group_ids are arrays. Add notes only when useful for audit or speaker context.

{
  "id": "s01_overview",
  "title": "Overview",
  "layout_tree": {
    "slide_size": { "width": 13.333, "height": 7.5 },
    "root_group_id": "root",
    "groups": { "root": { "id": "root", "role": "slide", "layout_mode": "absolute", "object_ids": ["title"], "group_ids": [], "bbox": {           
                                          
  

Layout Grid & Safe Margins

• Reserve a content-safe margin on every edge; default 0.5 in for 13.333×7.5 in slides. Only layout_design full-bleed bands may cross an edge.
• Use a consistent column grid, e.g. 12 columns with 0.2–0.25 in gutters; align sibling cards to shared tops, widths, and heights.
• Keep a vertical rhythm: title band first, then content below the title rule, e.g. y ≤ 1.3 in.
• No content object may extend past the slide bounds (0,0)–(width,height) or into the safe margin.
• A footer object may enter the declared footer rail. It must stay on the slide canvas and cannot overlap a content object.

Groups

• Each group must include id, role, layout_mode, object_ids, group_ids, and bbox.
• Use layout_mode: "absolute" for generated slides to make the coordinate contract explicit.
• Keep group IDs unique and stable for audit repairs.
• Keep every child inside its parent bbox; siblings at the same level must not overlap unless one is layout_design behind the other.
• Use groups for semantic organization and audit readability; coordinates remain final object coordinates.

Objects

• Every object must include id, kind, role, classification, content, style, bbox, and z_index.
• Supported kind values: text, shape, image, line, table.
• classification is layout_design for decorative/background objects, content for meaningful text, tables, lines, and media.
• Shape names: rect, round_rect, oval, triangle, diamond, hexagon, parallelogram, chevron, pentagon, trapezoid, and arrow variants.
• Shape content must include content.shape; text on a shape uses content.text. Image content uses content.path, content.blob_base64, and content.alt.
• Meaningful images require content.alt. Decorative images must have classification: "layout_design" and must not appear in the slide reading order.
• A sourced metric, chart value, quotation, or factual claim requires source_ref with source_id, locator, claim_type, and verification_status. Use locator for a page, figure, table, section, or spreadsheet range.
• Table content uses content.rows; make column widths sum to bbox.width, size rows for wrapped text, and split long tables with repeated headers.
• Line content must include content.x1, content.y1, content.x2, and content.y2.
• Connectors anchor to edge midpoints, leave a small node-border gap, and route around other nodes.
• Do not use chart objects. Build charts from editable text, shapes, lines, and tables. A chart image may support the slide, but it cannot be the only presentation of editable chart values or labels.

Styling

• Every text-bearing object and table must include style.font_size and style.color.
• Every line object must include style.line and style.line_width.
• Every shape object must include content.shape, style.fill, and style.line.
• Specify text color with style.color; do not rely on inferred contrast or default text color.
• Use a consistent z_index stack: background band (0) < card/panel (1) < rule (2) < image/diagram (3) < body text (4) < label/badge (5) < callout/number (6). Decorative overlaps are allowed only when the lower object is layout_design.
• When text sits on a shape or card, inset the text bbox by ≤0.1 in on each side from the shape bbox and size the text to that inner area, so on-card text never overflows the card.
• Every normal content slide must include at least one layout_design object or style-derived visual structure such as an accent band, card shell, divider, signature shape, or image treatment.
• Do not use a raster or SVG as the full content of a slide. When a source visual contains essential text, labels, numbers, or a legend, recreate that information with editable native objects. Keep the original visual only as an optional supporting asset or hidden reference.

Type Scale

Recommended/minimum pt: title 24–32/20; H2 16–20/14; claim 13–15/12; body 11–12/10; evidence 10–11/10; label 9–10/9; footer/meta 8–9/8. Decorative layout_design text may go below the content floor; any content text must stay at 9 pt or above.

Build Contract (spec → PPTX)

No renderer is bundled. Author the JSON spec and a small python-pptx build script. To keep rendered output matching audited coordinates:

• Start each slide from blank layout slide_layouts[6] so placeholders, theme text, and bullet styles do not leak in.
• Place every object from its bbox with Inches(...) geometry; never rely on placeholder auto-position.
• For every text frame set word_wrap = True and auto_size = MSO_AUTO_SIZE.NONE; disable shape autofit/auto-grow.
• Zero or shrink default text insets (margin_left/right/top/bottom), or subtract them from capacity estimates.
• Set vertical anchor (MSO_ANCHOR) and horizontal alignment (PP_ALIGN) explicitly.
• Map style.font_size→Pt, colors→RGBColor, style.line_width→Pt/Emu, dash→MSO_LINE_DASH_STYLE.
• Preserve image aspect ratio (see pptx-visual-assets); do not stretch to a mismatched bbox.
• Mark hidden slides with show="0" and keep them last.
• Reject every zero or negative bbox before adding a shape, line, image, table, or text box. A valid ZIP package can still contain geometry that PowerPoint will not open.
• Write a small build manifest with the builder path, input spec path, output PPTX path, slide count, and build warnings. Do not add a generic renderer only to create this manifest.

A JSON-audit pass can still overflow if the build script skips these text-frame controls.

Repair Rules

• If content collides, edit bboxes, z-order, grouping, slide density, or split the slide.
• If text overflows, shorten copy, enlarge the bbox, or split content across slides. Lower font_size only as a last resort, and never below the type scale minimum.
• For CJK or other full-width text, halve the Latin character-capacity estimate so dense Japanese/Chinese/Korean copy does not silently overflow.
• If an object sits outside the slide bounds or inside the safe margin, move or resize it back inside; only layout_design full-bleed bands may cross an edge.
• If an object is misplaced, repair the final coordinates directly; do not add layout hints expecting a later tool to resolve them.