Internal · Framework Review

pretty-slides Framework Overview

How we went from 1,000-line AI-generated HTML to a 250-line YAML spec — and why that matters.

How it worksSavingsComponent libraryPros & consRoadmap

Version

v0.1.0

Stack

Node.js · Handlebars · js-yaml

Commit

decbe6a

01 / 07

The Problem

What we were solving

Asking AI to generate a slide deck in raw HTML is like asking it to hand-write assembly.

Old approach — raw HTML

AI writes ~1,000 lines of HTML per deck
Simultaneously invents CSS and content
No component vocabulary — reinvents every card, table, timeline
Navigation JS duplicated in every file
One typo in a CSS rule breaks the whole deck
Impossible to diff or version content vs style

New approach — YAML spec

AI writes ~250 lines of YAML per deck
Only thinks about content — style is pre-built
Named component library — type: card, type: timeline
Nav, progress bar, keyboard shortcuts: written once
Builder validates structure before rendering
YAML diffs cleanly — content changes are obvious

Core insight

Output tokens are the expensive ones (5× cost of input). Anything the AI doesn't have to write saves both money and quality degradation from cognitive load.

4–6×

More HTML than YAML written

~80%

Fewer output tokens per deck

02 / 07

Architecture

How it works

A three-layer pipeline — the AI only touches the top layer.

1 · Content Agent

Claude receives a topic + tight system prompt listing the component catalog. Outputs only valid YAML.

2 · YAML Spec

Declarative slide data — types, text, colors. No HTML, no CSS, no JS. Diffs cleanly in git.

3 · builder.js

Handlebars engine reads spec, dispatches to component templates, inlines theme CSS, emits one self-contained HTML file.

4 · Output HTML

Fully styled, interactive, keyboard-navigable presentation. Zero runtime dependencies.

# Option A — AI generates the YAML
pretty-slides new "Redis Internals" \
  --slides 10 --audience engineers

# Option B — write YAML by hand
# (non-AI editors can author directly)

# Compile to HTML (no AI, deterministic)
pretty-slides build slides.yaml

# Build + browser + live reload
pretty-slides preview slides.yaml

# Explore the component vocabulary
pretty-slides components

What the AI never writes

CSS variables, reset styles, nav JS, keyboard handlers, progress bar, Handlebars templates, grid layout, font imports, canvas chart JS, range-slider wiring.

03 / 07

Expected Savings

By the numbers

Based on measured output from both presentations built so far.

Token comparison — per deck

Metric	Raw HTML	YAML spec	Saving
Output lines	~1,000	~250	75%
Output tokens (est.)	~14,000	~2,800	80%
Cost at Sonnet rates	$0.21	$0.04	$0.17
Thinking scope	Style + content	Content only	qualitative
Build time (AI step)	~45s	~12s	~73%

At 100 decks/month that's ~$17 saved in output tokens alone — but the bigger win is quality. A model thinking only about content writes better content.

183

Lines of YAML (example deck)

1,051

Lines of HTML produced

301

Lines of YAML (harnesses deck)

1,148

Lines of HTML produced

The real saving

The ~4,300 lines of framework code (builder, templates, CSS) are written once and reused across every deck at zero AI cost.

04 / 07

Component Library

Built-in components — live examples

Every cell below is an actual rendered instance of that component type.

◆

card

Feature Card

Accents, badges, symbols, analogy boxes, and meter bars in one component.

callout

Highlights key information inline with a green left border.

callout · warn

Red variant signals caution.

analogy

Bridges technical concepts to familiar mental models from other engineering domains.

timeline · step 1

Vertical dot-connected steps for flows or histories.

Step 2

Supports any number of items.

Step 3

Dots auto-connect via CSS.

table

Metric	Value
p99 latency	3ms
uptime	99.9%
error rate	0.01%

code

def greet(name: str) -> str:
    # syntax highlighting built-in
    return f"Hello, {name}!"

bullets

Supports bold and italic
And inline code in items

Numbered variant
Auto-increments

stat-row

Big numbers for metrics and KPIs:

80%

Tokens saved

4–6×

HTML expansion

05 / 07

Evaluation

Pros & cons

Strengths

80% fewer output tokens — direct cost reduction
Consistent visual language — no drift between decks
AI writes better content — single responsibility
Git-friendly — YAML diffs show intent, not markup noise
Non-AI editable — anyone can tweak YAML without knowing HTML
Zero runtime deps — output is a single self-contained HTML file
Validated output — unknown component types warn at build time

Limitations

Component-constrained — unconventional layouts need new templates
Interactive charts are rigid — fn_body JS is a sharp edge
No visual preview in editor — must build to see result
One theme — dark-minimal only in v0.1
No PDF export — browser print works but isn't great
AI must know the catalog — prompt length grows with more components
No image support — purely typographic for now

06 / 07

Roadmap

What comes next

Prioritized by impact-to-effort ratio.

v0.2 — Near term

light-clean theme
quote component — large pull quote with attribution
icon-row component — emoji/symbol + label grid
steps component — horizontal step flow
Image support (img component, base64 inlined)
Speaker notes (hidden <aside>, toggled with n)

v0.3 — Medium term

PDF export via Puppeteer (pretty-slides export)
Parallel sub-agent generation — one agent per slide
neon-dark and corporate-light themes
Reveal.js output mode (alternative to custom nav)
Schema validation with helpful error messages
Watch mode with browser auto-refresh via WebSocket

v1.0 — Longer term

Web UI — drag-and-drop YAML builder
Plugin system — pretty-slides add-theme / add-component
GitHub Actions integration — build on push
Multi-deck project management
Presenter mode — two-window, current + next slide
Accessibility audit pass (ARIA, contrast ratios)

Summary

The key design decision

Separate what to say from how to show it.

The framework owns the visual layer permanently. The AI owns the content layer per deck. Neither intrudes on the other.

Today

YAML in → HTML out. 80% fewer tokens, consistent design, two working decks.

v0.3

PDF export, parallel generation, 3 themes, schema validation.

v1.0

Web UI, plugin system, presenter mode, GitHub Actions CI.