officecli-pptx

# OfficeCLI PPTX Skill ## Setup If `officecli` is missing: - **macOS / Linux**: `curl -fsSL https://d.officecli.ai/install.sh | bash` - **Windows (PowerShell)**: `irm https://d.officecli.ai/install.ps1 | iex` Verify with `officecli --version` (open a new terminal if PATH hasn't picked up). If install fails, download a binary from https://github.com/iOfficeAI/OfficeCLI/releases. ## ⚠️ Help-First Rule **This skill teaches what good slides look like, not every command flag. When a property name, enum value, or alias is uncertain, consult help BEFORE guessing.** ```bash officecli help pptx # List all pptx elements officecli help pptx <element> # Full element schema (e.g. shape, chart, animation, connector, zoom, group, background) officecli help pptx <verb> <element> # Verb-scoped (e.g. add shape, set slide) officecli help pptx <element> --json # Machine-readable schema ``` Help reflects the installed CLI version. When skill and help disagree, **help is authoritative**. Triggers to run help immediately: `UNSUPPORTED props:` warning, unknown animation preset, `connector.shape=` enum drifts, prop-vs-alias (`lineWidth` vs `line.width`, `color` vs `font.color`). ## Shell & Execution Discipline **Shell quoting (zsh / bash).** ALWAYS quote element paths (`"/slide[1]/..."`) — zsh globs unquoted `[1]` to `no matches found`. Escapes happen at two layers; the CLI handles one for you: 1. **Shell.** `$` in a value still belongs to the shell — single-quote the whole value: `--prop text='$15M'`. Double-quoted `"$15M"` gets expanded to `M`. The CLI does NOT unescape `\$` for you. 2. **CLI (`text=`).** The two-char escapes `\n` and `\t` ARE interpreted, consistently across pptx / docx / xlsx — `\n` is a line / paragraph break, `\t` is a tab. To produce a literal backslash-n in text, double it (`\\n`); this is rarely what you want. 3. **JSON (batch).** Real newlines / tabs can also be passed as `"\n"` / `"\t"` inside a `<<'EOF'` heredoc; both forms produce the same result. If in doubt, `view text` after writing and compare character-for-character. **Incremental execution.** One command → check exit code → continue. A 50-command script that fails at command 3 cascades silently. After any structural op (new slide, chart, animation, connector) run `get` before stacking more. ## Requirements for Outputs These are the deliverable standards every deck MUST meet. Violating any one = not done, regardless of content quality. ### All decks **One idea per slide.** If a slide needs a second title to explain what it covers, split it. Dense "everything about X" slides lose the audience inside 3 seconds. Use a section divider to group related one-idea slides, not a mega-slide. **Explicit type hierarchy — do NOT rely on theme defaults.** Theme defaults drift between masters. Set sizes explicitly on every text shape. | Element | Minimum | Typical | Min shape height | | -------------------- | --------------- | ------- | ---------------- | | Slide title | **≥ 36pt** bold | 36–44pt | ≥ 2cm | | Section / subtitle | ≥ 20pt | 20–24pt | ≥ 1.2cm | | Body text | **≥ 18pt** | 18–22pt | ≥ 1cm | | Caption / axis label | ≥ 10pt muted | 10–12pt | ≥ 0.6cm | Rule of thumb: **min shape height ≈ font_pt × 0.05cm**. An 18pt sublabel in a 0.8cm-tall box will overflow — `view annotated` catches this. Title must be **≥ 2× body size** (36pt over 20pt works; 28pt over 20pt looks timid). Four legit exceptions to body ≥ 18pt: chart axis labels, legends, footer / page number, and ≤ 5-word KPI sublabels (e.g. "Active users"). Descriptive sentences must be ≥ 18pt. Left-align body; center only titles and hero numbers. If "the cards won't fit", drop cards instead of shrinking font. **Two fonts max, one palette.** One heading font + one body font (e.g. Georgia + Calibri). One dominant brand color (60–70% weight) + one supporting + one accent. Never mix 4+ colors in body content. **Every slide carries a non-text visual.** Shape, chart, icon, gradient band. A bullet-only deck is interchangeable with a Word doc. Exceptions: literal quote slides, code blocks, a single summary-table slide. **Speaker notes on every content slide.** `--type notes --prop text="..."`. The speaker needs a script; the audience shouldn't read the slide verbatim. **Preserve existing templates.** When a file already has a theme and masters, match them. Existing conventions override these guidelines. ### Visual delivery floor (applies to EVERY deck) Before declaring done, the per-slide render (see QA) MUST satisfy: - **No placeholder tokens rendered as content.** `{{name}}`, `$fy$24`, `<TODO>`, `lorem`, `xxxx`, empty `()`/`[]` in chart titles never appear. - **No overflow past slide edges.** For 16:9 (33.87 × 19.05cm), every shape satisfies `x + width ≤ 33.87cm` AND `y + height ≤ 19.05cm`. `get` and check — don't eyeball. - **No text overflow inside shapes.** A 72pt KPI in a 4cm-tall box clips. Shrink the number, enlarge the box, or shorten the text — never trim content to fit. - **Cover slide is content-rich.** Title + subtitle + presenter/client block + date + a brand band or key-takeaway strap. A cover with 80% whitespace reads as a stub. - **Contrast.** On fills with brightness < 30% (`1E2761`, `36454F`, `000000`, deep forest / berry / cherry), every run of body text, card body, chart series fill, and icon color must be `FFFFFF` or brightness > 80%. Mid-gray (`6B7B8D` ≈ 44%) reads fine on a laptop and vanishes on projection. Verify via `view html` after the dark-fill pass. - **No `\$` literals in slide text.** If `view text` shows a literal `\$`, the shell didn't unescape it (the CLI does NOT interpret `\$`). Single-quote the value: `--prop text='$15M'`. Note: `\n` and `\t` ARE interpreted as a real paragraph break / tab; seeing those as literals means the value was double-escaped (`\\n`). If any fails, STOP and fix before declaring done. ### KPI fit math **KPI text must fit the card — pre-compute, don't eyeball.** In a 7cm-wide card at 60pt Georgia bold, values with `$` and `.` (wide glyphs) wrap at 4 characters. `$9.4M` breaks the card; use `$9M` + "USD millions" sublabel, or move to the 3-card 9.78cm layout. Upper bound: `max_size_pt ≈ card_width_cm × denom`, where denom = 10 for 1–2 chars, 7 for 3–4 chars, 5 for 5+ chars. ### `layout=blank` and alt text - **`layout=blank` is the default for custom designs.** Titles become plain `shape` elements, not placeholders. `view outline` / `view issues` reporting `(untitled)` / `Slide has no title` is **expected**, not a defect. Use `layout=title` + `placeholder[title]` only when screen-reader outline compatibility matters. - **Alt text verification.** `view stats "Pictures without alt text: 0"` is a false-positive zero (alt auto-fills to filename) — verify via `view annotated`. ## Design Principles A deck is not a document. The audience has 3 seconds to get each slide. Before adding anything, ask: "If the audience reads only the biggest element and glances once, do they get the point?" If they have to read the bullets, the biggest element is wrong. ### Grid, margins, negative space Standard widescreen is **33.87 × 19.05cm**. Treat it as a 12-column grid internally: - **Edge margin ≥ 1.27cm** (0.5") on all sides. - **Inter-block gap ≥ 0.76cm** (0.3") between cards / columns / rows. - **≥ 20% negative space per slide.** Filling every pixel reads as amateur. - For card grids: `usable = 33.87 − 2·margin − (N−1)·gap`, then `col_width = usable / N`. Don't hand-pick x coordinates. ### Font pairings Two fonts max — one for headings, one for body. Pair by document register, not by novelty. "Best For" is a prompt, not a decree; if the topic matches a row, use it as the default and move on. | Header | Body | Best For | | ------------ | ------------- | ------------------------------------------- | | Georgia | Calibri | Formal business, finance, executive reports | | Arial Black | Arial | Bold marketing, product launches | | Calibri | Calibri Light | Clean corporate, minimal design | | Cambria | Calibri | Traditional professional, legal, academic | | Trebuchet MS | Calibri | Friendly tech, startups, SaaS | | Impact | Arial | Bold headlines, event decks, keynotes | | Palatino | Garamond | Elegant editorial, luxury, nonprofit | | Consolas | Calibri | Developer tools, technical / engineering | Set both fonts explicitly on every shape (`--prop font=Georgia` on title shapes, `--prop font=Calibri` on body shapes) — theme-default inheritance drifts between masters. ### Color and contrast One dominant color does 60–70% of visual weight, two supporting tones, one accent used sparingly. Never use 4+ colors in body content. Columns are: **Primary** (dominant — the one color you see first), **Secondary** (the supporting tone), **Accent** (sparing, one-hit emphasis), **Text** (body on light fills), **Muted** (captions / axis labels / footer). | Theme | Primary | Secondary | Accent | Text | Muted | | ------------------ | -------- | --------- | -------- | -------- | -------- | | Coral Energy | `F96167` | `F9E795` | `2F3C7E` | `333333` | `8B7E6A` | | Midnight Executive | `1E2761` | `CADCFC` | `FFFFFF` | `333333` | `8899BB` | | Forest & Moss | `2C5F2D` | `97BC62` | `F5F5F5` | `2D2D2D` | `6B8E6B` | | Charcoal Minimal | `36454F` | `F2F2F2` | `212121` | `333333` | `7A8A94` | | Warm Terracotta | `B85042` | `E7E8D1` | `A7BEAE` | `3D2B2B` | `8C7B75` | | Berry & Cream | `6D2E46` | `A26769` | `ECE2D0` | `3D2233` | `8C6B7A` | | Ocean Gradient | `065A82` | `1C7293` | `21295C` | `2B3A4E` | `6B8FAA` | | Teal Trust | `028090` | `00A896` | `02C39A` | `2D3B3B` | `5E8C8C` | | Sage Calm | `84B59F` | `69A297` | `50808E` | `2D3D35` | `7A9488` | | Cherry Bold | `990011` | `FCF6F5` | `2F3C7E` | `333333` | `8B6B6B` | Pick by topic, not by default — finance reads Midnight Executive, a product launch reads Coral Energy, safety / LOTO reads Cherry Bold. If the closest named theme is not quite right, blend (e.g. Forest primary + gold `D4A843` accent). Use **Text** on light fills, **Muted** for captions / axis / footer, `FFFFFF` or Secondary for body on dark fills. On dark backgrounds, text and chart series follow the Hard rules contrast floor above. ### Chart-choice decision table Wrong chart type kills the 3-second test: | Data shape | Use | Avoid | | ------------------------------------ | --------------------------------------------------------------- | ---------------------------------------- | | Category comparison (A vs B vs C) | `column` (vertical) / `bar` (≥ 6 categories, horizontal) | pie (slices merge), line (no time axis) | | Time series, 1–3 series | `line` | area (occlusion), bar (implies discrete) | | Part-of-whole, 2–5 slices | `pie` / `doughnut` | pie with 8+ slices (unreadable) | | Correlation / distribution | `scatter` | line (implies ordering) | | Multiple categories × metrics, dense | stacked `column` or heatmap | one chart per metric — consolidate | | KPI snapshot (single big number) | **Large-text shape** (60–72pt + ≤ 5-word sublabel), NOT a chart | gauge chart, tiny bar | Rule of thumb: if > 3 series and > 8 categories, split into two charts or switch to a table. ### Animation restraint Each animation is a cognitive interrupt. Limits: - **≤ 1 animation per slide**, duration **≤ 600ms**. - Use only `fade`, `appear`, or a single `zoom-entrance` on a hero slide. - Never: `bounce`, `swivel`, `fly-from-edge`, `spin`, multi-object choreography. - Animation is runtime-only — verify in a live presentation viewer. ### Layout patterns & data display Vary layout across slides — repeating the same pattern makes every slide feel identical. Pick one per slide from these building blocks: | Pattern | When to use | Key measurement |