# Deck Spec Reference

A deck is described by a JSON file passed to `scripts/build_deck.py`.

## Top level
```json
{
  "template": "<path to .potx/.pptx>",   // optional; default = bundled Qvantum template
  "output":   "<path to output .pptx>",   // required
  "images_dir": "<base dir>",  // optional — if omitted, the builder auto-discovers a 'pics from Sharepoint/' folder at or above the spec (or cwd); image paths are then relative to it, e.g. "Stock Images/foo.jpg" (portable across machines)
  "footer":   "<default footer text>",    // optional; applied to layouts that have a footer
  "slides": [ <slide>, ... ]              // required
}
```

## Slide
```json
{
  "layout": "Tripple_messages_light",      // one of the 18 layout names (see layouts.md)
  "footer": "<override footer>",           // optional
  "placeholders": { "<idx>": <field> },    // key = placeholder idx from layouts.md
  "images":       { "<idx>": "<path>" }    // key = PICTURE placeholder idx
}
```
- `images` are inserted (and auto-cropped to fill) before text. Photos larger than 2200 px are downscaled automatically.
- Image paths may be absolute or relative to `images_dir`.

## Field
Either a **plain string** (auto-styled by placeholder type) or a **rich object**:
```json
{ "paragraphs": [
  {
    "text": "Web & dashboards",
    "weight": "regular | semibold",   // semibold -> "Host Grotesk SemiBold"
    "size": 16,                        // points
    "color": "002656",                // hex, no '#'
    "align": "left | center | right",
    "upper": false,                    // UPPERCASE the text
    "italic": false,
    "spacing": 1.4,                    // letter-spacing in pt (labels)
    "space_before": 0, "space_after": 8,  // paragraph spacing in pt
    "bullet": false                    // true keeps the template's bullet
  }
] }
```

## Brand defaults to reach for
- Title / big statement → `weight:"regular"`, `size:32–40`, `color:"232222"`
- Section title → `weight:"semibold"`, `size:24–28`, `color:"232222"`
- Column / sub-head → `weight:"semibold"`, `size:16–18`, `color:"002656"` (navy) or `"232222"`
- Eyebrow / label → `weight:"semibold"`, `size:11–13`, `color:"91877A"` (brown), `upper:true`, `spacing:1.2–1.6`
- Body / list item → `weight:"regular"`, `size:14–16`, `color:"232222"`, `space_after:6–8`

See `example/q-work-before-summer.deck.json` for a complete 5-slide example.
