Frontend Slides: a zero-dependency HTML slide skill that lets non-designers pick their taste from three real previews
zarazhangrui/frontend-slides
zarazhangrui/frontend-slides is a coding-agent skill, MIT, primary language JavaScript, 29,716 stars / 2,326 forks, described in one line as making beautiful slides on the web with a coding agent's frontend abilities. Its design premise is the first Philosophy item in the README: you do not need to be a designer to make something good-looking, you only need to react to what you see. That sentence determines the whole architecture. Most PPT prompt collections ask you to describe a style first (minimal, techy, business); SKILL.md explicitly rejects that route - Phase 2 is called Style Discovery, states that most people cannot describe their design preferences in words, and makes the default experience visual comparison: generate three single-page HTML previews, open them automatically, and let the user pick, with an explicit instruction not to ask whether they want options or a preset selector. The three-slot ratio is a hard rule: one safe preset (from the 12 curated entries in STYLE_PRESETS.md, grouped by temperament - dark Bold Signal / Electric Studio / Creative Voltage / Dark Botanical, light Notebook Tabs / Pastel Geometry / Split Pastel / Vintage Editorial, specialised Neon Cyber / Terminal Green / Swiss Modern / Paper & Ink), at least one bold template (34 design systems in bold-template-pack, from the author's other repo beautiful-html-templates, each with three real screenshots), and one wildcard (a second bold template or an agent-designed custom look, used when the brief holds an opportunity sharper than any template). The artefact is a zero-dependency single HTML file with all CSS and JS inlined - no npm, no build tool, no framework - justified plainly: dependencies are liabilities, an HTML file still opens in ten years, a 2019 React project does not. Progressive disclosure is token engineering: the agent first reads only selection-index.json with its mood / tone / best_for / avoid_for / formality / density / scheme fields, then the preview.md cards of the shortlist, and reads a full design.md only for the single template the user finally picks, with an explicit do-not-copy-template.html rule. One rule is marked NON-NEGOTIABLE: every style preview must look like the real first page of the user's deck rather than a diagnostic card - no preview, template, preset, Option A-B-C, filename or path may be rendered on the slide, and requirement notes such as 'sharp and provocative' must not become content. Core principle 5 is NON-NEGOTIABLE too: a fixed 1920x1080 canvas scaled uniformly, 16:9 even on phones, letterboxing allowed and re-layout forbidden; each supporting constraint maps to a real bug (inline the whole of viewport-base.css, show and hide pages only with the visibility / opacity / pointer-events based.active /.visible classes and never display:none, use clamp outside the stage only, never negate a CSS function directly but write calc(-1 * clamp(...)), and support prefers-reduced-motion). The anti-AI-slop section addresses the agent in the second person and names the convergence tendencies to avoid - Inter / Roboto / Arial, purple gradients on white, predictable layouts - with the sharpest line being that you will still converge on common choices across generations (Space Grotesk for example), so avoid it. The acceptance bar is professional: verify overflow and panel overlap in a rendered browser screenshot, because checking scrollHeight alone is not enough since grid panels can visually cover each other. Six phases cover three modes (new build, PPTX conversion via extract-pptx.py, enhancing existing HTML) and two density settings, the artefact carries inline editing (press E, save with Ctrl+S), and Phase 6 documents the operational pitfalls of deploy.sh (Vercel) and export-pdf.sh (Playwright, where –compact renders at 1280x720 and usually cuts 50-70%). We did not install the plugin or produce a real deck, so it is graded as pending reproduction.
Our takeTwelve safe presets, 34 bold templates, and one NON-NEGOTIABLE rule that every preview must look like the real first page: style selection is moved from describing to looking, which is a product decision for non-designers rather than template hoarding. Two more ideas worth copying into any generative-UI pipeline: a fixed 1920x1080 stage in exchange for layout determinism, and acceptance by rendered screenshot checking both overflow and panel overlap, since scrollHeight alone cannot catch z-axis covering. We did not install it and produce a deck, so it is graded as pending reproduction.
/plugin marketplace add https://github.com/zarazhangrui/frontend-slides 然后 /plugin install frontend-slides@frontend-slidesWhat problem it actually solves
zarazhangrui/frontend-slides is a coding-agent skill, MIT licensed, JavaScript as the main language, 29,716 stars and 2,326 forks. Its one-line description says it makes beautiful slides on the web using a coding agent's frontend skills, but the real design thesis is that it is built for people who are not designers. The first item in its Philosophy section is blunt: you do not need to be a designer to make beautiful things, you just need to react to what you see.
That single sentence determines the whole architecture. Most PPT prompt collections ask you to describe a style first ("minimal", "techy", "corporate"), and SKILL.md explicitly rejects that route: Phase 2 is called Style Discovery, its stated premise is that most people cannot articulate design preferences in words, so the default experience is always visual comparison - generate three single-slide HTML previews, open them automatically, let the user pick. It even forbids asking the user whether they want options or a preset picker.
The artefact is equally opinionated: a zero-dependency single HTML file with all CSS and JS inline, no npm, no build tools, no framework. The second Philosophy item gives a practical reason - dependencies are debt, a single HTML file will still open in ten years, and a 2019 React project will not.
The three-preview mix is a hard rule
This is the piece of product design most worth copying. The previews are not three arbitrary generations; the mix is constrained.
| Slot | Source | Purpose |
|---|---|---|
| 1 safe preset | one of the 12 curated presets in STYLE_PRESETS.md | readability fallback; for conservative or high-stakes decks it must be "especially restrained" |
| at least 1 bold template | one of the 34 design systems indexed in bold-template-pack/selection-index.json | brings design ambition so the user has something to react to |
| 1 wildcard | a second bold template or a self-generated custom design | creates the strongest contrast; when the brief has a sharper design opportunity than any template, this slot is for free design |
The 12 safe presets are grouped by feel. Dark: Bold Signal (confident, high-impact), Electric Studio (clean professional split-panel), Creative Voltage (retro-modern with electric blue and neon), Dark Botanical (elegant, warm accents). Light: Notebook Tabs (editorial paper with colourful tabs), Pastel Geometry (friendly vertical pills), Split Pastel (two-colour vertical split), Vintage Editorial (witty, geometric). Specialty: Neon Cyber (particle backgrounds, neon glow), Terminal Green (developer/hacker), Swiss Modern (Bauhaus geometry), Paper & Ink (drop caps, pull quotes). SKILL.md also ships a mood-to-preset table: impressed/confident maps to Bold Signal, Electric Studio, Dark Botanical; excited/energized to Creative Voltage, Neon Cyber, Split Pastel; calm/focused to Notebook Tabs, Paper & Ink, Swiss Modern; inspired/moved to Dark Botanical, Vintage Editorial, Pastel Geometry.
The 34 bold templates come from the author's companion repo beautiful-html-templates, each shown with three real screenshots in the README. We counted the names: Soft Editorial (Cormorant Garamond on warm paper with sage, blush and lemon), Editorial Forest, Pin & Paper, Sakura Chroma, Stencil & Tablet, Cobalt Grid, Vellum, Emerald Editorial, Neo-Grid Bold, Editorial Tri-Tone, Creative Mode, Monochrome, People's Platform (Block & Bold), Pink Script - After Hours, 8-Bit Orbit, BlockFrame, Blue Professional, Bold Poster, Broadside, Capsule, Cartesian, Coral (cream and coral on near-black in oversized Bebas Neue), Daisy Days (hand-drawn daisies and rainbows), Grove, Mat (mid-century modern with wood undertones), Playful (Syne display, indie launch feel), Raw Grid (neo-brutalist thick borders and offset shadows), Retro Windows (Windows 95 chrome, MS Sans Serif), Retro Zine (beige paper, riso-print energy), Scatterbrain (pastel sticky notes with Caveat handwriting), Signal (deep navy with a single muted-gold accent), Studio (black canvas, electric-yellow type), Biennale Yellow (Dutch-editorial poster), Long Table (cream and rust-red supper-club).
The accompanying progressive disclosure is clean, and it is token engineering rather than style engineering: the agent first reads only the compact selection-index.json (whose mood, tone, best_for, avoid_for, formality, density and scheme fields drive the match), reads the small preview.md cards only for shortlisted candidates to build title-slide previews, and reads the full design.md for exactly one template - only after the user picks it. SKILL.md adds that you must not read or copy template.html unless the selected design.md is missing a critical implementation detail.
Preview authenticity: one rule marked NON-NEGOTIABLE
This section reveals exactly what the author got burned by. The rule: every style preview must look like a real first slide from the user's deck, not a diagnostic card. Internal workflow text must never be rendered on a slide - no preview, generated from, preview.md, template, preset, style option, Option A/B/C, file names, paths or source-document labels. Template names and slugs must never appear on the slide itself (they belong only in the message to the user). User requirement notes must never be rendered as slide content either - "sharp and provocative", "safe option", "bold option", "for internal sharing", "audience: ..." are all banned unless the user explicitly wants that exact phrase in the deck.
When a slide needs chrome, only real deck chrome is allowed: the deck title, section title, date, author, company, page number, or a genuine content phrase from the user's material. Before opening previews, inspect the visible text and revise if any internal metadata shows up. The custom-wildcard path adds one more: never render "custom", "wildcard", "AI-generated" or any design-process label on the slide.
The value of this rule goes well beyond slides. It generalises to generated artefacts must not leak the scaffolding: users should see the product, not the agent's working process. Any team building generative UI should copy it.
The fixed 1920x1080 stage: five engineering invariants
Core principle 5 is marked NON-NEGOTIABLE: every deck is authored inside a fixed 1920x1080 canvas that scales uniformly to the viewport. Slides stay 16:9 on every screen including phones, and content must not be reflowed to fit the device. Letterboxing and pillarboxing are fine; re-layout is not. That is the opposite of most "responsive slides" libraries, and what it buys is layout certainty - the design size is the final size.
The supporting constraints are unusually specific, and each one maps to a real bug.
| Rule | What breaks otherwise |
|---|---|
Read viewport-base.css and include its full contents in the <style> block of every deck | missing stage-scaling and slide-switching CSS makes the whole deck's fit behaviour unpredictable |
Slide visibility only via .active / .visible using visibility, opacity and pointer-events; never display:none / display:block | later layout classes such as .slide-content { display: flex; } override it and every slide becomes visible at once |
clamp() only for non-slide UI outside the stage, or for small fallback previews where a full stage is impractical | fluid units inside the stage mean giving up the fixed design size |
Never negate CSS functions directly (-clamp(), -min(), -max()); write calc(-1 * clamp(...)) | browsers silently ignore them - no error, the value just does nothing |
Include prefers-reduced-motion support | accessibility gap |
Fonts are constrained too: Fontshare or Google Fonts only, never system fonts. Code quality requirements live in Phase 3 - every section needs a clear /* === SECTION NAME === */ comment block plus detailed comments, which maps to Philosophy item four: comments are kindness, code should explain itself to future-you.
Anti-AI-slop: model convergence written as an explicit adversary
The Design Aesthetics section is written in the second person, addressing the agent directly: "You tend to converge toward generic, 'on distribution' outputs. In frontend design, this creates what users call the AI slop aesthetic." It then lists four things to avoid: overused font families (Inter, Roboto, Arial, system fonts), cliched colour schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
The sharpest line is this one: "You still tend to converge on common choices (Space Grotesk, for example) across generations. Avoid this: it is critical that you think outside the box!" It names the second-order convergence too - the model swaps the font, but swaps it for another font everyone else's model also picks. The positive requirements are four: typography that is beautiful, unique and interesting; committed colour (CSS variables for consistency, dominant colours with sharp accents beating timid evenly-distributed palettes, drawing from IDE themes and cultural aesthetics); motion that prioritises CSS-only solutions and focuses on high-impact moments, because one well-orchestrated staggered page load creates more delight than scattered micro-interactions; and backgrounds that build atmosphere and depth instead of defaulting to solid colours.
This pattern - admit the model has a convergence tendency, name the tendency concretely, then demand deliberate deviation - works far better than saying "be creative". We saw no clause of equal self-adversarial strength in guizang-ppt-skill.
Workflow: six phases, two density modes
Phase 0 detects the mode: A new presentation (go to Phase 1), B PPTX conversion (jump to Phase 4), C enhancement of an existing HTML deck (read it, understand it, enhance it). Mode C gets its own modification rules, because adding content is the biggest risk under a fixed stage: count existing elements against density limits before adding anything; images must fit inside the 1920x1080 canvas, and if the slide is already full you split it into two; text is capped at 4-6 bullets per slide, and exceeding it means continuation slides; after any modification verify the stage is still 16:9, no text overflows its card, no panels overlap, and screenshots look correct at 1280x720 plus one phone viewport; and if a modification would cause overflow, proactively reorganise and tell the user rather than waiting to be asked.
Phase 1 requires all four questions at once (use the native structured-question UI when the environment provides one, otherwise one concise message with numbered choices): Purpose (pitch deck / teaching-tutorial / conference talk / internal presentation), Length (5-10 / 10-20 / 20+), Content readiness (all ready / rough notes / topic only), and Density. It explicitly says do not ask about inline editing in Phase 1 - users should not have to choose editing behaviour before seeing a draft. Inline editing is a post-draft affordance included by default unless the user asks for a locked or export-only file.
Density is a dimension most template systems lack, and it drives slide count, type scale, text per slide and layout density.
| Density mode | Best for | Design behaviour |
|---|---|---|
| Low density / speaker-led | public talks, keynote-style sharing, live explanation | one idea per slide, large type, strong hierarchy, generous negative space, 1-3 bullets max, more slides if needed |
| High density / reading-first | reports, handouts, async review, detailed internal docs | self-contained slides, structured grids, tables and annotations, 4-8 bullets or 4-6 cards where readable, tighter but still intentional spacing |
Baseline limits apply to both: no scrolling, no overflow, no overlapping panels, no text below comfortable reading size. When content exceeds the selected density mode you split into more slides instead of shrinking until it becomes cramped. If the user's needs are mixed, pick the closer of the two modes rather than inventing a middle option: live-audience persuasion defaults low-density, async circulation or detailed review defaults high-density.
If the user provides an image folder, Step 1.2 runs four moves: scan and list every image file; inspect each one with the agent's image-understanding capability (fall back to filenames and metadata, and ask the user only when necessary); evaluate each for what it shows, USABLE or NOT USABLE with a reason, what concept it represents and its dominant colours; then co-design the outline. That last step is written with emphasis - this is not "plan slides then add images", the structure is designed around text and images together from the start (three screenshots become three feature slides, one logo becomes the title and closing slide). If a usable logo was identified, it is embedded as base64 into each of the three Phase 2 previews, so the user sees their own brand styled three ways.
Verification: scrollHeight is not enough, look at rendered screenshots
Once a bold template is chosen in Phase 3, its design.md is treated as a design recipe: preserve its fonts, palette, decorative vocabulary, spacing rhythm and component grammar; produce a fixed 1920x1080 stage scaled uniformly regardless of whether the source template used deck-stage.js or viewport-fluid CSS; treat viewport-fluid values in design.md as design proportions to translate into stage coordinates rather than keeping them as live reflow rules; keep the output a single self-contained file; and do not copy demo slide content or mimic the source template too literally.
The key sentence is the acceptance criterion: after generating, verify both content overflow and panel overlap in rendered browser screenshots, because scrollHeight checks alone are not enough - grid panels can visually cover each other. That is professional judgement. Overflow checks cannot catch occlusion on the z-axis, and occlusion is the most common failure mode inside a fixed-size stage. The self-generated wildcard path has parallel rules: treat that preview's CSS and layout as the recipe, expand the same visual system across the deck, do not switch back to a preset or bold template after the user chose the custom direction, and design any missing layouts from that system rather than importing patterns from another style.
When there are no images, CSS-generated visuals (gradients, shapes, patterns) are a fully supported first-class path, not a degradation.
Conversion, delivery and sharing
Phase 4 conversion runs python scripts/extract-pptx.py <input.pptx> <output_dir> (needs python-pptx), presents the extracted slide titles, content summaries and image counts for confirmation, then goes through Phase 2 style discovery, and finally generates HTML preserving all text, images (into assets/), slide order and speaker notes (as HTML comments).
Phase 5 delivery has four jobs: delete .frontend-slides/slide-previews/, open the file, tell the user the location, style name, slide count, navigation (arrow keys, space, swipe/tap if enabled) and how to customise (:root CSS variables for colours, the font link for typography, the .reveal class for animations), and note that the artefact has built-in inline editing: hover the top-left corner or press E to enter edit mode, click any text to edit, Ctrl+S to save.
Phase 6 is optional sharing, and both routes come with unusually concrete operational detail.
| Route | Script | Gotchas and mitigations (verbatim from README / SKILL) |
|---|---|---|
| Deploy to a live URL | scripts/deploy.sh (Vercel free tier) | the script auto-detects local assets referenced via src="...", but CSS background-image or unusual paths may be missed, so open the deployed URL and check every image; prefer deploying a whole folder when there are many assets; filenames with spaces work but Vercel encodes them as %20, and hyphens are the fix if images still break; redeploying overwrites the same URL so no new link is needed; first-time users are walked through signup and vercel login |
| Export to PDF | scripts/export-pdf.sh (Playwright) | a headless browser screenshots each slide at 1920x1080 and combines them, so animation and interactivity are not preserved (tell the user up front); the first run downloads about 150MB of Chromium and takes 30-60 seconds; the script finds slides by querying .slide, so externally-created HTML using another class name fails with "0 slides found"; images must be loadable over HTTP (the script serves the HTML's parent directory, so relative paths work and absolute filesystem paths do not); an 18-slide deck can produce a ~20MB PDF, and above 10MB it asks whether to compress - --compact renders at 1280x720 and typically cuts 50-70% with minimal visual difference |
The repo also ships a YouTube walkthrough (372Iksaz8b0) and a deck about the skill made with the skill, as self-evidence.
Installation and runtime fit
Claude Code installs from a custom marketplace source, and the two commands must be sent as two separate messages, not pasted into one prompt.
/plugin marketplace add https://github.com/zarazhangrui/frontend-slides
/plugin install frontend-slides@frontend-slidesThe README specifically warns to use the HTTPS URL: the shorter zarazhangrui/frontend-slides form may make Claude Code attempt SSH, which fails if GitHub is not already in your known_hosts. Once installed the command is /frontend-slides:frontend-slides, because Claude Code namespaces plugin-installed skills as /plugin-name:skill-name; a manually copied standalone skill under ~/.claude/skills/frontend-slides is not namespaced and is invoked as /frontend-slides.
Other agents - the README names Codex, Kimi Code, OpenCode and Gemini CLI - take a different path: send the agent the repo link and have it start from SKILL.md, loading only the referenced support files it needs (STYLE_PRESETS.md, viewport-base.css, html-template.md, animation-patterns.md, bold-template-pack/, scripts/). Agents with filesystem access can install it into a local skills directory for you; those without can still follow SKILL.md for the current session. There is exactly one hard prerequisite: a local coding agent with filesystem access and the ability to run shell commands.
Architecture: progressive disclosure in one table
| File | Purpose | Loaded when |
|---|---|---|
SKILL.md | core workflow and rules | always (on skill invocation) |
STYLE_PRESETS.md | 12 curated visual presets | Phase 2 style selection |
bold-template-pack/selection-index.json | compact metadata for the 34 bold templates | Phase 2 style selection |
bold-template-pack/templates/*/preview.md | small style cards for shortlisted bold previews | Phase 2, after shortlisting |
bold-template-pack/templates/*/design.md | full design system for the selected template | Phase 3, after user selection (only that one) |
viewport-base.css | mandatory fixed-stage CSS | Phase 3 generation (inlined in full) |
html-template.md | HTML structure and JS features | Phase 3 generation |
animation-patterns.md | animation reference and effect-to-feeling guide | Phase 3 generation |
scripts/extract-pptx.py | PPT content extraction | Phase 4 conversion |
scripts/deploy.sh / scripts/export-pdf.sh | deploy to Vercel / export to PDF | Phase 6 sharing |
The author sums the structure up as giving the agent a map first, then revealing only the specific files needed for the current choice. Maintenance-only source metadata and regeneration helpers are deliberately kept outside the user-facing skill package.
Where it sits in agientry
We file it under the Agent Skills documents domain, with runtimes claude-code and codex - the first is the native plugin install path, the second is the first entry in the README's "Other Coding Agents" section. OpenCode, Gemini CLI and Kimi Code take the generic "read SKILL.md" path, so we did not tag them separately: they are a universal fallback rather than an adaptation target of this repo.
It and op7418/guizang-ppt-skill are two answers to the same problem, and they are best read together. frontend-slides bets on discovery - letting non-designers find their own taste by looking at three real previews, with a large template pool (12 presets plus 34 bold templates), a self-generated wildcard leaving room for freedom, and acceptance by eyeballing rendered screenshots. guizang bets on constraint - two visual systems whose class names are not interchangeable, 22 locked layouts, three validators, a px-graded repair ladder, and a built-in local presenter mode with rehearsal timing. If you need to find a visual direction quickly or convert an existing PPTX to the web, pick frontend-slides; for a serious live talk that needs presenter mode and script-verifiable consistency, pick guizang.
An honest statement of our verification boundary: everything here comes from reading README.md (594 lines, including the full list of 34 bold templates and the deployment and export gotchas) and SKILL.md (380 lines, including the five core principles, the fixed-stage rules, the six phases and the progressive-disclosure table). We did not install the plugin, did not produce a real deck, did not test extract-pptx.py against a complex PPTX, and did not measure the actual --compact compression ratio or how the 34 bold templates hold up under real content. All of that is graded as pending reproduction.
SOURCE LINKS