adewale/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.

| Phase | Load these files | Purpose | |-------|-----------------|---------| | 1. Determine mode | (none) | — | | 2. Gather sources | SOURCES.md (project decks only) | Source-material lookup, extraction heuristics, through-line, project identity | | 3. Intake | PRESENTATION_PHILOSOPHY.md, STORYTELLING.md | Rhetorical principles, narrative structure, through-line design | | 4. Style direction | STYLE_PRESETS.md | Visual presets and token palettes | | 5. Write spec | DECK_SPEC.md, SLIDE_KINDS.md | Spec schema and slide type catalog | | 6. Compile | COMPILER_RULES.md, SLIDEV_REFERENCE.md | Compilation phases, Slidev features | | 7. Validate | ACCEPTANCE_CHECKLIST.md, LLM_TELLS.md | Quality gates | | 8. Deliver | (none — instructions below) | — |

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/*.

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
• 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: Run node tools/deck-lint.mjs on the deck directory. Fix all errors before delivery. Warnings are quality flags — address them if feasible.

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 or contrast. Build the deck, then run node tools/render-gate.mjs <built-dist> (or python tools/build-and-verify.py <dir>:<name> --rendered). Fix any flash-bang, contrast, or overflow it reports.

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

One command: builds the deck, creates a Workers Static Assets project, deploys. Requires npx wrangler login first. Pass --name my-talk for a custom worker name.

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:

• 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.