Recording as GIF#

Guidestar demos can be recorded as animated GIFs for use in contexts that don’t support JavaScript — such as Confluence, README files, or slide decks. The recording is performed by a headless browser that plays back the demo and captures frames, then assembles them into a looping GIF.

From a Wireframe#

The examples/record.py script opens each built demo page in headless Chromium, captures frames during one full playback cycle, and assembles them into an animated GIF. Playback controls are hidden during recording.

How it works#

Wireframes are authored once in examples/wireframes/ — these are the layout and styling for your demo UI.

Demo configs live in examples/demos/ as JSON files. Each config references a wireframe and defines the step sequence:

{
  "wireframe": "kitchen-sink.html",
  "title": "Kitchen Sink — All Built-in Actions",
  "steps": [
    "#btn-sidebar@1800:click",
    "#sidebar@800:toggle-class=open",
    "#input-search@1500:set-value=pipeline"
  ],
  "repeat": true,
  "height": "420px"
}

Multiple configs can reference the same wireframe with different step sequences.

A build script (examples/build.py) combines each config with its wireframe and inlines the controller JS and CSS into a single self-contained HTML page.
The recording script (examples/record.py) plays each page and produces a GIF.

Running locally#

# Build self-contained HTML pages
python examples/build.py

# Record animated GIFs (requires: pip install playwright Pillow
# and: playwright install chromium)
python examples/record.py

# Check the output
ls _site/*.html _site/*.gif

Recording options#

python examples/record.py --fps 10 --width 800         # defaults
python examples/record.py --demo kitchen-sink-full      # one demo only
python examples/record.py --site _site --out _site      # custom dirs

Higher --fps produces smoother GIFs but larger files. The default of 10 fps is a good balance.

Demo config reference#

Key	Default	Description
`wireframe`	(required)	Filename of the wireframe HTML in `examples/wireframes/`
`title`	`"Wireframe Demo"`	Page `<title>`
`steps`	`[]`	Array of step shorthand strings or step objects
`repeat`	`true`	Loop the demo on completion
`autoStart`	`true`	Start automatically when visible
`height`	`"100vh"`	Container height in the built page
`pauseOnInteraction`	`true`	Pause on user clicks inside the demo
`initialClass`	`""`	CSS class(es) applied to the content root on load

See Demo Options for full details on step syntax and options.

Reusing wireframes with different step sequences#

The same wireframe can power multiple demos. For example:

examples/
  wireframes/
    kitchen-sink.html          ← one wireframe
  demos/
    kitchen-sink-full.json     ← long demo (all actions)
    kitchen-sink-short.json    ← short demo (highlights only)

Both JSON configs reference "wireframe": "kitchen-sink.html" but define different step sequences. The build script produces a separate self-contained HTML page and GIF for each.

From a Live Application (SPAs and External Sites)#

For complex single-page applications — or any site on a different origin that cannot be loaded via htmlSrc — the Robot Framework Capture pipeline captures the real browser at build time instead of at view time.

Playwright drives the real Chromium browser against the live URL.
API mocking intercepts calls with fixture data via page.route() (no application modifications required).
Screenshots or DOM snapshots are captured at each marked step and assembled into a static wireframe that Guidestar replays without any live page injection.

The captured wireframe feeds the same guidestar-build pipeline and can also be recorded as a GIF with guidestar-record — see Robot Framework Capture for the full workflow.