scene-ppt

Scenario-based PPT Design

This skill provides two things:

1. Template references: Finished samples in styles/<branch>/exemplar/ and samples/.
2. Design guidelines: Instructions in guide/ on "how to organize, what shapes to use."

Core principle: Style follows scenario and materials, not hardcoded. Samples define quality benchmarks and demonstration techniques—not templates to copy. New decks must be re-composed for their own content. Copying sample layouts or making every deck look identical is exactly the "AI feel" this skill aims to avoid.

Environment Requirements

• macOS, Google Chrome, uv. Rendering uses the local Chrome instance; no browser download needed.
• Fonts are macOS system fonts and cannot be bundled with the skill. Chinese font weights must be specified using PostScript names, e.g., STSongti-SC-Black, FZLTTHK--GBK1-0. Using only family name plus font-weight will fall back to regular weight.

Workflow

00 Scenario Judgment

First read the user's materials. Do not ask questions that the materials can answer. Then only ask questions where "the answer changes design decisions," at most 3 to 4 at a time. Use the question tool if available.

Question	What It Determines
What occasion? e.g., competition pitch, course/academic presentation, class meeting/school event, work report, other	Which style branch to select
Live projection or send file for self-reading? How long?	Information density and page count. Live projection: large text, few words, ~1 min per page. File: denser information allowed
What should the audience remember and feel? e.g., professional & trustworthy, thoughtful, warm & fun, passionate	Which theme within the branch
Any mandatory colors, logos, or template requirements? e.g., school emblem, class flag color, event requirements	Primary color variables

Scenario → Branch and Theme

Scenario	Branch	How to Choose Theme	Density
Challenge Cup, Internet+ competition, entrepreneurship pitch, project defense	roadshow-cn	Single theme; if competition leans commercial, use gold tone with tech cyan	Full (70%+)
Course final report, book report, group research presentation	course-report	Humanities/social sciences: paper; STEM/design/data: swiss	Allow whitespace, high font size contrast
Class meeting, midterm/final review, sports meet, club, graduation	school-event	Memories/gratitude: handbook; competition/motivation: pop	Allow whitespace, one "physical object" per page
Need high design sensibility & personal style: portfolio walkthrough, job/grad school interview self-intro, design sharing, personal keynote	curve-minimal	Want restraint, rationality, design-draft feel, or for file delivery/printing: pen (light background). Want more expressiveness, personal flair, live projection: ribbon (dark background)	Very sparse, lots of whitespace; only one focal point per page
None fits	Create new theme or branch (see below)	—	—

When no branch fits, do not force the closest one. Derive a new tokens.css following the order: "mood → fonts → shape language → colors." Required and optional variables are documented at the top of styles/roadshow-cn/tokens.css. Always use scripts/fontcheck.py to confirm Chrome actually uses the specified fonts.

Primary colors should prioritize user materials: school standard colors, class flag colors, topic-related colors.

01 Organize Materials

List photos, key numbers, direct quotes, and certificate files from the user's materials. The number of photos directly affects layout: when fewer than 3 photos, avoid a photo wall. Currently this step is done manually—no scripts yet.

02 Outline

First define chapters, then assign roles to each page: cover, section page, content page, data page, closing. Typical page types per branch are documented in styles/<branch>/style.md.

03 Choose Shapes Per Page

For each page, identify its information relationship (hierarchy, sequence, comparison, ranking, proportion, key number, parallel, live photo…), then consult guide/shapes.md to find the corresponding candidate shapes. Select one based on selection criteria and the current branch. If you cannot explain "why this shape," you chose wrong. Add decorations last, selected by composition role (Section 4 of the same document).

04 Render

1. Write your HTML following the file structure of the selected branch's exemplar/deck.html, but do not copy its layout:
   • First line of <head>: put the theme script: <script>{const t=new URLSearchParams(location.search).get('theme');if(t)document.documentElement.dataset.theme=t}</script>. If omitted, render.py will silently render with the default theme even if a theme name is passed.
   • Then load tokens.css, lib/base.css, and the branch's components.css in order. For roadshow-cn, which is a single-theme branch and does not use lib/base.css, follow its own sample.
   • At the end of page, load lib/shapes.js.
   • Each page is a <section class="slide">, dimension 1920×1080.
2. In-page <style> only contains coordinates and dimensions. Use var(--c-*) for colors, or read from JS via Shapes.T('role name').
3. Photo placeholders: use <div class="photo" data-label="…">. When actual images exist, put <img> inside.
4. Render command:

uv run --with playwright python scripts/render.py <deck.html> <output_dir> [theme_name]

05 Review

• render.py automatically checks: text box overflow (only checks elements with .fit), JS errors, ellipsis, missing theme variables.
• Manually review every page's PNG. Automatic checks cannot detect overlapping, occlusion, or orphaned words at line ends. Newly created pages almost always have such issues on first render.
• Check against guide/anti-patterns.md: cards-only, pink-purple gradients, emoji replacing illustrations all count as failures.
• Large calligraphic, handwritten, or display fonts for titles should not have .fit; otherwise the check will generate false positives.

06 Delivery

Provide the PNGs and PDF (already generated by render.py) to the user for their own review. Editable PPTX export is not currently supported; modifications require editing the HTML and re-rendering.

File Index

Path	Content	When to Read
guide/shapes.md	Information relationships → shapes, with reasoning, scene variants, implementation, variable dependencies	Phase 03, used per page
guide/anti-patterns.md	Typical traits of AI-generated PPTs	Phase 05
styles/<branch>/style.md	Branch's suitable scenarios, design techniques, page types, theme selection basis	After selecting branch
styles/<branch>/tokens.css	Color, font, and size variables; different themes override via [data-theme]	When changing primary colors or creating new theme
styles/<branch>/components.css	HTML components for the branch	Phase 04
styles/<branch>/exemplar/	4-page samples plus screenshots for each theme	Phase 04, for technique reference
styles/school-event/samples/banhui-full/	12-page full class meeting sample (handbook theme, well received)	Refer for pacing when building a complete deck
lib/shapes.js	19 SVG generators (structure, data, decoration, hand-drawn)	Phase 04
lib/base.css	Reset styles, canvas, photo placeholders	Phase 04
scripts/render.py	Rendering, checks, export to PNG and PDF	Phases 04, 05
scripts/pixeldiff.py	Pixel-by-pixel comparison for regression testing	After modifying lib/
scripts/fontcheck.py	Check which fonts Chrome actually uses	When creating new theme or changing fonts

Not Yet Completed

• Phases 01 to 03 have no scripts yet; they must be done manually following the instructions above.
• guide/organization.md (chapter skeleton, page roles, rhythm for a full deck) is not yet written.
• Editable PPTX export is not supported.
• Fonts are not cross-machine portable: switching to a non-macOS environment requires using packable open-source web fonts.