diff --git a/README.md b/README.md index 450fbf3..97529fb 100644 --- a/README.md +++ b/README.md @@ -1,99 +1,143 @@ # Future PPT Skill -`future-ppt` is a Codex skill for turning mature documents into **native editable PowerPoint decks** through a production workflow: +`future-ppt` is a Codex skill for turning mature documents, reports, research notes, and strategy materials into **native editable PowerPoint decks**. + +It is designed as a small PPT production system: first align the audience and decision context, then compile the narrative, route each page to the right visual form, generate SVG pages, lint the deck, and export a native PPTX through [`ppt-master`](https://github.com/hugohe3/ppt-master). + +## What Is New In This Version + +This iteration upgrades the original open-source skill from a basic document-to-slides workflow into a stronger presentation workflow: + +- needs alignment before production +- rapid sample mode for quick 1-3 page direction previews +- claim / evidence / implication narrative compiler +- style archetype playbooks, including consulting, launch, IC, government, technical, operating review, and talent/research decks +- visual-form router +- reusable page component library +- image-first workflow for generated image assets without sacrificing information hierarchy +- automated visual lint script for SVG decks +- stronger QA rubric for editability, rhythm, layering, and generated assets + +## Production Flow ```text -source document --> document deconstruction --> slide brief matrix +needs alignment +-> source import +-> narrative compiler +-> slide brief matrix + visual router +-> art direction + component plan +-> visual evidence plan -> design contract +-> optional Figma / Canva / generated-image assist -> page SVGs --> QA +-> automated visual lint + QA -> native PPTX export ``` -It is designed to cooperate with [ppt-master](https://github.com/hugohe3/ppt-master): the agent owns content decomposition, style control, page briefs, and QA; `ppt-master` handles SVG validation, post-processing, and native PPTX export. - ## What This Skill Optimizes For -- Editable PPTX, not whole-slide screenshots -- Slide-level information architecture before design -- Prompt-driven or reference-PPT-driven style control -- Explicit visual-form selection per page -- QA across information design, aesthetics, layout, and export safety +- Native editable PPTX, not whole-slide screenshots +- Decision-oriented narrative, not document slicing +- Page-level claim / evidence / implication +- Explicit visual-form and component selection per page +- Stronger design language through archetypes and reusable components +- Generated images as atmosphere or metaphor, never factual evidence +- Visual QA before handoff -## Environment Compatibility +## Requirements | Layer | Requirement | Notes | |---|---|---| -| Agent runtime | Codex with local skills, file I/O, and shell access | Tested as a Codex Desktop local skill | -| OS | macOS or Linux recommended | Windows should work if `ppt-master` and Python deps are configured | -| Python | 3.10+ | Used by `ppt-master` and helper scripts | -| PPT engine | `ppt-master` | Recommended v2.4.0+ | -| Render preview | `rsvg-convert` optional | Used to create PNG previews/montages from SVG | -| DOCX fallback | `python-docx` optional | Useful when `ppt-master` DOCX conversion lacks `mammoth` | -| Image generation | optional | Use Codex image generation or `ppt-master` image backends for atmosphere/background assets only | - -The workflow was tested with: - -- macOS -- Codex Desktop -- Python 3.14 system runtime for simple scripts -- `ppt-master` main branch around v2.4.0 -- `rsvg-convert` +| Agent runtime | Codex with local skills, file I/O, and shell access | Built for Codex Desktop/local skill use | +| PPT engine | `ppt-master` | Recommended: latest main or v2.4.0+ | +| Python | 3.10+ | Used by helper scripts and `ppt-master` | +| Render preview | `rsvg-convert` optional | Useful for PNG previews/montages | +| Image generation | optional | Use host image generation or configured `ppt-master` backends | + +Set `PPT_MASTER_HOME` if your `ppt-master` checkout is not at `$HOME/tools/ppt-master`: + +```bash +export PPT_MASTER_HOME="$HOME/tools/ppt-master" +``` ## Install -Clone this repository into your Codex skills directory: +Clone into your Codex skills directory: ```bash mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" -git clone https://github.com//future-ppt-skill.git \ +git clone https://github.com/TonyLTalentexe/future-ppt-skill.git \ "${CODEX_HOME:-$HOME/.codex}/skills/future-ppt" ``` -Install or clone `ppt-master`: +Install `ppt-master`: ```bash mkdir -p "$HOME/tools" git clone https://github.com/hugohe3/ppt-master "$HOME/tools/ppt-master" ``` -Optionally set: +## Example Prompts -```bash -export PPT_MASTER_HOME="$HOME/tools/ppt-master" +```text +Use $future-ppt to turn this mature industry report into a 10-page editable PPT. +Position it as an investor/IC memo deck. Start with needs alignment and keep risks visible. ``` -## Usage - -Example prompt: - ```text -Use $future-ppt to turn this mature document into an editable launch-quality PPT. -Use the attached reference PPT for style extraction. Keep the output native editable. +用 future-ppt 基于这个行业研究文档快速做 2-3 页 PPT 小样。 +定位是行业研报，信息量要足，先让我看方向和效果。 ``` -Chinese prompt example: - ```text 用 future-ppt 把这个成熟文档做成一份可编辑 PPT。 -先做页面分镜表，再按“纯黑底、白色粗体、霓虹 CMYG 点缀”的发布会风格生成。 +定位是行业研报，信息量要足，但要有视觉结构感。 +先做需求对齐、claim/evidence/implication，再生成页面。 ``` -## Workflow Artifacts +```text +Use $future-ppt to make this technical report into a launch-style deck. +Use generated images only as conceptual backgrounds; keep all facts, charts, and labels native. +``` + +## Expected Artifacts -Every serious run should produce: +Serious runs should produce: +- `needs_alignment_brief.md` +- `claim_evidence_implication.md` - `slide_brief_matrix.md` +- `visual_evidence_plan.md` - `design_contract.md` -- `design_spec.md` - `spec_lock.md` +- `asset_prompt_pack.md` when generated/source imagery is used - `svg_output/` - `svg_final/` -- `exports/*.pptx` -- `previews/montage.png` +- `preview_montage.png` +- `visual_lint.json` - `qa_report.md` +- `exports/*.pptx` + +Rapid sample runs may produce compact versions of the same planning artifacts and 1-3 finished slides. See `references/rapid-sample-mode.md`. + +## QA Helpers + +Check whether the exported deck has editable text: + +```bash +python3 scripts/check_pptx_native.py path/to/deck.pptx +``` + +Run best-effort visual lint on a `ppt-master` project: + +```bash +python3 scripts/deck_visual_lint.py path/to/project \ + --svg-dir path/to/project/svg_final \ + --preview-dir path/to/project/preview_png \ + --json-out path/to/project/visual_lint.json +``` + +`deck_visual_lint.py` checks for common risks such as image-only slides, tiny text, likely text overlap, over-bright/busy previews, repeated card-grid patterns, and low type hierarchy. It is a review aid, not a replacement for human montage inspection. ## Repository Layout @@ -101,17 +145,27 @@ Every serious run should produce: future-ppt-skill/ ├── SKILL.md ├── agents/openai.yaml +├── examples/ ├── references/ -│ ├── design-contracts.md -│ ├── qa-rubric.md -│ └── slide-brief-matrix.md +│ ├── needs-alignment-and-style-archetypes.md +│ ├── narrative-compiler.md +│ ├── rapid-sample-mode.md +│ ├── style-archetype-playbooks.md +│ ├── visual-form-router.md +│ ├── page-component-library.md +│ ├── image-first-deck-workflow.md +│ ├── automated-visual-qa.md +│ └── ... └── scripts/ - └── check_pptx_native.py + ├── check_pptx_native.py + └── deck_visual_lint.py ``` -## Design Philosophy +## Open-Source Boundary + +This repository contains the reusable skill workflow and helper scripts. It intentionally does not include private source documents, generated client decks, internal research artifacts, or licensed presentation templates. -Do not design slides directly from raw documents. First define each page's job, information load, and visual form. Once every page is a clear production unit, decks can scale from 5 pages to 50 pages while staying coherent under a shared design contract. +Use mature templates as references for composition logic, chart/table grammar, density, and pacing. Do not copy proprietary slide masters, brand marks, watermarks, or exact layouts without permission. ## License diff --git a/SKILL.md b/SKILL.md index 0847292..1738b12 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,116 +1,265 @@ --- name: future-ppt -description: Convert mature Chinese or English documents, reports, interview drafts, research notes, or strategy materials into editable, launch-quality PowerPoint decks. Use when the user asks to 做PPT, 生成PPT, 文档转PPT, 汇报材料, 发布会风格PPT, 可编辑PPT, 固化PPT工作流, or wants a deck with explicit style extraction, prompt-driven visual direction, slide-level information architecture, and QA before delivery. +description: Convert mature Chinese or English documents, reports, interview drafts, research notes, or strategy materials into editable, launch-quality PowerPoint decks. Use when the user asks to 做PPT, 生成PPT, 文档转PPT, 汇报材料, 发布会风格PPT, 可编辑PPT, 固化PPT工作流, or wants a deck with audience/purpose/style needs alignment, narrative claim-evidence-implication compilation, explicit template/style archetype selection, page component routing, style extraction, art direction, visual evidence planning, source/asset strategy, Figma-assisted design-system/reference extraction, Canva-assisted template/brand/design ideation, optional Figma/Canva reference drafts, automated visual lint, and QA before delivery. --- # Future PPT Turn mature source material into a native editable PPTX through a production workflow: -`source document -> document deconstruction -> slide brief matrix -> design contract -> page SVGs -> QA -> native PPTX export` +`needs alignment → source import → narrative compiler → slide brief matrix + visual router → art direction + component plan → visual evidence plan → design contract → optional Figma/Canva/generated-image assist → page SVGs → automated visual lint + QA → native PPTX export` -This skill is a workflow wrapper around `ppt-master` plus agent judgment. It exists to prevent jumping directly from a document into slide design. +This skill is a workflow wrapper around `ppt-master` plus Codex judgment. It exists to prevent jumping directly from a document into slide design before audience, purpose, content boundaries, and style archetype are clear. -## Required Environment +## Required Tools -- Codex or another agent runtime that supports local skills, file I/O, and shell commands. -- Python 3.10+. -- `ppt-master` cloned locally. Default discovery order: - - `$PPT_MASTER_HOME` - - `~/tools/ppt-master` - - `./ppt-master` -- Optional but recommended: `rsvg-convert` for SVG preview PNGs. -- Optional for DOCX conversion fallback: `python-docx`. +- Prefer local `ppt-master` at `${PPT_MASTER_HOME:-$HOME/tools/ppt-master}`. +- If missing, clone `https://github.com/hugohe3/ppt-master` to that path. +- If a local UTF-8 guard exists, run it after editing Chinese Markdown/SVG/Python files. +- Use `rsvg-convert` when available for SVG preview PNGs. +- When the Figma plugin is available, treat it as an optional design source, review surface, or Figma Slides deliverable path. +- When the Canva plugin is available, treat it as an optional template/brand-kit/reference-design/moodboard layer, not as the default final production path. +- Treat image generation as a first-class optional asset-production layer for conceptual backgrounds, hero atmosphere, section dividers, and non-factual illustrative scenes. Prefer `${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/image_gen.py` when a requested/configured backend can write files directly; otherwise use the host `image_gen` capability when the user asks for Image2/Imagen/Gemini/Codex/local image generation, when the deck needs a high-design image-first pass, or when CLI environment variables are not configured. Do not decide image generation is unavailable only from missing shell API keys. +- When local professional agent workflows are available, use them as methodology references through `references/agency-agent-workflow.md`. +- The default final artifact remains native editable PPTX unless the user explicitly asks for Figma Slides, Canva, or multiple deliverables. + +## Default Dark Neon Style + +Unless the user provides another explicit visual direction or reference deck, every future PPT defaults to the dark-neon style in `references/dark-neon-default.md`: + +- pure black background, bold white primary type, no decorative gradients as page background +- high-saturation neon accents: cyan, magenta, yellow, neon green +- extremely minimal dark-mode composition with chart/data emphasis carried by neon strokes, dots, bars, and keywords +- if the project has a real brand logo asset, place it in the top-right corner, scaled small enough to brand the page without competing with the title + +When using a real brand asset, copy it into the project `images/` directory and add it as a small bitmap mark while keeping text, diagrams, and charts native editable. If no brand asset is provided, use native typography/page marks instead of inventing a logo. + +Important: this default style is only a visual skin. It does not replace art direction. Every deck still needs a visual evidence plan and subject-specific imagery, diagrams, charts, or source screenshots when those would make the point clearer. + +Important: do not let the default style collapse into a deck of rigid logic diagrams. High-design PPTs need a rhythm of cinematic anchor visuals, object metaphors, data/evidence pages, and native diagrams. Use `references/cinematic-visual-language.md` when a deck needs stronger visual memory, cover/section imagery, object-led pages, or generated images from image models such as GPT Image / Imagen / Gemini. If the user asks for a more beautiful deck, Image2-style visuals, or more use of Codex/local image generation, also use `references/image-first-deck-workflow.md` so generated imagery improves the design without overpowering the information layer. ## Workflow -### 1. Establish Inputs +### 1. Align Needs Before Production + +Read `references/needs-alignment-and-style-archetypes.md` at the start of serious PPT tasks. + +If the user asks for a quick 1-3 page sample, style test, direction preview, or "先做几页看看效果", also read `references/rapid-sample-mode.md` and use Rapid Sample Mode. Rapid samples may use compact planning artifacts, but still need needs assumptions, claim/evidence/implication, visual routing, rendered preview, visual lint, and native PPTX export. + +Before making pages, identify the audience, decision/action needed, use context, desired style archetype, content boundaries, and forbidden material. Create `needs_alignment_brief.md` before `slide_brief_matrix.md`. + +Ask up to three concise questions when the missing answers would materially change the deck. Prioritize: + +- audience + decision/action needed +- must-include and must-not-include content +- style archetype or reference direction, e.g. McKinsey-style consulting, BCG-style strategic narrative, Xiaomi/launch, investor/IC, government, academic/technical, operating review, talent/research map + +Do not ask questions that can be inferred from the source document, path, meeting title, prior conversation, or user-provided reference. If the user says "直接做", "先出一版", or urgency is clear, proceed with explicit assumptions in `needs_alignment_brief.md` and note those assumptions in the final handoff. + +Mature PPT templates and consulting styles should be learned as composition logic, information hierarchy, chart/table grammar, and pacing. Do not copy proprietary masters, exact slide designs, watermarks, or brand marks without permission. + +### 2. Establish Inputs Identify: - source content document(s) - optional reference PPT for style extraction +- optional mature template/reference style to learn from: consulting, McKinsey-style, BCG-style, Xiaomi/launch, investor/IC, government, academic, operating review, or user-provided template +- optional Figma URL, Figma design system, or Figma Slides target +- optional Canva design URL, Canva brand kit, Canva brand template, or Canva reference/moodboard target +- optional image-generation preference, e.g. Imagen, Gemini, OpenAI image model, Image2-style workflow, or host-native `image_gen` +- optional image-first/high-design expectation: how many pages may use generated images, and whether non-cover pages must stay information-priority +- optional local agent/workflow reference - optional style prompt, e.g. "纯黑底、白色粗体、霓虹 CMYG 点缀" +- audience, purpose, decision/action needed, reading mode, and time budget from `needs_alignment_brief.md` +- content contract: must include, nice to have, must not include, sensitive/uncertain content, required evidence, appendix expectations - expected output length and use case +- expected final deliverable: native PPTX, Figma Slides, Canva design, or multiple outputs If the user does not specify page count, choose by narrative load. For MVP tests, use 5-10 pages; for production, create as many pages as the Slide Brief Matrix requires. -### 2. Locate `ppt-master` +Default deliverable decision: -Set a shell variable before commands: +- If the user asks for "PPT", "PowerPoint", "可编辑 PPT", or gives no format preference, produce native PPTX through `ppt-master`. +- If the user explicitly asks for "Figma Slides", "Figma 里做一版", "用 Figma 出方案", or wants collaborative Figma editing, use the Figma Slides path in `references/figma-integration.md`. +- If the user explicitly asks for "Canva", "Canva 里做一版", "用 Canva 模板", or gives a Canva design URL, use the Canva path in `references/canva-integration.md` as a reference, moodboard, or separate Canva deliverable. +- If the user provides a Figma URL as a visual reference, use Figma only to extract style evidence and screenshots, then translate it into `design_contract.md` and `spec_lock.md`. +- If the user provides a Canva URL as a visual reference, read its pages/content/thumbnails through Canva tools, then translate findings into `design_contract.md`, `visual_evidence_plan.md`, and `spec_lock.md`. -```bash -PPT_MASTER_HOME="${PPT_MASTER_HOME:-$HOME/tools/ppt-master}" -``` +### 3. Create Project -If missing: +Use `ppt-master`: ```bash -git clone https://github.com/hugohe3/ppt-master "$PPT_MASTER_HOME" +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/project_manager.py init --format ppt169 --dir +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/project_manager.py import-sources --copy ``` -### 3. Create Project +If DOCX conversion fails because `mammoth` is missing, extract with `python-docx` and save a Markdown source into `sources/`. -```bash -python3 "$PPT_MASTER_HOME/skills/ppt-master/scripts/project_manager.py" init --format ppt169 --dir -python3 "$PPT_MASTER_HOME/skills/ppt-master/scripts/project_manager.py" import-sources --copy -``` +For branded runs, also create `/images/` and copy the logo asset there before generating SVG pages. -If DOCX conversion fails because `mammoth` is missing, extract with `python-docx` and save a Markdown source into `sources/`. +### 4. Compile Narrative Before Designing + +Read `references/narrative-compiler.md`, then create `claim_evidence_implication.md`. + +Do this before `slide_brief_matrix.md`. The deck must have: -### 4. Deconstruct Before Designing +- one-sentence thesis tied to audience and decision/action +- source inventory with evidence strength and uncertainty +- 3-6 chapter-level claims for serious decks +- page-level claim, evidence, implication, confidence, and source trace +- mainline vs appendix split +- explicit exclusions for content that should not appear or should move to appendix + +For analytical, consulting, IC, board, technical, and talent decks, page headlines should usually be assertion headlines, not topic labels. If a page has no implication, cut it, merge it, or move it to appendix. + +### 5. Deconstruct Before Designing Create `slide_brief_matrix.md` before generating slides. Do not skip this. Each page must define: - page type - page job +- target audience read: live claim, leave-behind proof, or appendix detail +- source claim from `claim_evidence_implication.md` - core message - information load - source content - visual form +- selected component from `references/page-component-library.md` - why this visual fits +- visual evidence asset: actual image/chart/diagram/source screenshot/generated asset, or "none intentionally" +- asset source and usage note: local, public URL, generated, Canva/Figma reference, or original native drawing - editable elements - speaker-note intent -Use `references/slide-brief-matrix.md`. +Use `references/slide-brief-matrix.md`, `references/visual-form-router.md`, and `references/page-component-library.md`. + +The visual form must route from information structure, not decoration. If more than 30% of pages become generic card grids, revise the matrix before generating slides. + +### 5A. Optional Agency Micro-Pipeline + +Use this when the user mentions local/professional agents, asks to improve design workflow, criticizes design quality, or the deck is high-stakes. + +Read `references/agency-agent-workflow.md`, then create lightweight versions of the relevant agent artifacts: + +- `agent_workflow_plan.md`: phases, roles, handoffs, gates, retry policy +- `claim_spine.md`: Visual Storyteller pass with narrative arc, proof objects, and pacing +- `brand_guardian_audit.md`: brand consistency and do-not-use rules +- `asset_prompt_pack.md`: generated/source image prompts when imagery is needed; for generated imagery, include backend/model preference, prompt, negative prompt, filename, final derivative filename, aspect ratio, crop intent, status, and native overlay plan +- `asset_risk_review.md`: required when people, culture, institutions, logos, or factual-looking generated assets appear + +Do not simulate a huge multi-agent bureaucracy for a small deck. Borrow the discipline: clear role passes, evidence-based gates, and final skepticism. -### 5. Lock Design +### 6. Lock Design + +Before `design_contract.md`, create `visual_evidence_plan.md` and run the art-direction pass in `references/art-direction.md`. The design contract must obey `needs_alignment_brief.md`. Create both: - `design_contract.md`: human-readable style contract - `spec_lock.md`: machine-readable color, font, page rhythm, and forbidden values -Support three style sources: +Support four style sources: - preset style: e.g. launch black, consulting, academic, government, dark tech +- needs-aligned archetype: e.g. McKinsey-style consulting, BCG-style strategic narrative, Xiaomi/launch, investor/IC, government, academic/technical, operating review, talent/research map - reference PPT extraction: inspect colors, fonts, layout rhythm, chart language, image posture - style prompt: translate prompt into exact HEX, typography, density, visual rules -Use `references/design-contracts.md`. +Use `references/design-contracts.md`. If an archetype was selected, read `references/style-archetype-playbooks.md` and translate the chosen archetype into page grammar, chart/table posture, density policy, image posture, and forbidden moves. + +### 6A. Mandatory Art Direction Pass + +Read `references/art-direction.md`. Do not start SVG generation until every slide has: + +- one-sentence audience takeaway +- dominant visual object or clear reason not to use one +- visual evidence category: representational / organizational / explanatory / data / source / atmospheric +- asset plan and provenance +- selected component and visual-form route +- thumbnail-read hierarchy: what is visible at 25% zoom +- layer stack and scale risk when the slide uses networks, loops, maps, center nodes, or overlapping visual systems + +If more than 30% of pages are text boxes with decorative accents, revise the matrix before generating slides. + +If the deck feels like a sequence of rigid logic diagrams, read `references/cinematic-visual-language.md` and revise the page rhythm before generating SVGs. At minimum, important decks should identify anchor pages that can carry a cinematic image, object metaphor, atmospheric field, or large visual object instead of another small-card diagram. + +### 6B. Optional Generated Image Asset Pass + +Use this when `visual_evidence_plan.md` includes generated assets, the user asks for Imagen/Gemini/Image2/Codex/local image generation, the user criticizes weak design, or a cover/section/concept page needs stronger atmosphere than native shapes can provide. + +Read `references/generated-image-assets.md`. For high-design or image-led decks, also read `references/image-first-deck-workflow.md`. Then: + +- create or update `asset_prompt_pack.md` +- write an image resource list with raw filename, final derivative filename, slide, role, dimensions/aspect ratio, status, backend/model preference, and provenance note +- use deep prompts, not generic style words: narrative job, subject, environment, composition, camera/lens or illustration treatment, lighting, material texture, palette, negative constraints, crop-safe region, and native overlay plan +- for image-led decks, combine this with `references/cinematic-visual-language.md`: generated images should create memorable objects or atmospheres, not generic tech wallpaper +- generate assets sequentially; when using host `image_gen`, copy selected outputs from `$CODEX_HOME/generated_images/...` or the host-provided output location into `/images/`; when using a file backend, generate directly into `/images/`; retry once on failure, then mark the asset `Needs-Manual` +- for non-cover slides, create information-priority derivatives by cropping/resizing, darkening/desaturating, and baking the intended visibility into the raster asset; do not rely on SVG `` as the main readability control +- create `image_asset_contact_sheet.png` before embedding many generated assets, especially when most slides have backgrounds +- make P01/cover visually strong when useful, but make content-page backgrounds subordinate: at 25% zoom, title, key number, or native diagram must read before the generated image +- keep factual slide content native: no generated chart labels, fake paper screenshots, fake institution marks, fake UI, fake logos, or fake scientific evidence +- record every generated file, prompt, backend/model or fallback, and status in the project artifacts + +If generated imagery fails quality review, revise the prompt, create a darker information-priority derivative, or replace the image with a native diagram/source visual. Do not hide weak AI imagery behind glows. + +### 6C. Optional Figma Assist + +Use this only when the user provides a Figma reference, asks to use Figma, wants Figma Slides, or the plugin can materially improve design quality. + +Read `references/figma-integration.md`, then choose one mode: + +- **Reference extraction**: use Figma screenshots/design context/design-system search to derive palette, typography, spacing, composition rhythm, and chart language; write `figma_style_extract.md`; convert findings into `design_contract.md` and `spec_lock.md`. +- **Figma Slides ideation**: after `slide_brief_matrix.md` and `design_contract.md` exist, generate a Figma Slides draft or options only when requested. Treat it as a deliverable or moodboard, not a replacement for native PPTX unless explicitly chosen. +- **Review aid**: use Figma screenshots or canvas inspection to compare generated pages against the reference style; record findings in `qa_report.md`. + +Never let Figma-generated output skip the matrix, contract, native-element editability rules, or automated PPTX QA. -### 6. Generate Pages +### 6D. Optional Canva Assist + +Use this when the user provides a Canva design, asks for Canva, wants brand templates/brand kits, or the deck needs stronger visual ideation before native PPTX production. + +Read `references/canva-integration.md`, then choose one mode: + +- **Canva reference extraction**: read pages/content/notes/thumbnails from an existing Canva design; write `canva_style_extract.md`; translate findings into design and asset rules. +- **Brand/template alignment**: use Canva brand kits or brand templates to discover approved colors, fonts, logos, locked elements, page types, and image language. +- **Creative candidate / moodboard**: after the slide brief matrix exists, use Canva presentation generation or template exploration to produce a visual candidate only with the required outline-review flow and user approval. +- **Asset inspiration**: use Canva only to guide the asset plan; rebuild final text, diagrams, charts, and labels as native PPTX elements whenever final deliverable is PowerPoint. + +Never use Canva output as a whole-slide bitmap deck unless the user explicitly accepts a non-native visual mockup. + +### 7. Generate Pages Generate SVG pages into `svg_output/`. Keep each page faithful to its slide brief and `spec_lock.md`. Rules: - one page, one job +- every analytical page expresses claim, evidence, and implication - big text for live-presentation pages - choose visual form based on information structure, not decoration +- use the selected component family from `page-component-library.md` unless there is a documented reason to deviate +- alternate visual modes deliberately: cinematic anchor visuals, object metaphors, native diagrams, evidence/data pages, and decision pages +- for network, loop, map, stack, and center-anchor pages, read `references/layering-and-scale.md` and apply its z-order and scale contract before drawing SVG +- use actual visual evidence where it improves comprehension: photos, screenshots, charts, mechanism diagrams, architecture diagrams, maps, portraits, institution/product marks, or generated scene assets +- keep decorative assets subordinate; if an image does not clarify the message, remove it - no whole-slide bitmap as final output -- use generated images only as background/atmosphere/source assets; keep text, charts, diagrams, and labels native editable +- use generated images only as controlled backgrounds, hero atmosphere, conceptual illustrations, or section assets; keep text, charts, diagrams, labels, logos, and factual evidence native or sourced +- when referencing generated images in SVG, use `` and keep native overlays outside the bitmap +- for image-first decks, use preprocessed information-priority background files on non-cover pages; titles, numbers, labels, center anchors, and cards must sit on top of generated imagery with enough native dark backing to read cleanly +- on cinematic/object-first pages, let one visual object occupy a meaningful share of the canvas; do not reduce every idea to equal-weight cards -### 7. QA And Export +### 8. QA And Export Run in order: ```bash -python3 "$PPT_MASTER_HOME/skills/ppt-master/scripts/svg_quality_checker.py" -python3 "$PPT_MASTER_HOME/skills/ppt-master/scripts/total_md_split.py" -python3 "$PPT_MASTER_HOME/skills/ppt-master/scripts/finalize_svg.py" -python3 "$PPT_MASTER_HOME/skills/ppt-master/scripts/svg_quality_checker.py" /svg_final --format ppt169 -python3 "$PPT_MASTER_HOME/skills/ppt-master/scripts/svg_to_pptx.py" -s final +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/svg_quality_checker.py +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/total_md_split.py +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/finalize_svg.py +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/svg_quality_checker.py /svg_final --format ppt169 +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/svg_to_pptx.py -s final ``` Then run: @@ -119,16 +268,36 @@ Then run: python3 /scripts/check_pptx_native.py ``` -Render PNG previews and a montage. Inspect visually. Use `references/qa-rubric.md` and write `qa_report.md`. +Render PNG previews and montage. Then run: + +```bash +python3 /scripts/deck_visual_lint.py --json-out /visual_lint.json +``` + +Inspect visually. Use `references/qa-rubric.md` and `references/automated-visual-qa.md`, then write `qa_report.md`. + +QA must include a narrative section: deck thesis, page claim/evidence/implication coverage, mainline/appendix split, and any unsupported or assumption-based claims. + +If the agency micro-pipeline was used, the final QA must include an Evidence Collector section and a Reality Checker verdict. The default final verdict is `NEEDS WORK` until rendered evidence proves otherwise. + +If generated imagery was used, QA must include a generated-asset section: file existence, prompt provenance, backend/model or host `image_gen` path, contact sheet path when applicable, no fake text/logos/UI, no factual hallucination, crop fit, overlay readability, and whether the image actually improves the slide's argument. -### 8. Deliver +If image-first or generated-background pages were used, QA must include a background-dominance check: at 25% zoom, P01 may allow the hero image to dominate, but every non-cover page must let title, key number, or native diagram read before the background. If a content-page image is the first read, mark the slide `NEEDS WORK` and create a darker information-priority derivative or remove the image. + +If any slide uses a center anchor, radial network, loop, route map, or overlapping connectors, QA must include a layering/scale check: center anchor and its text sit above connectors, connector lines do not bleed through labels, and dominant objects remain larger than secondary nodes at thumbnail size. + +QA must also include a component/rhythm check for important decks: if most slides are card grids, funnels, radial maps, or abstract logic diagrams with no cinematic anchor/object-led pages, or if the component choice does not match the claim's information structure, mark the deck `NEEDS WORK` for design impact even when automated checks pass. + +### 9. Deliver Final response should include: - exported PPTX path +- Figma/Canva URLs or reference artifacts when used - preview montage path -- intermediate artifacts: `slide_brief_matrix.md`, `design_contract.md`, `qa_report.md` -- automated QA results +- intermediate artifacts: `needs_alignment_brief.md`, `claim_evidence_implication.md`, `slide_brief_matrix.md`, `visual_evidence_plan.md`, `design_contract.md`, `asset_prompt_pack.md` when used, `qa_report.md`, and agency artifacts when used +- image-first artifacts when used: `image_asset_contact_sheet.png` and final generated-image derivative list +- automated QA results: `check_pptx_native.py`, `deck_visual_lint.py`, and visual montage review - unresolved issues and recommended next iteration ## Quality Bar @@ -143,3 +312,5 @@ For launch-style decks inspired by Xiaomi: - no generic "title + three cards" unless the brief truly requires modular comparison For dense report decks, preserve clarity through page-level briefs, not by cramming paragraphs into boxes. + +If a produced deck feels visually thin, do not simply add glow, cards, or random illustrations. Re-run the art-direction pass, replace text-only pages with stronger visual evidence, and regenerate the weakest pages. diff --git a/agents/openai.yaml b/agents/openai.yaml index 5da4de0..e9cfbdb 100644 --- a/agents/openai.yaml +++ b/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Future PPT" - short_description: "成熟文档解构到可编辑发布级PPT的完整标准生产工作流" - default_prompt: "Use $future-ppt to turn this mature document into an editable launch-quality PPT." + short_description: "成熟文档到可编辑PPT，含需求对齐、叙事编译、组件路由、Image2资产和自动QA" + default_prompt: "Use $future-ppt to turn this mature document into an editable launch-quality PPT. First align audience, purpose, decision/action, content boundaries, and style archetype; compile claim/evidence/implication; then build a slide brief matrix with visual-form routing and page components, a visual evidence plan, design contract, and QA report. When design quality matters, run the agency micro-pipeline with narrative, brand, design-system, cinematic/generated/source asset prompts, image-first information-priority derivatives, evidence, visual lint, and reality-check passes." diff --git a/examples/slide_brief_matrix.example.md b/examples/slide_brief_matrix.example.md index 9305044..75bf18a 100644 --- a/examples/slide_brief_matrix.example.md +++ b/examples/slide_brief_matrix.example.md @@ -1,9 +1,9 @@ # Slide Brief Matrix Example -| Page | Page Type | Page Job | Core Message | Info Load | Visual Form | Why This Visual | Source Content | -|---|---|---|---|---|---|---|---| -| P01 | cover | Establish topic and tone | The deck evaluates product talent by potential, not resume | light | black launch cover + neon orbit | Creates a memorable system metaphor | Title and thesis | -| P02 | problem | Reject weak signals | Past products, team size, and results are insufficient | light | giant statement + strike lines | One clear launch-style claim | Opening argument | -| P03 | model | Introduce the framework | L, C, A, and Ego form the minimum model | medium | hub-spoke model | Four variables orbit one subject | Framework section | -| P04 | analysis | Explain decision height | L asks which altitude a person can judge from | medium | maturity ladder | Levels are naturally hierarchical | L section | -| P05 | conclusion | Define investability | Invest people who can define complex systems | medium | threshold ladder | A decision threshold is best shown as a ladder | VC section | +| page_id | page_type | page_job | target_read | source_claim | core_message | information_load | visual_form | selected_component | why_this_visual | visual_evidence_asset | source_content | +|---|---|---|---|---|---|---|---|---|---|---|---| +| P01 | thesis | Establish the investment question | live claim | The category should be reframed around the user's real job-to-be-done | The opportunity is not the visible gadget, but the system that makes the job easier | light | claim hero + proof chips | Claim Hero + Native Proof | A strong thesis needs one memorable read plus a few proof anchors | native shapes; optional sourced/product image | executive summary | +| P02 | market | Rebuild the market map | leave-behind proof | The addressable market should be calculated from substitute behavior, not category labels | The real market bottom-up comes from substitute products and usage frequency | dense | three-segment comparison + activation threshold | Assertion + Exhibit | Market logic requires comparison and a threshold, not a decorative TAM circle | native table/chart | market sizing section | +| P03 | route | Explain the sequence of entry points | leave-behind proof | The wedge should start where adoption friction is lowest | Start narrow, prove repeat use, then platformize | medium | stage roadmap | Roadmap / Stage Gate | A route is sequential and should show gates and proof milestones | native roadmap | product strategy section | +| P04 | risk | Make diligence risks visible | leave-behind proof | The biggest risk is reliability and distribution, not only technical feasibility | A plausible product still fails if service, insurance, and compliance do not work | dense | risk matrix | Risk Matrix | Investment decisions need downside visibility and mitigation | native table | risk section | +| P05 | decision | Close with the recommended next action | live claim | The next step is a targeted validation sprint, not a broad search | Approve a focused diligence plan before committing to company sourcing | medium | decision board | Recommendation / Decision Board | A closing page should state the ask, reasons, risks, and next action | native board | conclusion | diff --git a/references/agency-agent-workflow.md b/references/agency-agent-workflow.md new file mode 100644 index 0000000..5f684cb --- /dev/null +++ b/references/agency-agent-workflow.md @@ -0,0 +1,180 @@ +# Agency Agent Micro-Pipeline + +Use this when the user mentions local agents, asks for stronger design quality, asks to "try harder", or when a deck is important enough that one-pass production is risky. + +This reference distills local professional/agency-style workflows into a PPT-specific process. Do not paste private agent files into a deck project. Convert their roles into concrete artifacts and gates. + +## Core Doctrine + +- Evidence over claims: every quality statement needs rendered proof, source notes, or measurable checks. +- No phase advances without a gate: narrative, design system, visual evidence, render QA, and final readiness must each pass. +- Default to `NEEDS WORK` during QA. First versions normally need revision. +- Use structured handoffs so context does not disappear between narrative, design, asset, build, and QA steps. +- Maximum 3 retry cycles for a stubborn slide or deck-level defect; then escalate by decomposing or changing the approach. + +## Role Map For PPT Work + +| Local agent pattern | PPT role | Required artifact | +|---|---|---| +| Agents Orchestrator | Pipeline owner and gatekeeper | `agent_workflow_plan.md` | +| Visual Storyteller | Narrative arc, pacing, visual metaphor | `claim_spine.md` and updates to `slide_brief_matrix.md` | +| Brand Guardian | Brand integrity and consistency | `brand_guardian_audit.md` and `design_contract.md` | +| UX Architect / UI Designer | Design system, tokens, slide components | `spec_lock.md`, component/archetype rules in `design_contract.md` | +| Image Prompt Engineer | Generated/source asset prompts | `asset_prompt_pack.md` when generated imagery is used | +| Inclusive Visuals Specialist | Human/cultural/identity image risk review | `asset_risk_review.md` when people, institutions, places, or cultural imagery appears | +| Evidence Collector | Screenshot/contact-sheet QA | QA section in `qa_report.md` with visual evidence issues | +| Reality Checker | Final readiness verdict | final verdict in `qa_report.md` | + +## Required Micro-Pipeline + +### 1. Orchestrator Setup + +Create `agent_workflow_plan.md` for substantial decks. + +```markdown +# Agent Workflow Plan + +| Phase | Role | Input | Output | Gate | +|---|---|---|---|---| +| Narrative | Visual Storyteller | source notes | claim_spine.md | every slide has a claim + proof object | +| Brand | Brand Guardian | brand assets/reference | design_contract.md | palette/type/logo rules are explicit | +| System | UX/UI | design_contract.md | spec_lock.md + archetypes | tokens and component rules are executable | +| Assets | Image Prompt / Inclusive Visuals | visual_evidence_plan.md | asset_prompt_pack.md / asset_risk_review.md | assets are relevant, credible, and safe | +| Build | PPT executor | matrix + specs | native PPTX | automated checks pass | +| QA | Evidence Collector / Reality Checker | rendered pages | qa_report.md | final verdict justified by evidence | +``` + +Also record retry policy: `Attempt 1`, `Attempt 2`, `Attempt 3`, then escalate by redesigning the weak slide rather than decorating it. + +### 2. Visual Storyteller Pass + +Create or update `claim_spine.md`: + +- beginning: why this deck exists and the audience tension +- middle: evidence progression and conflicts/tradeoffs +- end: decision, recommendation, or next question +- emotional rhythm: which pages are anchor, breathing, dense, proof, or decision pages +- visual metaphor: the deck's repeated organizing image, e.g. stack, route map, loop, funnel, operating system, maturity gate + +Every non-appendix slide must have: + +- assertion title +- proof object +- support note +- intended audience reaction + +### 3. Brand Guardian Pass + +Create `brand_guardian_audit.md` when a brand, organization, event, or default style matters. + +Check: + +- logo use: authentic local/official asset only; no pseudo-logo drawings +- palette roles: semantic color names, not random accent reuse +- typography: exact font stack and hierarchy +- voice: board brief, launch stage, academic, government, investor, or editorial +- do-not-use list: forbidden colors, decorative styles, icons, image treatments, language tone +- accessibility: contrast and small-text risk + +Translate only executable rules into `design_contract.md` and `spec_lock.md`. + +### 4. UX/UI Design-System Pass + +Before drawing pages, define a small slide component library: + +- canvas grid and margin system +- title block positions +- footer/page-label/logo treatment +- chart language +- table language +- route/stack/loop/map/card archetypes +- density budgets for light, medium, dense, and appendix slides +- minimum sizes for labels, captions, and notes + +If two slides use similar information, reuse a component or archetype instead of inventing a new layout. + +### 5. Asset Prompt And Risk Pass + +Use this when a page needs generated or sourced imagery. + +For `asset_prompt_pack.md`, each asset prompt must include: + +- backend/model preference and fallback path, e.g. Imagen/Gemini/OpenAI/host-native/image_gen +- output filename and expected dimensions +- narrative job +- subject +- context/environment +- composition/camera +- lighting/color grade +- material/texture or illustration treatment +- style reference +- aspect ratio +- negative constraints +- intended slide and crop area +- native overlay plan: which text, labels, logo, and callouts remain editable outside the bitmap +- status: `Pending`, `Generated`, `Needs-Manual`, `Rejected`, or `Replaced-Native` + +For `asset_risk_review.md`, check: + +- no fake text, logos, seals, institution marks, or UI screenshots +- no generic stock-photo human representation +- no culturally inaccurate clothing, architecture, symbols, or geography +- no clone faces or unrealistic anatomy in generated people images +- generated factual visuals are labeled as conceptual or replaced with native diagrams +- generated scientific-looking imagery is not used as proof, microscopy, benchmark output, source screenshot, or paper evidence +- prompt provenance and backend/model are recorded for every generated asset + +Scientific/technical decks should prefer native diagrams, charts, paper/source cards, and annotated screenshots over generated decorative imagery. + +### 6. Evidence Collector Pass + +After export, render the PPTX to PNG pages and a montage. In `qa_report.md`, include: + +- rendered preview path +- what the contact sheet actually shows +- 3-5 issues found on first pass, or a clear explanation of why fewer issues remain after fixes +- exact slide IDs changed after QA +- before/after note when a slide was redrawn + +Visual QA must trust screenshots over intention. If a rendered page has text collision, weak hierarchy, or tiny labels, it fails even if the SVG source looked acceptable. + +### 7. Reality Checker Pass + +Final verdict defaults to `NEEDS WORK`. + +Only mark `READY` when: + +- automated QA passes +- native editability check passes +- montage has no visible collisions +- every page has a claim and proof object +- brand rules are followed +- sources/provenance are documented for factual claims and non-native assets +- residual risks are explicitly listed + +Avoid inflated scores. A first "good" deck can still be `NEEDS WORK` if the contact sheet lacks variety, proof, or executive clarity. + +## PPT Handoff Template + +Use inside `agent_workflow_plan.md` or `qa_report.md` when a phase changes. + +```markdown +## Handoff: [Role] -> [Role] + +- Input: +- Output: +- Acceptance criteria: +- Evidence required: +- Known risks: +- Next action: +``` + +## What To Borrow From The Local Agents + +- From `design-visual-storyteller.md`: narrative arc, emotional journey, visual pacing, data storytelling, progressive disclosure. +- From `design-brand-guardian.md`: brand foundation, visual identity system, voice rules, consistency audit. +- From `design-ux-architect.md` and `design-ui-designer.md`: tokens, spacing, typography hierarchy, reusable components, developer-ready specs. +- From `design-image-prompt-engineer.md`: subject/context/lighting/camera/style/negative-prompt structure for generated imagery. +- From `design-inclusive-visuals-specialist.md`: explicit anti-bias and authenticity checks for people/culture/place imagery. +- From `testing-evidence-collector.md` and `testing-reality-checker.md`: screenshots as proof, default skepticism, no fantasy approvals. +- From NEXUS coordination docs: phase gates, handoff templates, retry loops, and evidence-based progression. diff --git a/references/art-direction.md b/references/art-direction.md new file mode 100644 index 0000000..6b52bfe --- /dev/null +++ b/references/art-direction.md @@ -0,0 +1,129 @@ +# Art Direction And Visual Evidence + +Use this before generating SVG pages. The goal is to make the deck visually convincing, not merely styled. + +## First Principles + +- One idea per slide: split overloaded pages instead of shrinking everything. +- Start each analytical slide with an assertion headline, then support it with visual evidence and an implication. +- Use visuals to do work that words cannot: show structure, comparison, mechanism, scale, evidence, context, or emotion. +- Do not add images for decoration. Every image must be representational, organizational, explanatory, data-bearing, source/proof, or controlled atmosphere. +- Favor consistent grids, repeated components, and a small number of page archetypes so the deck feels designed as a system. +- Use strong hierarchy: one dominant object, one headline, one takeaway. Secondary labels must not compete with the main read. +- Build slides that still communicate when forwarded without a presenter: assertion headline, visible evidence, compact caption, and speaker notes. +- Balance native logic diagrams with cinematic anchor visuals or object metaphors when the deck needs design impact. A deck that is all funnels, cards, and radial maps may be correct but visually forgettable. + +## Required Artifact: `visual_evidence_plan.md` + +Create this file after `slide_brief_matrix.md` and before `design_contract.md`. Use `claim_evidence_implication.md` to verify each page's claim and evidence, then use `visual-form-router.md` and `page-component-library.md` to select the visual form and component. + +```markdown +# Visual Evidence Plan + +| page_id | audience_takeaway | claim | implication | component | dominant_visual | visual_evidence_category | asset_plan | source/provenance | native_editability_plan | thumbnail_read | risk | +|---|---|---|---|---|---|---|---|---|---|---|---| +| P03 | ... | ... | ... | timeline / career arc | timeline + portrait/photo | source / organizational | use scholar metric callout + career timeline | local/source/public/generated | timeline and labels native; portrait optional bitmap | title + metric + arc visible | avoid tiny labels | +``` + +For important decks, also create or embed a `Visual Object Brief` for anchor pages. See `cinematic-visual-language.md`. + +## Visual Evidence Categories + +- **Representational**: portrait, product screenshot, institution logo, actual object, cell image, lab photo. +- **Organizational**: timeline, stack, matrix, map, system architecture, route diagram. +- **Explanatory**: mechanism, process, causal loop, before/after, annotated model. +- **Data**: chart, table, metric strip, benchmark result, citation count, funding amount. +- **Source/proof**: paper title screenshot, publication card, quote chip, citation callout. +- **Atmospheric**: generated or sourced background that sets tone; use sparingly and never as the only reason a slide exists. +- **Object/metaphor**: a large generated, sourced, or native visual object that makes an abstract idea memorable; factual content remains native or sourced. + +## Asset Strategy + +For every page, choose one: + +- **Native-only**: best for clean diagrams, charts, matrices, timelines, and executive logic. +- **Public/source image**: use when an actual person, place, product, paper, cell image, or screenshot increases trust. +- **Generated image**: use for conceptual backgrounds, abstract scientific environments, cover imagery, or section dividers when no source image is appropriate. +- **Generated object/scene**: use for cinematic anchor pages or visual metaphors when a large visual object helps the audience feel scale, network, transition, or urgency. +- **Canva/Figma reference**: use as style or layout inspiration, then rebuild final PPT elements natively. +- **No image intentionally**: allowed only when the native diagram is already the visual evidence. + +If any page uses **Generated image**, run `references/generated-image-assets.md` before SVG generation and create `asset_prompt_pack.md`. Generated assets must have filenames, prompt provenance, backend/model or host `image_gen` path, and status before they are embedded. + +If generated images are used as a recurring deck language, run `references/image-first-deck-workflow.md`. Define which pages are allowed to be strong image-led pages and which pages require information-priority derivatives. P01 may be visually dominant; non-cover pages must let title, key number, native diagram, or evidence cards read before the image at 25% zoom. + +If a deck feels visually dry or overly diagrammatic, run `references/cinematic-visual-language.md` and convert selected cover/section/thesis pages into object-first anchor pages. + +## Image Quality Rules + +- Prefer fewer, larger, more meaningful visuals over many small decorative thumbnails. +- Place labels next to the parts of the image/diagram they explain. +- Credit sources for public images, screenshots, charts, and statistics in notes or small captions. +- Avoid clip art, generic stock photos, decorative science backgrounds, and unrelated icons. +- If using AI-generated images, keep them as controlled backgrounds, hero atmosphere, conceptual illustrations, or section assets. Keep all factual labels, charts, diagrams, logos, source proof, and citations native or sourced. +- For information-heavy pages with generated backgrounds, use a darkened/desaturated raster derivative rather than relying only on SVG image opacity. +- For scientific/technical decks, prefer diagrams, mechanism illustrations, annotated screenshots, microscopy/source visuals, and data charts over generic photos. + +## Generated Image Prompt Discipline + +Generated image prompts must be specific enough to control composition, not just style. Each generated asset needs: + +- narrative job: what feeling or argument the image carries +- subject and environment: concrete objects and setting +- composition/crop: where title and native overlays will sit +- camera or illustration treatment +- lighting/color grade tied to `spec_lock.md` +- negative constraints: no text, watermark, logo, fake UI, fake labels, or factual-looking evidence +- image intensity and native overlay plan: cover can be strong; content pages need safe zones and subdued backgrounds + +Do not ask image generation models to make readable slide text, charts, citations, diagrams, or logos. Generate the visual field; build the information layer natively. + +## Layering And Scale Rules + +For networks, loops, maps, and center-node diagrams, read `layering-and-scale.md` before drawing the page. + +- Define the dominant anchor and its intended scale before placing connectors. +- Draw relationship lines below nodes and center anchors. +- Center anchors and their text must sit on top of the relationship layer. +- If connector lines pass through a center node, use an opaque backplate/mask or terminate the lines at the node boundary. +- Do not let transparency or small scale make the anchor weaker than surrounding nodes. + +## Page Archetype Menu + +Use a small set of archetypes per deck: + +- Hero claim + primary visual +- Cinematic anchor visual +- Object metaphor + native claim overlay +- Assertion-evidence slide +- Timeline / migration path +- System stack / layered architecture +- Mechanism loop / process flow +- 2-axis map / 2x2 matrix +- Evidence card + source proof +- Benchmark chart / metric strip +- Dense reference table +- Closing judgment board + +If the deck has too many unique layouts, simplify to 5-7 archetypes and vary content within them. + +For reusable component rules, load `page-component-library.md`. For mapping information structure to visual form, load `visual-form-router.md`. + +## Thumbnail QA + +Render a montage and inspect at thumbnail size. A page fails if: + +- the headline is not legible +- the dominant visual cannot be recognized +- every element has equal visual weight +- labels collide or require zooming +- connector lines or grid marks cross center-anchor labels +- the center object is lower in layer order than relationships around it +- on non-cover pages, a generated background dominates the title, key metric, or native diagram +- the deck has no memorable anchor object or cinematic page +- every page uses the same abstract logic-diagram language +- the page looks like a text box with decorations +- the image is attractive but does not clarify the point +- the selected component does not match the claim/evidence/implication plan + +Fix by changing the visual form or asset, not by adding more decoration. diff --git a/references/automated-visual-qa.md b/references/automated-visual-qa.md new file mode 100644 index 0000000..1580b4c --- /dev/null +++ b/references/automated-visual-qa.md @@ -0,0 +1,81 @@ +# Automated Visual QA + +Use this before final handoff, after SVG preview rendering and before or after PPTX export. + +Automated checks do not replace human design judgment. They catch structural risks that commonly make decks feel weak: image-only pages, tiny text, repeated card grids, unsafe backgrounds, approximate text overlaps, and missing editable text. + +## Required Script + +Run: + +```bash +python3 /scripts/deck_visual_lint.py +``` + +If preview PNGs are in a nonstandard folder: + +```bash +python3 /scripts/deck_visual_lint.py --preview-dir +``` + +Write the findings into `qa_report.md` under `Automated Visual Lint`. + +## What It Checks + +SVG-level: + +- page count +- text count and editable text risk +- image count and image-only slide risk +- tiny font sizes +- approximate text bounding-box collisions +- text outside canvas +- forbidden or fragile SVG features +- repeated dense card-grid patterns + +PNG-level when previews are available: + +- average brightness +- contrast +- edge/detail intensity +- possible over-bright or over-busy backgrounds + +Deck-level: + +- too many pages with similar card-heavy structure +- too many image-heavy pages +- too many text-heavy pages +- lack of visual rhythm + +## How To Interpret + +Treat `ERROR` as blocking. + +Treat `WARN` as a required review item: + +- fix it when the issue is real +- mark it as accepted only when the deck's purpose justifies it, e.g. dense appendix pages + +The script is conservative and best-effort. It cannot fully understand group transforms, complex typography, or the real semantic first-read. Always inspect the preview montage after running it. + +## Common Fixes + +| Finding | Likely Fix | +|---|---| +| low text count with images | rebuild title/labels natively; do not use full-slide screenshot | +| tiny font | split page, move detail to appendix, enlarge labels | +| possible overlap | adjust layout, line breaks, component spacing | +| bright/busy preview | darken background derivative, add safe-zone panel, simplify image | +| repeated card grid | reroute pages through `visual-form-router.md` | +| too many image-heavy pages | keep images for cover/anchors; use native exhibits for proof pages | + +## Human Follow-Up + +After the script, inspect: + +- 25% montage first-read +- page rhythm +- whether selected style archetype is visible +- whether each page's component matches the claim +- whether generated images are doing real work +- whether the final PPTX remains editable diff --git a/references/canva-integration.md b/references/canva-integration.md new file mode 100644 index 0000000..49246b7 --- /dev/null +++ b/references/canva-integration.md @@ -0,0 +1,86 @@ +# Canva Integration Reference + +Use this reference when the user provides a Canva URL/design ID, asks to use Canva, wants stronger template/brand/moodboard help, or needs a separate Canva design deliverable. + +## Boundary + +- Default final deliverable remains native editable PPTX via `ppt-master`. +- Use Canva as a brand/template/moodboard/reference-design layer. +- Do not silently convert a requested PPTX into a Canva-only deliverable. +- Do not paste Canva pages as whole-slide bitmap images into the final PPTX unless the user explicitly wants a visual mockup rather than editable PowerPoint. +- Local files cannot be imported into Canva through the connector unless they are available via a public HTTPS URL. Keep local-file workflows in `ppt-master` unless the user uploads/shares a public URL. + +## What Canva Adds + +- Existing design search and reading: find user-owned/shared Canva presentations, read page content, page thumbnails, and presenter notes. +- Brand consistency: inspect/use brand kits and brand templates when available. +- Template acceleration: search brand templates; use autofill only when a template has a non-empty dataset and the user confirms the template. +- Creative ideation: generate Canva presentation candidates through the required outline-review flow. +- Repurposing: import public HTTPS PDFs/PPTX/DOCX/URLs into Canva when the user provides a public URL. +- Editing: update text/media/layout in existing Canva designs through an editing transaction, then commit only after explicit user approval. + +## Mode 1: Canva Reference Extraction + +Use when the user provides a Canva design URL or design ID. + +1. Extract the design ID from `https://www.canva.com/design/{design_id}`. Resolve shortlinks first when needed. +2. Use Canva design metadata, pages/thumbnails, content, and presenter notes to inspect: + - page count and page rhythm + - title, body, caption hierarchy + - dominant visual objects and image posture + - color palette and repeated components + - logo/brand placement + - chart/table/diagram language +3. Write `/canva_style_extract.md`. +4. Translate findings into: + - `visual_evidence_plan.md` + - `design_contract.md` + - `spec_lock.md` + +Do not copy every Canva element. Extract the system: hierarchy, grid, rhythm, palette, and image strategy. + +## Mode 2: Brand Kit / Brand Template Alignment + +Use when the user says the deck must be on-brand or asks to use a Canva template. + +1. If the user asks for an on-brand design, list brand kits and let the user choose. +2. If the user asks for a template, search brand templates, not existing designs. +3. For generation from template, use only templates with non-empty datasets and confirm the selected template with the user. +4. Inspect dataset fields before autofill. +5. Translate brand/template rules into native PPT constraints: + - colors → HEX roles in `spec_lock.md` + - typography → PPT-safe font family and exact sizes + - logos → project `images/` + - locked/repeated elements → master-like slide constants + - page types → deck archetypes + +## Mode 3: Canva Creative Candidate / Moodboard + +Use only after `slide_brief_matrix.md` and `visual_evidence_plan.md` exist. + +For Canva presentation generation: + +- Start with Canva outline review. Do not bypass it. +- Keep generated candidate decks short unless the user explicitly wants a full Canva version. +- Treat the candidate as visual R&D unless Canva is the requested deliverable. +- Extract what works: cover composition, image posture, title scale, section rhythm, color pairings, and slide archetypes. +- Rebuild final PPTX natively through `ppt-master`. + +## Mode 4: Import / Export Reality Check + +- Canva can import public HTTPS files through the connector; it cannot access local `/Users/...` paths. +- Canva Connect APIs support exporting Canva designs to formats including PDF, PNG/JPG, MP4, and PPTX for eligible presentation designs, but the current Codex plugin session may not expose a direct local export tool. Check available tools before promising an export. +- When the final deliverable is a local PPTX, do not depend on Canva export. Use Canva for ideation/reference, then export through `ppt-master`. +- If the user explicitly wants a Canva editable design, deliver the Canva design URL and clearly label it separately from the native PPTX. + +## Mode 5: Canva-Assisted QA + +Add a Canva section to `qa_report.md` when used: + +- Canva source/design/template/brand kit used +- extracted visual rules +- pages that adopted Canva-inspired archetypes +- pages intentionally diverging from Canva and why +- whether final PPTX remained native-editable + +Canva design polish does not replace SVG/PPTX QA. Always still render previews, inspect the montage, and run native editability checks. diff --git a/references/cinematic-visual-language.md b/references/cinematic-visual-language.md new file mode 100644 index 0000000..bff2cd5 --- /dev/null +++ b/references/cinematic-visual-language.md @@ -0,0 +1,140 @@ +# Cinematic Visual Language + +Use this when the user wants a deck with stronger design feeling, when a deck looks like a series of rigid logic diagrams, or when generated-image models such as GPT Image / Imagen / Gemini can create better anchor visuals. + +The goal is not to make the deck decorative. The goal is to give the deck visual memory: a few pages should have a clear object, scene, atmosphere, or cinematic frame that the audience can remember after the meeting. + +## Design Principle + +Pretty PPTs usually have rhythm: + +- **anchor visual pages**: one large object or atmosphere, short claim, minimal text +- **native diagram pages**: logic, mechanism, system, route, workflow +- **evidence pages**: source cards, metrics, screenshots, tables, charts +- **decision pages**: crisp recommendation boards + +If every page is a diagram, the deck becomes intellectually clear but visually dry. If every page is a generated image, the deck becomes pretty but untrustworthy. Use both. When many pages use generated images, apply `image-first-deck-workflow.md`: cover pages may be visually strong, while non-cover pages need subdued, information-priority backgrounds. + +## Anchor Visual Modes + +Choose one mode for important cover, section, or thesis pages: + +| Mode | Use When | Visual Posture | +|---|---|---| +| Cinematic atmosphere | The page needs emotion, scale, or awe | full-bleed or 60-75% canvas image with native title overlay | +| Object metaphor | The page needs a memorable concept | one dominant object: battery core, constellation, bridge, lens, compass, control room, data crystal | +| Material macro | The topic is science/technology/materials | close-up material landscape, electrode layers, membrane texture, particles, lattice | +| Spatial map | The topic is networks or ecosystems | star map, city grid, orbital routes, terrain map, mission control board | +| Editorial hybrid | The page needs both proof and mood | large image/object plus native evidence chips or metrics | + +For business/executive decks, usually 25-40% of slides can be anchor or object-led pages. Dense appendix/report decks may use fewer. A 10-12 page important deck should normally have at least 2-4 visually memorable anchor pages. + +## Image Intensity Discipline + +Generated images should have different strength by page role: + +- cover: strong hero image or object can dominate if title space is clean +- section anchor: cinematic but simple; short native claim on top +- thesis/content page: image supports one native diagram, metric, or claim +- dense evidence page: image is absent or reduced to a dark texture + +For non-cover pages, the audience should read the title, key number, native diagram, or decision text before the image. If the image is the first read in a preview montage, darken/desaturate it, create an information-priority derivative, crop away detail, or remove it. + +## Object-First Brief + +Before writing prompts or drawing SVG, define the object: + +```markdown +## Visual Object Brief + +| page_id | claim | visual_object | why_this_object | image_mode | native_overlay | risk | +|---|---|---|---|---|---|---| +| P01 | talent map becomes an operating system | energy-storage constellation | shows route + network + scale | generated hero | title left, labels native | avoid generic starfield | +``` + +Good visual objects are concrete: + +- energy-storage constellation +- glowing battery core in a black void +- orbital route map around a material crystal +- mission-control table with route lights +- molecular/material lattice turning into a city grid +- bridge between overseas research stars and Chinese industrial nodes + +Weak visual objects are vague: + +- technology background +- innovation +- futuristic energy +- abstract science +- AI network + +## Generated Image Prompt Pattern + +Use this pattern for image-led slides: + +```text +Presentation anchor image, 16:9. [Narrative job]. A single dominant [visual object] in [specific environment], [composition and negative space], [camera/lens or illustration treatment], [lighting/color grade tied to spec_lock], [material/texture/detail], premium editorial science/technology style, suitable for native Chinese title overlay, no readable text inside image, no logo, no watermark, no fake UI, no chart, no institution seal. +``` + +Add a negative prompt: + +```text +text, letters, watermark, logo, fake UI, fake chart, fake labels, fake institution seal, stock photo, people, faces, clutter, blurry, low quality, oversaturated gradient, random sci-fi decoration +``` + +## Advanced Energy Examples + +### Cover + +Visual object: energy-storage talent constellation. + +Prompt direction: + +```text +Presentation anchor image, 16:9. Show advanced energy storage talent as a navigable constellation, not a list. A deep black star-map-like field with six luminous route clusters implying solid-state batteries, sodium-ion batteries, flow batteries, compressed-air storage, flywheel/gravity storage, and hydrogen storage. One elegant central energy core connects to orbital research and industry nodes. Premium scientific editorial visualization, restrained cyan, magenta, yellow, neon green, and electric blue, generous empty space on the left for native title text, crisp lines, cinematic darkness, no text, no logo, no fake charts, no people. +``` + +### Overseas Network Page + +Visual object: origin star with alumni orbit. + +Prompt direction: + +```text +A single bright origin star representing a research lab, with smaller orbiting stars spreading toward a subtle map-like horizon, dark premium background, thin luminous trails, sense of overseas-to-China bridge, clean negative space for native labels, no map labels, no text, no logos. +``` + +### Industrial Conversion Page + +Visual object: material lattice becoming city power grid. + +Prompt direction: + +```text +A macro energy material lattice on the left gradually transforming into a clean city-scale power grid on the right, dark cinematic presentation background, restrained neon route colors, premium scientific visualization, no text, no logos, no fake UI. +``` + +## Native Overlay Rules + +- All titles, labels, metrics, route names, source notes, and logos stay native PowerPoint objects. +- Generated images should provide scene, object, texture, scale, and emotion. +- Do not ask an image model to draw Chinese text, data labels, company names, or charts. +- Compose images with negative space where native text will sit. +- Avoid busy images behind dense data. +- Use native dark panels, scrims, and center anchors above the image layer when content needs protection. +- On radial/network/loop pages, connector lines and generated backgrounds stay behind the center anchor and its text. + +## Visual Rhythm QA + +During montage review, fail the deck if: + +- every page is a logic diagram, card grid, funnel, or radial map +- generated images look like generic tech wallpaper and could fit any topic +- anchor images do not have one recognizable object +- images compete with native text or make it hard to read +- non-cover backgrounds are the first read at 25% zoom +- there is no breathing page after multiple dense evidence pages +- object scale is too timid: the visual is present but not memorable + +Fix by replacing one or more logic pages with an object-first page, not by adding decorative background images behind the same diagram. diff --git a/references/dark-neon-default.md b/references/dark-neon-default.md new file mode 100644 index 0000000..7b90713 --- /dev/null +++ b/references/dark-neon-default.md @@ -0,0 +1,38 @@ +# Dark Neon Default + +Use this as the default PPT aesthetic when no stronger style reference is supplied. + +## Visual Identity + +- Background: pure black `#000000`. +- Primary text: pure white `#FFFFFF`, bold or extra-bold. +- Secondary text: cool gray, restrained, never low-contrast. +- Accent palette: cyan `#00F5FF`, magenta `#FF2BD6`, yellow `#FFE600`, neon green `#39FF14`. +- Layout: extreme minimal dark mode, generous negative space on claim pages, tighter but still scanable structure on analysis pages. +- Brand asset: optional. Use only real user-provided logos or bundled project assets. + +## Logo Rule + +- Default placement: top-right corner on every slide when a real logo is provided. +- Recommended 16:9 SVG coordinates: top-right safe area, scaled small enough to avoid competing with the title. +- Keep transparent-background PNG logos intact; do not redraw them as fake text or pseudo-marks. +- If the title or chart genuinely conflicts with the logo, reduce width before moving it. + +## Implementation + +- Copy the real logo asset into the deck project `images/` directory. +- Add the logo as a small `` brand mark on every SVG page before finalization. +- Do not add opacity to the `` tag; the SVG QA checker treats image opacity as a forbidden pattern. +- In PPTX QA, one approved media asset is acceptable when the only media asset is the real logo. + +## Composition Rules + +- No beige, brown, corporate blue, or washed gradient themes unless the user explicitly requests them. +- Do not use gradient blobs, orbs, or decorative bokeh as background. +- Keep text, charts, diagrams, and labels native editable in the PPTX. +- Generated or bitmap images are acceptable for backgrounds, subject images, or brand marks, but not as whole-slide screenshots. +- Use neon color only to encode emphasis, data, topology, or hierarchy; avoid turning every element bright. + +## Tone + +The deck should feel like a premium future-industry board briefing: black field, white conviction, neon evidence. diff --git a/references/design-contracts.md b/references/design-contracts.md index 03dea1b..8cc7e3a 100644 --- a/references/design-contracts.md +++ b/references/design-contracts.md @@ -12,6 +12,10 @@ Human-readable contract: ## Style Positioning - Inspiration: - Audience: +- Purpose / decision needed: +- Reading mode: +- Selected archetype: +- Why this archetype fits: - Emotional register: - What this deck must feel like: - What it must avoid: @@ -30,12 +34,36 @@ Human-readable contract: ## Page Rhythm - Anchor pages: +- Cinematic/object pages: - Breathing pages: - Dense pages: +- Appendix / leave-behind pages: +- Component families allowed: +- Component families forbidden: + +## Visual Evidence Strategy +- Dominant visual categories: +- Cinematic/object-led anchor pages: +- Image/source posture: +- Diagram/chart posture: +- AI-generated image boundary: +- Image-first intensity ladder: +- Information-priority derivative rule: +- Asset credit/provenance rule: + +## Figma/Canva Assist +- Figma reference or system used: +- Canva reference, brand kit, or template used: +- Extracted rules adopted: +- Rules intentionally rejected: ## Visual Rules - One-page-one-job rule: +- Audience fit rule: +- Claim/evidence/implication rule: - Chart language: +- Table language: +- Component language: - Image posture: - Decoration boundary: @@ -94,6 +122,28 @@ Choose from or adapt: - government-report: formal red/blue, authoritative hierarchy - academic-defense: serif/sans mix, structured evidence and citations +### Needs-Aligned Archetype + +Load `needs-alignment-and-style-archetypes.md` and `style-archetype-playbooks.md` when selecting a design language from audience and purpose. + +Translate the selected archetype into: + +- page archetypes: executive summary, exhibit, comparison, roadmap, launch claim, evidence appendix, etc. +- composition logic: assertion headline, exhibit-first, hero-object, dashboard, formal report, technical mechanism +- chart/table grammar: what kinds of tables, charts, captions, and footnotes are expected +- density and reading mode: live presentation, leave-behind, or both +- forbidden moves: styles that would undermine the audience's trust + +### Component Contract + +Load `page-component-library.md` and define: + +- primary component families used in this deck +- where each component is allowed: mainline, proof page, appendix, section anchor +- chart/table density per component +- native editability rules +- repeated component limits: avoid making most pages the same card grid unless the deck is intentionally a catalog + ### Reference PPT Extraction Inspect: @@ -108,6 +158,20 @@ Inspect: Translate findings into `design_contract.md` and `spec_lock.md`; do not blindly copy every visual artifact. +### Canva / Figma Reference Extraction + +When the visual source is Canva or Figma, extract the system instead of copying the surface: + +- palette roles, not just visible colors +- typography hierarchy, not just font names +- grid, margins, density, and page rhythm +- image posture: full bleed, cropped editorial, isolated object, screenshot, proof card, or no image +- chart/table/diagram language +- repeated components and where they are allowed +- visual evidence categories that make the reference feel credible + +Record extracted rules in `canva_style_extract.md` or `figma_style_extract.md`, then translate them into this contract and `spec_lock.md`. + ### Prompt Style Translate style prompt into exact constraints. Example: @@ -122,3 +186,42 @@ Contract: - big claims in 54-82px bold - no paragraph cards - charts and emphasis only use neon colors + +## Asset And Editability Contract + +Every final PowerPoint should remain editable. Define: + +- native elements: titles, labels, diagrams, tables, charts, arrows, callouts +- acceptable bitmap elements: logo, portrait, source screenshot, microscopy/cell image, generated atmosphere, product/institution image +- forbidden bitmap usage: whole-slide screenshots used as final pages, image-only text, non-editable charts, decorative image collages +- provenance: source URL/file/generation prompt/Canva or Figma reference for each non-native asset + +## Layer And Scale Contract + +For any network, route map, loop, or center-anchor slide, include explicit rules: + +- layer stack: background → grid → connectors → peripheral nodes → center mask/backplate → center anchor → center text → logo/footer +- center anchor scale: specify radius/box size, label size, and opacity/backplate rule +- connector policy: terminate at anchor boundary or pass below an opaque mask +- thumbnail rule: center anchor must be recognized before secondary nodes at 25% zoom + +## Cinematic Visual Contract + +For high-design decks, define: + +- visual rhythm: which pages are cinematic anchors, object metaphors, native diagrams, evidence pages, and decision pages +- anchor object: the concrete thing the audience should remember +- generated image role: atmosphere/object/scene only; native overlays carry all factual content +- negative-space rule: where title and metrics will sit +- generic-image ban: no tech wallpaper that could fit any deck + +## Image-First Contract + +When generated images are used across many pages, define: + +- page intensity: cover, section anchor, thesis/content, dense evidence +- effective image presence: strong for cover; subdued for non-cover information pages +- derivative naming: raw asset and final content-safe derivative filename +- overlay protection: native dark panels, scrims, center masks, and title-safe zones +- first-read rule: on non-cover pages, title/key number/native diagram must read before the image at 25% zoom +- contact sheet rule: `image_asset_contact_sheet.png` required before embedding many generated assets diff --git a/references/figma-integration.md b/references/figma-integration.md new file mode 100644 index 0000000..c306ce5 --- /dev/null +++ b/references/figma-integration.md @@ -0,0 +1,90 @@ +# Figma Integration Reference + +Use this reference only when the user provides a Figma URL, asks to use Figma, wants Figma Slides, or a Figma design system can improve the deck. + +## Boundary + +- Default to native editable PPTX via `ppt-master`. +- Use Figma as style evidence, design-system discovery, ideation, or a parallel Figma Slides deliverable. +- Do not silently replace a requested PowerPoint with a Figma Slides deck. +- Do not use whole-slide screenshots as the final PPTX pages. Text, diagrams, charts, labels, and major shapes must remain editable in PowerPoint. + +## Required Figma Practices + +- Before any `use_figma` call, load the `figma-use` skill and follow its API rules. +- For full Figma screen construction from code or a multi-section layout, also load `figma-generate-design`. +- Prefer `get_design_context`, `get_screenshot`, `get_libraries`, and `search_design_system` for read/extraction work before writing custom Figma JavaScript. +- Every `use_figma` write must return created or mutated node IDs. +- Treat Figma tokens/components as design evidence. Translate them into explicit PPT constraints: HEX colors, font families, sizes, margins, spacing, chart rules, and forbidden values. + +## Mode 1: Figma Reference Extraction + +Use when the user provides a Figma URL as a visual reference. + +1. Extract `fileKey` and, when present, `nodeId` from the URL. +2. If no `nodeId` is present, use read-only `use_figma` to list pages and top-level frames, then choose the relevant frame before screenshotting. +3. Use `get_screenshot` for the reference node. +4. Use `get_design_context` when a node is provided and style/code metadata would help. +5. Use `get_libraries` and `search_design_system` when the deck should follow a published design system. +6. If needed, use read-only `use_figma` to inspect pages, local styles, variables, and frame geometry. +7. Write `/figma_style_extract.md` with: + - reference URL, file key, node ID, and screenshot artifact + - palette and semantic color roles + - typography and size hierarchy + - margin/grid/spacing rhythm + - chart, diagram, icon, and image language + - page rhythm and density observations + - constraints that must not be copied directly +8. Translate the extraction into `visual_evidence_plan.md`, `design_contract.md`, and `spec_lock.md`. + +## Mode 2: Design-System Assisted PPT + +Use when the user wants the deck to align with an existing Figma design system. + +Search broadly and simply. Useful queries: + +- colors: `background`, `surface`, `text`, `brand`, `accent`, `gray`, `blue`, `green`, `red` +- typography: `heading`, `title`, `body`, `caption` +- spacing and shape: `space`, `spacing`, `gap`, `radius`, `border` +- deck components: `chart`, `metric`, `card`, `table`, `timeline`, `tag` + +Keep only values that can be executed in SVG/PPT: + +- convert color tokens to HEX in `spec_lock.md` +- map text styles to concrete font family, weight, size, and line-height +- convert spacing/radius tokens into numeric slide units or SVG coordinates +- describe components as visual language, not as imported UI widgets +- map useful component patterns to deck archetypes and page-level visual evidence categories + +## Mode 3: Figma Slides Ideation Or Deliverable + +Use `generate_deck` only after `slide_brief_matrix.md` and `design_contract.md` exist. + +The prompt to `generate_deck` must be self-contained and include: + +- title, audience, use case, objectives, and tone +- slide-by-slide outline derived from the slide brief matrix +- role for every slide, with varied layouts and no repeated role more than twice in a row +- concrete content and visual direction per slide +- enforceable rules from `design_contract.md` +- palette and theme from `spec_lock.md` + +Decision rules: + +- If Figma Slides is the requested deliverable, return the Figma Slides URL and note that the result is editable in Figma. +- If native PPTX is the requested deliverable, use Figma Slides only as a moodboard/reference option and continue through `ppt-master`. +- If the user wants both, generate native PPTX and a Figma Slides version, then clearly label them as separate artifacts. + +## Mode 4: Figma-Assisted QA + +Use when a Figma reference or Figma Slides draft exists. + +Add a Figma section to `qa_report.md`: + +- reference artifacts used +- palette/typography/rhythm match +- pages that diverge from the reference and why +- issues visible in screenshots: cropped text, weak hierarchy, over-dense labels, inconsistent spacing +- whether the final PPTX still passes native editability checks + +Figma visual quality does not replace automated PPTX QA. Always still run the SVG quality checks, export, native-element check, preview render, and montage inspection. diff --git a/references/generated-image-assets.md b/references/generated-image-assets.md new file mode 100644 index 0000000..425e47b --- /dev/null +++ b/references/generated-image-assets.md @@ -0,0 +1,157 @@ +# Generated Image Assets + +Use this reference when a PPT needs AI-generated imagery as a real design asset, not as last-minute decoration. + +Generated images can improve a deck when they create a memorable atmosphere or conceptual object that sourced images cannot provide. They can also weaken a deck when they pretend to be evidence. The boundary is strict: generated images may support mood, metaphor, and composition; factual claims, labels, charts, logos, UI, paper screenshots, citations, and scientific proof stay native or sourced. + +When the deck needs a more polished, cinematic, high-design feel, pair this reference with `cinematic-visual-language.md`. When the user wants Image2/Codex/local image generation used broadly across the deck, also use `image-first-deck-workflow.md`. In that mode, generated images should create memorable objects or scenes while native PowerPoint remains the information layer. + +## When To Generate + +Use generated images for: + +- cover heroes with controlled negative space +- section dividers +- cinematic anchor pages with one dominant object +- visual metaphors that make a strategic idea memorable +- abstract scientific or technological environments +- conceptual metaphors such as route maps, operating systems, virtual labs, or computational worlds +- background textures where the image supports a native diagram or headline +- non-factual editorial illustrations where the audience will not mistake the image for evidence + +Do not generate: + +- real people portraits unless the user explicitly wants synthetic people +- institution logos, seals, certificates, paper screenshots, UI screenshots, or charts +- microscopy/cell images that will be read as real experimental evidence +- maps or geographic scenes that need exactness +- text-heavy images; all text should be native PowerPoint text + +## Required Artifact: `asset_prompt_pack.md` + +Create this before generating or embedding any generated asset. + +```markdown +# Asset Prompt Pack + +## Deck Style Anchor + +Shared visual language: + +## Image Resource List + +| filename | slide | role | dimensions | aspect_ratio | backend/model | status | provenance_note | +|---|---|---|---|---|---|---|---| +| cover_virtual_cell_world.png | P01 | hero background | 1920x1080 | 16:9 | preferred: Imagen/Gemini/OpenAI; actual: TBD | Pending | AI-generated conceptual atmosphere; not factual evidence | + +## Prompts + +### cover_virtual_cell_world.png + +- slide/use: P01 cover hero +- narrative job: make the audience feel the scale shift from wet lab cells to computable living systems +- native overlay plan: title on left third; all labels and logo native +- crop-safe region: preserve empty dark space on left; detailed object on right +- prompt: +- negative prompt: +- alt text: +- review notes: +``` + +Status values: + +- `Pending`: prompt planned; file not generated yet +- `Generated`: file exists in `/images/` +- `Generated-Derivative`: raw image exists and a cropped/resized derivative is used in slides +- `Info-Priority-Derivative`: raw image was darkened/desaturated/blended into a content-safe background derivative +- `Needs-Manual`: generation attempted once plus one retry and failed +- `Rejected`: generated file exists but failed quality/risk review and must not be used +- `Replaced-Native`: generation was dropped in favor of a native diagram or sourced asset + +## Deep Prompt Stack + +Each prompt should include these layers, in this order: + +1. **Use case and role**: presentation background, hero asset, section divider, conceptual illustration. +2. **Narrative job**: the feeling or argument the image must carry. +3. **Subject**: concrete visual objects, not vague nouns like "future" or "innovation". Prefer one recognizable object for anchor pages. +4. **Context/environment**: lab, computational space, cell interior, city, network, archive, boardroom, etc. +5. **Composition**: rule of thirds, central object, left negative space, top-safe title band, object scale. +6. **Camera or illustration treatment**: macro, aerial, isometric, editorial 3D, cinematic, scientific visualization, vector-like. +7. **Lighting and color grade**: exact palette from `spec_lock.md`, contrast, glow level, dark/light background. +8. **Material and detail**: glass, membrane, particles, grid, fiber, paper, metal, volumetric light, restrained texture. +9. **Output constraints**: aspect ratio, resolution, no text, no logo, no watermark, no fake UI. +10. **Negative prompt**: ban artifacts and anything that could be mistaken for evidence. + +Bad prompt: + +```text +futuristic virtual cell, neon style, high quality +``` + +Better prompt: + +```text +Presentation hero background, 16:9. A conceptual scientific visualization of a virtual cell as a computable living system: translucent cell membrane on the right third, layered organelle-like networks, faint simulation grid, orbital data paths, and small luminous particles suggesting molecular dynamics. Deep black background with controlled cyan, magenta, yellow, and neon-green accents matching a dark launch deck. Cinematic macro-scientific composition, sharp central subject, soft volumetric light, restrained glow, generous empty dark space on the left for native title text, no text inside the image, no logo, no watermark, no fake microscopy, no fake labels, no charts. +``` + +## Backend Selection + +Use the first available path that matches the user's request and can produce files in the project. Codex host `image_gen` is a valid production path; do not conclude that image generation is unavailable only because terminal environment variables or CLI backends are missing. + +1. If the user explicitly names a backend such as Imagen, Gemini, OpenAI, Qwen, or Seedream and `ppt-master/scripts/image_gen.py` is configured for it, use that file-based backend. +2. If the user explicitly asks for Image2-style, Codex built-in, or local image generation, use the host `image_gen` capability and then copy the selected result into `/images/`. +3. If no backend is specified and `ppt-master/scripts/image_gen.py` has a configured `IMAGE_BACKEND`, use it. +4. If the CLI backend is not configured but the host `image_gen` capability is available, use host `image_gen` instead of falling back to placeholders. +5. If no backend can run, still produce `asset_prompt_pack.md` and mark images `Needs-Manual`; continue with native diagrams or placeholders rather than blocking the whole deck. + +Useful local check: + +```bash +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/image_gen.py --list-backends +``` + +Generation command pattern: + +```bash +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/image_gen.py \ + "" \ + --negative_prompt "" \ + --aspect_ratio 16:9 \ + --image_size 1K \ + --output /images \ + --filename cover_virtual_cell_world +``` + +Generate one image at a time. Confirm the file exists before generating the next image. + +When using the host `image_gen`, preserve the original generated file and copy a project-local version into `/images/`. If the host stores images under `$CODEX_HOME/generated_images/...`, treat that location as provenance and the project copy as the deck asset. + +For non-cover pages, create a content-safe derivative before embedding. Crop/resize to 16:9, desaturate slightly, blend with black or the slide background, and save a clearly named derivative such as `p05_network_bg34.png` or `p07_core_info.png`. Prefer this baked raster derivative over relying on SVG `` for readability. + +## Embedding Rules + +- Save generated files in `/images/` using the filename from `asset_prompt_pack.md`. +- Reference from slide SVGs with ``. +- Keep native overlays separate: title, labels, logo, citations, charts, callouts, and legends remain editable. +- Put generated image layers below native panels, diagrams, center anchors, labels, and logos. +- For content pages, use the final information-priority derivative in the SVG, not the bright raw generation. +- Use crop geometry deliberately; do not stretch a generated image to hide poor composition. +- If the image needs text-like marks to look useful, the image is the wrong asset. +- If the image could fit any technology deck, the prompt is too generic. Add subject-specific objects, materials, environment, and narrative job. + +When many generated assets are used, create `image_asset_contact_sheet.png` before export. The contact sheet should show the final derivative that will be embedded, not only the raw generated image. + +## Review Gate + +Before final export, render the slide and check: + +- no fake text, marks, logos, seals, UI, or charts +- no visual claim that looks like factual microscopy, paper evidence, or real institution proof +- native text remains readable on top of the image +- for non-cover pages, title/key number/native diagram reads before the image at 25% zoom +- crop keeps the intended subject and negative space +- image style matches the deck's palette and does not fight the native diagram language +- the slide is stronger with the image than with a native diagram or source visual + +Record results in `qa_report.md`. diff --git a/references/image-first-deck-workflow.md b/references/image-first-deck-workflow.md new file mode 100644 index 0000000..48f5a9b --- /dev/null +++ b/references/image-first-deck-workflow.md @@ -0,0 +1,168 @@ +# Image-First Deck Workflow + +Use this reference when the user asks for a more beautiful, premium, cinematic, Image2-like, or generated-image-heavy PPT. + +The goal is not to turn the deck into an image gallery. The goal is to let generated images create visual memory while native PowerPoint objects carry the facts. + +## Core Rule + +Generated imagery creates mood, metaphor, scale, and subject-specific objects. + +Native PowerPoint carries: + +- titles and subtitles +- names, organizations, people, companies, labs, papers, and citations +- metrics, charts, labels, legends, and callouts +- process diagrams, evidence cards, and decision text +- logos and any factual marks + +If an image contains readable text, fake UI, fake labels, fake logos, or scientific-looking proof, reject it, crop it away, or cover it with native design structure. Do not ask the image model to render factual content. + +## When To Use Image-First + +Use it when: + +- the user says the deck lacks design feeling or is too diagram-heavy +- the deck needs cover/section pages with stronger memory +- the topic benefits from cinematic science, technology, industry, space, material, city, network, lab, or object metaphors +- the user explicitly mentions Image2, Imagen, Gemini, GPT Image, Codex image generation, local image generation, or deep visual prompts + +Do not use it blindly for dense evidence appendices, legal/procurement pages, or pages where exact screenshots and charts are the evidence. + +## Visual Intensity Ladder + +Choose an intensity per page before generating images. + +| Page Type | Image Role | Effective Image Presence | Notes | +|---|---|---:|---| +| Cover | hero scene or dominant object | 70-100% | Can be visually strong if title has clean negative space | +| Section anchor | atmosphere or object metaphor | 55-75% | Short claim, minimal secondary text | +| Thesis page | dominant object plus native proof chips | 45-65% | Keep factual chips on opaque or semi-opaque native panels | +| Standard content page | subdued background or side object | 34-44% | Text and numbers must read first | +| Dense evidence page | texture only or no image | 25-38% | Use real evidence, charts, or native structure instead | + +On every non-cover page, if the generated image is the first thing the eye reads at 25% zoom, the page fails. Create a darker, lower-visibility derivative or remove the image. + +## Prompt Recipe + +Write one prompt per slide asset. Avoid generic words like "future", "innovation", "technology background", and "high quality" unless the prompt also has a concrete object and scene. + +Required prompt components: + +1. Use case: presentation background, hero image, section divider, object illustration. +2. Narrative job: what the audience should feel or understand. +3. Concrete subject: one visual object or scene tied to the slide claim. +4. Environment: lab, cell interior, material lattice, power grid, mission control, star map, industrial route, city infrastructure, archive, etc. +5. Composition: title-safe band, card-safe zone, negative space, object position, crop intent. +6. Treatment: cinematic macro, premium editorial 3D, scientific visualization, isometric, aerial, material close-up. +7. Lighting and palette: match `spec_lock.md`; restrained glow; avoid noisy gradients. +8. Output constraints: 16:9, no text, no letters, no numbers, no logo, no watermark, no fake UI, no fake chart, no people/faces unless explicitly needed. +9. Native overlay plan: where titles, cards, metrics, and labels will sit. + +Prompt skeleton: + +```text +Presentation background, 16:9. [Narrative job]. A [concrete visual object] in [specific environment], [composition with title-safe/card-safe negative space], [camera or illustration treatment], [lighting and palette from the deck], [material and detail]. Premium editorial science/technology visualization. No text, letters, numbers, logo, watermark, fake UI, fake chart, fake labels, people, or faces. Designed for native PowerPoint title/cards overlaid outside the image. +``` + +## Built-In Image Generation Path + +Codex host image generation is a valid production path. Do not conclude that image generation is unavailable only because terminal environment variables or CLI backends are missing. + +Preferred order: + +1. If the user explicitly names a backend and `ppt-master/scripts/image_gen.py` is configured for it, use that file-based backend. +2. If the user asks for Image2/Codex/local image generation, or the CLI backend is not configured, use the host `image_gen` capability. +3. Copy the selected generated file from `$CODEX_HOME/generated_images/...` or the host-provided output location into `/images/`. +4. Keep the original generated file untouched; use project-local copies and derivatives for the deck. + +Generate sequentially. After each generation, confirm: + +- file exists +- image is 16:9 or can crop cleanly to 16:9 +- no text-like artifacts, logos, fake UI, charts, or factual-looking proof +- subject and negative space match the slide job + +## Information-Priority Derivatives + +For non-cover slides, bake readability into the raster asset instead of relying on SVG image opacity. Some converters and QA tools handle transparent image references inconsistently, and preprocessed assets are easier to review. + +Create a derivative per content slide: + +- crop/resize to 1280x720 or 1920x1080 +- desaturate slightly +- blend with black or the slide background +- optionally add a stronger dark safe zone behind the title or cards +- save as `_info.png` or `_bg34.png` + +Recommended effective presence: + +- cover: 70-100% +- section anchor: 55-75% +- standard content: 34-44% +- dense evidence: 25-38% + +The derivative should still feel designed, but it must read second after the title, numbers, and main native diagram. + +## Contact Sheet Gate + +Before embedding image assets across a deck, create `image_asset_contact_sheet.png` in the project folder or `images/` folder. + +The contact sheet should show: + +- filename +- slide id +- role +- final derivative used, not only the raw generated image + +Use the contact sheet to catch repeated motifs, over-bright backgrounds, generic wallpaper, and inconsistent palette before the PPTX export step. + +## Embedding And Layering + +Layer order: + +1. Background color or base shape +2. Generated image/background derivative +3. Native dark scrims or safe-zone panels +4. Native diagrams, cards, charts, and callouts +5. Native title, key numbers, labels, and citations +6. Logo and page marks + +For radial, center-anchor, loop, route-map, and network slides, connector lines must stay behind the center anchor and its text. The center text must be fully legible at thumbnail size. + +Do not use a generated image to compensate for weak slide logic. If the information layer is unclear without the image, fix the slide brief or diagram first. + +## QA Checks + +During montage review, run the background dominance check: + +- at 25% zoom, what do you see first? +- for P01, the hero image may be first or tied with the title +- for non-cover pages, the title, key number, or native object must read before the image +- if the image reads first, create a darker derivative, add a native safe zone, crop to reduce detail, or remove it + +Generated-image QA must also confirm: + +- no fake text, logos, UI, charts, seals, institution marks, or paper screenshots +- all factual content is native or sourced +- prompt provenance is recorded in `asset_prompt_pack.md` +- image role is specific to the slide, not generic technology wallpaper +- crop and safe zones match the overlay plan +- image improves the argument or emotional memory of the page + +## Required Artifact Updates + +When this workflow is used, update: + +- `asset_prompt_pack.md`: include raw asset, final derivative filename, backend/model, prompt, negative prompt, status, and native overlay plan +- `visual_evidence_plan.md`: mark generated assets as atmospheric, metaphorical, or object-led, not factual evidence +- `qa_report.md`: include contact sheet path, background dominance verdict, fake-text/logos/UI check, crop fit, and overlay readability + +Useful statuses: + +- `Pending`: prompt written; no file yet +- `Generated`: raw image exists in project images +- `Generated-Derivative`: derivative exists and is used +- `Info-Priority-Derivative`: derivative is darkened/desaturated for content readability +- `Rejected`: image failed QA and must not be embedded +- `Replaced-Native`: image concept was replaced with native/source visual diff --git a/references/layering-and-scale.md b/references/layering-and-scale.md new file mode 100644 index 0000000..fe45591 --- /dev/null +++ b/references/layering-and-scale.md @@ -0,0 +1,65 @@ +# Layering And Scale + +Use this before generating SVG pages that contain networks, loops, route maps, center nodes, system stacks, connector lines, or overlapping visual objects. + +Layering and scale are readability controls, not decoration. A page can pass XML validation and still fail if connector lines sit above the visual anchor, or if a center node is too transparent or too small to dominate the diagram. + +## Z-Order Contract + +Draw SVG elements in this order, back to front: + +1. Background fill. +2. Subtle grid, non-semantic texture, or atmosphere. +3. Source images or generated background images. +4. Connector lines, routes, arrows, and low-emphasis relationships. +5. Peripheral nodes, cards, labels, and secondary chips. +6. Dominant-object mask or backplate that interrupts connectors behind the anchor. +7. Center anchor shape and center anchor text. +8. Critical callouts, badges, page number, and logo. + +For SVG-to-PPTX conversion, later SVG elements normally become visually higher layers. Therefore center anchors and their text should be emitted after connector lines and peripheral nodes unless the slide intentionally needs another foreground object. + +## Center Anchor Pattern + +When a page has a central object such as `人才资产`, `崔屹系`, `Virtual Cell`, `平台`, or `Operating System`: + +- keep generated backgrounds, texture fields, and large atmospheric images below all connectors and nodes +- draw connector lines first +- draw an opaque or nearly opaque backplate over the connector crossing area +- draw the center circle/card on top of the backplate +- draw the center label last +- keep center text out of any line crossing path + +Do not rely on semi-transparent fill to protect readability. If connectors pass under the anchor, either: + +- use a solid or 0.96+ opacity center fill/backplate, or +- split connector lines so they stop at the anchor boundary, or +- place a black/panel-colored mask between connectors and center node. + +## Scale Contract + +Before drawing, define a scale role for every major object: + +| Role | Minimum Guidance | +|---|---| +| center anchor | visually 1.25-1.6x stronger than surrounding nodes; label >= 18px | +| peripheral node/card | secondary to anchor; label >= 12px, preferred >= 14px | +| connector line | visible but subordinate; opacity usually 0.45-0.75 | +| headline | dominant page read; not smaller than important node labels | +| footnote/source | small but not competing with diagram | + +Scale includes text, stroke, fill opacity, and occlusion area. A large circle with transparent fill may still read as too weak if lines bleed through it. + +## Network / Loop QA + +After rendering, inspect the slide at full size and in the montage: + +- center anchor text is not crossed by lines, arrows, node borders, or grid artifacts +- center anchor is visually on top of the relationship layer +- generated background detail does not sit visually above or behind the center label strongly enough to reduce readability +- connectors terminate cleanly or disappear behind a mask/backplate +- the center object still reads first at thumbnail size +- no secondary card is visually heavier than the anchor unless that is the intended story +- logo and page/footer sit above background but do not compete with the diagram + +If a slide fails this QA, fix by changing layer order, opacity, masks, line termination, or object scale. Do not fix by adding glow around the text; that usually hides the underlying structural problem. diff --git a/references/narrative-compiler.md b/references/narrative-compiler.md new file mode 100644 index 0000000..8df6d4d --- /dev/null +++ b/references/narrative-compiler.md @@ -0,0 +1,126 @@ +# Narrative Compiler + +Use this after needs alignment and source import, before `slide_brief_matrix.md`. + +The job is to convert a mature document into a decision-ready narrative spine. Do not start slide design until the deck has a clear thesis, claim sequence, evidence plan, and appendix split. + +## Required Artifact: `claim_evidence_implication.md` + +```markdown +# Claim Evidence Implication + +## Deck Thesis +- audience: +- decision_or_action: +- one_sentence_thesis: +- success_criterion: + +## Source Inventory +| source_section | useful_claims | evidence | uncertainty | main_or_appendix | +|---|---|---|---|---| + +## Narrative Spine +| chapter | claim | role_in_argument | must_prove | likely_pages | +|---|---|---|---|---| + +## Page Claim Plan +| page_id | page_role | claim | evidence | implication | confidence | source_trace | main_or_appendix | +|---|---|---|---|---|---|---|---| + +## Exclusions +| content | reason | destination | +|---|---|---| + +## Open Risks +| risk | affected_page | mitigation | +|---|---|---| +``` + +## Compile Steps + +1. **Inventory the source** + - Extract useful facts, arguments, examples, numbers, people, organizations, timelines, and unresolved questions. + - Mark evidence strength: primary/source, quantified, expert judgment, weak/inferred, unsupported. + +2. **Choose the deck thesis** + - Write one sentence that names the judgment the deck should make easier. + - If the user only wants background, make the thesis an orientation claim, not a recommendation. + +3. **Build the narrative spine** + - Use 3-6 chapter claims for serious decks. + - Each chapter must either diagnose, compare, explain, prove, recommend, or close a decision. + +4. **Split mainline and appendix** + - Mainline contains what the audience must understand to act. + - Appendix contains detail, source proof, long tables, technical depth, and optional backup. + +5. **Create page claims** + - Every page needs a claim, evidence, and implication. + - If a page cannot name its implication, merge it, cut it, or move it to appendix. + +## Claim Types + +| Type | Use When | Good Headline Shape | +|---|---|---| +| Diagnosis | explaining the problem | "The bottleneck is shifting from X to Y" | +| Insight | revealing a non-obvious pattern | "The same metric hides two different talent profiles" | +| Comparison | ranking or choosing | "Option A wins on speed, but B controls strategic risk" | +| Mechanism | explaining why something works | "Three feedback loops make the platform compound" | +| Opportunity | sizing or prioritizing | "The near-term wedge is small but strategically central" | +| Risk | surfacing uncertainty | "The largest risk is not technical readiness, but transferability" | +| Recommendation | telling the audience what to do | "Prioritize a small expert pod before broad market sourcing" | +| Decision | asking for action | "Approve the next-step outreach list and validation plan" | + +## Headline Rules + +Good PPT headlines are claims, not topics. + +Weak: + +- "Technology Roadmap" +- "Key Experts" +- "Market Analysis" + +Better: + +- "The roadmap is converging around three validation bottlenecks" +- "The expert pool is deep, but the industry-transfer subset is narrow" +- "Market scale is less decisive than deployment-cycle fit" + +For consulting, IC, board, and executive decks, every analytical page should have an assertion headline. For launch decks, the headline can be a short emotional claim, but it still needs a clear page job. + +## Evidence Rules + +Every claim needs at least one evidence mode: + +- source fact: document section, paper, screenshot, quote, chart, database, public source +- quantified proof: metric, ranking, benchmark, count, trend +- structural proof: mechanism, architecture, causal loop, process +- comparative proof: table, 2x2, waterfall, matrix, ranked options +- judgment proof: clearly labeled expert interpretation or assumption + +Never let generated imagery act as evidence. Generated imagery can make the claim memorable; evidence must be native, sourced, or explicitly reasoned. + +## Mainline Budget + +Use the audience and reading mode from `needs_alignment_brief.md`: + +- live senior presentation: 8-15 mainline pages, lower text density, more speaker notes +- leave-behind report: 15-35 pages, stronger captions and appendix +- IC/board: 10-20 mainline pages plus risk/source appendix +- launch/inspiration: 6-14 pages, strong pacing, few dense pages +- technical review: as many pages as needed, but keep mechanisms and evidence separated + +## Narrative QA + +Before slide design, fail the plan if: + +- the deck thesis is missing or generic +- page headlines are topic labels instead of claims +- a major claim has no evidence +- evidence pages do not say what the audience should conclude +- too much source detail sits in the mainline +- risks are hidden in a deck meant for investment, technical, or executive judgment +- the appendix split is undefined for a dense source document + +Fix the narrative before improving visuals. A beautiful deck with a weak claim spine is still weak. diff --git a/references/needs-alignment-and-style-archetypes.md b/references/needs-alignment-and-style-archetypes.md new file mode 100644 index 0000000..aac6806 --- /dev/null +++ b/references/needs-alignment-and-style-archetypes.md @@ -0,0 +1,137 @@ +# Needs Alignment And Style Archetypes + +Use this reference at the start of every serious PPT task, before slide design or SVG generation. + +The deck's design language should be selected from audience, purpose, decision context, and content risk. Do not start by choosing colors or decoration. + +## Alignment Gate + +Create `needs_alignment_brief.md` before `slide_brief_matrix.md`. + +If the user has not provided enough context, ask up to three concise questions before producing the deck, unless they explicitly ask to proceed immediately. Do not ask for information that can be inferred from the source document, file path, meeting title, or prior context. + +If the task is urgent or the user says "直接做", proceed with explicit assumptions in `needs_alignment_brief.md` and mention the assumptions in the final handoff. + +## Required Brief + +```markdown +# Needs Alignment Brief + +## Situation +- source_files: +- meeting/context: +- audience: +- audience_knowledge_level: +- presenter: +- decision_or_action_needed: +- time_budget: + +## Deck Job +- primary_goal: +- secondary_goal: +- what_success_looks_like: +- final_deliverable: +- expected_length: +- reading_mode: live presentation / leave-behind / both + +## Content Contract +- must_include: +- nice_to_have: +- must_not_include: +- sensitive_or_uncertain_content: +- required_evidence: +- expected_appendix: + +## Style Direction +- selected_archetype: +- reason_for_archetype: +- reference_sources_or_templates: +- density_level: +- visual_posture: +- chart_table_posture: +- image_generation_posture: +- tone_words: +- forbidden_style_moves: + +## Assumptions And Open Questions +- assumptions: +- blocking_questions: +- nonblocking_questions: +``` + +## Three-Question Intake + +When context is missing, prefer questions that resolve multiple choices: + +1. Audience and decision: "这份 PPT 主要给谁看？希望对方看完做出什么判断或动作？" +2. Content boundary: "哪些内容必须出现？哪些内容不希望出现或需要弱化？" +3. Style archetype: "更像咨询公司汇报、投委会/董事会材料、小米发布会、学术答辩、政府汇报，还是其他参考？" + +Ask fewer questions when the answer is already implied. For example, a fund internal talent report can usually infer `audience = investment/research leadership` and `goal = make sourcing/judgment/action easier`, but still may need style and exclusion boundaries. + +## Style Archetype Menu + +Use archetypes as design logic, not as copied templates. Learn their composition, hierarchy, table logic, chart density, and pacing. Do not claim the output is an official McKinsey/BCG/Xiaomi template unless the user provides such a template and usage rights. After selecting an archetype, load `style-archetype-playbooks.md` for production rules. + +| Archetype | Best For | Composition Logic | Visual Language | Avoid | +|---|---|---|---|---| +| McKinsey-style consulting | CEO/strategy/board problem solving | assertion headline, exhibit-first pages, clean charts, MECE sections, strong takeaway boxes | white or very restrained background, crisp grids, waterfall/bar/2x2, compact footnotes | cinematic decoration, vague icons, unsupported claims | +| BCG-style strategic narrative | market maps, portfolio choices, transformation | big strategic frame, opportunity maps, matrices, journey, bold section pages | slightly warmer/editorial, geometric blocks, strong charts and scenario pages | over-dense tables without implication | +| Bain/operator style | action plan, GTM, operations, sales | recommendation first, workstreams, owners, impact/effort, roadmap | pragmatic tables, dashboards, status colors, simple decision boards | overly abstract thesis pages | +| Xiaomi/launch style | product/technology launch, inspiring internal pitch | one claim per page, huge type, dramatic object, rhythm of breath/density | pure dark or stage-like background, strong contrast, hero visuals, minimal prose | tiny charts, many equal cards, long paragraphs | +| Investor/IC memo deck | investment committee, financing, fund decision | thesis, market, team, traction, risks, ask, evidence appendix | restrained premium, strong numbers, proof cards, risk boxes | hiding risks, overly promotional language | +| Government/official report | policy, public institution, formal leadership | formal hierarchy, context-policy-action, stable tables | red/blue or restrained official palette, sober typography, clear captions | edgy neon, speculative visuals | +| Academic/technical defense | experts, scientists, technical review | problem-method-result-contribution, diagrams, citations | clear mechanisms, source figures, equations/tables where needed | marketing language, fake science imagery | +| Design/brand pitch | brand, product, experience proposal | moodboard, principles, options, before/after, concept routes | large images, typographic polish, material/color systems | unexplained business logic | +| Internal operating review | weekly/monthly management, execution | KPI first, variance, root cause, decision/action | dashboard, traffic lights, trend charts, owner/action tables | decorative covers and weak action items | +| Talent/research map |人才挖掘, expert landscape, candidate strategy | landscape map, funnel, tiering, archetype comparison, next actions | network maps, evidence cards, source-backed ranking, restrained highlights | treating candidates as decorative portraits | + +## Matching Rules + +Choose by purpose: + +- If the deck must persuade a senior executive to choose a path, use consulting or strategic narrative. +- If the deck must trigger an investment or resource decision, use investor/IC. +- If the deck must excite or launch, use Xiaomi/launch. +- If the deck must withstand expert scrutiny, use academic/technical. +- If the deck must manage execution, use operating review. +- If the deck must source or compare people, use talent/research map. + +Choose by reading mode: + +- Live presentation: fewer words, larger claims, stronger pacing, more speaker notes. +- Leave-behind: more evidence, tables, captions, appendices, and source notes. +- Both: main deck stays presentation-readable; appendix carries detail. + +## Content Boundary Rules + +Define what not to include before writing pages: + +- uncertain claims without evidence +- sensitive people/company details +- unsupported rankings +- fake logos, fake screenshots, fake citations, or fake charts +- overly promotional language when the audience expects judgment +- technical details that belong in appendix +- decorative images that do not support the decision + +## Template Learning Rules + +When using mature templates or references: + +- extract page archetypes: cover, agenda, executive summary, exhibit, comparison, roadmap, appendix +- extract grid and margin system +- extract table density and chart grammar +- extract headline style and implication placement +- extract image posture: hero, proof screenshot, object, portrait, none +- extract pacing: dense pages vs breathing pages + +Do not copy: + +- proprietary slide masters, exact layouts, icons, watermarks, or brand marks without permission +- irrelevant decorative motifs +- template text placeholders + +The final deck should feel like it understands the reference's operating logic, not like a pasted template skin. + +After template learning, update `design_contract.md` with the selected archetype, page grammar, component families, chart/table posture, and forbidden moves. diff --git a/references/page-component-library.md b/references/page-component-library.md new file mode 100644 index 0000000..c91a127 --- /dev/null +++ b/references/page-component-library.md @@ -0,0 +1,248 @@ +# Page Component Library + +Use this while building `slide_brief_matrix.md` and generating SVG pages. The library gives reusable page patterns so decks feel designed as systems instead of one-off drawings. + +Record the chosen component in `slide_brief_matrix.md` under `visual_form`. + +## Component Selection Rules + +- Choose one primary component per page. +- Add secondary chips/callouts only when they support the primary component. +- Keep a deck to 5-7 component families unless the source genuinely requires more. +- Components must obey the selected style archetype and reading mode. + +## Components + +### Executive Summary Board + +Use when: opening a strategy, IC, board, or management deck. + +Structure: + +- assertion title +- 3-5 conclusion blocks +- proof line or metric per block +- decision/request strip + +Best for: consulting, IC, government, operating review. + +Avoid: long paragraphs, decorative icons without evidence. + +### Claim Hero + +Use when: one message needs to land emotionally or memorably. + +Structure: + +- huge claim +- one visual object or empty stage-like field +- optional single proof metric +- speaker notes carry detail + +Best for: launch, section anchor, thesis page. + +Avoid: tables, many equal cards, busy generated backgrounds. + +### Assertion + Exhibit + +Use when: an analytical page needs to prove one point. + +Structure: + +- assertion headline +- dominant exhibit: chart, matrix, table, map, or mechanism +- implication callout +- source note + +Best for: consulting, IC, technical, strategy. + +Avoid: title-only topic labels. + +### 2x2 / Axis Map + +Use when: two independent variables determine meaning. + +Structure: + +- x/y axes with clear labels +- plotted items or zones +- highlighted winning/priority zone +- implication caption + +Best for: option positioning, market landscape, talent segmentation. + +Avoid: more than 12 plotted items unless labels are simplified. + +### Roadmap / Stage Gate + +Use when: sequence, maturity, plan, or validation path matters. + +Structure: + +- 3-6 stages +- time or maturity axis +- milestone proof +- risk or decision gates + +Best for: operating plan, technical validation, investment next steps. + +Avoid: vague phases such as "Phase 1/2/3" without actions. + +### Timeline / Career Arc + +Use when: history, development, career, technology evolution, or sequencing matters. + +Structure: + +- chronological axis +- major events grouped by meaning +- inflection points highlighted +- takeaway on pattern + +Best for: talent research, technology background, company development. + +Avoid: equal-weight event lists. + +### Mechanism Diagram + +Use when: explaining why a system works. + +Structure: + +- inputs / mechanism / outputs +- arrows or feedback loops +- labels near components +- one implication callout + +Best for: science, technology, platform, operating model. + +Avoid: decorative flow arrows with no causal meaning. + +### System Stack + +Use when: architecture, layers, capabilities, or dependencies matter. + +Structure: + +- layered stack +- capability labels +- dependency arrows or interfaces +- bottleneck/risk marker + +Best for: platform, technology route, organization capability. + +Avoid: too many layers with tiny text. + +### Evidence Card Grid + +Use when: multiple proof objects support one claim. + +Structure: + +- 3-6 evidence cards +- each card has fact, source, and implication +- cards grouped by proof type + +Best for: IC proof, talent evidence, source-backed reports. + +Avoid: more than 6 cards in mainline. + +### Source Proof Card + +Use when: credibility requires showing a paper, quote, website, screenshot, or source record. + +Structure: + +- source title / screenshot crop +- short native caption +- why it matters +- citation in notes or footer + +Best for: technical, talent, IC, due diligence. + +Avoid: fake screenshots or generated paper-like imagery. + +### Benchmark Chart + +Use when: comparison across companies, candidates, technologies, or options matters. + +Structure: + +- sorted bar/column/scatter/table +- highlight one answer +- source note +- implication + +Best for: consulting, IC, operating review. + +Avoid: unsorted decorative charts. + +### Risk Matrix + +Use when: judgment requires downside visibility. + +Structure: + +- risk categories +- likelihood / impact / mitigation +- owner or next validation + +Best for: IC, technical diligence, executive decisions. + +Avoid: hiding severe risks in small footnotes. + +### Recommendation / Decision Board + +Use when: the deck needs a closing action. + +Structure: + +- recommended action +- why now +- expected upside +- risks / mitigations +- explicit ask + +Best for: all decision decks. + +Avoid: ending with a generic "thank you" page. + +### Talent Landscape Map + +Use when: people, labs, schools, companies, or expert communities must be organized. + +Structure: + +- segmentation axis or network +- tiers or clusters +- evidence chips +- sourcing/action implications + +Best for: talent research and expert mapping. + +Avoid: unsupported rankings or portrait collage aesthetics. + +### Image Object + Native Proof + +Use when: a generated/sourced object creates memory but facts still need proof. + +Structure: + +- large object/scene +- native proof chips or metric strip +- title-safe negative space +- image is atmospheric/metaphorical, not evidence + +Best for: image-first, launch, premium science/technology decks. + +Avoid: letting the image dominate content pages. + +## Component QA + +A component fails if: + +- it does not match the page claim +- the visual form is chosen for decoration rather than information structure +- the title, dominant object, and implication are all competing +- table/chart labels are too small at 25% zoom +- the component creates a new style not used elsewhere in the deck diff --git a/references/qa-rubric.md b/references/qa-rubric.md index 7e9b38a..0a0f4ba 100644 --- a/references/qa-rubric.md +++ b/references/qa-rubric.md @@ -8,13 +8,24 @@ Required checks: | Check | Pass Criteria | |---|---| +| `needs_alignment_brief.md` | exists for serious decks; audience, purpose/decision, content contract, style archetype, and assumptions are documented | +| `claim_evidence_implication.md` | exists; every mainline page has claim, evidence, implication, confidence, source trace, and main/appendix status | +| visual router / component plan | every slide brief has `visual_form`, `selected_component`, and `why_this_visual` tied to information structure | | `svg_quality_checker.py ` | 0 errors before finalize | | `svg_quality_checker.py /svg_final --format ppt169` | 0 errors after finalize | | `spec_lock drift` | none | +| `visual_evidence_plan.md` | exists; every page has an asset strategy and provenance | +| generated assets | if used, `asset_prompt_pack.md` exists; every generated file has prompt provenance, backend/model or host `image_gen` path, file existence status, and no fake text/logos/UI/factual proof | +| image-first contact sheet | if multiple generated images/backgrounds are used, `image_asset_contact_sheet.png` exists and shows the final embedded derivatives | +| background dominance | if generated backgrounds are used, P01 may be hero-led; every non-cover page has title/key number/native diagram reading before the background at 25% zoom | | PPTX export | succeeds | -| native check | media count low/zero; text runs present | +| native check | text runs present; media count is explainable by approved logos, source images, screenshots, or generated backgrounds; no image-only slide text | +| `deck_visual_lint.py ` | runs; ERROR findings are fixed; WARN findings are fixed or explicitly accepted in `qa_report.md` | | notes | one note file per SVG | | previews | PNG pages + montage rendered | +| layering/scale | network/loop/map slides have center anchors above connectors, no connector bleed through labels, and dominant objects scaled above secondary nodes | +| Canva/Figma artifacts | extraction/candidate links documented when used | +| agency micro-pipeline | if used, `agent_workflow_plan.md`, `claim_spine.md`, and final Reality Checker verdict documented | ## Human QA Dimensions @@ -22,23 +33,56 @@ Score 1-10: | Dimension | Questions | |---|---| +| needs alignment | Does the deck match the real audience, purpose, reading mode, and decision/action needed? | +| narrative spine | Does every mainline page have a clear claim, evidence, and implication? | | information architecture | Does each page have one job? Is the sequence logical? | +| narrative arc | Does the deck have beginning/middle/end, pacing, and a clear decision destination? | | visual-form matching | Is the chosen diagram/chart the right form for the information? | +| visual evidence strength | Does the dominant visual clarify, prove, or emotionalize the point rather than decorate it? | +| visual rhythm and memorability | Does the deck alternate logic diagrams with cinematic/object-led anchor pages where appropriate? | +| asset quality/provenance | Are sourced/generated/Canva/Figma-inspired assets high quality, relevant, and credited? | +| generated image control | If AI images are used, do they have strong composition, native overlay safety, no fake evidence, and a clear narrative job? | +| image-first information hierarchy | On non-cover pages, does the information layer read before the generated background? | | aesthetic consistency | Does every page obey the style contract? | +| style archetype fit | Does the deck use the selected archetype's composition/table/chart logic rather than a generic template skin? | +| component fit | Does each page use a visual component that matches the information structure? | +| brand consistency | Are logo, palette, typography, voice, and do-not-use rules respected? | | layout readability | Are title, labels, and visual objects readable at thumbnail size? | +| layer/scale discipline | Are foreground anchors, labels, and masks on top of connectors/backgrounds? Does scale reinforce the intended hierarchy? | | launch quality | Does the page have a memorable dominant read? | | editability | Are text, labels, and major shapes editable? | ## Release Threshold - MVP acceptable: no automated QA failures; average human QA >= 8 -- Production acceptable: no automated QA failures; no page below 8 in layout readability; visual-form matching >= 8.5 +- Production acceptable: no automated QA failures; no page below 8 in layout readability; visual-form matching >= 8.5; visual evidence strength >= 8.5; Reality Checker verdict is `READY` or residual risks are explicitly accepted ## Common Failure Modes - The slide is a paragraph with decoration. +- The deck starts designing before audience, purpose, decision/action, and content exclusions are clear. +- The deck summarizes source sections instead of compiling claim/evidence/implication. +- Page headlines are topic labels instead of assertions. +- Evidence exists but the implication is missing. +- A mature template style is copied as surface decoration rather than translated into composition, chart/table logic, and pacing. +- The selected style archetype mismatches the context, e.g. launch-style drama for a technical due diligence deck or consulting density for a live product reveal. +- The deck is a sequence of rigid logic diagrams with no cinematic anchor, object metaphor, or visual breathing page. +- Generated images are used as generic background wallpaper rather than subject-specific visual objects. +- Generated backgrounds are too bright or detailed, so the audience reads the image before the slide's title, number, or native diagram. - The visual form does not match the information structure. +- The selected page component is generic or repetitive; the deck becomes a sequence of similar cards. - Neon/gradient accents become decorative noise instead of information hierarchy. - Dense labels ruin launch-style readability. +- Connector lines, arrows, or grids sit above the center node or cross the center text. +- A semi-transparent center node lets relationship lines bleed through the label area. +- Scale is applied only to shapes, not to the full visual group including text, stroke, mask, and occlusion area. - Reference PPT style is copied superficially instead of translated into constraints. - Final PPT is an image deck rather than native editable shapes. +- The page uses attractive but generic imagery that does not improve trust or comprehension. +- Generated images contain text-like marks, fake UI, fake logos, invented labels, or scientific-looking "evidence". +- Generated images were embedded without prompt provenance or review status. +- Generated image opacity is handled only in SVG instead of using a reviewed, content-safe raster derivative for information-heavy pages. +- Canva/Figma output is pasted into PowerPoint instead of being rebuilt as native editable structure. +- The visual evidence plan is skipped, so pages default to cards, glow, and icons. +- Fantasy approval: `qa_report.md` says "excellent" or "ready" without rendered evidence and specific issue review. +- No handoff continuity: narrative, brand, design system, assets, and QA each make independent decisions that do not reconcile. diff --git a/references/rapid-sample-mode.md b/references/rapid-sample-mode.md new file mode 100644 index 0000000..18746a7 --- /dev/null +++ b/references/rapid-sample-mode.md @@ -0,0 +1,103 @@ +# Rapid Sample Mode + +Use this when the user asks for a quick 1-3 page PPT sample, style test, direction preview, or "先做几页看看效果". + +The goal is speed with enough process discipline to test the workflow. Do not run the full production ceremony, but do not skip narrative judgment. + +## When To Use + +Use rapid sample mode when: + +- the user asks for 1-3 pages +- the user wants to evaluate style or workflow quality +- the source document is mature but the output is explicitly a preview +- time matters more than exhaustive coverage + +Do not use it for final board decks, client deliverables, regulatory/official decks, or high-stakes decision materials unless the user explicitly asks for a quick concept first. + +## Minimum Artifacts + +Create lightweight versions of: + +- `needs_alignment_brief.md` +- `claim_evidence_implication.md` +- `slide_brief_matrix.md` +- `visual_evidence_plan.md` +- `design_contract.md` +- `qa_report.md` + +Skip or defer: + +- large agency workflow artifacts +- full appendix planning +- generated image contact sheet, unless generated images are used +- multiple style directions, unless the user asks + +## Page Count Guidance + +For 1 page: + +- show the core thesis and 2-4 proof anchors. +- use `Claim Hero + Native Proof` or `Assertion + Exhibit`. + +For 2 pages: + +- P01: thesis / reframing +- P02: market / mechanism / route, depending on source + +For 3 pages: + +- P01: thesis / reframing +- P02: market, mechanism, or evidence structure +- P03: route, risk, decision, or next-step plan + +## Default Archetype + +If the user says "industry report", "research note", or "信息量要足", default to: + +- style: industry research / investor judgment +- reading mode: quick leave-behind +- density: medium-high +- visual posture: native exhibits, comparison cards, roadmap/risk board +- image posture: no generated image unless visual concept is central + +## Rapid Workflow + +1. Infer needs from the user request and source path; ask only if the missing answer would change the sample. +2. Read the document's executive summary, main section headings, conclusion, data tables, product route, and risks. +3. Write a compact `claim_evidence_implication.md`. +4. Route pages through `visual-form-router.md` and choose components from `page-component-library.md`. +5. Build 1-3 SVG pages. +6. Run: + +```bash +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/svg_quality_checker.py +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/finalize_svg.py +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/svg_quality_checker.py /svg_final --format ppt169 +python3 ${PPT_MASTER_HOME:-$HOME/tools/ppt-master}/skills/ppt-master/scripts/svg_to_pptx.py -s final +python3 /scripts/deck_visual_lint.py +python3 /scripts/check_pptx_native.py +``` + +7. Render a preview montage and inspect it before delivery. + +## Quality Bar + +Rapid samples can be incomplete, but they should still show: + +- one clear thesis +- one visual form per page +- enough information density to test the target use case +- editable native text and shapes +- no obvious text overlap or unreadable labels +- no private source material embedded in open-source examples + +## Handoff Language + +When delivering, state that this is a direction preview, not the final production deck. Mention: + +- selected positioning +- pages generated +- preview montage +- QA results +- what should improve in a full version diff --git a/references/slide-brief-matrix.md b/references/slide-brief-matrix.md index cf75ee8..b1757c6 100644 --- a/references/slide-brief-matrix.md +++ b/references/slide-brief-matrix.md @@ -9,16 +9,25 @@ Create this before any SVG page generation. | page_id | `P01`, `P02`, etc. | | page_type | cover / problem / model / analysis / evidence / strategy / transition / conclusion / appendix | | page_job | The one task this page performs | +| target_read | live claim / leave-behind proof / appendix detail | +| source_claim | Page claim from `claim_evidence_implication.md` | | core_message | The one sentence viewers must remember | | information_load | light / medium / dense | | source_content | Source paragraphs, section names, or data used | | visual_form | e.g. big statement, axis map, ladder, matrix, curve, flywheel, timeline, comparison table | +| selected_component | Primary component from `page-component-library.md` | | why_this_visual | Why the visual form matches the information structure | +| visual_evidence_asset | Actual image/chart/diagram/source screenshot/generated asset, or `none intentionally` | +| asset_source_usage | Local file, public URL, generated asset, Canva/Figma reference, or original native drawing; include credit/usage notes when relevant | | editable_elements | Text, shapes, labels, chart marks, lines, groups | | speaker_note_intent | What the presenter should say | ## Visual Form Selection +Select visual forms based on `needs_alignment_brief.md` and `claim_evidence_implication.md`, not only on content structure. A senior executive deck usually needs implication-first exhibits; a launch deck needs claim-first breathing pages; a technical review needs mechanisms and evidence; an operating review needs KPI/action tables. + +Use `visual-form-router.md` before choosing the visual form, then use `page-component-library.md` before drawing the slide. + | Information Structure | Preferred Visual | |---|---| | one strong claim | giant type / launch statement | @@ -31,6 +40,33 @@ Create this before any SVG page generation. | decision threshold | threshold ladder / stage gate | | feedback loop | flywheel / cycle | +## Archetype Influence + +| Archetype | Slide Matrix Bias | +|---|---| +| McKinsey-style consulting | assertion headlines, exhibit-first analysis, clear implication, restrained appendix | +| BCG-style strategic narrative | market/opportunity maps, portfolio matrices, transformation journeys | +| Xiaomi/launch | one claim per page, large type, hero visuals, low prose density | +| Investor/IC | thesis, proof, risk, ask, downside, decision page, appendix evidence | +| Government/official report | formal hierarchy, policy/context/action, conservative charts and tables | +| Academic/technical | problem-method-result, mechanisms, citations, technical appendix | +| Operating review | KPI, variance, root cause, owner/action, roadmap | +| Talent/research map | landscape, ranking/tiering, evidence cards, network/funnel, next actions | + +## Visual Evidence Selection + +The matrix is not complete until each page has a dominant visual strategy. Choose one: + +- representational evidence: actual person, institution, product, paper, dataset, microscope/cell image, interface screenshot +- organizational evidence: timeline, stack, map, matrix, architecture, ecosystem, route diagram +- explanatory evidence: mechanism, process, causal loop, model comparison, annotated transformation +- data evidence: chart, metric strip, benchmark, citation/funding/publication count, table +- source/proof evidence: paper card, quote chip, citation panel, website/document screenshot +- controlled atmosphere: generated or sourced hero/section background; use sparingly and keep factual content native +- none intentionally: only when the native diagram/table itself is the evidence + +Avoid using a decorative stock image as the visual plan. If the image does not increase trust, comprehension, or emotional focus, replace it with a diagram, data object, or source proof. + ## Density Budget - light: one claim + one visual object; usually no more than 8 text runs @@ -45,11 +81,16 @@ If a page exceeds its density budget, split it or move detail into notes. page_id: P07 page_type: analysis page_job: Explain why L and C must be assessed together +target_read: leave-behind proof +source_claim: "High complexity changes the meaning of the same decision level" core_message: High complexity changes the meaning of the same decision level information_load: medium source_content: "C 产品复杂度" section, paragraphs 45-71 visual_form: 2-axis map +selected_component: 2x2 / Axis Map why_this_visual: L and C are independent variables; combinations matter +visual_evidence_asset: native 2-axis map with three benchmark candidate points +asset_source_usage: original native drawing; source paragraphs cited in speaker notes editable_elements: title, axes, tick labels, point labels, curve, takeaway speaker_note_intent: Explain that a C6-L4.5 person may beat a C1-L5 person ``` diff --git a/references/style-archetype-playbooks.md b/references/style-archetype-playbooks.md new file mode 100644 index 0000000..ac3f9d1 --- /dev/null +++ b/references/style-archetype-playbooks.md @@ -0,0 +1,296 @@ +# Style Archetype Playbooks + +Use this after `needs_alignment_brief.md` selects a style archetype. These are production rules for composition, charts, tables, density, and image posture. + +Use archetypes as operating logic. Do not claim the deck is an official template from any firm or brand unless the user provides licensed source material. + +## How To Apply + +For the selected archetype, record in `design_contract.md`: + +- page grammar +- allowed components +- chart/table posture +- headline style +- density and appendix policy +- image posture +- forbidden moves + +## McKinsey-Style Consulting + +Best for: senior strategy, board problem solving, market entry, transformation, diagnosis. + +Page grammar: + +- assertion headline at top +- exhibit owns the page: chart, matrix, table, waterfall, bridge, benchmark +- implication box or takeaway strip near the exhibit +- source note small but present +- section pages are sober and short + +Common components: + +- executive summary with 3-5 conclusions +- issue tree / MECE logic tree +- 2x2 matrix +- waterfall / bridge chart +- benchmark bar chart +- market map +- option comparison table +- recommendation roadmap + +Chart/table posture: + +- charts need explicit takeaway, not just data +- tables are compact and sorted by implication +- use restrained color to mark the answer, not to decorate + +Avoid: + +- cinematic backgrounds on analytical pages +- generic icons as proof +- unsupported claims +- long paragraphs without exhibit logic + +## BCG-Style Strategic Narrative + +Best for: strategic choices, market landscapes, portfolio analysis, transformation journeys. + +Page grammar: + +- bold strategic frame +- opportunity/portfolio map or journey visual +- scenarios and choices made visible +- slightly more editorial section pacing than pure consulting + +Common components: + +- strategic narrative arc +- portfolio matrix +- opportunity pool +- transformation roadmap +- capability maturity model +- future-back scenario page +- ecosystem map + +Chart/table posture: + +- matrices and maps are central +- tables should end with strategic implication +- charts often compare scenarios or capability positions + +Avoid: + +- operational detail without strategic frame +- over-dense appendix logic in mainline +- decorative strategy words with no evidence + +## Bain / Operator Style + +Best for: execution, growth plan, GTM, operations, integration, performance improvement. + +Page grammar: + +- recommendation first +- clear owner/action/timing/impact +- dashboard or operating model +- next-step clarity + +Common components: + +- KPI dashboard +- workstream plan +- impact/effort matrix +- initiative roadmap +- risk/action register +- customer or funnel diagnostic +- operating cadence page + +Chart/table posture: + +- tables are action-oriented +- metrics are tied to owners and next decisions +- use traffic-light status only when status is meaningful + +Avoid: + +- abstract conceptual pages without action +- huge hero visuals +- claims that do not imply a next step + +## Xiaomi / Launch Style + +Best for: product, technology, vision, internal rally, public-facing inspiration. + +Page grammar: + +- one claim per page +- huge type, strong contrast +- one dominant object or generated/sourced hero visual +- very low prose density +- rhythm alternates breath pages and proof pages + +Common components: + +- hero claim +- product/object reveal +- single metric impact page +- before/after +- feature stack +- moment-of-truth comparison +- closing vision page + +Chart/table posture: + +- charts are simplified and dramatic +- tables should be avoided in mainline unless visually reduced +- detailed proof belongs in appendix + +Avoid: + +- many equal cards +- tiny labels +- consulting-style dense exhibits +- AI images overpowering the claim + +## Investor / IC Memo Deck + +Best for: investment committee, fund decision, financing, deal review, resource allocation. + +Page grammar: + +- thesis first +- proof and risk are both visible +- each page helps decide invest / pass / investigate further +- appendix stores source detail + +Common components: + +- investment thesis page +- market / timing page +- team or talent quality page +- traction/proof page +- valuation or economics page +- risk matrix +- diligence plan +- decision request + +Chart/table posture: + +- numbers must be sourced or clearly assumed +- risk tables are not cosmetic; include mitigation +- scenarios are more useful than single-point certainty + +Avoid: + +- hiding downside +- generated images that look like evidence +- overly promotional language + +## Government / Official Report + +Best for: public institution, policy, formal leadership update, official briefing. + +Page grammar: + +- context -> issue -> action -> expected effect +- formal hierarchy +- stable tables and clear captions +- conservative visual rhythm + +Common components: + +- policy context page +- status dashboard +- regional / sector comparison +- implementation roadmap +- responsibility matrix +- risk control page + +Chart/table posture: + +- tables can be denser but must remain legible +- captions should state official interpretation +- color use should be restrained and consistent + +Avoid: + +- edgy neon or theatrical effects +- speculative visuals +- informal wording + +## Academic / Technical Defense + +Best for: expert review, scientific explanation, technical due diligence, research defense. + +Page grammar: + +- problem -> method -> mechanism -> evidence -> contribution +- source-backed claims +- diagrams and citations are primary +- appendix can be deep + +Common components: + +- research question page +- mechanism diagram +- method comparison +- experimental/result table +- literature map +- technical risk page +- contribution summary + +Chart/table posture: + +- exactness matters +- figures need captions and source traces +- dense pages are acceptable if they serve expert scrutiny + +Avoid: + +- marketing claims +- fake science images +- unsourced generated visuals as proof + +## Talent / Research Map + +Best for: talent sourcing, expert mapping, candidate strategy, org/research landscape. + +Page grammar: + +- landscape first +- rank/tier with evidence +- compare archetypes and transferability +- end with sourcing action + +Common components: + +- talent landscape map +- candidate funnel +- tiering matrix +- evidence card +- network/origin map +- transferability risk table +- outreach priority board + +Chart/table posture: + +- rankings need evidence and uncertainty +- tables should separate fact, inference, and action +- source cards build trust + +Avoid: + +- treating people as decorative portraits +- unsupported rankings +- confusing research strength with fit + +## Mixed Archetypes + +Many good decks combine archetypes: + +- IC + technical: thesis/risk structure with technical mechanism pages +- consulting + launch: executive logic with a few cinematic anchor pages +- talent map + operator: landscape plus action plan + +When mixing, choose one dominant archetype and name the secondary style. Do not let every page use a different grammar. diff --git a/references/visual-form-router.md b/references/visual-form-router.md new file mode 100644 index 0000000..47a4411 --- /dev/null +++ b/references/visual-form-router.md @@ -0,0 +1,73 @@ +# Visual Form Router + +Use this while converting `claim_evidence_implication.md` into `slide_brief_matrix.md`. + +The router maps information structure to visual form. It prevents defaulting to generic cards, funnels, or decorative diagrams. + +## Routing Table + +| Information Structure | Primary Question | Preferred Visual Forms | Evidence Mode | +|---|---|---|---| +| one strong claim | What must land? | claim hero, single metric, object + proof | proof metric, source note, speaker notes | +| list of conclusions | What are the few takeaways? | executive summary board, conclusion cards | source line per conclusion | +| two variables | What position or tradeoff matters? | 2x2, axis map, scatter | plotted evidence, labels | +| many comparable items | Which is better/worse? | ranked table, benchmark chart, heatmap | metrics, source notes | +| change over time | What changed and when? | timeline, curve, roadmap | dated facts, milestones | +| process or plan | What happens next? | roadmap, stage gate, swimlane | actions, owners, gates | +| mechanism or causality | Why does it work? | mechanism diagram, loop, system stack | causal labels, inputs/outputs | +| ecosystem or network | Who connects to whom? | network map, orbit map, landscape map | source-backed nodes | +| hierarchy | What sits above/below? | pyramid, stack, tree, capability ladder | classification evidence | +| portfolio choice | Where should we focus? | portfolio matrix, opportunity map | attractiveness/fit metrics | +| risk and uncertainty | What could go wrong? | risk matrix, sensitivity table, scenario page | likelihood/impact/mitigation | +| source proof | Why should we trust it? | source proof card, citation panel, screenshot crop | primary source | +| talent comparison | Who fits and why? | talent landscape map, tiering matrix, evidence cards | fact/inference/action split | +| technical detail | How exactly? | mechanism, architecture, annotated figure, appendix table | citations and exact labels | + +## Routing Process + +For each planned page: + +1. Read the page claim from `claim_evidence_implication.md`. +2. Identify the information structure, not the topic. +3. Pick one primary visual form. +4. Pick one evidence mode. +5. Choose a component from `page-component-library.md`. +6. Write `why_this_visual` in the slide brief. + +## Bad Routing Patterns + +Avoid these: + +- using three cards because the source has three paragraphs +- using a radial map because it looks impressive but the data is not relational +- using a funnel when the story is actually a maturity ladder +- using a generated background when the page needs source proof +- using a dense table in a live launch page +- using a hero claim page for a decision that needs risk visibility + +## Density Routing + +Use reading mode from `needs_alignment_brief.md`: + +- live: claim hero, assertion + exhibit, simple axis map, simplified roadmap +- leave-behind: assertion + exhibit, tables, source cards, appendix pages +- both: mainline uses simplified components; appendix carries tables and sources + +## Visual Rhythm Routing + +For decks longer than 8 pages, plan rhythm: + +- avoid 3+ dense pages in a row unless the deck is a technical appendix +- insert section/anchor page after major narrative shifts +- use object-first or cinematic pages only when they support the argument +- mix charts/tables with diagrams and source proof; do not make every page a card grid + +## Router QA + +Fail the matrix if: + +- more than 40% of mainline pages use the same component without a narrative reason +- more than 30% of pages are generic card grids +- a page's `why_this_visual` says only "clear" or "nice-looking" +- a visual form does not match the information structure +- evidence-heavy claims are routed to atmospheric image pages diff --git a/scripts/deck_visual_lint.py b/scripts/deck_visual_lint.py new file mode 100755 index 0000000..2641951 --- /dev/null +++ b/scripts/deck_visual_lint.py @@ -0,0 +1,343 @@ +#!/usr/bin/env python3 +"""Best-effort visual lint for future-ppt SVG decks. + +This script intentionally uses lightweight heuristics. It should surface +layout and rhythm risks for human review, not replace rendered QA. +""" + +from __future__ import annotations + +import argparse +import json +import math +import re +import statistics +import sys +import xml.etree.ElementTree as ET +from dataclasses import asdict, dataclass +from pathlib import Path +from typing import Iterable + +try: + from PIL import Image, ImageFilter, ImageStat +except Exception: # pragma: no cover - optional dependency + Image = None + ImageFilter = None + ImageStat = None + + +SVG_NS = "{http://www.w3.org/2000/svg}" + + +@dataclass +class Finding: + level: str + page: str + code: str + message: str + + +@dataclass +class PageStats: + page: str + text_count: int + image_count: int + rect_count: int + path_count: int + min_font: float | None + max_font: float | None + text_chars: int + possible_overlaps: int + avg_luma: float | None = None + contrast: float | None = None + edge_detail: float | None = None + + +def local_name(tag: str) -> str: + if "}" in tag: + return tag.rsplit("}", 1)[1] + return tag + + +def parse_float(value: str | None) -> float | None: + if not value: + return None + match = re.search(r"-?\d+(?:\.\d+)?", value) + return float(match.group(0)) if match else None + + +def inherited_font_size(elem: ET.Element) -> float | None: + value = elem.get("font-size") or elem.attrib.get("style", "") + if "font-size" in value and ";" in value: + match = re.search(r"font-size\s*:\s*([0-9.]+)", value) + return float(match.group(1)) if match else None + return parse_float(elem.get("font-size")) + + +def text_content(elem: ET.Element) -> str: + return "".join(elem.itertext()).strip() + + +def iter_svg_files(project: Path, svg_dir: Path | None) -> list[Path]: + candidates: list[Path] = [] + if svg_dir: + candidates.append(svg_dir) + candidates.extend([project / "svg_final", project / "svg_output"]) + for candidate in candidates: + if candidate.exists(): + files = sorted(candidate.glob("*.svg")) + if files: + return files + return sorted(project.rglob("*.svg")) + + +def infer_preview_dirs(project: Path, preview_dir: Path | None) -> list[Path]: + dirs: list[Path] = [] + if preview_dir: + dirs.append(preview_dir) + for name in ( + "png_final", + "png_output", + "previews", + "preview", + "rendered", + "exports", + "qa", + ): + dirs.append(project / name) + return [d for d in dirs if d.exists()] + + +def find_preview(svg: Path, preview_dirs: list[Path]) -> Path | None: + stems = {svg.stem, svg.stem.replace("slide_", ""), svg.stem.replace("page_", "")} + pngs: list[Path] = [] + for directory in preview_dirs: + pngs.extend(directory.glob("*.png")) + for png in pngs: + if png.stem in stems: + return png + page_num = re.search(r"(\d+)", svg.stem) + if page_num: + number = page_num.group(1).lstrip("0") or "0" + for png in pngs: + png_num = re.search(r"(\d+)", png.stem) + if png_num and (png_num.group(1).lstrip("0") or "0") == number: + return png + return None + + +def preview_stats(path: Path) -> tuple[float, float, float] | tuple[None, None, None]: + if Image is None or ImageStat is None or ImageFilter is None: + return None, None, None + try: + image = Image.open(path).convert("L").resize((320, 180)) + stat = ImageStat.Stat(image) + avg_luma = float(stat.mean[0]) + contrast = float(stat.stddev[0]) + edges = image.filter(ImageFilter.FIND_EDGES) + edge_detail = float(ImageStat.Stat(edges).mean[0]) + return avg_luma, contrast, edge_detail + except Exception: + return None, None, None + + +def approx_text_boxes(text_elems: Iterable[ET.Element]) -> list[tuple[float, float, float, float, str]]: + boxes: list[tuple[float, float, float, float, str]] = [] + for elem in text_elems: + text = text_content(elem) + if not text: + continue + x = parse_float(elem.get("x")) + y = parse_float(elem.get("y")) + font = inherited_font_size(elem) or 18.0 + if x is None or y is None: + continue + width = max(8.0, len(text) * font * 0.55) + height = font * 1.25 + boxes.append((x, y - height, x + width, y + height * 0.25, text[:32])) + return boxes + + +def count_overlaps(boxes: list[tuple[float, float, float, float, str]]) -> int: + overlaps = 0 + for i, a in enumerate(boxes): + ax1, ay1, ax2, ay2, _ = a + area_a = max(0.0, ax2 - ax1) * max(0.0, ay2 - ay1) + if area_a <= 0: + continue + for b in boxes[i + 1:]: + bx1, by1, bx2, by2, _ = b + ix1, iy1 = max(ax1, bx1), max(ay1, by1) + ix2, iy2 = min(ax2, bx2), min(ay2, by2) + inter = max(0.0, ix2 - ix1) * max(0.0, iy2 - iy1) + if inter and inter / area_a > 0.18: + overlaps += 1 + return overlaps + + +def lint_svg(svg: Path, preview_dirs: list[Path]) -> tuple[PageStats, list[Finding]]: + findings: list[Finding] = [] + page = svg.stem + try: + root = ET.parse(svg).getroot() + except ET.ParseError as exc: + stats = PageStats(page, 0, 0, 0, 0, None, None, 0, 0) + return stats, [Finding("ERROR", page, "svg_parse", f"cannot parse SVG: {exc}")] + + elems = list(root.iter()) + text_elems = [e for e in elems if local_name(e.tag) == "text"] + image_count = sum(1 for e in elems if local_name(e.tag) == "image") + rect_count = sum(1 for e in elems if local_name(e.tag) == "rect") + path_count = sum(1 for e in elems if local_name(e.tag) == "path") + texts = [text_content(e) for e in text_elems if text_content(e)] + fonts = [inherited_font_size(e) for e in text_elems] + fonts = [f for f in fonts if f is not None] + boxes = approx_text_boxes(text_elems) + overlaps = count_overlaps(boxes) + + preview = find_preview(svg, preview_dirs) + avg_luma, contrast, edge_detail = preview_stats(preview) if preview else (None, None, None) + + stats = PageStats( + page=page, + text_count=len(texts), + image_count=image_count, + rect_count=rect_count, + path_count=path_count, + min_font=min(fonts) if fonts else None, + max_font=max(fonts) if fonts else None, + text_chars=sum(len(t) for t in texts), + possible_overlaps=overlaps, + avg_luma=avg_luma, + contrast=contrast, + edge_detail=edge_detail, + ) + + if len(texts) == 0: + findings.append(Finding("ERROR", page, "no_text", "no SVG text elements found; final slide may be image-only")) + elif image_count and len(texts) < 2: + findings.append(Finding("WARN", page, "image_low_text", "image present with very little text; verify native title/labels exist")) + + if stats.max_font is not None and stats.max_font < 24: + findings.append(Finding("WARN", page, "small_title", f"largest font is {stats.max_font:.1f}px; title may be too small")) + if stats.min_font is not None and stats.min_font < 10: + findings.append(Finding("WARN", page, "tiny_text", f"smallest font is {stats.min_font:.1f}px; likely unreadable in PPT")) + if stats.text_chars > 900: + findings.append(Finding("WARN", page, "text_heavy", f"{stats.text_chars} text characters; consider appendix or split page")) + if overlaps: + findings.append(Finding("WARN", page, "possible_overlap", f"{overlaps} approximate text overlaps detected")) + + for x1, y1, x2, y2, sample in boxes: + if x1 < -5 or y1 < -5 or x2 > 1300 or y2 > 740: + findings.append(Finding("WARN", page, "text_outside_canvas", f"text may exceed canvas: {sample!r}")) + break + + fragile = [] + for elem in elems: + name = local_name(elem.tag) + if name in {"foreignObject", "style", "script", "animate", "animateTransform"}: + fragile.append(name) + if name == "g" and elem.get("opacity") is not None: + fragile.append("g opacity") + if fragile: + findings.append(Finding("WARN", page, "fragile_svg", "fragile SVG features: " + ", ".join(sorted(set(fragile))))) + + if avg_luma is not None: + if image_count and avg_luma > 92 and contrast > 54: + findings.append(Finding("WARN", page, "bright_busy_preview", f"preview may be bright/busy: luma={avg_luma:.1f}, contrast={contrast:.1f}")) + if image_count and edge_detail is not None and edge_detail > 26: + findings.append(Finding("WARN", page, "busy_background", f"preview has high edge/detail intensity: {edge_detail:.1f}")) + + return stats, findings + + +def deck_level_findings(stats: list[PageStats]) -> list[Finding]: + if not stats: + return [Finding("ERROR", "deck", "no_svg", "no SVG files found")] + findings: list[Finding] = [] + total = len(stats) + image_heavy = sum(1 for s in stats if s.image_count > 0 and s.text_count < 5) + card_heavy = sum(1 for s in stats if s.rect_count >= 8 and s.image_count == 0) + text_heavy = sum(1 for s in stats if s.text_chars > 900) + if image_heavy / total > 0.45: + findings.append(Finding("WARN", "deck", "too_image_heavy", f"{image_heavy}/{total} pages are image-heavy; verify native information layer")) + if card_heavy / total > 0.5: + findings.append(Finding("WARN", "deck", "repeated_card_grid", f"{card_heavy}/{total} pages look card-heavy; check visual rhythm")) + if text_heavy / total > 0.35: + findings.append(Finding("WARN", "deck", "too_text_heavy", f"{text_heavy}/{total} pages exceed text density threshold")) + font_maxes = [s.max_font for s in stats if s.max_font is not None] + if font_maxes and statistics.median(font_maxes) < 30: + findings.append(Finding("WARN", "deck", "low_type_hierarchy", f"median max font is {statistics.median(font_maxes):.1f}px")) + return findings + + +def print_report(project: Path, stats: list[PageStats], findings: list[Finding]) -> None: + errors = [f for f in findings if f.level == "ERROR"] + warns = [f for f in findings if f.level == "WARN"] + print(f"# Deck Visual Lint\n") + print(f"project: {project}") + print(f"pages_checked: {len(stats)}") + print(f"errors: {len(errors)}") + print(f"warnings: {len(warns)}\n") + print("| page | text | images | rects | paths | min_font | max_font | chars | overlaps | luma | contrast | edge |") + print("|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|") + for s in stats: + def fmt(value: float | int | None) -> str: + if value is None: + return "" + if isinstance(value, float): + return f"{value:.1f}" + return str(value) + + print( + f"| {s.page} | {s.text_count} | {s.image_count} | {s.rect_count} | {s.path_count} | " + f"{fmt(s.min_font)} | {fmt(s.max_font)} | {s.text_chars} | {s.possible_overlaps} | " + f"{fmt(s.avg_luma)} | {fmt(s.contrast)} | {fmt(s.edge_detail)} |" + ) + if findings: + print("\n## Findings\n") + for f in findings: + print(f"- {f.level} `{f.code}` [{f.page}]: {f.message}") + else: + print("\nNo findings. Still inspect the rendered montage manually.") + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("project_path", type=Path) + parser.add_argument("--svg-dir", type=Path) + parser.add_argument("--preview-dir", type=Path) + parser.add_argument("--json-out", type=Path) + args = parser.parse_args() + + project = args.project_path.resolve() + if not project.exists(): + print(f"error: project path not found: {project}", file=sys.stderr) + return 2 + + svg_files = iter_svg_files(project, args.svg_dir) + preview_dirs = infer_preview_dirs(project, args.preview_dir) + all_stats: list[PageStats] = [] + all_findings: list[Finding] = [] + + for svg in svg_files: + stats, findings = lint_svg(svg, preview_dirs) + all_stats.append(stats) + all_findings.extend(findings) + + all_findings.extend(deck_level_findings(all_stats)) + print_report(project, all_stats, all_findings) + + if args.json_out: + payload = { + "project": str(project), + "stats": [asdict(s) for s in all_stats], + "findings": [asdict(f) for f in all_findings], + } + args.json_out.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8") + + return 1 if any(f.level == "ERROR" for f in all_findings) else 0 + + +if __name__ == "__main__": + raise SystemExit(main())