---
description: 'Per-slide content YAML schema template with supported element types, fields, and usage instructions'
---

# Content YAML Template

Use this template when creating or updating a slide's `content.yaml` file. Each slide folder (`content/slide-NNN/`) contains one `content.yaml` that defines the slide's layout, text, shapes, and optional style overrides.

## Instructions

* All position and size values (`left`, `top`, `width`, `height`) are in inches.
* Color values use `#RRGGBB` hex format or `@theme_name` references. Named color references (`$color_name`) are not supported.
* Font names are specified as literal font family names (e.g., `Segoe UI`, `Cascadia Code`).
* Elements render in the order listed — later elements draw on top of earlier ones.
* Speaker notes are required on all content slides when `speaker_notes_required: true` is set in the global style.
* The `layout` field is informational and helps describe the slide structure; it does not auto-apply a PowerPoint layout.
* The `background` block sets a per-slide background fill. When omitted, no background fill is applied.
* The `rotation` field (degrees, 0–360) is supported on `shape`, `textbox`, and `image` elements. Omit or set to 0 for no rotation.
* Markdown-like list lines in `text` fields are interpreted as PowerPoint lists during rendering.

## Template

```yaml
# Slide metadata
slide: 1
title: "Production-Grade AI-Assisted Software Engineering"
section: "Introduction"
layout: "title"       # title | content | divider | two-column | blank

# Optional per-slide background
background:
  fill: "#1B1B1F"     # solid color fill; use #RRGGBB or @theme_name

# Elements placed on the slide, rendered in order
elements:
  - type: shape
    shape: rectangle
    left: 0
    top: 0
    width: 13.333
    height: 0.12
    fill: "#0078D4"

  - type: textbox
    left: 0.8
    top: 1.5
    width: 11.0
    height: 1.8
    text: "Production-Grade AI-Assisted\nSoftware Engineering"
    font: "Segoe UI"
    font_size: 36
    font_color: "#F8F8FC"
    font_bold: true
    alignment: left       # left | center | right | justify

  - type: textbox
    left: 0.8
    top: 4.4
    width: 10.0
    height: 0.8
    text: "Beyond Vibe Coding: Engineering with AI for Real-World Software"
    font: "Segoe UI"
    font_size: 20
    font_color: "#9CA3AF"

  - type: shape
    shape: rounded_rectangle
    left: 0.8
    top: 1.5
    width: 2.8
    height: 0.55
    fill: "#0078D4"
    corner_radius: 0.1
    rotation: 270           # degrees; vertical text bottom-to-top
    text: "HYPER-VELOCITY ENGINEERING"
    text_font: "Segoe UI"
    text_size: 11
    text_color: "#F8F8FC"
    text_bold: true

  - type: image
    path: "images/background.png"
    left: 0
    top: 0
    width: 13.333
    height: 7.5
    rotation: 0              # optional; degrees 0-360

  - type: rich_text
    left: 0.8
    top: 5.8
    width: 10.0
    height: 0.6
    segments:
      - text: "GitHub Copilot  |  "
        font: "Segoe UI"
        size: 14
        color: "#9CA3AF"
      - text: "context engineering"
        font: "Cascadia Code"
        size: 14
        color: "#FFD700"
      - text: "  |  RPI Workflow"
        font: "Segoe UI"
        size: 14
        color: "#9CA3AF"

  - type: card
    left: 0.8
    top: 1.4
    width: 5.5
    height: 2.8
    title: "WHAT MOST TEAMS DO"
    title_color: "#F8F8FC"
    title_size: 16
    title_bold: true
    accent_bar: true
    accent_color: "#00B4D8"
    content:
      - bullet: "Open Copilot Chat, type a prompt, paste the result"
        color: "#F8F8FC"
      - bullet: "No structure, no verification, no persistence"
        color: "#9CA3AF"

  - type: arrow_flow
    left: 1.0
    top: 3.0
    width: 11.0
    height: 1.5
    items:
      - label: "Research"
        color: "#0078D4"
      - label: "Plan"
        color: "#00B4D8"
      - label: "Implement"
        color: "#10B981"

  - type: numbered_step
    left: 1.0
    top: 2.0
    width: 5.0
    height: 0.8
    number: 1
    label: "Configure VS Code Extensions"
    description: "Install the HVE extension pack."
    accent_color: "#0078D4"

  - type: table
    left: 1.0
    top: 2.0
    width: 11.0
    height: 3.0
    columns:
      - width: 3.0
      - width: 4.0
      - width: 4.0
    rows:
      - cells:
          - text: "Feature"
            font_bold: true
            fill: "#0078D4"
            font_color: "#F8F8FC"
          - text: "Status"
            font_bold: true
            fill: "#0078D4"
            font_color: "#F8F8FC"
          - text: "Notes"
            font_bold: true
            fill: "#0078D4"
            font_color: "#F8F8FC"
      - cells:
          - text: "Authentication"
          - text: "Complete"
            font_color: "#10B981"
          - text: "OAuth 2.0 with PKCE"
      - cells:
          - text: "Merge status"
            merge_right: 2        # merge this cell across 2 additional columns
          - text: ""
          - text: ""
    first_row: true               # style first row as header
    horz_banding: true            # alternate row shading

  - type: chart
    left: 1.0
    top: 2.0
    width: 10.0
    height: 5.0
    chart_type: column_clustered  # see Supported Chart Types table
    categories:
      - "Q1"
      - "Q2"
      - "Q3"
      - "Q4"
    series:
      - name: "Revenue"
        values: [100, 150, 130, 180]
      - name: "Costs"
        values: [80, 90, 85, 95]
    title: "Quarterly Results"
    has_legend: true

  - type: connector
    connector_type: elbow         # straight | elbow | curve
    begin_x: 2.0
    begin_y: 3.0
    end_x: 8.0
    end_y: 5.0
    line_color: "#0078D4"
    line_width: 2
    dash_style: solid             # see Line Dash Styles table
    head_end: none                # none | arrow | triangle | stealth | diamond | oval
    tail_end: arrow

  - type: group
    left: 1.0
    top: 2.0
    width: 5.0
    height: 3.0
    elements:
      - type: shape
        shape: rectangle
        left: 1.0
        top: 2.0
        width: 2.0
        height: 1.0
        fill: "#0078D4"
      - type: textbox
        left: 1.2
        top: 2.2
        width: 1.6
        height: 0.6
        text: "Group Title"
        font_color: "#F8F8FC"

# Speaker notes (required for all content slides)
speaker_notes: |
  Welcome to the HVE workshop. This presentation covers how to use AI
  as a reliable engineering partner rather than a copy-paste tool.
  Key points: structured workflows, context engineering, verification.
```

## Supported Element Types

| Type            | Description                                     | Required Fields                                                        |
|-----------------|-------------------------------------------------|------------------------------------------------------------------------|
| `shape`         | Rectangle, rounded rectangle, arrow, etc.       | `shape`, `left`, `top`, `width`, `height`                              |
| `textbox`       | Plain text box                                  | `left`, `top`, `width`, `height`, `text`                               |
| `rich_text`     | Mixed font/color text segments                  | `left`, `top`, `width`, `height`, `segments`                           |
| `image`         | PNG image placement                             | `path`, `left`, `top`, `width`, `height`                               |
| `card`          | Styled panel with optional title and bullets    | `left`, `top`, `width`, `height`                                       |
| `arrow_flow`    | Horizontal arrow flow diagram                   | `left`, `top`, `width`, `height`, `items`                              |
| `numbered_step` | Numbered step with label and description        | `left`, `top`, `width`, `height`, `number`, `label`                    |
| `table`         | Data table with headers, merging, and styling   | `left`, `top`, `width`, `height`, `columns`, `rows`                    |
| `chart`         | Data chart (bar, line, pie, scatter, etc.)      | `left`, `top`, `width`, `height`, `chart_type`, `categories`, `series` |
| `connector`     | Line connecting two points with optional arrows | `connector_type`, `begin_x`, `begin_y`, `end_x`, `end_y`               |
| `group`         | Container grouping nested child elements        | `left`, `top`, `width`, `height`, `elements`                           |

## Supported Shape Types

| Shape                       | python-pptx Constant                    |
|-----------------------------|-----------------------------------------|
| `rectangle`                 | `MSO_SHAPE.RECTANGLE`                   |
| `rounded_rectangle`         | `MSO_SHAPE.ROUNDED_RECTANGLE`           |
| `oval`                      | `MSO_SHAPE.OVAL`                        |
| `circle`                    | `MSO_SHAPE.OVAL` (alias)                |
| `diamond`                   | `MSO_SHAPE.DIAMOND`                     |
| `pentagon`                  | `MSO_SHAPE.PENTAGON`                    |
| `hexagon`                   | `MSO_SHAPE.HEXAGON`                     |
| `right_triangle`            | `MSO_SHAPE.RIGHT_TRIANGLE`              |
| `trapezoid`                 | `MSO_SHAPE.TRAPEZOID`                   |
| `parallelogram`             | `MSO_SHAPE.PARALLELOGRAM`               |
| `cross`                     | `MSO_SHAPE.CROSS`                       |
| `donut`                     | `MSO_SHAPE.DONUT`                       |
| `cloud`                     | `MSO_SHAPE.CLOUD`                       |
| `star_5_point`              | `MSO_SHAPE.STAR_5_POINT`                |
| `right_arrow`               | `MSO_SHAPE.RIGHT_ARROW`                 |
| `left_arrow`                | `MSO_SHAPE.LEFT_ARROW`                  |
| `up_arrow`                  | `MSO_SHAPE.UP_ARROW`                    |
| `down_arrow`                | `MSO_SHAPE.DOWN_ARROW`                  |
| `left_right_arrow`          | `MSO_SHAPE.LEFT_RIGHT_ARROW`            |
| `notched_right_arrow`       | `MSO_SHAPE.NOTCHED_RIGHT_ARROW`         |
| `chevron`                   | `MSO_SHAPE.CHEVRON`                     |
| `flowchart_process`         | `MSO_SHAPE.FLOWCHART_PROCESS`           |
| `flowchart_decision`        | `MSO_SHAPE.FLOWCHART_DECISION`          |
| `flowchart_terminator`      | `MSO_SHAPE.FLOWCHART_TERMINATOR`        |
| `flowchart_data`            | `MSO_SHAPE.FLOWCHART_DATA`              |
| `left_brace`                | `MSO_SHAPE.LEFT_BRACE`                  |
| `right_brace`               | `MSO_SHAPE.RIGHT_BRACE`                 |
| `callout_rectangle`         | `MSO_SHAPE.RECTANGULAR_CALLOUT`         |
| `callout_rounded_rectangle` | `MSO_SHAPE.ROUNDED_RECTANGULAR_CALLOUT` |

## Supported Chart Types

| Chart Type         | python-pptx Constant             |
|--------------------|----------------------------------|
| `column_clustered` | `XL_CHART_TYPE.COLUMN_CLUSTERED` |
| `column_stacked`   | `XL_CHART_TYPE.COLUMN_STACKED`   |
| `bar_clustered`    | `XL_CHART_TYPE.BAR_CLUSTERED`    |
| `bar_stacked`      | `XL_CHART_TYPE.BAR_STACKED`      |
| `line`             | `XL_CHART_TYPE.LINE`             |
| `line_markers`     | `XL_CHART_TYPE.LINE_MARKERS`     |
| `pie`              | `XL_CHART_TYPE.PIE`              |
| `doughnut`         | `XL_CHART_TYPE.DOUGHNUT`         |
| `area`             | `XL_CHART_TYPE.AREA`             |
| `radar`            | `XL_CHART_TYPE.RADAR`            |
| `scatter`          | `XL_CHART_TYPE.XY_SCATTER`       |
| `bubble`           | `XL_CHART_TYPE.BUBBLE`           |

## Line Dash Styles

| Style           | python-pptx Constant                |
|-----------------|-------------------------------------|
| `solid`         | `MSO_LINE_DASH_STYLE.SOLID`         |
| `dash`          | `MSO_LINE_DASH_STYLE.DASH`          |
| `dash_dot`      | `MSO_LINE_DASH_STYLE.DASH_DOT`      |
| `dash_dot_dot`  | `MSO_LINE_DASH_STYLE.DASH_DOT_DOT`  |
| `long_dash`     | `MSO_LINE_DASH_STYLE.LONG_DASH`     |
| `long_dash_dot` | `MSO_LINE_DASH_STYLE.LONG_DASH_DOT` |
| `round_dot`     | `MSO_LINE_DASH_STYLE.ROUND_DOT`     |
| `square_dot`    | `MSO_LINE_DASH_STYLE.SQUARE_DOT`    |

## Slide-Level Fields

| Field           | Type     | Description                                                                           |
|-----------------|----------|---------------------------------------------------------------------------------------|
| `slide`         | `int`    | 1-based slide number                                                                  |
| `title`         | `string` | Slide title (informational)                                                           |
| `section`       | `string` | Optional section grouping                                                             |
| `layout`        | `string` | Informational layout hint: `title`, `content`, `divider`, `two-column`, `blank`       |
| `background`    | `object` | Per-slide background; contains `fill` with a color value (`#RRGGBB` or `@theme_name`) |
| `speaker_notes` | `string` | Speaker notes text; required when `speaker_notes_required` is true                    |

## Common Element Fields

These optional fields apply to `shape`, `textbox`, and `image` element types:

| Field      | Type     | Default | Description                                                                       |
|------------|----------|---------|-----------------------------------------------------------------------------------|
| `left`     | `float`  | —       | Horizontal position in inches                                                     |
| `top`      | `float`  | —       | Vertical position in inches                                                       |
| `width`    | `float`  | —       | Element width in inches                                                           |
| `height`   | `float`  | —       | Element height in inches                                                          |
| `name`     | `string` | auto    | Shape name for identification                                                     |
| `rotation` | `float`  | `0`     | Rotation in degrees (0–360); 90 = clockwise quarter turn, 270 = counter-clockwise |

## Textbox Fields

| Field             | Type     | Default    | Description                                                                         |
|-------------------|----------|------------|-------------------------------------------------------------------------------------|
| `text`            | `string` | —          | Text content; use `\n` for line breaks                                              |
| `font`            | `string` | `Segoe UI` | Font family name                                                                    |
| `font_size`       | `int`    | `16`       | Font size in points                                                                 |
| `font_color`      | `string` | —          | Text color as `#RRGGBB` or `@theme_name`                                            |
| `font_bold`       | `bool`   | `false`    | Bold text weight. `bold` is accepted as an alias                                    |
| `italic`          | `bool`   | `false`    | Italic text style                                                                   |
| `underline`       | `bool`   | `false`    | Underline text decoration                                                           |
| `alignment`       | `string` | inherited  | Paragraph alignment: `left`, `center`, `right`, `justify`                           |
| `hyperlink`       | `string` | —          | URL applied to the text run                                                         |
| `space_before`    | `float`  | —          | Space before paragraph in points                                                    |
| `space_after`     | `float`  | —          | Space after paragraph in points                                                     |
| `line_spacing`    | `float`  | —          | Line spacing in points                                                              |
| `level`           | `int`    | `0`        | Paragraph indentation level (0–8)                                                   |
| `margin_left`     | `float`  | —          | Text frame left margin in inches                                                    |
| `margin_right`    | `float`  | —          | Text frame right margin in inches                                                   |
| `margin_top`      | `float`  | —          | Text frame top margin in inches                                                     |
| `margin_bottom`   | `float`  | —          | Text frame bottom margin in inches                                                  |
| `auto_size`       | `string` | —          | Auto-size behavior: `none`, `fit` (shape to fit text), `shrink` (text to fit shape) |
| `vertical_anchor` | `string` | —          | Vertical text alignment within frame: `top`, `middle`, `bottom`                     |

### Markdown List Interpretation Contract

For `textbox.text` values, markdown-like list lines are always interpreted as PowerPoint list paragraphs.

* Unordered list markers: `-`, `+`, `*`
* Ordered list markers: `1.`, `2.`, `3.` and `1)`, `2)`, `3)`
* Leading indentation controls PowerPoint paragraph level
* Lines that do not match list markers are rendered as normal text paragraphs

Example:

```yaml
text: |
  Outcomes

  - Improve cycle time
  - Reduce rework
  1. Identify bottlenecks
  2) Validate fixes
```

## Shape Text Fields

When a shape contains inline text, use these prefixed fields:

| Field        | Type     | Default    | Description                              |
|--------------|----------|------------|------------------------------------------|
| `text`       | `string` | —          | Text displayed inside the shape          |
| `text_font`  | `string` | `Segoe UI` | Font family for shape text               |
| `text_size`  | `int`    | `16`       | Font size in points for shape text       |
| `text_color` | `string` | —          | Text color as `#RRGGBB` or `@theme_name` |
| `text_bold`  | `bool`   | `false`    | Bold text weight for shape text          |

For `shape.text`, the same markdown list interpretation contract applies as `textbox.text`.

## Color Syntax

Color values in content YAML accept three formats:

| Syntax                | Example                                | Description                                             |
|-----------------------|----------------------------------------|---------------------------------------------------------|
| Hex value             | `"#0078D4"`                            | Direct RGB hex color                                    |
| Theme reference       | `"@accent_1"`                          | Maps to the presentation theme's `MSO_THEME_COLOR` enum |
| Theme with brightness | `{theme: "accent_1", brightness: 0.4}` | Theme color with brightness adjustment (-1.0 to 1.0)    |

Available theme color names: `accent_1` through `accent_6`, `dark_1`, `dark_2`, `light_1`, `light_2`, `text_1`, `text_2`, `background_1`, `background_2`, `hyperlink`, `followed_hyperlink`.

## Fill Syntax

The `fill` field on shapes and backgrounds accepts three formats:

### Solid fill

```yaml
fill: "#0078D4"             # hex value
fill: "@accent_1"           # theme color
```

### Gradient fill

```yaml
fill:
  type: "gradient"
  angle: 90                 # gradient direction in degrees
  stops:
    - position: 0
      color: "#0078D4"
    - position: 50
      color: "#00B4D8"
    - position: 100
      color: "#10B981"
```

### Pattern fill

```yaml
fill:
  type: "pattern"
  pattern: "cross"          # MSO_PATTERN_TYPE name (e.g., cross, diagonal_stripe)
  foreground: "#000000"
  background: "#FFFFFF"
```

## Line Properties

Line/border properties apply to shapes and connectors:

| Field        | Type     | Description                             |
|--------------|----------|-----------------------------------------|
| `line_color` | `string` | Line color (any color syntax)           |
| `line_width` | `float`  | Line width in points                    |
| `dash_style` | `string` | Dash style (see Line Dash Styles table) |

## Connector Fields

| Field            | Type     | Default    | Description                                                                |
|------------------|----------|------------|----------------------------------------------------------------------------|
| `connector_type` | `string` | `straight` | Connector routing: `straight`, `elbow`, `curve`                            |
| `begin_x`        | `float`  | —          | Start X position in inches                                                 |
| `begin_y`        | `float`  | —          | Start Y position in inches                                                 |
| `end_x`          | `float`  | —          | End X position in inches                                                   |
| `end_y`          | `float`  | —          | End Y position in inches                                                   |
| `head_end`       | `string` | `none`     | Start arrowhead: `none`, `arrow`, `triangle`, `stealth`, `diamond`, `oval` |
| `tail_end`       | `string` | `none`     | End arrowhead: `none`, `arrow`, `triangle`, `stealth`, `diamond`, `oval`   |

## Table Fields

| Field          | Type   | Default | Description                               |
|----------------|--------|---------|-------------------------------------------|
| `columns`      | `list` | —       | Column definitions with `width` in inches |
| `rows`         | `list` | —       | Row definitions with `cells` list         |
| `first_row`    | `bool` | `false` | Apply first-row (header) banding          |
| `last_row`     | `bool` | `false` | Apply last-row banding                    |
| `first_col`    | `bool` | `false` | Apply first-column banding                |
| `last_col`     | `bool` | `false` | Apply last-column banding                 |
| `horz_banding` | `bool` | `false` | Apply horizontal row banding              |
| `vert_banding` | `bool` | `false` | Apply vertical column banding             |

### Cell Fields

| Field             | Type     | Description                                   |
|-------------------|----------|-----------------------------------------------|
| `text`            | `string` | Cell text content                             |
| `fill`            | `string` | Cell background color                         |
| `font_color`      | `string` | Cell text color                               |
| `font_bold`       | `bool`   | Bold text in cell                             |
| `font_size`       | `int`    | Font size in points                           |
| `font`            | `string` | Font family                                   |
| `vertical_anchor` | `string` | Vertical alignment: `top`, `middle`, `bottom` |
| `merge_right`     | `int`    | Merge across N additional columns             |
| `merge_down`      | `int`    | Merge across N additional rows                |

## Chart Fields

| Field        | Type     | Default            | Description                                  |
|--------------|----------|--------------------|----------------------------------------------|
| `chart_type` | `string` | `column_clustered` | Chart type (see Supported Chart Types table) |
| `categories` | `list`   | —                  | Category labels for x-axis                   |
| `series`     | `list`   | —                  | Data series; each has `name` and `values`    |
| `title`      | `string` | —                  | Chart title                                  |
| `has_legend` | `bool`   | `true`             | Display chart legend                         |

Scatter and bubble charts use `data_points` instead of `categories`/`values`:

```yaml
series:
  - name: "Scatter Data"
    data_points:
      - x: 1.0
        y: 2.5
      - x: 3.0
        y: 4.1
```

## Placeholder Content

When using a template PPTX with themed layouts, populate layout placeholders with the `placeholders` section:

```yaml
slide: 1
layout: "Title Slide"
placeholders:
  0: "Presentation Title"      # placeholder index 0 (typically title)
  1: "Subtitle text here"      # placeholder index 1 (typically subtitle)
elements: []
speaker_notes: |
  Opening slide with template placeholders populated.
```

Placeholder indices correspond to the layout's placeholder positions. Use the `--template` argument with `build_deck.py` to load layouts from the template file, and define layout name mappings in `style.yaml` under the `layouts` section.

*🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.*
