Guizang PPT Skill: two locked visual systems and three validators as a web-deck engineering spec
op7418/guizang-ppt-skill
A web presentation-deck skill open-sourced by (op7418), AGPL-3.0, primary language HTML, 26,809 stars. It is not a prompt template that writes slide copy for you; it is an engineering specification that makes an agent reliably produce a single-file HTML swipe deck you can present on stage. The README states the provenance on its first screen: the rules were distilled round by round from the author's own offline talks, and every pitfall landed in references/checklist.md. The decisive reason for HTML over PPTX is that HTML and CSS are text an agent can read, edit and verify directly - a script can measure how many px a slide overflows by, and Playwright can render it for a real visual check. Its core asset is two visual systems with mutually incompatible class names and very different constraint strength: Style A (editorial magazine x e-ink, 10 paste-ready layout skeletons, 5 theme presets, Chinese display headlines capped at 5 characters with nowrap) and Style B (Swiss International, 22 named layouts S01-S22 that are locked, body pages may only pick from them and must write data-layout, 4 anchor colours IKB #002FA7 / #FFD500 / #C5E803 / #FF6B35, square corners with no gradient or shadow, large type forced to weight 200). The most counter-intuitive decision is that custom hex values are not allowed: when a user supplies an arbitrary colour the agent should politely refuse and lay out the presets instead, and SKILL.md says protecting the aesthetic matters more than giving freedom. What separates it from ordinary template packs is three validators plus a repair ladder: validate-swiss-deck.mjs statically checks registered layouts, image slots, text inside SVG and headline alignment, and with Playwright measures DOM overflow in px, bottom whitespace, the nav-safe line and title gap; validate-presenter-mode.mjs catches duplicate slide IDs, mismatched notes, a timing plan over 90% of the target and missing controls; check-presenter-runtime-sync.mjs exists solely to catch drift in the presenter runtime copied into both templates. Guessing-based fixes are forbidden: 1-40px overflow gets micro-adjustment only, 40-90px local spacing compression, 90-160px may squeeze a headline or split a page, and only above 160px may you change layout or delete content. A fully local presenter mode ships inside (press P: dual-window sync, structured notes stored by data-slide-id rather than page number, rehearsal timing, laser pointer and circling, black/white screen and audience-screen freeze, with no cloud relay, phone remote or AI coach), and under Codex it offers to generate imagery with GPT-Image 2.0 plus multi-platform covers such as a 21:9 article header or a 3:4 carousel. It states its own bad fits: dense tables, training courseware, multi-editor collaboration, and it cannot export PPTX. We did not install it and produce a real deck, so it is graded as pending reproduction.
Our takeIt turns web slides into a script-verifiable engineering spec: two locked layout systems, three validators, and a repair ladder graded by pixels (1-40 micro-adjust, 40-90 compress spacing, 90-160 split pages, only above 160 may content be deleted), plus a fully local presenter mode with rehearsal timing. The idea worth stealing is the ban on custom hex values - aesthetic correctness is managed as a non-negotiable product constraint rather than left to model discretion. We have not produced a real deck with it, so it is graded as pending reproduction.
npx skills add https://github.com/op7418/guizang-ppt-skill --skill guizang-ppt-skillThe problem it actually solves
This skill by (op7418) is not "a prompt template that writes slide copy for you". It is a complete engineering specification for making an agent reliably produce a single-file HTML swipe deck that can be presented on stage. AGPL-3.0, primary language HTML, 26,809 stars. Its provenance is on the first screen of the README: the rules were distilled from the author's own offline talks ("One-person company: the organisation folded by AI", "A new way of working"), and every pitfall encountered went into references/checklist.md.
Why HTML rather than PPTX? The README gives four reasons, and we think the second is the one that matters: HTML and CSS are text, so an agent can read, edit and verify them directly. A PPTX is a binary package that an agent manipulates indirectly through a library and cannot self-inspect after rendering. HTML can be measured by a script ("how many px does this slide overflow by") and rendered by Playwright for a real visual check. Delivery is lighter too: one file opens with a double click, presents, ships, screenshots, and the presenter tooling ships inside it.
Two visual systems that do not share class names
The easiest thing to get wrong about this skill: Style A and Style B are not "a different CSS skin". They are two layout systems with mutually incompatible class names and very different constraint strength. SKILL.md repeats the warning — the same class name renders completely differently in the two templates. h-hero is Noto Serif SC in Style A and Inter at weight 200 in Style B.
| Dimension | Style A · editorial magazine x e-ink | Style B · Swiss International |
|---|---|---|
| Template | assets/template.html | assets/template-swiss.html |
| Typography | Serif headlines (Noto Serif SC + Playfair Display) + sans body + monospace metadata | Sans-serif throughout (Inter + Helvetica + Noto Sans SC); any serif is a defect |
| Background | WebGL fluid / contour / dispersion, visible only on hero pages | WebGL hairline grid + dot matrix; body pages stay flat |
| Layouts | 10 paste-ready layout skeletons | 22 named layouts S01-S22; body pages may only use those, each writes data-layout, inventing a structure is forbidden |
| Theme colour | 5 presets: Ink Classic / Indigo Porcelain / Forest Ink / Kraft Paper / Dune | 4 anchor colours: Klein Blue IKB #002FA7 / Lemon Yellow #FFD500 / Lemon Green #C5E803 / Safety Orange #FF6B35 |
| Hard rules | Chinese display headline at most 5 characters with nowrap; image grids use height:Nvh, never aspect-ratio | Square corners, no gradient, no shadow, no radius; 1px hairlines; headline-to-body type ratio at least 8:1; display weight must be 200 and 600/700/800 headlines are banned; KPI must be a Data Hero at 18-22% of screen width |
| Aesthetic anchor | Like Monocle magazine with code pasted on | Massimo Vignelli / Helvetica Forever / Muller-Brockmann grid systems |
The most counter-intuitive decision: custom hex values are not accepted. When a user supplies an arbitrary colour, the agent is instructed to politely decline and lay out the presets instead, and mixing is banned (ink from one theme, paper from another). SKILL.md says it plainly: a bad colour pairing ruins the frame instantly, so protecting the aesthetic matters more than giving freedom. That is not laziness; it treats aesthetic correctness as a product constraint, which is the opposite of most template systems that let you configure everything.
Layout quality made measurable
This is what separates it from a pile of slide prompts: three validators plus a repair ladder.
| Script | What it blocks |
|---|---|
scripts/validate-swiss-deck.mjs | Static checks on registered layouts, image slots, text written inside SVG, headline alignment, dangerous SVG; with Playwright available it also measures real rendering metrics: M1 DOM/visual overflow (exact px and the lowest and highest offending elements), M1 bottom whitespace, M1 nav-safe (content intruding into the bottom pagination safe line), M2 title gap |
scripts/validate-presenter-mode.mjs | Missing or duplicate page IDs, notes misaligned with pages, missing required fields or wrong types on optional ones, a total time plan exceeding 90% of the target duration budget, and missing timing/rehearsal/auto-advance/annotation/pre-show-check/audience-screen-recovery controls. Accepts --target-minutes 30 |
scripts/check-presenter-runtime-sync.mjs | Drift of presenter CSS / JS between the two templates — the same runtime is copied into both, so divergence is inevitable over time, and this script exists purely to catch it |
Worth copying is that it forbids gut-feel rewrites. The "measure before you change" section gives an explicit ladder: 1-40px of overflow means micro-adjust only (shift the content group up or tighten one gap, do not delete content); 40-90px means compress spacing locally; 90-160px allows slightly shrinking a headline or splitting a page; only beyond 160px may you change layout, merge modules or delete content. Re-run afterwards, and if bottom whitespace grew you over-corrected. It also states that code can only prove class names and structure exist, not that the layout is comfortable — you must open the page and look at every slide, waiting 1-2 seconds for entrance animations to settle before screenshotting so you do not mistake a mid-animation frame for a layout bug.
Step 3.0 class preflight: the source of every generation bug
SKILL.md marks this section most important. The layout skeletons use many class names, and if the template <style> has no matching definition the browser falls back to defaults — wrong headline font, cards squashed together, a pipeline collapsed onto one line, images piled at the bottom of the page. The rule: before writing any slide code, read the template you are using (at least to the end of the <style> block), check every class you intend to use against the Pre-flight list in the layouts file, and if a class is missing add it to the template <style> rather than inlining it per slide. The template is the only source of class names; for custom needs use style="..." inline and do not invent class names.
Step 3.0.5, "plan the theme rhythm", is flagged as equally important, and its rules are greppable: every page <section> must carry one of light / dark / hero light / hero dark (writing only hero is not allowed); three or more consecutive pages on one theme is banned; a deck of 8+ pages must contain at least one hero dark and one hero light; a deck may not consist of light body pages only; insert a hero page every 3-4 pages. After generation, grep 'class="slide' index.html lists the rhythm for human confirmation before delivery.
Presenter mode: entirely local, no cloud relay
Both templates embed the same presenter runtime, entered by pressing P in the bottom-right corner. It does not rely on live captions, a cloud relay, a phone remote or an AI coaching service — dual-window sync, notes, timing, rehearsal, auto-advance and annotation all happen in the local HTML and browser.
The capability list is longer than we expected: current and next page stacked vertically and always kept at 16:9 (scaled as a whole on small screens, never cropped or squashed); grid page selection switching in place inside the preview area; structured notes where title, page purpose, talking points and transition are mandatory while interaction, tone, advance timing, fallback and pronunciation only appear if the outline supplied them; a bottom bar showing elapsed, current-page and remaining/overtime separately; rehearsal mode recording actual per-page duration and a session summary, stored in the local browser with no AI scoring by design; auto-advance off by default, enabled only when the outline gives per-page dwell seconds or the user turns on a global interval in settings, and paused whenever the grid, settings or annotation tools are open, the page is hidden, or the audience screen loses sync; laser pointer and circle-select mirrored to the audience screen; one-key blackout, whiteout or audience freeze with automatic catch-up on resume; an explicit "not connected" state when the audience window closes or the heartbeat times out, with one-click reopen; auto-close of the audience window on exit, with the audience side showing "presentation ended" when the browser refuses to close it. Shortcuts: arrow keys navigate, Home/End first and last, G grid, L laser, C circle, B/W blackout and whiteout, F freeze, ? full list.
The notes data structure is carefully designed: every <section> needs a unique, stable data-slide-id, and SPEAKER_NOTES is keyed by page ID rather than array index or page number — otherwise reordering pages silently shifts notes the user already edited in the presenter view. The division of labour is fixed too: the slide carries only what the audience must see right now (conclusion, structure, evidence); purpose states the page's job in the overall narrative; talk adds background and judgement without reciting the slide; transition explains why the next page follows; minutes (the speaking plan) and autoAdvanceSeconds (playback behaviour) must stay separate. Facts without a source may not be written into notes; missing information that affects correctness is marked "to be supplied" or asked about, while optional stage information that does not affect content is simply omitted. The default is 3-5 prompt-card style talking points, not a verbatim script, and total planned time may occupy at most 90% of the user's duration so pauses and accidents have room.
Codex illustration flow and multi-platform covers
Under Codex, once the deck draft is done the skill proactively asks whether to generate illustrations with GPT-Image 2.0 / GPT-M 2.0 — it never generates by default. Available types: documentary-style human photography (Fuji / Leica feel for real scenes), infographics and flow, comparison and system-relationship diagrams, screenshot beautification or screenshot redesign, data posters, and multi-image collages for very wide slots (avoiding three 16:9 images crammed into three columns).
Four hard image rules are worth quoting separately: an image is embedded material and must not carry its own footer, header, title, corner badge, page number or decorative border; language follows the deck, so a Chinese deck's infographic uses Chinese labels; aspect ratio matches the destination slot first — 21:9 for Swiss heroes, 16:9 / 16:10 for general heroes, 16:10 for screenshot redesign, uniform height for grids; and when a user screenshot must stay faithful, read references/screenshot-framing.md first and use the built-in backgrounds in assets/screenshot-backgrounds/ (5 for style-a, 4 for style-b) to do CleanShot X-style programmatic scaling, padding and alignment, only regenerating with the image model when the original is too messy, too narrow, or needs conceptual expression.
The same visual rules also produce covers: WeChat article header 21:9, WeChat share card 1:1, Xiaohongshu cover or carousel 3:4, video-account landscape 16:9. The principle matches the deck — few keywords, visual weight on the big headline, no body-copy pile-up.
Workflow and file loading order
Step 0 mandates checking for upstream updates first (git fetch then rev-list --count HEAD..@{u}; if greater than zero, ask the user whether to pull --ff-only and never auto-update). Step 1 is a seven-question clarification checklist whose first question must fix Style A or B, because that decides which template, layouts and themes files get used; the other six cover audience and occasion, duration (15 minutes is about 10 pages, 30 about 20, 45 about 25-30), raw material, image and screenshot handling, theme colour, and hard constraints. Runtime adaptation is spelled out: in Claude Code use Ask Question for itemised clarification, in Codex do not assume those tools exist, ask at most 1-3 critical questions at a time, and if a gap does not block work, make a reasonable assumption and state it.
Without an outline it builds a narrative arc: hook 1 page, context 1-2, core 3-5, shift 1, takeaway 1-2 — and only after the arc, the page plan and the theme rhythm table are all three aligned does it move to Step 2. For a real talk there is a fourth table: page number / page ID / section / page purpose / audience-visible information / speaker supplement / planned minutes / transition / optional stage information.
Resources load on demand across eleven reference files: components.md (fonts, colour, grid, icons, callout, stat, pipeline, motion), layouts.md (ten Style A skeletons), swiss-layout-lock.md (the Style B layout lock that body pages must register against), layouts-swiss.md (the 22-page skeleton notes plus a small clearly-labelled experimental zone), swiss-map-component.md (the S08 map extension using MapLibre points and connections), themes.md / themes-swiss.md, image-prompts.md, screenshot-framing.md, presenter-mode.md, and checklist.md (graded P0/P1/P2/P3). For motion, the Motion One loader and recipe logic are already embedded in the template's bottom module script, so the agent only adds data-anim / data-animate in HTML and never touches the JS; assets/motion.min.js (about 64KB) is the offline fallback and degrades to "no animation but readable content" when the network is gone.
Platform support and stated limits
| Platform | Status | Notes |
|---|---|---|
| Claude Code | Supported | Native skill workflow, best for generating and iterating decks |
| Codex | Supported | Best for deck generation, invoking image generation, browser-based visual checks |
| Cursor / other local agents | Usable | Needs file read-write and shell execution |
| WorkBuddy | In progress | A separate listing version, stripping channel differences the platform does not need |
| Plain chatbots | Not recommended | Without a filesystem and browser preview it is hard to produce a complete deck reliably |
It states its own unfit scenarios, which we respect: large tables and stacked charts (use normal PPT), training courseware (not enough information density), and multi-person collaborative editing (this is static HTML). PPTX export is also out — the core deliverable is HTML, presented in a browser, screenshotted or screen-recorded; if you need PPTX, treat the HTML pages as visual masters and convert, but that is not the main flow. For low-power machines, B switches to static mode, stopping the WebGL / ASCII canvas RAF and the Motion entrance animations.
Where it sits in agientry
We file it under Agent Skills in the documents domain, with runtimes claude-code and codex — the two the README marks "supported"; Cursor is marked merely "usable" by the project itself. It is one of two answers in the same race as zarazhangrui/frontend-slides: frontend-slides bets on "let non-designers discover their taste by looking at previews", guizang bets on "nail two visual systems down until a script can verify them". The former has more freedom and a bigger template pool (12 presets plus 34 bold templates); the latter has more consistency and verifiability (22 locked layouts, three validators, a px-graded repair ladder). For a serious offline talk that needs presenter mode and rehearsal timing, pick guizang; for quickly discovering a visual direction, or converting an existing PPTX to the web, pick frontend-slides.
An honest statement of our verification boundary: every conclusion here comes from reading README.md (24.8KB) and SKILL.md (632 lines) in full, including the three validators' responsibilities, the px thresholds of the repair ladder, the complete presenter-mode capability list and shortcuts, and both styles' class inventories and theme hex values. We have not installed it and generated a deck ourselves, so Swiss-style fidelity to the 22 layouts under real content, the actual interception rate of the Playwright measurement items, and presenter-mode stability on a real projector over HDMI are unverified by us and graded as pending reproduction.
SOURCE LINKS