| 1 | # Layout Templates |
| 2 | |
| 3 | **Layout = a structure-only reusable template bundle.** It owns canvas, |
| 4 | Master/Layout structure, page types, slot geometry, semantic text roles, |
| 5 | alignment/wrapping/capacity behavior, and the SVG roster. It does not own |
| 6 | brand color, typeface/weight identity, the final resolved type scale, logo, |
| 7 | voice, or icon style. Those identity decisions come from an explicit |
| 8 | brand/deck source or from the Strategist confirmation stage. |
| 9 | |
| 10 | A layout may describe the content shapes and delivery conditions its geometry |
| 11 | can support. It must not own a communication objective, audience outcome, |
| 12 | scenario-specific narrative sequence, fixed boilerplate, or example content |
| 13 | that downstream generation is expected to preserve. Those application rules |
| 14 | belong to a Deck. A structurally useful “board update” page can remain a |
| 15 | Layout; a board-update sequence with required decision, risk, and action roles |
| 16 | is a Deck. |
| 17 | |
| 18 | Neutral colors, safe fonts, and provisional sizes may appear in SVG prototypes |
| 19 | so the structure is reviewable. They are preview values, not a locked identity |
| 20 | segment or final type scale. The reusable rule is the role hierarchy and its |
| 21 | spatial behavior. When the workspace is used, Strategist inspects the actual |
| 22 | prototypes and current content, decides how much structure to reuse, and writes |
| 23 | the internal exporter plan automatically. |
| 24 | |
| 25 | | Axis | Layout behavior | |
| 26 | |---|---| |
| 27 | | Template kind | `layout`: structure only | |
| 28 | | Internal creation strategy | AI derives `standard` / `fidelity` for a new system or `mirror` for validated source-package materialization; the field is tool provenance, not a user choice | |
| 29 | | Application planning | Strategist automatically decides literal, structural, or style-only use and derives any strict/adaptive exporter value | |
| 30 | | PPTX structure | The workspace is `structured`; the derived application plan decides whether generated pages compile its structure or use it only as visual reference | |
| 31 | |
| 32 | The discovery source of truth is [`layouts_index.json`](./layouts_index.json) |
| 33 | (`layout_id → { summary, canvas_format, page_count, page_types }`). This README |
| 34 | defines the kind and intentionally does not enumerate installed layouts. The |
| 35 | shared kind and workspace model lives in the parent |
| 36 | [`README.md`](../README.md). |
| 37 | |
| 38 | Layout mirror has one additional eligibility rule: the validated source |
| 39 | contract must already be brand-neutral and application-neutral. A source |
| 40 | outside that boundary can become a Layout only through `standard` or |
| 41 | `fidelity`, which deliberately authors a new neutral system. If its identity or |
| 42 | application rules must remain literal, create a Deck instead. Removing either |
| 43 | kind of rule is never a mirror operation. |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## Selection and identity boundary |
| 48 | |
| 49 | Selection follows the parent README's Default Stage-1 |
| 50 | [`generate-pptx`](../../workflows/generate-pptx.md) template-choice contract. |
| 51 | Its Layout choices come only from `layouts_index.json`; no |
| 52 | directory scan or bare-ID/style-phrase match is allowed. A supplied exact root |
| 53 | appears in the same selector, defaults Stage 1 to template mode, and preselects |
| 54 | that specific candidate only when it is the sole supplied root. Registered |
| 55 | exact roots are `library`; other exact roots remain `explicit`. |
| 56 | Choosing and confirming an entry runs the conditional |
| 57 | [`apply-template-workspace`](../../workflows/stages/apply-template-workspace.md) |
| 58 | stage, which owns path normalization, compatibility checks, installation, and |
| 59 | fusion after Stage 1 and before Stage 2. Template-aware reading begins in final Stage 2 from the |
| 60 | installed project-local copy. |
| 61 | Quick applies a supplied exact Layout root directly and otherwise uses free |
| 62 | design. It uses installed prototypes as flat authoring inputs; reusable |
| 63 | native Master/Layout compilation remains a default lock-backed capability. |
| 64 | This file owns the Layout schema and its identity/application boundary. Chat |
| 65 | discovery reads the same index and returns exact roots; a bare ID never resolves |
| 66 | implicitly. |
| 67 | |
| 68 | --- |
| 69 | |
| 70 | ## `design_spec.md` contract |
| 71 | |
| 72 | The spec stores portable structural metadata plus rules unique to this layout. |
| 73 | It omits the deck-only Template Overview/application contract and every |
| 74 | identity section. The frontmatter `summary` carries the concise selection |
| 75 | context. |
| 76 | |
| 77 | ```markdown |
| 78 | --- |
| 79 | layout_id: <slug> |
| 80 | kind: layout |
| 81 | category: general | scenario | government | special |
| 82 | summary: <one-line structural use case> |
| 83 | canvas_format: ppt169 |
| 84 | canvas_width: 1280 |
| 85 | canvas_height: 720 |
| 86 | canvas_viewbox: "0 0 1280 720" |
| 87 | replication_mode: standard | fidelity | mirror |
| 88 | native_structure_mode: structured |
| 89 | page_count: <N> |
| 90 | page_types: [cover, toc, chapter, content, ending] |
| 91 | --- |
| 92 | |
| 93 | # [Layout Name] — Design Specification |
| 94 | |
| 95 | ## IV. Signature Design Elements |
| 96 | ## V. Page Roster |
| 97 | ## VII. Placeholder Overrides # omit when none |
| 98 | ``` |
| 99 | |
| 100 | `replication_mode` records how the workspace was produced. Create Template |
| 101 | derives it from the natural-language brief and source evidence; users do not |
| 102 | need to select or understand this field. |
| 103 | |
| 104 | `Signature Design Elements` describes only reusable structure: grids, zones, |
| 105 | image behavior, density rhythm, semantic text roles, alignment/wrapping/ |
| 106 | capacity behavior, and slot conventions. It must not introduce a brand |
| 107 | palette, typeface identity, final type scale, communication objective, or |
| 108 | required narrative sequence. `Page Roster` lists every SVG with its Layout |
| 109 | key, PowerPoint picker name, supported content shape, and slot behavior. |
| 110 | |
| 111 | --- |
| 112 | |
| 113 | ## Structured SVG and slot contract |
| 114 | |
| 115 | Every SVG is a complete preview and declares one root Master and Layout. |
| 116 | Master/Layout fixed visuals are direct atoms. A reusable slot is a top-level |
| 117 | `<g id>` with positive design-zone bounds and exactly one compatible carrier; |
| 118 | zero-slot Layouts are valid. A typed `picture`, `chart`, or `table` slot does |
| 119 | not by itself promise an inserted picture or native data object: the generated |
| 120 | Slide supplies its content, and Chart/Table native replacement remains an |
| 121 | explicit export choice. |
| 122 | |
| 123 | Use canonical `{{PLACEHOLDER}}` names where they fit. A layout with intentional |
| 124 | vocabulary overrides declares a `placeholders:` map in frontmatter. Full rules: |
| 125 | [`template-designer.md`](../../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). |
| 126 | |
| 127 | `standard` and `fidelity` author new SVGs and a new Master/Layout/slot system. |
| 128 | `mirror` preserves existing source identities, parentage, assignments, |
| 129 | placeholder facts, and supported visuals in a new workspace without semantic |
| 130 | synthesis. Legacy semantic contracts are not upgraded in place; create a new |
| 131 | workspace through [`create-template`](../../workflows/create-template.md). A |
| 132 | flat directory shape alone is not a legacy signal. |
| 133 | |
| 134 | --- |
| 135 | |
| 136 | ## Workspace and creation |
| 137 | |
| 138 | ```text |
| 139 | <template_workspace>/ |
| 140 | ├── templates/ # design_spec.md + SVG prototypes |
| 141 | ├── images/ # optional bitmaps; SVG href is ../images/<name> |
| 142 | ├── icons/ |
| 143 | │ └── imported/ # optional canonical imported vectors |
| 144 | └── exports/ # review evidence; ignored during template use |
| 145 | └── <layout_id>_template_preview.pptx |
| 146 | ``` |
| 147 | |
| 148 | Library scope writes `skills/ppt-master/templates/layouts/<layout_id>/` and |
| 149 | updates the index. Project scope uses an initialized `projects/<name>/` |
| 150 | workspace and does not register globally. Empty optional directories are |
| 151 | omitted. |
| 152 | |
| 153 | 1. Enter [`workflows/create-template.md`](../../workflows/create-template.md), which dispatches structure-only output to [`create-layout.md`](../../workflows/create-template/create-layout.md). |
| 154 | 2. Validate with `svg_quality_checker.py --template-mode`. |
| 155 | 3. Run `template_preview_pptx.py` when review is requested and always when the roster declares multiple Masters. |
| 156 | 4. In library scope, register with `register_template.py <id> --kind layout`. |
| 157 | |
| 158 | General SVG/PPT rules remain authoritative in |
| 159 | [`shared-standards-core.md`](../../references/shared-standards-core.md) and |
| 160 | [`pptx-structure-interface.md`](../../references/pptx-structure-interface.md). |
| 161 | See [`styles/`](../styles/) when reusable method and visual direction should be |
| 162 | combined with this structure without becoming identity truth. |
| 163 |