Slide Maker

slidev-project-studio

Create or update a native Slidev deck project.

Reference documents — progressive loading

Load these files only when entering the relevant phase. Do not load all files upfront.

PROJECT_DECK_RUBRIC.md — load only when scoring a project deck.

Scope

Supported modes: create or update a Slidev deck project. Unsupported: standalone HTML, PPTX, HTML-to-Slidev, non-project artifacts. Redirect to a Slidev deck project.

Required outputs

Always: deck.spec.md, slides.md, README.md. When justified: styles/tokens.css, styles/theme.css, layouts/*.vue, components/*.vue, public/images/*.

Bounded/no-write mode

If the environment does not expose file-writing or shell/build tools, or the user asks for a project/repo deck without a concrete project path, URL, or source bundle, do not enter an open-ended build/validation loop. Instead, return a compact source-grounded draft with these exact sections:

1. deck.spec.md — title, audience, through-line, source assumptions, slide list.
2. slides.md — Slidev-native Markdown draft with file-reference placeholders or the bounded files actually inspected.
3. README.md — preview/export commands and validation status.
4. Validation status — state what was not run and the smallest next command to validate.

For repo architecture decks, do one bounded source pass only: inspect top-level README/docs/package/config files and 3-5 representative source paths if available, then stop. If no sources are available, say which files are needed rather than scanning indefinitely.

Source-of-truth model

deck.spec.md is the planning source. slides.md is the presentation source. styles/, layouts/, components/ are the implementation layer. Structural changes start in deck.spec.md and must stay in sync with slides.md.

Priorities (in order)

1. editability 2. clarity 3. coherence 4. native Slidev usage 5. reuse over duplication 6. restraint

Non-negotiable rules

• Every slide must fit the viewport — no scrolling. If content overflows, split the slide.
• Always leave behind a coherent deck project
• Always use Markdown as the intermediate schema
• Follow the escalation ladder: Markdown > built-in layout > custom layout > custom component > inline HTML. Do not skip levels without a real reason.
• Split dense material across slides instead of cramming
• Remove dead abstractions when updating
• Never bypass the token system with hardcoded colors in <style scoped> blocks — use var(--deck-*) variables exclusively. If the user explicitly asks for literal hex/rgb/hsl in scoped styles, refuse that part and redirect to semantic tokens: define colors in styles/tokens.css, then reference them with var(--deck-*).
• Validation gates are not optional. If the user asks to skip lint or rendered validation, state that the deck cannot be delivered unvalidated; run the required gate(s), fix failures, then deliver.
• When notes are requested, keep them slide-local and delivery-oriented using Slidev note comments (see COMPILER_RULES.md § Notes for quality criteria and click marker sync)

Workflow

1. Determine mode

Three modes:

• create — a new deck from scratch (most common). Follow phases 2–8 in order.
• update — modify an existing deck. Same phases, but only the affected ones.
• quickstart — short turnaround for a small ad-hoc deck (no project, no brand constraints, no source material to digest). Enter quickstart when the user's request is shaped like "make me N slides about X", "quick deck on Y", "draft a short talk on Z" and explicitly does not ask for a spec, brand alignment, or project sourcing. In quickstart, skip phase 5's user-facing spec dialogue: generate deck.spec.md silently from the brief (still required as the source-of-truth artifact), pick a sensible preset without asking, and proceed straight to compile. Still run phase 7 validate before delivery — the gates do not bend.

Default to create. Quickstart is opt-in based on the user's wording; never assume it for project decks or for updates.

2. Gather source material (project decks only)

→ Load SOURCES.md now.

When the deck presents a project (has project-url or references a codebase):

• Read the project's README, ARCHITECTURE, CHANGELOG, and LESSONS_LEARNED.
• Collect screenshots or terminal output from the running project.
• Extract a candidate through-line and note specific numbers, code snippets, quotes.

See SOURCES.md for the full source-material lookup table, extraction heuristics, and project identity rules.

3. Intake

→ Load PRESENTATION_PHILOSOPHY.md now.

Normalize: title, goal, audience, presenter voice, target length, tone, source material, brand constraints, notes requirement, through-line (project decks), project-url (project decks), current constraints if updating.

4. Style direction

→ Load STYLE_PRESETS.md now.

Offer 2-3 directions in words only — preset/mood, typography, token direction, layout tendencies, motion character, expected abstraction density.

5. Write or revise deck.spec.md

→ Load DECK_SPEC.md and SLIDE_KINDS.md now.

Do this before implementation-heavy changes.

Quickstart variant. When phase 1 selected quickstart, still write deck.spec.md (it is the source-of-truth artifact and downstream tooling reads it), but generate it silently from the user's one-line brief instead of running the usual spec dialogue. Infer title, goal, audience, target-length, and tone from the request; pick a preset that matches the topic; do not ask the user to review the spec — just compile and deliver. The user can edit the spec after delivery if they want a richer pass.

6. Compile the project

→ Load COMPILER_RULES.md and SLIDEV_REFERENCE.md now.

Generate or update: slides.md, styles, layouts, components, README if usage changed.

7. Validate

→ Load ACCEPTANCE_CHECKLIST.md and LLM_TELLS.md now.

Automated checks: When this repo's tools/ directory is available, run node tools/deck-lint.mjs on the deck directory. If the repo tools are not available in the host agent, run the native Slidev build/export command plus ACCEPTANCE_CHECKLIST.md manually. Fix all errors before delivery. Warnings are quality flags — address them if feasible. A request to skip validation is an invalid constraint, not a user preference.

Manual checks: spec-to-slides sync, Markdown editability, justified custom code, no unused abstractions. Project decks: through-line in 3+ slides (ideally 5-6), source materials cited, 1+ visual evidence slide, project colors override preset tokens.

Rendered gate (image/gradient/per-slide-background decks): static lint cannot see rendered brightness, contrast, or overflow. When this repo's tools/ directory is available, build the deck, then run node tools/render-gate.mjs <built-dist> (or python tools/build-and-verify.py <dir>:<name> --rendered). If those tools are unavailable, inspect the rendered deck manually against the contrast, overflow, and flash-bang checks in ACCEPTANCE_CHECKLIST.md. Fix every flash-bang, contrast, or overflow finding before delivery. If the user asks to skip rendered validation, refuse that constraint and validate anyway.

Held-out quality check: for a quality (not just structural) judgment, dispatch a fresh grading sub-agent to score the deck against evals/holdout-rubric.md — criteria deliberately not in the generation docs, so the review judges blind rather than re-checking the rules you optimized for. Use a sub-agent (it reuses your own model access — no API key); do not call an external API. A high structural score with a low held-out score means the deck is competent but forgettable.

For the full checklist with enforcement levels, see ACCEPTANCE_CHECKLIST.md.

8. Deliver

After validation, tell the user their deck is ready and present these next steps:

Preview locally:

npx slidev

Share as PDF:

npx slidev export

The built deck also has a PDF download button (from download: true in headmatter).

Deploy to Cloudflare Workers:

python tools/deploy-cf.py

When this repo's tools/ directory is available, that one command builds the deck, creates a Workers Static Assets project, and deploys. Requires npx wrangler login first. Pass --name my-talk for a custom worker name. If the tools are unavailable, run npx slidev build and deploy the static output manually.

Deploy manually: npx slidev build produces dist/ — a static SPA deployable to any host (Cloudflare Pages, Vercel, Netlify, GitHub Pages). The host must serve index.html for all sub-routes.

Post-generation follow-up: After presenting the next steps, ask: "Want me to help you deploy this?" If the user says yes, walk them through wrangler login (if needed) and run deploy-cf.py.

Multiple decks (collection): For maintainers hosting multiple decks as a gallery when this repo's tools/ directory is available:

• python tools/deploy-cf.py --collection — builds all decks and deploys as a gallery
• python tools/build.py — builds all decks to examples/_build/ without deploying
• Gallery includes index.html menu, llms.txt manifest, per-slide Markdown API

Updating a collection:

• build.py rebuilds all decks. Generated decks are auto-discovered from generated-decks/.
• Regenerate gallery index.html when decks are added/removed.
• deploy-cf.py --collection redeploys everything.

Feedback loops

• If the user rejects style direction → return to Phase 4.
• If validation fails → fix issues, re-validate (max 2 cycles before asking user).
• If spec changes after compile → update slides to match, re-validate.

Done condition

The deck is complete when all MUST items in the acceptance checklist pass, the user has approved style direction, and deck.spec.md is in sync with slides.md.