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](SOURCES.md) (project decks only) | Source-material lookup, extraction heuristics, through-line, project identity | | 3. Intake | [PRESENTATION_PHILOSOPHY.md](references/PRESENTATION_PHILOSOPHY.md), [STORYTELLING.md](references/STORYTELLING.md) | Rhetorical principles, narrative structure, through-line design | | 4. Style direction | [STYLE_PRESETS.md](STYLE_PRESETS.md) | Visual presets and token palettes | | 5. Write spec | [DECK_SPEC.md](DECK_SPEC.md), [SLIDE_KINDS.md](SLIDE_KINDS.md) | Spec schema and slide type catalog | | 6. Compile | [COMPILER_RULES.md](COMPILER_RULES.md), [SLIDEV_REFERENCE.md](SLIDEV_REFERENCE.md) | Compilation phases, Slidev features | | 7. Validate | [ACCEPTANCE_CHECKLIST.md](ACCEPTANCE_CHECKLIST.md), [LLM_TELLS.md](references/LLM_TELLS.md) | Quality gates | | 8. Deliver | (none — instructions below) | — | [PROJECT_DECK_RUBRIC.md](references/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`.