Theming Your Report¶

Screenwright reports use Material Design 3 color roles and can be fully customized through a YAML theme file. You can change colors, fonts, animation timing, neon glow effects, and persona images.

Creating a Theme File¶

Create a file named screenwright-theme.yaml in your project root:

name: My Project Theme
extends: dark

Screenwright looks for this file automatically when generating the report. The extends field determines the base theme (dark or light). Any properties you specify override the base; everything else uses the defaults.

Color Customization¶

Set a Single Primary Color¶

The easiest way to customize your report is to set just the primary color. Screenwright will auto-generate the entire MD3 tonal palette from it:

colors:
  primary: "#FF6B35"

This generates all 18 color roles (on_primary, primary_container, secondary, surface, and so on) based on the primary color and whether the theme is dark or light.

Override Individual Colors¶

For full control, override any color role individually:

colors:
  primary: "#6750A4"
  on_primary: "#FFFFFF"
  primary_container: "#EADDFF"
  secondary: "#00897B"
  surface: "#121212"
  on_surface: "#E6E1E5"
  error: "#F2B8B5"

The available color roles follow MD3 conventions:

Role	Description
`primary`	Main brand color
`on_primary`	Text/icons on primary color
`primary_container`	Lighter variant of primary
`on_primary_container`	Text/icons on primary container
`secondary`	Accent color for secondary elements
`on_secondary`	Text/icons on secondary
`secondary_container`	Lighter variant of secondary
`on_secondary_container`	Text/icons on secondary container
`tertiary`	Third accent color
`on_tertiary`	Text/icons on tertiary
`error`	Error state color
`on_error`	Text/icons on error
`surface`	Background color
`on_surface`	Default text color
`surface_container`	Card/panel background
`surface_container_high`	Elevated card background
`outline`	Border color
`outline_variant`	Subtle border color

Neon Glow Settings¶

The report uses a neon glow effect on key elements. Configure it:

neon:
  enabled: true
  intensity: 0.3
  blur_radius: 20
  spread_radius: 10

To disable the glow entirely:

neon:
  enabled: false

Property	Default	Description
`enabled`	`true`	Whether glow effects are rendered
`intensity`	`0.3`	Glow opacity (0.0 to 1.0)
`blur_radius`	`20`	CSS blur radius in pixels
`spread_radius`	`10`	CSS spread radius in pixels

Custom Persona Images¶

By default, each Actor is shown with a generic persona SVG. You can assign custom images per Actor:

personas:
  default_image: persona-default.svg
  images:
    Ali: images/ali-avatar.png
    Maryam: images/maryam-avatar.png

Image paths are resolved relative to the YAML file's directory.

Animation Timing¶

Control animation durations throughout the report:

animation:
  actor_entrance_duration_ms: 600
  badge_pop_duration_ms: 300
  badge_stagger_ms: 100
  narration_fade_ms: 400
  arrow_draw_ms: 800
  target_appear_ms: 500
  step_transition_ms: 600
  autoplay_interval_ms: 3000

All values are in milliseconds.

Typography¶

Customize fonts and sizes:

typography:
  brand_font: "Inter, Roboto, system-ui, sans-serif"
  code_font: "JetBrains Mono, Fira Code, monospace"
  title_size: "2rem"
  body_size: "1rem"
  caption_size: "0.875rem"

Complete Example¶

Here is a full theme file showing all available options:

name: Neon Cyber
extends: dark

colors:
  primary: "#00E5FF"

neon:
  enabled: true
  intensity: 0.5
  blur_radius: 25
  spread_radius: 12

animation:
  actor_entrance_duration_ms: 800
  step_transition_ms: 400
  autoplay_interval_ms: 5000

personas:
  images:
    Ali: assets/ali.png
    Maryam: assets/maryam.png

typography:
  brand_font: "Fira Sans, system-ui, sans-serif"
  code_font: "Fira Code, monospace"

Light Theme Example¶

To start from the light base theme:

name: Clean Light
extends: light

colors:
  primary: "#1565C0"

neon:
  enabled: false

typography:
  brand_font: "Nunito, system-ui, sans-serif"

How It Works¶

When Screenwright generates the report:

It looks for screenwright-theme.yaml in the current working directory
If found, it loads the YAML and validates all values
It resolves the base theme (dark or light)
It deep-merges your overrides with the base theme
If only primary is set under colors, the full tonal palette is auto-generated
The merged theme is converted to CSS custom properties and injected into the HTML report