visual-ppt-deck-builder

Visual PPT Deck Builder

Core Judgment

This skill is not about "converting Markdown into PPT." It is responsible for turning a topic into a deliverable PPTX: first define the story, then define the style, then generate backgrounds, copy, transparent assets, charts, and layout page by page. The final deliverable must be editable .pptx, not just a set of screenshots.

When high-polish business analysis, investor, business review, or strategic narrative decks are needed, prioritize working with the system Presentations skill; this skill handles the more general "AI visual assets + PPTX composition" workflow.

Mandatory Workflow

Confirm the topic: topic, audience, use scenario, tone, and whether there is a brand or reference material.
Confirm the outline: first provide the chapters and narrative order; do not start making pages directly.
Confirm the style: prioritize the template imitation or effect-image master draft route. If the user provides high-quality .pptx, first treat it as the style master and extract the layout, fonts, colors, whitespace, and chart language; if there is no template, then combine user preferences and the topic, first write design_director_brieffor each style set, then directly produce complete effect-image master drafts, and then reverse-engineer the approved effect images into clean backgrounds, transparent assets, coordinate blueprints, and editable PPT layers. Each candidate set must ultimately include one editable PPTX sample page and one PNG preview exported from that PPTX; the sample must contain real titles, body text, metrics, and chart labels so the user can judge fonts, font-size hierarchy, layout density, and content capacity. By default, provide 8 independent style sets; do not cram multiple styles into one overview image.
Confirm the number of slides and the content of each page: output a slide plan, clearly writing the title, core message, proof target, and the backgrounds/transparent assets/charts that need to be generated for each page.
Generate slide by slide: according to the confirmed style, generate backgrounds, copy, transparent PNG assets, charts, and page layouts page by page.
Assemble the PPTX: prioritize editable text, shapes, charts, and image layers. Only large background images may be raster; body text, charts, and key labels must not be blurred into full-page images.
Hard gate acceptance: first run the deck spec quality check, then generate the full set of SVG preview images; do not deliver before it passes.
Delivery: check that the PPTX can open, the page count is correct, media assets exist, text does not overflow, and transparent assets overlay properly.

Style Candidate Requirements

Hard Rules After Skywork Benchmarking

Reference the product discipline of the Skywork PPT skill: PPT generation cannot be a black-box one-shot "file spewer"; it must have clear routing, template imitation capability, material supplementation, and long-task progress feedback. This skill follows the rules below:

If there is a template, imitate the template first: when the user provides .pptx , the template is the first source of style. First break down the template's page types, title hierarchy, fonts, color palette, whitespace, chart syntax, and image strategy, then generate new themed content. Do not bypass the template and reinvent the style.
Only make 8 candidate sets when there is no template: only when there is no template should you go with 8 style candidate sets. The candidates must first have real image master drafts or real raster background assets.
Formal backgrounds must come from image generation or user assets: Backgrounds, characters, architecture, technology stages, Eastern landscapes, product scenes, and other key visual assets must come from Codex imagegen, Skywork Design, reverse-engineering of user templates, or images provided by the user. Using SVG, HTML, Canvas, Pillow, or scripted graphics to pass off as commercial design assets is prohibited.
The program is only responsible for the editable layer: code can generate native PPT text, shapes, charts, and coordinate-based layout; it cannot take on key visual design.
Long tasks must continuously report progress: searching, generating master mockups, generating clean backgrounds, assembling the PPTX, and exporting previews must all inform the user of the current stage; there must be no long periods of silent waiting.

The 8 candidate sets must follow themockup master firstreal PPT production path: first use images to directly produce complete PPT mockups, allowing sample text, metrics, and charts in them, to judge aesthetics, layout, fonts, density, and chart language; after the user approves, generate a clean background version with text, numbers, charts, and labels removed based on this mockup, and split characters, decorations, icons, etc. into transparent assets; finally rebuild one PPTX page using editable PPT text, shapes, charts, and image layers, then export a PNG preview from the PPTX for the user to choose. Do not merely list text style names, and do not use SVG, HTML, CSS, Canvas, or full-page generated images to pass off as the final editable page. By default, candidates cover these directions:

In addition to color scheme and background, candidates must also be split into at least 6 different layout variants, and must pass through the expression system gate. The title locking method, body copy syntax, metric syntax, and chart syntax cannot all reuse the same skeleton; otherwise it is just a template reskin, not a truly selectable style library.

The expression system gate is evaluated across these 5 dimensions:

title_anchor: whether the title is a top-left report style, centered launch style, top-right inscription style, magazine front-page style, or another clear anchor.
body_pattern: whether the body is a three-paragraph brief, bottom ticker, scroll-column layout, feature short article, roadmap, or another content-carrying method.
proof_object: what this page uses to prove the point, such as a quadrant matrix, central stage column chart, path timeline, horizontal bar narrative chart, or product flow diagram.
metric_pattern: whether metrics are a vertical KPI ladder, right-side telemetry stack, seal-style data, pull-quote metrics, or another presentation method.
role_signature: the regional combinations on the page for titles, body copy, metrics, and chart proof objects must be clearly different; the 4 candidate sets cannot have the same set of role placements.

Each candidate set must also first write a design director brief, then generate the page. The brief must include at least expression_system、style_intent、typography_system、color_strategy、chart_language、layout_rhythm. This is not copy decoration, but the basis for subsequent evaluation: within the same style, fonts, colors, chart language, and background safe zones must be coordinated; between different styles, the expression methods, narrative rhythm, and proof objects must be clearly different.

Business-grade style candidates also have a hard threshold:container-box thinking is prohibited. The body area, metrics area, and chart area must be embedded into the negative space, paper texture, glass light bands, thin-line rhythm, or stylized coordinate areas reserved by the background; do not use two large rectangles to separately hold the body copy and chart, and do not put small outlined boxes around metrics. The number of large body containers, large chart containers, and metric outline boxes on a candidate page must be 0; light-colored styles must also blend through negative space, layering, and background texture, rather than covering the background with cards.

A higher-level threshold isreadability before decoration. The background image is not an atmosphere image; it must actively reserve reading safe zones for titles, body text, metrics, and charts: low texture, low noise, appropriate light-dark transitions, and it must not look like a rectangular card. For dark backgrounds, use white/light blue-gray text and highlight lines; for light backgrounds, use near-black/medium gray text and restrained accent colors. The main chart lines or main bars must be one clear brightness level above the background, and auxiliary lines should have reduced opacity; labels must not be placed over strong light, people, landscapes, architectural lines, or complex textures.Readability cannot be rescued by adding frames. If it is unclear, prioritize redoing the background safe zones, changing text/line colors, and adjusting chart placement rather than adding a frame.

Style candidates must retaincoordinate blueprint gate, but the blueprint is not an creative starting point out of thin air; it is reverse-engineered from the confirmed visual draft master. Each candidate must provide a 16:9 page coordinate blueprint, in inches, with the page baseline being 13.333 x 7.5. The blueprint must include at least title_zone、text_zone、chart_zone、metrics_zone、visual_focus_zone、protected_empty_zone, and each area must clearly specify x/y/w/h, purpose, and content capacity. The clean background prompt must include these coordinates and require the background to actively reserve low-texture, low-noise safe zones with appropriate light-dark transitions in the text and chart areas. When laying out the PPTX, titles, body text, metrics, and charts must be placed according to the blueprint coordinates; if the background breaks the safe zones, redo the clean background; if the content does not fit, first streamline the copy or adjust the outline, do not shrink it until it is illegible, and do not add frames to hide flaws.

Business calm type: suitable for business reviews, strategy reports, and board meetings.
Editorial magazine type: suitable for courses, brand stories, and public speeches.
Product demo type: suitable for App, SaaS, and tool launches.
Data chart type: suitable for industry reports, trend analysis, and investment and financing.
Visual narrative type: suitable for AI general courses, storytelling training, and creative proposals.
Guochao Eastern type: suitable for cultural brands, consumer goods, and Eastern aesthetics proposals.
Future tech type: suitable for AI product launches, innovation solutions, and tech events.
Investor narrative type: suitable for financing roadshows, business plans, and growth stories.

After the candidate images pass, solidify the selected direction into visual_style: color palette, font temperament, background strategy, chart language, transparent asset strategy, and prohibited elements.

Before formally generating 8 real sample packs, first generate or prepare 8 real raster background images. The file names must be background-<style-slug>.png, placed in the same directory, for example:

background-minimal-premium.png
background-playful-anime.png
background-data-analytics.png
background-oriental-heritage.png
background-future-tech.png
background-editorial-magazine.png
background-saas-product.png
background-investor-narrative.png

These backgrounds must come from Codex imagegen, Skywork Design, user template reverse engineering, or user-provided assets. Once ready, run the tool to generate 8 real sample packs:

node "${CODEX_HOME:-$HOME/.codex}/skills/visual-ppt-deck-builder/scripts/build_style_candidates.js" \
  --output-dir /absolute/path/style-candidates \
  --topic "<deck topic>" \
  --background-source-dir /absolute/path/generated-backgrounds

If there is no --background-source-dir, the tool will fail directly. This is intentional: formal candidates can no longer automatically draw backgrounds with a program. Only unit tests or structural validation may use --allow-placeholder-backgrounds, and the results generated by this switch must not enter the README, style library display, or commercial delivery.

The tool will generate:

style-candidate-spec.json: 8 style candidates, PPTX sample paths, PNG preview paths, background asset strategy, and PPT layer contract.
style-candidates.md: execution instructions and user confirmation checklist.
samples/style-sample-*.pptx: one page of real editable PPTX sample per style.
previews/style-sample-*.png: PNG previews exported from the corresponding PPTX samples.
prompts/style-reference-*.md: prompts used to first directly output the complete visual draft master.
prompts/clean-background-*.md: prompts used to generate a text-free clean background after the master is approved.
style-visual-qa.json: Visual QA report for text areas, chart areas, and background complexity; any failed candidate must not be shown as a passing sample.
style-design-qa.json: Main visual richness QA report; prevents the 8 candidates from degenerating into merely changing the background color.
design-director-qa.json: Design director acceptance report; checks internal style consistency, visual harmony, and cross-style diversity.

If you want to improve candidate quality, first follow prompts/style-reference-*.md to call Codex image generation capability one by one to generate complete effect image master drafts; after selecting a direction, then follow prompts/clean-background-*.md to generate a clean background, save it to assets/background-*.png and rerun the tool. Note: the clean background must not contain titles, body text, numbers, letters, chart labels, or UI text; these contents must be carried by the editable PPTX layer.

The background prompt must clearly define three types of areas:text-safe zone、chart-safe zone and low-detail transition area. These three types of areas are for letting PPT text and charts blend naturally into the background, not for later pasting cards. If the candidate preview shows unclear text, unclear charts, small text pressed onto complex textures, or lines pressed onto highlights, judge it directly as failed.

What is truly shown to the user is still 8 independent PNG previews, but these PNGs must be exported from a PPTX template, not generated directly by a full-page image generation model. Style samples must display sample titles, body text, key points, metrics, and chart labels, to check font character, title hierarchy, body text readability, card density, and chart language. In the final PPT, these contents must reuse the same editable text, shape, or chart layer implementation, and must not turn formal pages into full-page screenshots.

Transparent asset strategy

When transparent background assets are needed, call $transparent-visual-assets：

People, objects, icons, stickers, chart decorations, process nodes, and product illustrations should preferably be made as transparent PNGs.
The background can be generated separately, but do not bake the entire page's body text and charts into the background image.
If charts need to be user-editable, prefer drawing them with native PPT shapes or scripts; if they are complex illustrative diagrams, then use transparent PNGs.

PPTX generation method

There are two routes:

High-end deck route: Call the system Presentations skill, and use artifact-tool presentation JSX to build, render, review, and export PPTX.
General deterministic route: Use this skill's scripts/build_visual_pptx.jsto generate editable PPTX from a JSON deck spec.

Run helper:

node "${CODEX_HOME:-$HOME/.codex}/skills/visual-ppt-deck-builder/scripts/build_visual_pptx.js" \
  --spec /absolute/path/deck_spec.json \
  --output /absolute/path/final_deck.pptx

If executing in the Codex bundled runtime, prefer using:

/Users/dw/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node \
  "${CODEX_HOME:-$HOME/.codex}/skills/visual-ppt-deck-builder/scripts/build_visual_pptx.js" \
  --spec /absolute/path/deck_spec.json \
  --output /absolute/path/final_deck.pptx

For deck spec syntax, see references/deck-spec-schema.md。

The master draft reverse-decomposition page type already has a runnable sample:reference_visual_trend. It is used for business, anime, technology, and other trend data pages, treating the clean background as the full-page background and rebuilding the title, body text, metrics, bar chart, trend line, and labels entirely as editable PPT objects. When using this page type,background_image can only point to a clean background with no text and no charts; do not stuff an effect image master draft with complete copy and charts into the PPT as a background. The old alias reference_anime_trend is still compatible, but new samples should preferably use reference_visual_trend。

Different styles cannot share one rigid set of font colors, font sizes, and page skeletons. Backgrounds such as dark technology, light business, national trend paper texture, and lively anime must use layout_variant to adjust the title locking method, body text grammar, metric positions, and chart hierarchy, and then use overlay_style to adjust title/body/metric/chart colors, font sizes, chart gridline transparency, bar transparency, and bullet numbering, ensuring the visual language blends with the background, rather than hard-pasting the same set of text styles onto it.reference_visual_trend Currently supports minimal_left_report、future_dashboard_focus、oriental_vertical_scroll、editorial_feature_story、boardroom_summary_matrix、future_launch_stage、oriental_scroll_narrative、editorial_feature_spread eight variants; before adding a new style, you must add or reuse a truly matching layout variant and clearly define the expression system.

Before delivering a commercial deck, the quality gate must be run:

node "${CODEX_HOME:-$HOME/.codex}/skills/visual-ppt-deck-builder/scripts/validate_deck_quality.js" \
  --spec /absolute/path/deck_spec.json \
  --report /absolute/path/qa_report.json

Also generate a scannable preview of the entire page set:

node "${CODEX_HOME:-$HOME/.codex}/skills/visual-ppt-deck-builder/scripts/build_deck_preview.js" \
  --spec /absolute/path/deck_spec.json \
  --output-dir /absolute/path/preview

The preview directory will contain page-by-page slide-01.svg and contact-sheet.svg. It is not the final PPT rendering, but it can quickly reveal repeated page types, empty pages, template words, missing sources, and information density issues.

Before delivering multi-style sample sheets, the design director QA must also be run:

node "${CODEX_HOME:-$HOME/.codex}/skills/visual-ppt-deck-builder/scripts/design_director_qa.js" \
  --sample-dir /absolute/path/multi-style-samples \
  --report /absolute/path/design-director-qa.json

This report is not a substitute for human aesthetic judgment, but it first blocks low-level issues: within the same style, inconsistent fonts/colors/chart language, overlapping role placements across multiple style sets, repeated expression systems, backgrounds that are not raster, and large rounded-corner boxes appearing again in the PPTX will all be judged as failures.

Acceptance criteria

The user has confirmed the topic, outline, style, number of pages, and content of each page.
There are 8 style candidates, and each includes an editable PPTX sample and a PNG preview exported from the PPTX; the final style is explicitly selected.
A commercial deck has at least 6 pages and at least 5 layout types; it must cover a conclusion page, architecture/roadmap page, metrics/chart page, comparison page, and risks and next steps page.
Except for the title/section/closing pages, each page must have claim, that is, the one sentence this page truly aims to prove.
The PPTX page count matches the slide plan.
Titles, body text, and chart labels are editable objects and must not be turned into full-page screenshots.
Style candidates cannot just be “background + two large white boxes”; they must prove through fused layouts that the style can genuinely extend to business-grade PPT.
Style candidates cannot just be “the same layout + different backgrounds/color schemes”. At least 4 candidates must have different expression_system, and the role placement signatures of titles, body text, metrics, and proof objects must not repeat.
Style candidates must pass design-director-qa.json: each set consistency_score >= 0.8、harmony_score >= 0.8, across candidates diversity_signature must not repeat.
The background source of style candidates must be Codex imagegen, Skywork Design, reverse-engineered from a user template, or raster images provided by the user; programmatic test backgrounds cannot be shown as formal sample sheets.
Body text, metrics, and charts in style candidates must not be placed in rectangular containers; large-area body text containers, large-area chart containers, and metric outline boxes must be 0.
The background must have a reading safe zone, a chart safe zone, and a low-texture transition zone; the body text contrast target must be no lower than 4.5:1, and the chart main line/main bar contrast target must be no lower than 3:1.
Style candidates must generate and check style-visual-qa.json; if ok=false or any candidate has_background_overlap_risk=true, it cannot be accepted, and that sample sheet must not be placed in the README showcase.
If text or charts are unclear, do not fix it by adding boxes; you must redo the background safe zone, adjust the font color/line color, or move element positions.
Transparent assets have clean edges and remain legible when overlaid on both dark and light backgrounds.
Charts have a clear basis; data without a source must not be disguised as fact.
Residual template words such as Topic、Style、Assets、TODO、TBD、占位 are not allowed.
Final delivery .pptx, while retaining the deck spec, transparent assets, and key source images used for generation.

Read when needed

references/research-notes.md: research and trade-offs for open-source PPT generation solutions.
references/deck-spec-schema.md: JSON spec format supported by helper.