# Page Layout Template Library (1 Template)

Pre-built PPT page layout templates supporting multiple styles and use cases.

- **Full Index**: [README.md](./README.md) (human browsing — includes categories, primary colors, detailed tone)
- **Slim Index**: [layouts_index.json](./layouts_index.json) (lightweight lookup — `summary` / `keywords` per template id)

> **Template selection is opt-in by explicit path.** The main workflow defaults to free design. A template is only used when the user gives an explicit directory path (e.g. `skills/ppt-master/templates/layouts/ai_ops/` or any other path) in their initial message. Bare names like "ai_ops" do not trigger — `layouts_index.json` and this README are discovery aids for finding the path, not triggers in themselves. See `SKILL.md` Step 3.

---

## Quick Template Index

<!-- quick-index:begin -->
| Template Name | Category | Use Cases | Primary Color | Design Tone |
|---------------|----------|-----------|---------------|-------------|
| `ai_ops` | General | Telecom AI operations architecture, IT system overviews, digital transformation proposals, smart infrastructure reports | `#C00000` | Information-dense, structured, modular zoning, telecom/enterprise style |
<!-- quick-index:end -->

## Template Categories

### 1. Government & Enterprise Templates

Industry-standard designs for **government agencies and general state-owned enterprises**.
> **Distinction**: Unlike brand styles, these are not targeted at specific organizations but provide templates matching the common aesthetic preferences of government/SOE contexts (e.g., official document red, smart governance blue).

| Template | Description |
|----------|-------------|
| `ai_ops` | Enterprise digital intelligence style, telecom AI ops architecture, high-density reports (includes `reference_style.svg` style reference) |

> **Design philosophy**: Style and scenario are **orthogonal** concepts. Scenario templates define content structure; style templates define visual presentation. In theory, scenario templates can be combined with different styles.

---

## Template File Structure

Each template should contain the following standard files (TOC page is optional):

| Filename | Required | Purpose | Description |
|----------|----------|---------|-------------|
| `design_spec.md` | Yes | Design specification | Complete color, typography, and layout specs |
| `01_cover.svg` | Yes | Cover page | Title, subtitle, date, organization |
| `02_toc.svg` | Optional | Table of contents | Chapter list, navigation |
| `02_chapter.svg` | Yes | Chapter page | Chapter number, chapter title |
| `03_content.svg` | Yes | Content page | Fixed header/footer, flexible content area |
| `04_ending.svg` | Yes | Ending page | Thank-you message, contact info |

> **Design philosophy**: Templates define visual consistency and structural pages; content pages maintain maximum flexibility, letting AI determine layout based on actual content.

---

## design_spec.md Standard Structure

All template design specification documents should follow this chapter structure:

```markdown
# [Template Name] - Design Specification

> One-line description of applicable scenarios

## I. Template Overview
## II. Canvas Specification
## III. Color Scheme
## IV. Typography System
## V. Page Structure
## VI. Page Types
## VII. Layout Modes (Recommended)
## VIII. Spacing Specification
## IX. SVG Technical Constraints
## X. Placeholder Specification
## XI. Usage Guide (Recommended)
```

---

## Placeholder Specification

Templates use `{{PLACEHOLDER}}` format to mark replaceable content:

> For **newly created library templates**, use the canonical placeholder contract below. Some existing templates still contain legacy placeholder variants; those should be treated as historical exceptions rather than the standard for new assets.

### General Placeholders

| Placeholder | Purpose | Applicable Pages |
|-------------|---------|-----------------|
| `{{TITLE}}` | Main title | Cover |
| `{{SUBTITLE}}` | Subtitle | Cover |
| `{{DATE}}` | Date | Cover, Ending |
| `{{AUTHOR}}` | Author / Organization (Chinese) | Cover |
| `{{AUTHOR_EN}}` | Author / Organization (English) | Cover |

### Chapter-Related

| Placeholder | Purpose | Applicable Pages |
|-------------|---------|-----------------|
| `{{CHAPTER_NUM}}` | Chapter number | Chapter, Content |
| `{{CHAPTER_TITLE}}` | Chapter title | Chapter |
| `{{CHAPTER_TITLE_EN}}` | Chapter English subtitle | Chapter |

### Content Page

| Placeholder | Purpose | Applicable Pages |
|-------------|---------|-----------------|
| `{{PAGE_TITLE}}` | Page title | Content |
| `{{CONTENT_AREA}}` | Content area placeholder | Content |
| `{{PAGE_NUM}}` | Page number | Content, Ending |
| `{{SOURCE}}` | Data source | Content footer |

### Table of Contents

| Placeholder | Purpose |
|-------------|---------|
| `{{TOC_ITEM_1_TITLE}}` ~ `{{TOC_ITEM_N_TITLE}}` | TOC item titles |
| `{{TOC_ITEM_1_DESC}}` ~ `{{TOC_ITEM_N_DESC}}` | Optional TOC item descriptions |
| `{{TOC_ITEM_1}}` ~ `{{TOC_ITEM_N}}` | Legacy simple TOC items; do not use for new templates unless no description field is needed |

### Ending Page

| Placeholder | Purpose |
|-------------|---------|
| `{{THANK_YOU}}` | Thank-you message |
| `{{ENDING_SUBTITLE}}` | Ending page subtitle |
| `{{CLOSING_MESSAGE}}` | Closing message |
| `{{CONTACT_INFO}}` | Contact information |

---

## Usage

To use a template, give the AI an explicit directory path in your initial message — e.g. "用 `skills/ppt-master/templates/layouts/ai_ops/` 这个模板做……". The Step 3 logic copies that directory's SVGs + `design_spec.md` + assets into your project before Strategist starts.

The directory does not have to live under `templates/layouts/`. A template kept in `projects/<other_project>/template/` or any other location works the same way as long as you give the path.

After the copy:

1. Read `design_spec.md` to understand the design specification
2. Adjust colors based on project requirements (if needed)
3. Place logo files in the `images/` directory
4. Use the Executor role to generate SVG pages based on templates

---

## Template Development Guide

### Creating New Templates

1. Create a new directory under `templates/layouts/`
2. Create required files following the existing template structure
3. Ensure `design_spec.md` follows the standard chapter structure
4. All SVGs use `viewBox="0 0 1280 720"`
5. Follow SVG technical constraints (see below)
6. Validate the template directory with `python3 scripts/svg_quality_checker.py templates/layouts/<template_name> --format ppt169`
7. Register the new template by running `python3 scripts/register_template.py <template_id>` — it derives the `summary` and `keywords` index entry from `design_spec.md` and refreshes the Quick Index above

`layouts_index.json` is the lightweight lookup used to **discover** library templates (e.g. answering "what templates exist?"). It is not consulted when triggering Step 3 — Step 3 triggers on an explicit directory path the user supplied, regardless of whether that path is in the index. A template folder without an index entry still works fine if the user names its path; it just won't show up in discovery listings.

### SVG Technical Constraints (All Templates Must Comply)

#### Required

- viewBox: `0 0 1280 720`
- Backgrounds use `<rect>` elements
- Text wrapping uses `<tspan>`
- Transparency uses `fill-opacity` / `stroke-opacity`
- Gradients use `<defs>` with `<linearGradient>`

#### Forbidden (PPT Incompatible)

| Banned Element | Alternative |
|----------------|-------------|
| HTML named entities in text (`&nbsp;` `&mdash;` `&copy;` `&ndash;` `&reg;` …) | Write the raw Unicode character directly (`—` `–` `©` `®` `→` NBSP …); see shared-standards.md §1.0 |
| Bare `&` `<` `>` `"` `'` in text or attribute values | Escape as XML entities `&amp;` `&lt;` `&gt;` `&quot;` `&apos;` (e.g. `R&amp;D`, `error &lt; 5%`) |
| `<foreignObject>` | Use `<text>` + `<tspan>` |
| `clipPath` on shapes / groups / text | Draw the target geometry directly with the matching native element (`<circle>` / `<ellipse>` / `<rect rx>` / `<polygon>` / `<path>`). `clipPath` on `<image>` elements is conditionally allowed — see shared-standards.md §1.2 |
| `mask` | Use `fill-opacity` |
| `<style>` / `class` | Use inline styles |
| `textPath` | Use plain `<text>` |
| `animate*` | Static design |
| `script` | No interactivity supported |
| `rgba()` | Use HEX + `fill-opacity` |
| `<g opacity="...">` | Set opacity on each child element individually |

---
