pptx-slide-specification

# 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. ```json { "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. ```json { "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": { "x": 0, "y": 0, "width": 13.333, "height": 7.5 } } }, "objects": { "title": { "id": "title", "kind": "text", "role": "title", "classification": "content", "content": { "text": "Overview" }, "style": { "font_size": 30, "color": "#111827" }, "bbox": { "x": 0.75, "y": 0.55, "width": 8.5, "height": 0.65 }, "z_index": 2 } } } } ``` ## 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.