shumengya
50edff80f5
包含 extensions、skills、prompts、settings、auth、models、mcp 等配置。 排除 node_modules、npm 缓存、sessions 等运行时数据。
295 lines
12 KiB
Markdown
295 lines
12 KiB
Markdown
# 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`](./templates-guide.md); not repeated here.
|
||
|
||
---
|
||
|
||
## 1. The three kinds
|
||
|
||
| Kind | Physical dir | 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) |
|
||
|
||
The three are **parallel reference bundles**. The physical directory and the frontmatter `kind` field correspond one-to-one:
|
||
|
||
```yaml
|
||
# templates/brands/anthropic/design_spec.md
|
||
---
|
||
kind: brand
|
||
...
|
||
---
|
||
|
||
# templates/layouts/academic_defense/design_spec.md
|
||
---
|
||
kind: layout
|
||
...
|
||
---
|
||
|
||
# templates/decks/招商银行/design_spec.md
|
||
---
|
||
kind: deck
|
||
...
|
||
---
|
||
```
|
||
|
||
### 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 replica** of an existing PPT — the SVG geometry was drawn for that color palette and those typefaces, and identity + structure have been combat-tested together in the source deck. Its value is "validated cohesion", which a free layout + brand combo can't always reach.
|
||
|
||
But a deck is **not "an immutable replica"** — it's "a replica that serves as the default base, overridable by explicitly-supplied brand / layout". This gives users maximum freedom: by default you get a complete solution; when needed, swap identity or structure explicitly.
|
||
|
||
---
|
||
|
||
## 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**
|
||
|
||
```yaml
|
||
---
|
||
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**
|
||
|
||
```yaml
|
||
---
|
||
layout_id: <slug>
|
||
kind: layout
|
||
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 Eight Confirmations.
|
||
|
||
### Deck schema
|
||
|
||
**Frontmatter**
|
||
|
||
```yaml
|
||
---
|
||
deck_id: <slug>
|
||
kind: deck
|
||
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).
|
||
|
||
### `templates/brands/brands_index.json`
|
||
|
||
```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`
|
||
|
||
```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`
|
||
|
||
```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 e/f/g confirmations 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 Eight Confirmations path — the user says in chat "use the anthropic brand but change primary to #FF0000", and Strategist adjusts in confirmations 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:
|
||
|
||
```markdown
|
||
> **Fused from:**
|
||
> - deck: `templates/decks/招商银行/` (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 unchanged** — still "explicit directory path only" (see [[feedback-template-explicit-path-only]]). The `kind` field decides **how AI handles the path after triggering**:
|
||
|
||
| User path's `kind` | Step 3 action (per-kind branch) |
|
||
|---|---|
|
||
| `kind: brand` | Copy design_spec + logos + asset subdirs to `<project>/templates/` |
|
||
| `kind: layout` | Copy design_spec + SVG roster + assets to `<project>/templates/` |
|
||
| `kind: deck` | Copy design_spec + SVG roster + logos + all assets to `<project>/templates/` |
|
||
| Multi-path | Fuse into one `design_spec.md` per the table above; merge SVG / logo files from each source |
|
||
| Same-kind multiple | Run the "git-style conflict resolution" prompt above to determine the merge |
|
||
|
||
### Strategist Eight Confirmations narrowing per kind
|
||
|
||
When a deck path is supplied, the user already has a complete solution; the Eight Confirmations narrow 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` | brand directory (identity-only), reverse-engineered from brand assets |
|
||
| `workflows/create-template.md` | layout or deck directory, internal kind branch: default to deck (user supplies an existing PPT; extract full identity + structure); when the user explicitly says "structure only / drop the brand color", go to the layout branch |
|
||
|
||
After production, the frontmatter `kind` field determines whether the file lands under `templates/brands/` / `templates/layouts/` / `templates/decks/`.
|
||
|
||
---
|
||
|
||
## 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 Eight Confirmations 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
|