carousel-renderer

Carousel Renderer

Turn a CarouselSpec into final slide artifacts. The renderer owns final composition. Image generation may provide supporting assets, but must not be used to compose final text-heavy slides.

Quick Start

Validate and write an HTML preview:

python3 skills/carousel-renderer/scripts/render_carousel.py path/to/spec.json --validate-only

Render PNG slides:

python3 skills/carousel-renderer/scripts/render_carousel.py path/to/spec.json

Default output:

output/carousels/<title-slug>/index.html
output/carousels/<title-slug>/slide-01.png

Use --out-dir, --width, and --height for explicit exports.

Workflow

1. Read the CarouselSpec from carousel-generator or format-adapter.
2. Confirm each slide uses visual_system, not deprecated visual_direction.
3. Run render_carousel.py --validate-only first.
4. Inspect index.html for layout quality, exact text, and visual rhythm.
5. If supporting bitmap assets are missing, generate or source only those assets.
6. Run the renderer without --validate-only to export PNG slides.
7. Check exported PNGs for blank slides, text overflow, cramped cards, and weak depth.

Input Contract

Read references/rendering-contract.md when changing input handling, validation rules, or output artifacts.

Accepted JSON wrappers:

• { "carousel": { ... } }
• { "carousel_spec_json": { "carousel": { ... } } }
• { "adaptation": { "carousel": { ... } } }
• { "format_adaptation_spec_json": { "adaptation": { "carousel": { ... } } } }

Every slide must include:

• visual_system.layout
• visual_system.type
• visual_system.containers
• visual_system.assets
• visual_system.ui_callouts
• visual_system.depth
• visual_system.motion_hint
• visual_system.render_notes

Rendering Rules

• Use HTML/CSS as the source of truth for final composition.
• Preserve all text exactly.
• Prefer CSS layout, cards, pills, badges, step indicators, shadows, overlays, and transforms over bitmap prompt composition.
• Keep default dimensions at 1080x1350.
• Use asymmetric layouts and rule-of-thirds anchoring unless the slide is a CTA or the spec explicitly allows centered composition.
• Do not flatten cards, callouts, and text into a generated image.
• Use generated images only as embedded assets inside the layout.

Validation

Run tests after editing the script:

python3 -m unittest discover -s tests -p 'test_*.py'

Validate the skill:

python3 /Users/segun/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/carousel-renderer

Sample input lives at references/carousel-spec-example.json.