| 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 | | Formula Policy | <mixed, render-all, or text-only> | |
| 47 | | AI Image Acquisition Path | <confirmed path or not applicable> | |
| 48 | | Generation Mode | <continuous or split> | |
| 49 | | Spec Refinement | <enabled or disabled> | |
| 50 | | Speaker Notes | <enabled or disabled> — <explicit user instruction, final Stage-2 proactive policy, workflow default, or enabled Narration Audio dependency> | |
| 51 | | Custom Animations | <enabled or disabled> — <explicit instruction and object/all-motion scope, final Stage-2 proactive policy, or workflow default> | |
| 52 | | Narration Audio | <enabled or disabled> — <explicit user instruction, final Stage-2 proactive policy, or workflow default> | |
| 53 | | Created Date | <YYYY-MM-DD> | |
| 54 | |
| 55 | ## II. Canvas Specification |
| 56 | |
| 57 | | Property | Value | |
| 58 | | --- | --- | |
| 59 | | Format | <canonical format name> | |
| 60 | | Dimensions | <width × height> | |
| 61 | | viewBox | `<exact viewBox>` | |
| 62 | | Margins | <safe margins> | |
| 63 | | Content Area | <usable bounds> | |
| 64 | ``` |
| 65 | |
| 66 | 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. |
| 67 | |
| 68 | ### 2.2 Visual, typography, layout, and icons |
| 69 | |
| 70 | Use these exact subsections and field shapes: |
| 71 | |
| 72 | ```markdown |
| 73 | ## III. Visual Theme |
| 74 | |
| 75 | ### Theme Style |
| 76 | |
| 77 | - **Mode**: <confirmed preset or custom> |
| 78 | - **Visual style**: <confirmed preset or custom> |
| 79 | - **Theme**: <resolved identity direction> |
| 80 | - **Tone**: <resolved tone> |
| 81 | |
| 82 | ### Color Scheme |
| 83 | |
| 84 | | Role | HEX | Purpose | |
| 85 | | --- | --- | --- | |
| 86 | | Background | <HEX> | <semantic use> | |
| 87 | | Secondary background | <HEX> | <semantic use> | |
| 88 | | Primary | <HEX> | <semantic use> | |
| 89 | | Accent | <HEX> | <semantic use> | |
| 90 | | Secondary accent | <HEX> | <semantic use> | |
| 91 | | Body text | <HEX> | <semantic use> | |
| 92 | |
| 93 | ## IV. Typography System |
| 94 | |
| 95 | ### Font Plan |
| 96 | |
| 97 | | Role | Character (Reference) | Primary | English if non-English | Fallback tail | |
| 98 | | --- | --- | --- | --- | --- | |
| 99 | | Title | <category/modifier> | <family> | <family> | <fallback> | |
| 100 | | Body | <category/modifier> | <family> | <family> | <fallback> | |
| 101 | |
| 102 | - **Typography upgrade (Reference)**: <post-export role substitution after target installation; omit if none> |
| 103 | - **Title stack**: <complete ordered stack> |
| 104 | - **Body stack**: <complete ordered stack> |
| 105 | |
| 106 | ### Font Size Hierarchy |
| 107 | |
| 108 | | Purpose | Anchor Size (px) | |
| 109 | | --- | ---: | |
| 110 | | Body | <confirmed value> | |
| 111 | | Title | <confirmed value> | |
| 112 | | Subtitle | <confirmed value> | |
| 113 | | Annotation | <confirmed value> | |
| 114 | |
| 115 | ## V. Layout Principles |
| 116 | |
| 117 | ### Page Structure |
| 118 | |
| 119 | - **Header area**: <rule> |
| 120 | - **Content area**: <rule> |
| 121 | - **Footer area**: <rule> |
| 122 | |
| 123 | ### Spacing Specification |
| 124 | |
| 125 | | Element | Current Project | |
| 126 | | --- | --- | |
| 127 | | Safe margin | <value> | |
| 128 | | Content block gap | <value> | |
| 129 | | Icon-text gap | <value> | |
| 130 | |
| 131 | ## VI. Icon Usage Specification |
| 132 | |
| 133 | - **Primary bundled library**: <one of chunk-filled / tabler-filled / tabler-outline / phosphor-duotone, or none> |
| 134 | - **Brand-logo library**: <simple-icons when selected for real brand marks; omit otherwise> |
| 135 | |
| 136 | | Icon Path | Suitable Scenarios | |
| 137 | | --- | --- | |
| 138 | ``` |
| 139 | |
| 140 | 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 real brand marks were selected. The icon table records the curated synced 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 icons are prepared. |
| 141 | |
| 142 | When §VIII contains any `Acquire Via: ai` row, add this subsection under §III and preserve the complete confirmed AI direction: |
| 143 | |
| 144 | ```markdown |
| 145 | ### AI Image Strategy |
| 146 | |
| 147 | - **Image Rendering**: <confirmed preset or custom> |
| 148 | - **Visual**: <confirmed visual treatment> |
| 149 | - **Mood**: <confirmed mood and analogy> |
| 150 | ``` |
| 151 | |
| 152 | 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. |
| 153 | |
| 154 | ### 2.3 Visualization and image resources |
| 155 | |
| 156 | Use the §VII table only when at least one real catalog reference is selected. Always keep the §VIII table, including when it has no data rows: |
| 157 | |
| 158 | ```markdown |
| 159 | ## VII. Visualization Reference List |
| 160 | |
| 161 | | Page | Template | Usage | |
| 162 | | --- | --- | --- | |
| 163 | |
| 164 | ## VIII. Image Resource List |
| 165 | |
| 166 | | Filename | Dimensions | Ratio | Purpose | Type | Layout pattern | Crop Policy | Acquire Via | Status | Reference | text_policy | page_role | |
| 167 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | |
| 168 | ``` |
| 169 | |
| 170 | §VII is an optional page-local reference list. Each row records the page, catalog key, and a short semantic Usage—not geometry. The key derives `templates/charts/<key>.svg`; §IX remains authoritative over final type and realization. Omit an empty §VII and never add path, summary, runners-up, `no-template-match`, or `n/a`. Put unmatched fallbacks in §IX. Legacy wider rows remain readable; new specs use these three columns. |
| 171 | |
| 172 | For every independent data chart or pure text-grid table, add `- **Native-ready**: yes|no` to its §IX Slide block. Choose `yes` only when the confirmed requirement or artifact afterlife benefits from an editable native data object; otherwise use `no`. Conceptual visualizations and incidental sparklines, KPI trends, or insets omit this field and remain ordinary SVG. |
| 173 | |
| 174 | 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. Set `Crop Policy` to `adaptive` or `no-crop`; set `Acquire Via` to `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`. Preserve unresolved required assets as `Pending` or `Needs-Manual` instead of dropping or reclassifying them. |
| 175 | |
| 176 | §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. |
| 177 | |
| 178 | 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. |
| 179 | |
| 180 | ### 2.4 Complete page roster and notes |
| 181 | |
| 182 | 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. |
| 183 | |
| 184 | ```markdown |
| 185 | ## IX. Content Outline |
| 186 | |
| 187 | ### Part 1: <section name> |
| 188 | |
| 189 | #### Slide 01 - <page name> |
| 190 | |
| 191 | - **Audience move**: <audience state before → after> |
| 192 | - **Layout**: <composition; include the chosen prototype when template-active> |
| 193 | - **Title**: <preferred page title> |
| 194 | - **Core message**: <one governing assertion> |
| 195 | - **Content**: <complete intended on-slide content and hierarchy> |
| 196 | |
| 197 | ## X. Speaker Notes Requirements |
| 198 | |
| 199 | - **Generation**: <enabled or disabled> |
| 200 | - **Filename**: match each SVG filename under `notes/` |
| 201 | - **Content**: <notes content and source-handling policy> |
| 202 | - **Total duration**: <resolved duration> |
| 203 | - **Notes style**: <formal, conversational, interactive, or resolved equivalent> |
| 204 | - **Presentation purpose**: <inform, persuade, inspire, instruct, report, or resolved combination> |
| 205 | ``` |
| 206 | |
| 207 | When Speaker Notes is disabled, keep §X with only |
| 208 | `- **Generation**: disabled`; do not write filename, duration, style, or purpose |
| 209 | placeholders. An explicit notes-off/audio-on conflict blocks before authoring. |
| 210 | |
| 211 | Append either or both optional lines only when the capability earns a place; |
| 212 | never write an empty or `none` placeholder: |
| 213 | |
| 214 | ```markdown |
| 215 | - **Native shape suggestion**: <semantic object/result plus candidate preset/Connector family or Boolean operation/operand roles> |
| 216 | - **Motion suggestion**: <communication job plus desired page-entry or reveal relationship/order> |
| 217 | ``` |
| 218 | |
| 219 | Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visualization; mark it data-driven when source values determine geometry. §IX stays authoritative without a catalog match and may choose a custom visualization or table. Add `Native shape suggestion` only when a preset, stock Connector, or compound silhouette/cutout/intersection/fragment may help; name the semantic result plus candidate family or Boolean operands, never implementation geometry or keys. Executor chooses the primitive, preset, Boolean construction, or necessary freeform. 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 `Native-ready: yes|no` 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. §VIII image layout is non-empty free prose with optional library ids; chart rows are references. Executor owns geometry, hierarchy, treatment, and sparse local garnish. |
| 220 | |
| 221 | For free-design pages, describe `Layout` through relationships, hierarchy, regions, and column spans; do not prescribe element-level `x`, `y`, `width`, or `height` or duplicate the global geometry in §II/§V. Exact coordinates belong to Executor SVG authoring. Preserve literal geometry only when the user explicitly requires it or a mirror/template preservation contract owns it. |
| 222 | |
| 223 | --- |
| 224 | |
| 225 | ## 3. Machine validation |
| 226 | |
| 227 | ```bash |
| 228 | python3 skills/ppt-master/scripts/project_manager.py validate <project_path> |
| 229 | ``` |
| 230 | |
| 231 | 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. |
| 232 | |
| 233 | 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. |
| 234 |