| name | lumen-slides |
| description | Generate magazine-quality scroll-snap presentation deck as single HTML file. 10 slide patterns with reveal animations, keyboard + touch navigation, prefers-reduced-motion support. 4+ aesthetic presets. Invoke when user asks for deck, slides, pitch, presentation, slides from issue |
| version | 0.1.9 |
lumen-slides
Single-file scroll-snap deck. Inlined CSS + JS. Offline-playable. Magazine-quality typography, compositional variety, narrative arc.
📄 Rendered example: docs/examples/slides.html
Tier: capability (atomic) — does not invoke other lumen skills. Composites and playbooks may invoke it.
When to invoke
Slides are always opt-in. Only generate when this skill is explicitly invoked or the user asks for a slide deck.
Triggers: create deck, make a deck, slides, slide deck, presentation deck, pitch deck, slides from #N, keynote-style.
Pipeline (Frame → Template → Structure → Style → Deliver)
Full recipe in references/generate-slides-recipe.md. Summary:
- Frame — infer reader-action / takeaway / tone. Slides have a temporal dimension — compose a story arc, not a list of sections.
- Template — load the pattern registry and assign a
pattern_key to each planned slide. Reference skills/lumen-slides/_templates/index.json for the 10 available patterns and their metadata (composition variants, required/optional slots, CSS class contracts). Use loadTemplateRegistry() or getPatternByKey() from src/utils/template-registry.ts for programmatic access.
- Structure before writing HTML:
- Start with impact (title)
- Build context (overview)
- Deep dive (content, diagrams, data)
- Resolve (summary, next steps)
- Assign a composition (centered / left-heavy / right-heavy / split / edge-aligned / full-bleed) to each slide
- Style — pick ONE aesthetic from the 4 slide presets in
references/slide-patterns.md (Midnight Editorial, Warm Signal, Terminal Mono, Swiss Clean) or riff on a _shared/aesthetics/*.css file. Commit to one direction; carry it through every slide. Vary from previous decks in the same session.
- Deliver — start from
templates/slide-deck.html. All CSS/JS inlined. Offline file:// safe.
10 slide patterns
Exact .slide--{type} selectors recognized by the SlideEngine in templates/slide-deck.html. Full per-pattern HTML structure + decorative SVG + composition variants in references/slide-patterns.md.
| Selector | Use |
|---|
.slide--title | Hero (heading + subtitle + optional bg image) |
.slide--section | Section header (thin heading + color bar) |
.slide--content | Heading + paragraphs + bullet list |
.slide--quote | Full-bleed quote + attribution |
.slide--image | Full-bleed image + optional caption |
.slide--code | Code block with syntax highlighting |
.slide--comparison | Side-by-side columns |
.slide--table | HTML table with sticky header |
.slide--diagram | Inline fgraph or Mermaid; reuse lumen-diagram / lumen-mermaid |
.slide--closing | Final slide (CTA, contact) |
All patterns support .reveal child elements for stagger-in animations.
Template registry
skills/lumen-slides/_templates/index.json is the canonical registry for the 10 slide patterns. Each entry maps a pattern_key to metadata:
| Field | Description |
|---|
pattern_key | Stable identifier (e.g. title, content, diagram) |
name | Human-readable label |
description | When to use the pattern and its visual behavior |
composition_variants | Allowed spatial approaches for this pattern |
required_slots | CSS class selectors that must be present in the slide markup |
optional_slots | Additional selectors that may appear |
css_class_contract | Full set of selectors recognized by the SlideEngine for this pattern |
supports_reveal | Whether .reveal child elements animate on scroll |
For programmatic access, src/utils/template-registry.ts exports:
loadTemplateRegistry() — loads and validates index.json, returns a TemplateRegistry object. Cached after first call.getPatternByKey(key) — looks up a single SlidePattern by pattern_key. Returns undefined if the key is not found.
Validation enforces exactly 10 patterns, unique keys, and the full field schema. This registry is the single source of truth for both human authors (writing HTML by hand) and code generators (producing slides programmatically).
SlideEngine (built into templates/slide-deck.html)
- Scroll-snap container, one slide per viewport
- Keyboard nav: ↑ / ↓ / PgUp / PgDn / Home / End / Space
- Touch swipe (vertical)
prefers-reduced-motion honored (no transitions, no .reveal stagger)- Progress indicator (slide N / total)
- URL fragment sync (
#slide-3) for deep-link
- Print stylesheet (one slide per page)
Compositional variety (hard rule)
Consecutive slides MUST vary their spatial approach. Three centered slides in a row → push one off-axis. Alternate centered / left-heavy / right-heavy / split / edge-aligned / full-bleed.
Visual richness
- Proactively reach for visuals. If
surf CLI is available (which surf), generate images for title slides + full-bleed via surf gemini --generate-image. Embed as base64 data URI.
- Add SVG decorative accents, inline sparklines, mini-charts, and small Mermaid diagrams where they make the story compelling. Visual-first, text-second.
- Library guidance (Mermaid theming, Chart.js, font pairings) in
references/libraries.md.
Aesthetic presets
Two families of preset are available — pick one direction per deck and carry it through every slide.
Theme discovery
Themes resolve via src/utils/theme-resolver.ts in hierarchical order (highest priority wins):
- Project override —
<cwd>/_theme.css in the working directory
- User-global override —
~/.agent/lumen/_theme.css
- Built-in preset fallback —
skills/_shared/aesthetics/{preset}.css
The resolveTheme({ cwd, preset }) function returns the CSS string plus metadata about which source was used (project, global, or preset). If no custom theme is found, it falls back to the named preset (default editorial). This lets teams share a project-level _theme.css, individual users keep a personal default, and one-off decks still pick from the built-in library.
Typographic family (4 — minimalist)
Detail in references/slide-patterns.md. Best for technical / executive audiences where text is the payload.
- Midnight Editorial (
midnight-editorial) — dark serif, warm gold accents, magazine feel
- Warm Signal (
warm-signal) — cream + amber, narrative tone
- Terminal Mono (
terminal-mono) — monospace, high-contrast, technical
- Swiss Clean (
swiss-clean) — minimalist, tight grid, sharp typography
Illustrated family (6 — visual-rich, AI-generation-friendly)
Summary below; detailed per-preset specs (palette tokens, typography, layout rules, decorative SVG fragments, image-prompt templates, do/don't) in references/slide-illustrated-presets.md.
- comic-strip — warm round-headed characters with minimalist bodies, sparse backgrounds, occasional speech bubbles, zigzag ground/grass lines. Beige + sky-blue + grass-green palette. Best for warm, story-led explainers.
- ligne-claire — uniform line weight, flat color fills, 2–4 panel layouts, info-clarity over emotional warmth. Best for technical sequences where comic framing aids comprehension.
- neo-pop-magazine — aggressive typographic contrast (titles ~50% of slide), color-block sections, youth / social-feed aesthetic. Best for launch announcements and consumer-facing decks.
- bauhaus-geometric — circle / triangle / square / star carry semantic meaning per step; primary red-blue-yellow on paper white; form follows function. Best for process / framework decks where shapes reinforce structure.
- engineering-blueprint — white line-drawings on deep blueprint blue (~75% bg coverage), grid paper, dimension lines, red annotations as ~5% accent. Best for systems / architecture decks.
- neo-brutalism — 4–6px thick black borders on every element, high-saturation color blocks, ultra-large sans-serif (3–6vw), 6–10px solid drop shadows. Best for far-distance readability on long decks (auditorium, projection).
Design heuristic — illustration beats minimalism for AI imagery
When generating images for a deck via surf gemini --generate-image or similar, prefer illustrated presets over typographic-minimalist ones. Illustrated styles have an explicit visual vocabulary (lines, characters, color blocks) that image models can exploit; minimalist styles (dark bg + glowing text + whitespace) lack visual elements to anchor generation and produce flat, empty results. Image prompts should be short — 3 sentences describing mood and content beat 30-line specifications.
Or riff on any of _shared/aesthetics/*.css adapted for slides (5 options there).
templates/slide-deck-base.css (lifted from roxabi-forge) provides an alternative styling foundation if you want roxabi's slide tokens instead of visual-explainer's defaults.
Quality checks
- Each slide fits in viewport (100vh) without scroll
- Code slides: syntax highlighting works offline (no CDN dep that breaks
file://)
- Tables: sticky header on scroll within slide
prefers-reduced-motion disables all .reveal- Aesthetic chosen is recorded in HTML comment for traceability
- Compositional rule satisfied (no three consecutive same-composition slides)
- Story arc has an impact-build-resolve shape (no "list of sections")
- Mermaid diagrams (if any) use the zoom-pan pattern from
lumen-mermaid
Output
Single HTML file written to ~/.agent/lumen/<slug>.html. Open in browser.
PI extension route (v0.1.x)
Not wired through lumen-generate_visual PI tool. A deterministic schema (array of typed slides with pattern keys, titles, bullets, and optional diagram references) is feasible but not yet implemented. The LLM-authored CC path remains the right fit for decks that need multi-step compositional planning and image generation.
Sources
