How Visual Styles Are Defined in OpenMontage Using Style Playbooks and Design Tokens

OpenMontage defines visual styles through YAML-based style playbooks stored in the styles/ directory, which are transformed at runtime into CSS design tokens via the style_bridge in lib/hyperframes_style_bridge.py, enabling consistent visual languages across video compositions.

The OpenMontage framework separates design intent from implementation by using declarative configuration files rather than hard-coded values. Visual styles are defined in style playbooks—human-readable YAML files that describe complete visual languages including color palettes, typography, and motion pacing. These playbooks are then converted into design tokens (CSS custom properties) that power both Remotion React renderers and HyperFrames static generators, ensuring a single source of truth for all visual decisions.

What Are Style Playbooks?

Style playbooks are YAML configuration files that serve as the single source of truth for visual styling in OpenMontage. Each playbook describes a complete design system that can be versioned, shared, and reused across projects.

Structure and Sections

A playbook is organized into thematic sections that map to different aspects of visual design:

• visual_language: Defines the color palette and UI tones using keys like background, text, primary, accent, surface, and muted_text.
• typography: Specifies font families for different contexts through heading.font, body.font, and code.font.
• motion: Controls animation pacing via the pace field, accepting values like fast, moderate, or slow.
• asset_generation: Optional guidance for AI-driven image and video asset creation.

File Location and Loading

Playbook files reside in the styles/ directory at the repository root (e.g., styles/clean-professional.yaml). The load_playbook function in styles/playbook_loader.py handles file I/O and validation, returning a Python dictionary that downstream components consume.

from styles.playbook_loader import load_playbook
playbook = load_playbook("clean-professional")

This loader enforces schema validation and provides sensible defaults when optional fields are omitted, ensuring robust runtime behavior even with incomplete configurations.

From Playbooks to Design Tokens

OpenMontage converts static YAML configurations into dynamic design tokens—CSS custom properties that enable runtime theming without code changes. This transformation occurs through two specialized bridges depending on the output target.

The Transformation Pipeline

The framework supports dual rendering targets through separate conversion paths:

1. Remotion Runtime: The _build_theme_from_playbook function in tools/video/video_compose.py constructs a themeConfig prop object consumed by React components during video composition rendering.
2. HyperFrames Runtime: The style_bridge function in lib/hyperframes_style_bridge.py translates playbooks into CSS variable dictionaries and generates human-readable documentation.

Both pathways ensure that design decisions made in YAML propagate consistently to the final output, whether generating MP4 videos via Remotion or static HTML via HyperFrames.

The Style Bridge Algorithm

The lib/hyperframes_style_bridge.py module implements a deterministic six-step algorithm for token generation:

1. Load the playbook (or fall back to an empty dictionary if unspecified).
2. Extract color values using the _first helper, which selects the first entry from palette lists or returns a default token.
3. Normalize fonts via _font, handling both object notation ({font: "Inter"}) and plain string formats.
4. Derive motion easing from the pace field using _motion_easing, converting semantic labels like "moderate" into cubic-bezier curves.
5. Populate the CSS token map, applying any overrides from edit-decisions (project-specific tweaks that take precedence over playbook defaults).
6. Render a DESIGN.md file documenting the generated tokens and their source playbook for designer reference.

The resulting CSS custom properties follow a consistent naming convention: --color-bg, --color-fg, --color-primary, --font-heading, and --ease-primary. These are injected into the <:root> block of the HyperFrames index.html output.

Working with Style Playbooks

Creating and consuming visual styles requires understanding both the YAML authoring format and the token consumption patterns in downstream code.

Sample Playbook Structure

Below is the clean-professional playbook demonstrating the YAML schema:

identity:
  name: clean-professional
visual_language:
  color_palette:
    background: "#FFFFFF"
    text: "#212121"
    primary: "#0D47A1"
    accent: "#FF6F00"
    surface: "#F5F5F5"
    muted_text: "#757575"
typography:
  heading:
    font: "Montserrat"
  body:
    font: "Roboto"
  code:
    font: "JetBrains Mono"
motion:
  pace: "moderate"

Generating CSS Tokens

When processing this playbook through the HyperFrames bridge, OpenMontage produces a dictionary of CSS variables suitable for injection into stylesheets:

from lib.hyperframes_style_bridge import style_bridge

css_vars, design_md = style_bridge(playbook)

# css_vars contains:

# {

#   "--color-bg": "#FFFFFF",

#   "--color-fg": "#212121",

#   "--color-primary": "#0D47A1",

#   "--font-heading": "Montserrat",

#   "--ease-primary": "cubic-bezier(0.5, 0, 0.5, 1)",

#   ...

# }

Consuming Tokens in Components

Components reference these tokens through standard CSS var() functions rather than hard-coded values, enabling runtime theme switching:

.scene-title {
  font-family: var(--font-heading);
  color: var(--color-primary);
  transition: all var(--ease-primary);
}

Generated Documentation

The bridge also produces a DESIGN.md file that documents the design system for stakeholders:

# DESIGN — clean-professional

> Generated by OpenMontage HyperFrames style bridge (source: playbook `clean-professional`).

## Colors

- Background: `#FFFFFF`
- Foreground: `#212121`
- Primary: `#0D47A1`
- Accent: `#FF6F00`

Summary

• Style playbooks are YAML files stored in styles/ that define complete visual languages including colors, fonts, and motion pacing.
• The load_playbook utility in styles/playbook_loader.py parses these files into Python dictionaries for runtime consumption.
• Design tokens are generated via style_bridge in lib/hyperframes_style_bridge.py, converting YAML values into CSS custom properties like --color-primary and --font-heading.
• The bridge uses helper functions _first, _font, and _motion_easing to normalize playbook data into standard CSS formats.
• Both Remotion (_build_theme_from_playbook) and HyperFrames (style_bridge) consume the same playbook format, ensuring visual consistency across video and static outputs.
• Updates to a playbook automatically propagate throughout the project, enabling design system versioning without code changes.

Frequently Asked Questions

What is the difference between a style playbook and a design token in OpenMontage?

A style playbook is the source YAML configuration file (e.g., styles/clean-professional.yaml) that designers author and maintain. A design token is the runtime artifact—specifically a CSS custom property like --color-primary or --font-heading—generated by the style_bridge function. The playbook serves as the human-readable single source of truth, while tokens are the machine-optimized implementation that components actually reference.

How does OpenMontage handle motion pacing from the playbook?

The motion.pace field in the playbook (accepting fast, moderate, or slow) is translated into cubic-bezier easing functions by the _motion_easing helper inside lib/hyperframes_style_bridge.py. For example, a "moderate" pace becomes cubic-bezier(0.5, 0, 0.5, 1), which is then stored in the --ease-primary CSS variable for consistent animation timing across all scenes.

Can I override specific design tokens for individual projects?

Yes. During the sixth step of the style bridge algorithm, the system applies edit-decisions—project-specific tweaks that override playbook defaults before final token generation. This allows individual videos to adjust specific colors or fonts while inheriting the base visual language from the parent playbook, ensuring flexibility without breaking design system consistency.

Where are the style playbooks stored in the OpenMontage repository?

All style playbooks reside in the styles/ directory at the repository root, with individual playbook files named according to their visual identity (e.g., clean-professional.yaml, bold-cinematic.yaml). The load_playbook function in styles/playbook_loader.py discovers and loads these files by name, while lib/playbook_generator.py provides utilities for creating new playbook definitions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}