| 1 | # Design Spec Structure |
| 2 | |
| 3 | Project-level `design_spec.md` is a human-readable English-heading Markdown artifact. This file owns its normal authoring structure. [`schemas/design_spec.schema.json`](./schemas/design_spec.schema.json) provides structural lint for readable sections and page projection; it is not an execution lock and does not require textual equality with `spec_lock.md`. |
| 4 | |
| 5 | Strategist reads the complete final confirmation once, writes this artifact from that retained state plus source analysis, and audits every confirmed field here. Afterward, `spec_lock.md` is authored from the completed Design Spec plus current project/page/template context; normal lock authoring never reopens `result.json`. |
| 6 | |
| 7 | ## 1. Author the complete artifact |
| 8 | |
| 9 | After final confirmation, compose the entire document in active context from the retained final state, source analysis, and project context. Then create `<project_path>/design_spec.md` once, from the first line through §X. |
| 10 | |
| 11 | **Mandatory — new-project write**: The first non-empty line is exactly `<!-- ppt-master-schema: design-spec/v1 -->`, followed by `# <Project Name> - Design Spec`. Write every required section with final values and the complete page roster; include conditional §VII only when a real catalog reference is selected. Do not create a placeholder-bearing project file, copy example rows, or patch a scaffold field by field. |
| 12 | |
| 13 | `project_manager.py scaffold-spec` remains an optional manual convenience and overwrite-safe troubleshooting tool. It is not part of normal Generate authoring. Resume and refine paths edit an existing completed Design Spec rather than replacing it with a scaffold. |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## 2. Exact document contract |
| 18 | |
| 19 | Angle-bracketed text below is authoring notation, not project content. Resolve every universal value before writing the file; omit only rows explicitly marked conditional. Keep every required `##` heading; omit §VII when no real catalog reference is selected, while §VIII remains present even with no data rows. Do not copy examples, notation tokens, or a second schema description into the project artifact. |
| 20 | |
| 21 | ### 2.1 Header and project contract |
| 22 | |
| 23 | Start with this exact heading order: |
| 24 | |
| 25 | ```markdown |
| 26 | <!-- ppt-master-schema: design-spec/v1 --> |
| 27 | # <Project Name> - Design Spec |
| 28 | |
| 29 | ## I. Project Information |
| 30 | |
| 31 | | Item | Value | |
| 32 | | --- | --- | |
| 33 | | Project Name | <resolved project name> | |
| 34 | | Canvas Format | <canonical format and dimensions> | |
| 35 | | Page Count | <exact final count matching §IX> | |
| 36 | | Primary Language | <confirmed canonical BCP-47 content tag> | |
| 37 | | Target Audience | <confirmed audience> | |
| 38 | | Communication Intent | <confirmed intent, including priority or sequence> | |
| 39 | | Desired Audience Outcome | <confirmed observable outcome> | |
| 40 | | Core Message / Ask / Action | <confirmed core message or ask> | |
| 41 | | Delivery Context | <confirmed delivery context> | |
| 42 | | Artifact Afterlife | <confirmed afterlife> | |
| 43 | | Reading Mode | <text, balanced, presentation, or the active non-PPT equivalent> | |
| 44 | | Content Strategy | <confirmed material-divergence prose or balanced default> | |
| 45 | | Design Style | <resolved design direction> | |
| 46 | | AI Image Acquisition Path | <confirmed path or not applicable> | |
| 47 | | Generation Mode | <continuous or split> | |
| 48 | | Spec Refinement | <enabled or disabled> | |
| 49 | | Speaker Notes | <enabled or disabled> — <explicit user instruction, final Stage-2 proactive policy, workflow default, or enabled Narration Audio dependency> | |
| 50 | | Custom Animations | <enabled or disabled> — <explicit instruction and object/all-motion scope, final Stage-2 proactive policy, or workflow default> | |
| 51 | | Narration Audio | <enabled or disabled> — <explicit user instruction, final Stage-2 proactive policy, or workflow default> | |
| 52 | | Created Date | <YYYY-MM-DD> | |
| 53 | |
| 54 | ## II. Canvas Specification |
| 55 | |
| 56 | | Property | Value | |
| 57 | | --- | --- | |
| 58 | | Format | <canonical format name> | |
| 59 | | Dimensions | <width × height> | |
| 60 | | viewBox | `<exact viewBox>` | |
| 61 | | Margins | <safe margins> | |
| 62 | | Content Area | <usable bounds> | |
| 63 | ``` |
| 64 | |
| 65 | When a template workspace is active, append exactly one line after the §I table: `- **Template Application**: <confirmed or Strategist-resolved natural-language plan>`. Omit it for free design. Never replace this prose with internal reuse/adherence ids. |
| 66 | |
| 67 | ### 2.2 Visual, typography, layout, and icons |
| 68 | |
| 69 | Use these exact subsections and field shapes: |
| 70 | |
| 71 | ```markdown |
| 72 | ## III. Visual Theme |
| 73 | |
| 74 | ### Theme Style |
| 75 | |
| 76 | - **Mode**: <confirmed preset or custom> |
| 77 | - **Visual style**: <confirmed preset or custom> |
| 78 | - **Theme**: <resolved identity direction> |
| 79 | - **Tone**: <resolved tone> |
| 80 | |
| 81 | ### Color Scheme |
| 82 | |
| 83 | | Role | HEX | Purpose | |
| 84 | | --- | --- | --- | |
| 85 | | Background | <HEX> | <semantic use> | |
| 86 | | Secondary background | <HEX> | <semantic use> | |
| 87 | | Primary | <HEX> | <semantic use> | |
| 88 | | Accent | <HEX> | <semantic use> | |
| 89 | | Secondary accent | <HEX> | <semantic use> | |
| 90 | | Body text | <HEX> | <semantic use> | |
| 91 | |
| 92 | ## IV. Typography System |
| 93 | |
| 94 | ### Font Plan |
| 95 | |
| 96 | | Role | Character (Reference) | Primary | English if non-English | Fallback tail | |
| 97 | | --- | --- | --- | --- | --- | |
| 98 | | Title | <category/modifier> | <family> | <family> | <fallback> | |
| 99 | | Body | <category/modifier> | <family> | <family> | <fallback> | |
| 100 | |
| 101 | - **Typography upgrade (Reference)**: <post-export role substitution after target installation; omit if none> |
| 102 | - **Title stack**: <complete ordered stack> |
| 103 | - **Body stack**: <complete ordered stack> |
| 104 | |
| 105 | ### Font Size Hierarchy |
| 106 | |
| 107 | | Purpose | Anchor Size (px) | |
| 108 | | --- | ---: | |
| 109 | | Body | <confirmed value> | |
| 110 | | Title | <confirmed value> | |
| 111 | | Subtitle | <confirmed value> | |
| 112 | | Annotation | <confirmed value> | |
| 113 | |
| 114 | ## V. Layout Principles |
| 115 | |
| 116 | ### Deck-wide Direction |
| 117 | |
| 118 | - **Hierarchy direction**: <how attention should move across a typical page> |
| 119 | - **Composition tendency**: <non-binding macro direction; no coordinates or authoring method> |
| 120 | - **Cross-page continuity**: <what may recur or vary across the roster> |
| 121 | - **Spacing posture**: <dense, open, or variable behavior by page rhythm; no fixed gaps> |
| 122 | |
| 123 | ## VI. Icon Usage Specification |
| 124 | |
| 125 | - **Primary bundled library**: <one of chunk-filled / tabler-filled / tabler-outline / phosphor-duotone, or none> |
| 126 | - **Brand-logo library**: <simple-icons when actual content requires prepared real brand marks; omit otherwise> |
| 127 | |
| 128 | | Icon Path | Suitable Scenarios | |
| 129 | | --- | --- | |
| 130 | ``` |
| 131 | |
| 132 | Preserve Title/Body characters and resolved stacks; omit blank Typography upgrade and never place it in a stack. For each justified recurring family override, add the role to Font Plan plus `- **<Role> stack**: <complete ordered stack>`. Possible roles are `Annotation`, `Footer`, `Footnote`, `Data`, `Emphasis`, `Quote`, and `Code`; add only recurring, intentional differences. Add non-locked `Role rationale` only for an extra family. Do not collapse distinct Title/Body stacks or discard a declared optional role. Each Font Size Hierarchy value is a role anchor: Executor may vary one occurrence `±2px`; a short non-structural Hero/Display size may stay unlisted only while the same value is planned at most twice, and its third occurrence needs a named row. Add every recurring palette role and typography-size anchor established by the plan; do not enumerate one-off paint or font-family garnish. For confirmed custom directions, add the applicable `Mode References`, `Mode Behavior`, `Visual Style References`, and `Visual Style Behavior` lines under Theme Style. Include `Stroke Width` under §VI only for a stroke library. `simple-icons` may accompany the one primary bundled library and is recorded only when actual content requires real brand marks; it is never a separate confirmation choice. The icon table records the curated synced SVG pool and broad semantic scenarios, not exact page placement or mandatory use. User-provided, template-carried, imported, custom, and other prepared SVGs under the project `icons/` directory remain usable without being forced into that bundled selection. Leave the §VI table empty when no bundled or brand SVG icons are prepared. Illustrated icons are AI image resources: their production sheet and placed slice rows belong in §VIII, and only placed slices project to `spec_lock.md images`. |
| 133 | |
| 134 | When §VIII contains any `Acquire Via: ai` row, add this subsection under §III and preserve the complete confirmed AI direction: |
| 135 | |
| 136 | ```markdown |
| 137 | ### AI Image Strategy |
| 138 | |
| 139 | - **Image Rendering**: <confirmed preset or custom> |
| 140 | - **Visual**: <confirmed visual treatment> |
| 141 | - **Mood**: <confirmed mood and analogy> |
| 142 | ``` |
| 143 | |
| 144 | For a selected custom rendering, also add `Image Rendering Behavior`; add `Image Rendering References` only when the confirmed custom direction actually uses catalog material. Never add a separate image palette. |
| 145 | |
| 146 | ### 2.3 Visualization and image resources |
| 147 | |
| 148 | Use the §VII table only when at least one real Chart/Table catalog reference is selected. Always keep the §VIII table, including when it has no data rows: |
| 149 | |
| 150 | ```markdown |
| 151 | ## VII. Visualization Reference List |
| 152 | |
| 153 | | Page | Family | Template | Usage | |
| 154 | | --- | --- | --- | --- | |
| 155 | |
| 156 | ## VIII. Image Resource List |
| 157 | |
| 158 | | Filename | Dimensions | Ratio | Purpose | Type | Layout pattern | Crop Policy | Acquire Via | Status | Reference | text_policy | page_role | |
| 159 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | |
| 160 | ``` |
| 161 | |
| 162 | §VII lists at most one `chart|table` reference per page: canonical Template key |
| 163 | plus semantic Usage. Resolve `family/key`; never derive paths from bare keys. |
| 164 | §IX owns child visuals, unmatched fallbacks, and qualitative relationships as |
| 165 | free `Layout` / `Visualization` prose. Layout/Deck alone owns reusable |
| 166 | PowerPoint structure. Omit empty §VII and recall diagnostics; legacy rows stay |
| 167 | readable, while new specs use four columns. |
| 168 | |
| 169 | In §IX `Visualization`, key every independent data chart/pure text-grid table |
| 170 | in `kebab-case` and add one `Native-ready` map: `<key>=yes|no; ...`. Decide |
| 171 | `yes` by default; use `no` only when the native payload cannot express that |
| 172 | object. Qualitative relationships/read order remain unkeyed prose, as do |
| 173 | incidental microvisuals. |
| 174 | |
| 175 | In §VIII, author every planned or explicitly required resource from the confirmed source boundary. Write one concise, non-empty `Layout pattern` suggestion in ordinary language; optionally cite hierarchical ids from the layout library when they help recall a technique. An image-led `adaptive` row names the page job the image resolves next to the composition serving it; a `no-crop` or supporting row keeps the concise suggestion alone. Set `Crop Policy` to `adaptive` or `no-crop`; set `Acquire Via` to `ai`, `web`, `user`, `placeholder`, or `slice`. Preserve unresolved required assets as `Pending` or `Needs-Manual` instead of dropping or reclassifying them. Native formulas never enter this table or `spec_lock.md images`. |
| 176 | |
| 177 | §VIII `Layout pattern` is a per-resource preference. When a page uses several images, repeats one image in multiple views, or combines an image with native overlays, describe the page-level relationship and participating resources in §IX `Layout` / `Images`; do not duplicate an unchanged resource row merely to encode animation sequencing. |
| 178 | |
| 179 | Put native paint/overlay intent in §IX `Layout` plus `Images` for imagery—not a new field; state semantic job/layering, while Executor chooses type, stops, opacity, and geometry. |
| 180 | |
| 181 | ### 2.4 Complete page roster and notes |
| 182 | |
| 183 | Write one ordered Slide block per page. Slide count and order must equal §I `Page Count`; `Content` is a complete page brief, not a skeleton. |
| 184 | |
| 185 | ```markdown |
| 186 | ## IX. Content Outline |
| 187 | |
| 188 | ### Part 1: <section name> |
| 189 | |
| 190 | #### Slide 01 - <page name> |
| 191 | |
| 192 | - **Audience move**: <audience state before → after> |
| 193 | - **Layout**: <non-binding macro composition, hierarchy, and visual focus; include the chosen prototype when template-active> |
| 194 | - **Title**: <preferred page title> |
| 195 | - **Core message**: <one governing assertion> |
| 196 | - **Content**: <complete intended on-slide content and hierarchy> |
| 197 | - **Mathematical content**: <exact expression as a delimiter-free LaTeX body; omit when none> |
| 198 | |
| 199 | ## X. Speaker Notes Requirements |
| 200 | |
| 201 | - **Generation**: <enabled or disabled> |
| 202 | - **Filename**: match each SVG filename under `notes/` |
| 203 | - **Content**: <notes content and source-handling policy> |
| 204 | - **Total duration**: <resolved duration> |
| 205 | - **Notes style**: <formal, conversational, interactive, or resolved equivalent> |
| 206 | - **Presentation purpose**: <inform, persuade, inspire, instruct, report, or resolved combination> |
| 207 | ``` |
| 208 | |
| 209 | When Speaker Notes is disabled, keep §X with only |
| 210 | `- **Generation**: disabled`; do not write filename, duration, style, or purpose |
| 211 | placeholders. An explicit notes-off/audio-on conflict blocks before authoring. |
| 212 | |
| 213 | When an explicit final/literal narration script will become notes or generated |
| 214 | audio, make §X `Content` name that source and say `preserve verbatim`; keep the |
| 215 | full segmented script in `notes/total.md`, not in §IX or this Design Spec. |
| 216 | |
| 217 | Append the optional line only when the capability earns a place; never write an |
| 218 | empty or `none` placeholder: |
| 219 | |
| 220 | ```markdown |
| 221 | - **Motion suggestion**: <communication job plus desired page-entry or reveal relationship/order> |
| 222 | ``` |
| 223 | |
| 224 | Add `Mathematical content` whenever a Slide needs a mathematical expression preserved exactly. Store the expression body as valid LaTeX without `$...$`, `$$...$$`, `\(...\)`, or `\[...\]` source delimiters; the field does not classify inline versus structural use. This is content authority for [`native-formula.md`](../references/native-formula.md), not a formula policy, marker, or implementation request; Executor chooses ordinary text, inline native math, or block native math. Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visual model. Name every value-driven geometry, qualitative relationship, cell grid, and child visual here; only independent Chart/Table entries use object keys. Describe qualitative order, linkage, hierarchy, grouping, contrast, overlap, and reading path freely—not as a model name or grammar enum. §IX may choose a custom Chart/Table fallback. Native construction creates no Design Spec field; Executor discovers and selects it independently during realization. Add `Motion suggestion` whenever transition/reveal advice strengthens communication, regardless of the Custom Animations outcome; state purpose and semantic order/relationship, not registry keys, options, timing, ids, or coverage. The suggestion never activates animation execution by itself, creates content, or binds implementation. Describe required visible image states in `Layout` / `Images` only for an explicit motion requirement or an enabled Custom Animations outcome. Add keyed `Native-ready` only for independent data charts or pure text-grid tables, `Fact IDs` for sourced claims, and `Data class: scenario` for invented demo values. Except on preservation paths, `Cover impact` carries a binding hook and adaptable composition; apply the same split to `Closing impact` only when the deck genuinely resolves. Roster/order/content stay authoritative. §V/§IX layout, cover/closing composition, capability, motif, §VIII image-layout, and §VII Chart/Table directions remain References unless an explicit user/template/resource constraint promotes the named property; Executor considers each and may adopt, adapt, or decline it without upstream repair. Executor owns final geometry, hierarchy, treatment, and sparse local garnish. |
| 225 | |
| 226 | For free-design pages, describe `Layout` through relationships, hierarchy, visual focus, and optional macro region/span suggestions; do not prescribe element-level `x`, `y`, `width`, or `height`, fixed gaps, or an authoring method. Executor owns the final page composition and may depart from the recommendation while preserving its semantic job. Preserve literal geometry only when the user explicitly requires it or a mirror/template preservation contract owns it. |
| 227 | |
| 228 | --- |
| 229 | |
| 230 | ## 3. Machine validation |
| 231 | |
| 232 | ```bash |
| 233 | python3 skills/ppt-master/scripts/project_manager.py validate <project_path> |
| 234 | ``` |
| 235 | |
| 236 | Validation reads the Markdown directly. It reports missing or out-of-order I–X sections, unresolved `[fill...]` placeholders, missing per-slide `Audience move`, and a missing §III `AI Image Strategy` when an §VIII table selects `ai` acquisition. |
| 237 | |
| 238 | The schema validates structure only. Strategist role modules own field meaning, recommendation logic, page planning, image policy, and template policy. `spec_lock.md` owns stable execution anchors and routing selected in context; it is not an exhaustive value projection. On divergence, repair the Design Spec from the retained final state when Gate 1 fails, then re-author affected lock anchors from the audited Design Spec and current context. Never reopen `result.json` merely to author or validate the lock, and never use the lock to overwrite a valid Design Spec decision. |
| 239 |