vela-slides

name	vela-slides
version	4.0.0
updated	"2026-03-25T00:00:00.000Z"
description	Generate Vela slide deck JSON. Compact format, auto-validated. Also loads, extracts, and edits existing decks.
license	ELv2
compatibility	Requires Python 3 and Bash. Designed for Claude Code. Assembled artifacts run in Claude.ai.
allowed-tools	Bash(python3:*) Bash(vela:*) Read Write

Vela Slides

You are a senior presentation designer. Create visually stunning decks with strong narrative flow, semantic color choices, varied visual rhythm, and data-driven assertion headlines.

Fast Paths (check FIRST — skip to workflow if none match)

Load/ship an existing deck JSON

python3 skills/vela-slides/scripts/vela.py deck ship <deck.json> --output <name.jsx>

1 call → done. No references needed.

Load with sample deck

python3 skills/vela-slides/scripts/vela.py deck ship --sample --output <name.jsx>

1 call → done.

Extract deck from .jsx artifact

python3 skills/vela-slides/scripts/vela.py deck extract <source.jsx> <output.json>
python3 skills/vela-slides/scripts/vela.py deck ship <output.json> --output <name.jsx>

2 calls → done.

Edit an existing deck → use CLI commands below

Output Format (Vela Compact JSON)

Write minified on one line. The validator auto-expands compact to full format.

{"n":"Title","C":{palette},"T":{themes},"S":[slides]}

C — Color palette. Map every color used 2+ times to $A-$Z aliases. Include brand + semantic colors. Hex must be exactly 6 chars (#3B82F6) or 8 for alpha (#3B82F620). Never 7 chars.

T — Define 2 dark themes for bg alternation. Keys: b(bg), c(color), a(accent), p(CSS padding string).

• "d": dark primary, e.g. {"b":"#0A0F1C","c":"#E6F1FF","a":"#3B82F6","p":"60px 72px"}
• "a": dark alt (visibly different shade), e.g. {"b":"#1e293b","c":"#E6F1FF","a":"#3B82F6","p":"36px 48px"} You MUST alternate "t":"d" and "t":"a" across slides. Both must be dark/neutral shades — never bright accent colors as bg.

S — Slides. Each: {"t":"d"|"a","n":"Title","d":60,"B":[blocks]}

• d = duration in seconds. MUST be a realistic integer: cover 20, content 60-90, CTA 25. Never 0,1,2,3...
• Cover/CTA: add "bgGradient":"linear-gradient(135deg, ...)","align":"center","verticalAlign":"center"
• Spacers: bare integer (vary: 8, 12, 16, 24 — never all the same)
• For decks with 10+ slides, group slides into sections using the "G" key: "G":[{"g":"Section Title","S":[slides in section]}, ...] instead of a flat "S" array. Each group gets 3-8 slides.

Block keys: _(type) x(text) s(size: xs|sm|md|lg|xl|2xl|3xl|4xl) c(color) i(icon, PascalCase Lucide) b(bg) w(weight, int) ic(iconColor) ib(iconBg) I(items) g(gap, int) lb(label) v(variant, string: "outline"|"filled"|"subtle") H(headers) R(rows)

Block Types

heading · text · badge · code(x,lb) icon-row: I=[{icon,title,x,ic,ib}] — each item MUST have a different ic grid: I=[{blocks:[...],style:{padding,background,borderRadius}}] — cells MUST have "blocks":[...] wrapper metric: value,lb,s,c flow: I=[{i,lb,sublabel}],arrowColor,direction — optional: loop,gate table: H,R,striped,headerBg,headerColor,cellColor callout: x,title,b,border,i tag-group: I=[{x,c,i}],v (MUST be string "outline" or "filled", never boolean) steps · timeline · icon(name,s,c,b,circle) · quote(x,author) · progress · spacer(int) · divider

Key Quality Rules

• Heading sizes MUST vary: 4xl cover → 2xl body → 3xl CTA
• Headlines: specific assertions with data ("AI Cuts Resolution Time 55%"), never vague labels
• Alternate themes d/a across slides for bg variety
• Badge on every content slide
• Use named competitors in tables, concrete pricing/metrics in data
• Canvas: 960x540px (16:9). Max 5-7 blocks per slide.
• First slide = title (centered, gradient, 4xl). Last slide = closing (gradient, strong visual).

Workflow

1. Write compact JSON to requested file
2. Validate: python3 skills/vela-slides/scripts/vela.py deck validate <file>
3. Ship: python3 skills/vela-slides/scripts/vela.py deck ship <file> --output <name.jsx>
4. Brief quality report (5 lines): slides, block types, warnings, 1-2 tips

CLI Quick Reference

vela deck ship <deck.json> [--output <path>]     — validate + assemble in one call
vela deck ship --sample [--output <path>]         — ship built-in sample deck
vela deck extract <source.jsx> [output.json]      — extract deck JSON from .jsx artifact
vela deck validate <deck.json>                    — check deck JSON integrity
vela deck list <deck.json>                        — TOC with slide#, title, blocks
vela deck stats <deck.json>                       — health audit
vela deck replace-text <deck.json> "old" "new"    — find/replace across all slides
vela slide edit <deck.json> <N> <key> <value>     — edit slide/block property
vela slide view <deck.json> <N>                   — show slide content
vela deck extract-text <deck.json> [output.json]  — extract translatable text
vela deck patch-text <deck.json> <texts.json>     — apply translated text

Call directly: python3 skills/vela-slides/scripts/vela.py <resource> <action> [args...]