---
name: qvantum-powerpoint
description: Use when the user wants to create a Qvantum-branded PowerPoint / slide deck / .pptx (e.g. "make a Qvantum deck about X", "5 slides on Y in our template"). Generates brand-correct slides from the official Qvantum .potx template via python-pptx — real theme colours (navy #002656), Host Grotesk fonts, the Q logo on every layout — driven by a simple JSON deck spec, and renders each slide to PNG (via PowerPoint→PDF) for visual QA before handing over.
---

# Qvantum PowerPoint

Build on-brand Qvantum decks by **generating from the official `.potx` template** rather than restyling slides by hand. Every slide inherits the real theme (palette, fonts, the Q logo baked into each layout); you supply content + which layout, and the builder fills it in with brand-correct typography.

## When to use
- "Create a PowerPoint that follows our Qvantum template."
- "Make N slides about <topic> in the Qvantum style."
- Any Qvantum-branded deck, cover, or section opener.

## What's in this skill
```
assets/   Qvantum_PPT_template_251118.potx   ← the official template (source of truth)
          qvantum-logo-full / -symbol-navy / -symbol-white .png
          fonts/HostGrotesk-*.ttf            ← the brand font (install on each machine)
scripts/  build_deck.py                      ← the generator (template patch + JSON→.pptx)
          render_deck.py                     ← cross-platform QA render (pptx → PNGs)
reference/brand/    full brand reference (colours, type, logo, imagery, …)  ← READ FIRST
reference/layouts.md   placeholder map for all 18 layouts (idx → type → position)
reference/deck-spec.md the JSON deck-spec format
reference/example/     a complete 5-slide example spec + a rendered slide
```

## Workflow
1. **Read the brand reference first** — at minimum `reference/brand/powerpoint-playbook.md`, `colors.md`, `typography.md`. This is non-negotiable for staying on-brand. *(If the user keeps a project copy of `brand/`, read that too — it may be newer.)*
2. **Pick layouts** for the story from `reference/layouts.md`. One idea per slide; big Regular headline; minimal copy; lots of white space.
3. **Handle images.** Qvantum product/stock photos live on SharePoint and **cannot be fetched by tools (403)** — the user downloads them locally into a **`pics from Sharepoint/`** folder (containing `Products and Components Images/` + `Stock Images/`). The builder **auto-discovers that folder** by walking up from the deck spec (and the cwd), so use **relative paths** like `"Stock Images/foo.jpg"` and the deck stays portable across machines — no `images_dir` needed (set it only if the pics live somewhere else). Preview candidates with a PIL contact sheet before picking strong, clean, modern shots.
4. **Author a deck spec** (`*.deck.json`) per `reference/deck-spec.md`. Style each field with the brand type scale (Regular headlines, SemiBold uppercase labels, off-black `#232222` body, navy/brown accents).
5. **Build:** `python3 scripts/build_deck.py path/to/deck.json`
6. **QA visually — always.** Render every slide to PNG and look at it:
   ```sh
   python3 scripts/render_deck.py /abs/deck.pptx /abs/out
   ```
   `render_deck.py` is cross-platform: macOS → PowerPoint via AppleScript → `pdftoppm`; Windows → PowerPoint COM (PowerShell, no extra tools); Linux → LibreOffice. Read the `slide-*.png` files it writes, fix spacing/overflow/colour, and rebuild.

## Quick start
```sh
python3 ~/.claude/skills/qvantum-powerpoint/scripts/build_deck.py my.deck.json
```
Minimal spec:
```json
{
  "output": "/abs/my-deck.pptx",
  "images_dir": "/abs/pics",
  "footer": "AI @ Qvantum  ·  2026",
  "slides": [
    { "layout": "Main_slide_off-white",
      "images": { "1": "Products/hero.jpg" },
      "placeholders": {
        "13": { "paragraphs": [ {"text":"Eyebrow","weight":"semibold","size":12,"color":"91877A","upper":true,"spacing":1.6} ] },
        "14": { "paragraphs": [ {"text":"Big title","weight":"regular","size":36,"color":"232222"} ] },
        "15": { "paragraphs": [ {"text":"Subtitle","weight":"regular","size":16,"color":"232222"} ] }
      } }
  ]
}
```

## Brand rules (the short version — full detail in `reference/brand/`)
- **Lead with off-black `#232222` + off-white `#F4F4F4`/beige `#E5E6DF`.** Imagery carries the colour. Accents (navy `#002656`, blue, red, orange, yellow) **sparingly** — one accent thing per slide.
- **Host Grotesk.** Big headlines/statements = **Regular**; section titles, sub-heads, labels = **SemiBold** (`Host Grotesk SemiBold` is a *separate* family). Labels UPPERCASE + ~1.2–1.6 pt tracking.
- **Logo** is already on the template layouts — don't add one by hand.
- **One idea per slide**, generous white space, reduced copy.

## Gotchas
- The `.potx` ships with **10 example/"tips" slides** — `build_deck.py` strips them automatically (`clear_slides`).
- python-pptx can't open a `.potx` directly; the builder patches `[Content_Types].xml` (template→presentation) and swaps the theme font (Aptos→Host Grotesk) in a temp copy.
- **Font portability:** Host Grotesk renders here, but on machines without it, embed fonts in PowerPoint (*File ▸ Save ▸ Embed fonts*). python-pptx can't embed.
- Large photos are auto-downscaled to ≤2200 px to keep the file small.

## Setup on a new machine (incl. Windows)
Building a deck is **pure Python and fully cross-platform** (Windows/macOS/Linux); only the optional QA-render differs per OS and is handled by `render_deck.py`.
1. **Python deps:** `pip install python-pptx pillow lxml`.
2. **Fonts:** install Host Grotesk — the four `.ttf` files are bundled in `assets/fonts/`. Windows: select all four → right-click → *Install for all users*. macOS: double-click → *Install*. Without the font, text falls back and looks wrong (and decks won't embed it).
3. **Pictures:** place a `pics from Sharepoint/` folder (containing `Products and Components Images/` + `Stock Images/`) at or above where the deck spec lives — the builder auto-discovers it. Use relative image paths in the spec.
4. **(Optional) QA rendering** via `render_deck.py`: needs **Microsoft PowerPoint** (Windows: COM, no extra tools; macOS: also `pdftoppm` from poppler) or **LibreOffice** on Linux. Not needed to build or open decks.

> Note: deck specs are read as **UTF-8** and the Windows render path uses PowerPoint COM — both verified by code review; the Windows/Linux render branches are written but were validated only on macOS here.
