| 1 | # Deck Templates |
| 2 | |
| 3 | **Deck = a reusable solution for a recurring presentation family.** It owns an |
| 4 | application context together with presentation identity and reusable page |
| 5 | structure. The application context states which communication situations the |
| 6 | template serves, which audience outcomes it supports, and which narrative/page |
| 7 | roles commonly appear. It describes the resource; it does not decide which |
| 8 | pages or visible content a future presentation must retain. |
| 9 | A deck template is not a finished content deck, and `kind: deck` does not mean |
| 10 | “mirror the source PPT”. Its construction mode decides whether the system is |
| 11 | newly authored or materialized from validated source facts. |
| 12 | |
| 13 | | Axis | Deck behavior | |
| 14 | |---|---| |
| 15 | | Template kind | `deck`: descriptive application context + integrated identity + structure | |
| 16 | | 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 | |
| 17 | | Application planning | Strategist automatically decides which prototypes to select, repeat, skip, or reorganize and derives the exporter behavior | |
| 18 | | PPTX structure | The workspace is `structured`; the derived application plan decides whether generated pages compile its structure or use it only as visual reference | |
| 19 | |
| 20 | The discovery source of truth is [`decks_index.json`](./decks_index.json) |
| 21 | (`deck_id → { summary, canvas_format, page_count, primary_color }`). This README |
| 22 | defines the kind and intentionally does not enumerate installed decks. The |
| 23 | shared kind and workspace model lives in the parent |
| 24 | [`README.md`](../README.md). |
| 25 | |
| 26 | Index `summary` values lead with the recurring presentation family and intended |
| 27 | outcome. Visual tone alone is not enough to select a Deck; open its Template |
| 28 | Overview when application fit must be judged in detail. |
| 29 | |
| 30 | --- |
| 31 | |
| 32 | ## Selection and fusion |
| 33 | |
| 34 | Selection follows the parent README's Default Stage-1 |
| 35 | [`generate-pptx`](../../workflows/generate-pptx.md) template-choice contract. |
| 36 | Its Deck choices come only from `decks_index.json`; no |
| 37 | directory scan or bare-ID/style-phrase match is allowed. A supplied exact root |
| 38 | appears in the same selector, defaults Stage 1 to template mode, and preselects |
| 39 | that specific candidate only when it is the sole supplied root. Registered |
| 40 | exact roots are `library`; other exact roots remain |
| 41 | `explicit`. Choosing and confirming an entry runs the conditional |
| 42 | [`apply-template-workspace`](../../workflows/stages/apply-template-workspace.md) |
| 43 | stage, which owns path normalization, compatibility checks, installation, and |
| 44 | fusion after Stage 1 and before Stage 2. Template-aware reading begins in final Stage 2 from the |
| 45 | installed project-local copy. |
| 46 | Quick applies a supplied exact Deck root directly and otherwise uses free |
| 47 | design. It uses installed prototypes as flat authoring inputs; reusable |
| 48 | native Master/Layout compilation remains a default lock-backed capability. |
| 49 | This file owns the Deck schema and application-context boundary. Chat discovery |
| 50 | reads the same index and returns exact roots; a bare ID never resolves |
| 51 | implicitly. |
| 52 | |
| 53 | --- |
| 54 | |
| 55 | ## `design_spec.md` contract |
| 56 | |
| 57 | The spec stores portable metadata plus package-owned application, identity, |
| 58 | and structure rules. It does not repeat generic SVG rules, spacing libraries, |
| 59 | font-ratio bands, or the canonical placeholder table. |
| 60 | |
| 61 | ```markdown |
| 62 | --- |
| 63 | deck_id: <slug> |
| 64 | kind: deck |
| 65 | category: brand | general | scenario | government | special |
| 66 | summary: <one-line recurring presentation family and intended outcome> |
| 67 | primary_color: "#XXXXXX" |
| 68 | canvas_format: ppt169 |
| 69 | canvas_width: 1280 |
| 70 | canvas_height: 720 |
| 71 | canvas_viewbox: "0 0 1280 720" |
| 72 | replication_mode: standard | fidelity | mirror |
| 73 | native_structure_mode: structured |
| 74 | page_count: <N> |
| 75 | --- |
| 76 | |
| 77 | # [Template Name] — Design Specification |
| 78 | |
| 79 | ## I. Template Overview |
| 80 | ## II. Color Scheme |
| 81 | ## III. Typography # omit only when the shared default is used |
| 82 | ## IV. Signature Design Elements |
| 83 | ## V. Page Roster |
| 84 | ## VI. Assets # omit when none |
| 85 | ## VII. Placeholder Overrides # omit when none |
| 86 | ``` |
| 87 | |
| 88 | `replication_mode` records how the workspace was produced. Create Template |
| 89 | derives it from the natural-language brief and source evidence; users do not |
| 90 | need to select or understand this field. |
| 91 | |
| 92 | `Template Overview` is descriptive application context, not a style |
| 93 | description or future-use policy. It identifies the recurring presentation |
| 94 | family, intended audiences and outcomes, delivery/reading assumptions, and |
| 95 | representative narrative or page roles. These values may be broad when the |
| 96 | source supports a family of related uses, but they must be specific enough to |
| 97 | help Strategist understand the resource. |
| 98 | |
| 99 | `Page Roster` must list every SVG and its declared Master/Layout identity, then |
| 100 | describe its observed or intended role, visual character, reusable slots, and |
| 101 | structural capacity. It must not mark pages required/optional/repeatable or |
| 102 | content fixed/replaceable/example-only. Strategist inspects the actual roster |
| 103 | and current material and decides what to use. |
| 104 | |
| 105 | Every additional authored Master represents a distinct reusable design family, |
| 106 | not one Layout or an organizational duplicate. |
| 107 | |
| 108 | --- |
| 109 | |
| 110 | ## Structured SVG contract |
| 111 | |
| 112 | Every SVG is a complete preview and declares one root Master and Layout. |
| 113 | Master/Layout fixed visuals are direct atoms. Reusable content regions are |
| 114 | top-level slot groups with positive bounds and exactly one compatible carrier; |
| 115 | zero-slot Layouts are valid. `{{...}}` is the authoring vocabulary, while |
| 116 | `data-pptx-placeholder*` is the native reconstruction contract. |
| 117 | |
| 118 | `standard` and `fidelity` author new SVGs and a new Master/Layout/slot system. |
| 119 | `mirror` preserves existing source identities, parentage, assignments, |
| 120 | placeholder facts, and supported visuals in a new workspace without semantic |
| 121 | synthesis. Legacy semantic contracts are not upgraded in place; create a new |
| 122 | workspace through [`create-template`](../../workflows/create-template.md). A |
| 123 | flat directory shape alone is not a legacy signal. |
| 124 | |
| 125 | --- |
| 126 | |
| 127 | ## Workspace and creation |
| 128 | |
| 129 | ```text |
| 130 | <template_workspace>/ |
| 131 | ├── templates/ # design_spec.md + SVG prototypes |
| 132 | ├── images/ # optional bitmaps; SVG href is ../images/<name> |
| 133 | ├── icons/ |
| 134 | │ └── imported/ # optional canonical imported vectors |
| 135 | └── exports/ # review evidence; ignored during template use |
| 136 | └── <deck_id>_template_preview.pptx |
| 137 | ``` |
| 138 | |
| 139 | Library scope writes `skills/ppt-master/templates/decks/<deck_id>/` and updates |
| 140 | the index. Project scope uses an initialized `projects/<name>/` workspace and |
| 141 | does not register globally. Empty optional directories are omitted. |
| 142 | |
| 143 | 1. Enter [`workflows/create-template.md`](../../workflows/create-template.md), which dispatches recurring-application output with integrated identity and structure to [`create-deck.md`](../../workflows/create-template/create-deck.md). |
| 144 | 2. Validate with `svg_quality_checker.py --template-mode`. |
| 145 | 3. Run `template_preview_pptx.py` when review is requested and always when the roster declares multiple Masters. |
| 146 | 4. In library scope, register with `register_template.py <id> --kind deck`. |
| 147 | |
| 148 | See also [`styles/`](../styles/) for direction/method packages, |
| 149 | [`layouts/`](../layouts/) for structure-only packages, and |
| 150 | [`brands/`](../brands/) for identity-only packages. |
| 151 |