hugohe3--ppt-master/docs/templates-architecture.md

Template Architecture: Brand / Layout / Deck

This is the architecture alignment document. It defines the three template kinds at the data-model layer, the field sets of each design_spec.md, and the multi-path fusion + conflict resolution rules. Audience: contributors and AI workflows; answers "what should / shouldn't a template directory contain; how do they combine when multiple are supplied".

For user-facing usage (how to trigger, how to pick), see templates-guide.md; not repeated here.

---

1. The three kinds

Kind	Library workspace root	What it writes	What it does NOT write	Originating workflow
Brand	templates/brands/<id>/	Identity segment only: color / typography / logo / voice / icon style	No canvas, page structure, SVG roster	workflows/create-brand.md
Layout	templates/layouts/<id>/	Structure segment only: canvas / page structure / page types / SVG roster	No brand identity (no logo, no locked brand color)	workflows/create-template.md (layout branch)
Deck	templates/decks/<id>/	All segments: identity + structure + middle (template overview)	—	workflows/create-template.md (deck branch, default)

Every newly created or restored Layout/Deck SVG is a complete preview with root Master/Layout key and picker names, direct atomic Master/Layout elements, and top-level semantic slot groups. A normal slot has positive design-zone bounds and exactly one compatible carrier; composite object regions use explicit proxy binding, and zero-slot Layouts are valid. These specialized markers are authoritative; minimal data-pptx-role hints are added only for structural page-frame behavior they cannot express. standard / fidelity author new SVGs and new structure without preserving or distilling source topology. Mirror restores the source roster, identities, parentage, placeholder facts, and supported visuals without semantic synthesis; fixed-layer source groups are mechanically expanded into direct atoms. Strict keeps the selected declared Layout contract; adaptive retains the Master and may create a new Layout identity while authoring. Both export through pptx_structure.mode: structured. Packages with legacy Master/Layout semantics first run restore-pptx-structure; a legacy flat directory with design_spec.md at its root remains a supported compatibility shape and flat placement alone does not trigger restoration.

The three are parallel reference bundles. In library scope, the physical directory and the frontmatter kind field correspond one-to-one:

# templates/brands/anthropic/templates/design_spec.md
---
kind: brand
...
---

# templates/layouts/academic_defense/templates/design_spec.md
---
kind: layout
native_structure_mode: structured
...
---

# templates/decks/china_merchants_bank/templates/design_spec.md
---
kind: deck
native_structure_mode: structured
...
---

Output scope is separate from kind

create-template confirms where a Layout/Deck workspace is placed. This execution choice does not add a fourth kind and does not add a PPTX structure mode:

Scope	Workspace root	Core workspace	Discovery
library (default)	skills/ppt-master/templates/<kind>/<id>/	Required templates/; optional images/, icons/, and on-demand exports/	Register in the matching global index
project	projects/<name>/	The same routing contract	No global index update

Both roots have the same core shape:

<template_workspace>/
├── templates/
│   ├── design_spec.md
│   ├── *.svg
│   └── icons/                  # package/validation copy when used
├── images/                     # optional; SVG href uses ../images/<name>
├── icons/                      # optional; runtime vector assets
└── exports/                    # optional; created only for on-demand review
    └── <id>_template_preview.pptx

Empty optional directories are omitted; do not add placeholder files. An on-demand preview PPTX is derived review evidence, not a source template asset. Step 3 reads the workspace root and consumes templates/ plus any existing images/ and icons/; it ignores exports/. Library exports/ directories are Git-ignored.

PPTX import uses a two-level metadata model. The temporary lossless SVG keeps native-shape metadata, hidden carriers, and preview evidence; svg_authoring_view.py creates a lightweight model-facing projection without opaque payload or duplicate hidden carriers. The projection is never an export source. Authored modes use compact canonical metadata. Mirror may reuse converter-supported metadata on unchanged Slide-local/slot objects; fixed structural layers remain direct atoms, and unsupported or edited objects keep their SVG fallback. Export compiles only the declared SVG structure and never infers ownership.

Both scopes retain kind: layout or kind: deck in portable frontmatter. output_scope and target_project stay in the workflow brief and are not persisted into design_spec.md.

Before any final write, resolve the selected workspace root, require an empty templates/ root, and check all planned image and icon destination filenames for conflicts. Check a preview-PPTX destination only when review export was requested. Project scope additionally requires an initialized target project. Fail before writing anything; never merge or overwrite.

Segment partition

To make multi-path fusion override cleanly, every field belongs to a named segment. Default fusion granularity is whole-segment replacement:

Segment	Sections it contains	Override owner
Identity	Color Scheme / Typography / Logo / Voice & Tone / Icon Style	brand
Structure	Canvas Specification / Page Structure / Page Types / SVG Roster	layout
Middle	Template Overview (use cases / design intent / page rhythm narrative)	deck only; brand / layout don't write this

Why Deck is its own kind

A deck is the full identity + structure reference derived from an existing PPT or confirmed design direction — its geometry, color palette, and typefaces form one coherent system. Its value is "validated cohesion", which a free layout + brand combo can't always reach.

Its construction depends on replication mode. standard / fidelity author a new system from visual reference; mirror restores source identities and parentage one-to-one. Once packaged, either form is a complete reference solution that can be overridden by an explicitly supplied brand or layout.

---

2. design_spec.md schema per kind

The schema only specifies the required fields. "Don't write what isn't necessary" — if a field isn't listed here, don't add it.

Brand schema

Frontmatter

---
brand_id: <slug>
kind: brand
summary: <one-line use cases, including primary color>
primary_color: "<HEX>"
---

Body sections (full identity segment)

§	Title	Required fields
I	Brand Overview	Brand Name / Use Cases / Tone
II	Color Scheme	role / HEX / provenance (fact official truth | approx derived) / notes
III	Typography	role / family / weight
IV	Logo	file / form / usage + clearspace and lockup rules
V	Voice & Tone	formality / person / emoji / abbreviation policy
VI	Icon Style	preference (stroke / filled / duotone …) + recommended libraries

Forbidden: canvas viewBox, page types, SVG roster — those are layout's responsibility.

Layout schema

Frontmatter

---
layout_id: <slug>
kind: layout
native_structure_mode: structured
summary: <one-line use cases>
canvas_format: <ppt169 | ppt43 | a4 | ...>
page_count: <N>
page_types: [<cover, toc, chapter, content, ending, ...>]
---

Body sections (full structure segment + Template Overview)

§	Title	Required fields
I	Template Overview	Use Cases / Design Intent / Page Rhythm suggestions
II	Canvas Specification	Format / Dimensions / viewBox / Margins / Content Area
III	Page Structure	General Layout Grid / Decorative DNA / Navigation rules
IV	Page Types	Per-page role (cover / toc / chapter / content / ending …) + variant descriptions
V	SVG Page Roster	File list + purpose, each file mapped to a III/IV role

Forbidden: brand logo, brand voice & tone, official-truth color (provenance: fact) — those belong to brand. Layouts have no fallback color or typography by definition: identity segments are not written here; color and typography are decided live in Strategist's confirmation stage.

Deck schema

Frontmatter

---
deck_id: <slug>
kind: deck
native_structure_mode: structured
summary: <one-line use cases>
canvas_format: <ppt169 | ...>
page_count: <N>
primary_color: "<HEX>"
---

Body sections (full identity + full structure + middle)

§	Title	Segment
I	Template Overview	Middle
II	Canvas Specification	Structure
III	Color Scheme (with provenance)	Identity
IV	Typography	Identity
V	Logo	Identity
VI	Voice & Tone	Identity
VII	Icon Style	Identity
VIII	Page Structure	Structure
IX	Page Types	Structure
X	SVG Page Roster	Structure

Deck is the union of all identity + structure fields, with no optional sections. This keeps fusion's segment-level replacement granularity uniform.

---

3. The three index files

Each index maps one-to-one with its physical directory; fields are trimmed to what Strategist actually needs to pick (following the "meta + summary" pattern from charts_index.json, but preserving structured metadata that helps selection).

These indexes cover library scope only. A project-root workspace is intentionally absent from all three indexes and remains usable through its explicit projects/<name>/ path. Because both scopes use the same workspace shape, moving or copying the complete core workspace between them does not require asset-path rewriting; only library registration changes.

templates/brands/brands_index.json

{
  "<brand_id>": {
    "summary": "Anthropic brand identity — AI/LLM tech talks, developer conferences",
    "primary_color": "#D97757"
  }
}

• Keep primary_color — Strategist needs the dominant color at first glance when picking a brand
• Drop keywords — summary already carries the English equivalents; AI matches via natural language (same approach as the charts library)

templates/layouts/layouts_index.json

{
  "<layout_id>": {
    "summary": "Standard academic defense layout — cover/toc/chapter/content/ending",
    "canvas_format": "ppt169",
    "page_count": 5,
    "page_types": ["cover", "toc", "chapter", "content", "ending"]
  }
}

• Add canvas_format / page_count / page_types — Strategist needs to judge "can this skeleton hold my deck?" quickly
• No primary_color — layouts have no identity

templates/decks/decks_index.json

{
  "<deck_id>": {
    "summary": "China Merchants Bank transaction banking deck",
    "canvas_format": "ppt169",
    "page_count": 5,
    "primary_color": "#XXXXXX"
  }
}

• Includes primary_color (decks carry identity) + structural metadata
• Does not expand page_types — decks share the same page-type set as layouts; redundant to record

---

4. Multi-path fusion and conflict resolution

Override priority (implicit dispatch)

When the user supplies a set of paths in their initial message, Step 3 fuses them into <project>/templates/design_spec.md per the table below:

User paths	Fusion behavior
(none)	Skip Step 3, free design
brand only	Copy brand wholesale; structure stays free design
layout only	Copy layout wholesale; identity stays free design (Strategist fields e/f/g decide)
deck only	Copy deck wholesale
brand + layout	brand provides identity, layout provides structure (follows existing SKILL.md fusion table)
brand + deck	brand overrides deck's identity segment at segment level; structure + middle come from deck
layout + deck	layout overrides deck's structure segment at segment level; identity + middle come from deck
brand + layout + deck	brand overrides identity + layout overrides structure + deck provides middle; deck's original identity/structure segments are discarded wholesale

Whole-segment replacement (default granularity)

Fusion defaults to whole-segment integer replacement — e.g. on deck + brand, the entire Color Scheme / Typography / Logo / Voice / Icon Style five sections come from brand. No implicit field-level mixing (you will never get "primary from brand, secondary from deck").

Field-level micro-adjustment goes through the existing Strategist confirmation stage path — the user says in chat "use the anthropic brand but change primary to #FF0000", and Strategist adjusts fields e/g. Step 3 fusion does not add field-level syntax.

Same-kind multiple paths = git-style conflict resolution

User supplies brands/anthropic + brands/google (or any same-kind permutation):

AI: You supplied two brands. Detected segment-level conflicts:
    - Color Scheme (Anthropic orange-red vs Google multi-color)
    - Typography (Styrene/AnthropicSans vs GoogleSans/Roboto)
    - Logo (Anthropic mark vs Google mark)
    - Voice & Tone (restrained vs friendly)
    - Icon Style (stroke vs filled)

    (a) all from Anthropic / (b) all from Google / (c) pick per segment?

Rules:

• No implicit ordering — every cross-source segment difference is reported as a conflict
• Only when the user picks (c) does AI walk through each segment
• Field-level conflict resolution is out of scope — segment-level only
• layout × 2, deck × 2, brand × 2 handled the same way
• Max two of any one kind (more than that — ask the user to converge in chat first)

Provenance

When fusion happens (any multi-path case), the resulting <project>/templates/design_spec.md carries a provenance block immediately under its H1:

> **Fused from:**
> - deck: `templates/decks/china_merchants_bank/` (base)
> - brand: `templates/brands/anthropic/` (identity override)
> - layout: `templates/layouts/academic_defense/` (structure override)
> - conflicts resolved: Color Scheme from anthropic (user picked a)

This lets both AI and humans trace which segment came from where.

---

5. Relationship with SKILL.md Step 3

Trigger rule stays path-based — an explicit workspace-root path is still required (see feedback-template-explicit-path-only), and bare names never trigger. Step 3 first resolves <workspace>/templates/design_spec.md; for compatibility, it also accepts a legacy flat root containing <workspace>/design_spec.md. Flat placement is only a directory-shape compatibility case. It does not trigger restore-pptx-structure; restoration is required only when the SVG contract has legacy semantics such as native_structure_mode: template, missing Master identity, direct atomic placeholders, or distillation-era markers. The only narrow handoff exception is a create-template run in the current conversation: after validation, it may pass its exact workspace root directly into Step 3. The kind field decides how AI handles the path after triggering:

User path's kind	Step 3 action (per-kind branch)
kind: brand	Map workspace templates/ plus existing images/ and icons/ to the matching project peers; ignore exports/
kind: layout	Map workspace templates/ plus existing images/ and icons/ to the matching project peers; ignore exports/
kind: deck	Map workspace templates/ plus existing images/ and icons/ to the matching project peers; ignore exports/
Multi-path	Fuse one design_spec.md per the table above, then merge the existing portable roots after resolving collisions
Same-kind multiple	Run the "git-style conflict resolution" prompt above to determine the merge

Bitmaps share the workspace images/ pool and template SVGs reference them through ../images/. If the explicit input root is already the target project's root, Step 3 consumes the workspace in place: do not copy it onto itself and do not move its assets again. Otherwise, the complete core workspace is portable: it may be copied from a project root to a library root, from the library to a project, or reused from another workspace without changing its internal structure. Registration is the only scope-specific step.

Strategist confirmation stage narrowing per kind

When a deck path is supplied, the user already has a complete solution; the Strategist confirmation stage narrows to "target audience / page count / outline / tone tweaks" — deck-content fields. Other fields reuse the locked values directly. The narrowing rules live in references/strategist.md and spec_lock_reference.md.

---

6. Relationship with workflows

Workflow	Produces
workflows/create-brand.md	identity-only brand workspace using the common routes; empty optional directories are omitted
workflows/create-template.md	complete layout or deck workspace. standard / fidelity author new semantic SVGs; mirror restores the source contract. Output scope is library by default (templates/<kind>/<id>/ + registration) or project when confirmed (projects/<name>/, no registration). Both use the same optional-directory routing; preview PPTX is on demand. The internal kind branch still defaults to deck; explicit "structure only / drop the brand color" selects layout

In library scope, the frontmatter kind field determines which workspace parent is used under templates/brands/ / templates/layouts/ / templates/decks/. Project scope keeps the same kind semantics at the project workspace root. A complete workspace may migrate between scopes without reshaping; add or remove only the library index registration.

---

7. Non-goals (rejection list paired with this framing)

• No field-level override syntax in the fusion layer — field-level adjustment uses the existing Strategist confirmation stage path
• No batch conflict resolution for three or more of the same kind — ask the user to narrow it down in chat first
• No bilingual name mapping table — templates are named in their brand / scenario's native language (Chinese templates use Chinese names; English templates use snake_case); no forced unification
• No output-scope structure fork or CLI flag — output scope is a create-template brief decision; both layout/deck scopes declare native_structure_mode: structured