| name | screenshot-workflow |
| description | Captures live screenshots from the Lichtblick web app using Playwright MCP tools. Covers app lifecycle, viewport sizing, navigation, data loading, and image saving. |
Screenshot Workflow
Captures live screenshots from the running Lichtblick web application using
Playwright MCP. All documentation screenshots must come from the live app.
Never use placeholder images.
Prerequisites
- Lichtblick web app running at
http://localhost:8080
(started with yarn web:serve from the lichtblick directory)
- Playwright MCP configured in
.vscode/mcp.json
Browser Mode
Playwright MCP defaults to headed mode (visible browser window) as configured
in .vscode/mcp.json. This is the right default for interactive agents where the
user is present at HITL checkpoints and needs to observe or debug the capture.
Headless mode is also supported and produces equivalent screenshots — use it when:
- Running the visual regression agent unattended over many screenshots
- Working on a remote machine or CI runner with no display
- The agent being used has no browser-interaction HITL checkpoints
To switch to headless, add --headless to the args in .vscode/mcp.json:
"args": ["@playwright/mcp@latest", "--headless", "--viewport-size=1280,800"]
Important for visual regression: baseline screenshots and re-captures must
use the same mode. Mixing headed and headless renders can produce cosmetic
differences (GPU vs software anti-aliasing) that trigger false positives.
The default viewport is 1280×800, set via --viewport-size=1280,800 in
.vscode/mcp.json. Do not change this — all documentation screenshots must use
this viewport for visual consistency.
Element selectors are obtained at runtime from browser_snapshot, which returns
an accessibility tree with exact element references. Never hard-code CSS selectors
or XPath — always derive them from the current snapshot.
Step-by-Step Process
1. Verify the App is Running
Navigate to http://localhost:8080 using browser_navigate.
If the page fails to load, ask the user to start the app:
Please run yarn web:serve in the lichtblick directory and wait for
the webpack compilation to complete (about 60-90 seconds).
Do not attempt to start the app yourself — it requires a long-running
terminal process.
2. Set the Viewport Size
Use browser_resize to 1280x800 before navigating. This is the standard
viewport for all captures — the actual screenshot is then cropped to the
element, not the full window (see Step 6).
3. Load Sample Data (if needed)
Use these approaches in order of preference:
a) Drag-and-drop a local file
Use browser_drop with the file chosen during pre-flight
(from docs/sample-data/source-files/):
paths: ["<absolute-path-to-docs>/sample-data/source-files/<chosen-file>"]
b) Load a layout
If a specific layout was chosen during pre-flight, follow the
app-setup skill to import it from docs/sample-data/layouts/.
c) Install an extension
If an extension was chosen during pre-flight, follow the
app-setup skill to install it from docs/sample-data/extensions/
before loading data or taking screenshots.
4. Navigate to the Target UI Area
Use browser_snapshot to inspect the current page state, then:
- Open the Add panel menu to add a specific panel type
- Click settings icons, sidebar tabs, or menu items
- Use
browser_click on specific UI elements identified in the snapshot
5. Wait for Rendering
After loading data or switching panels:
- Use
browser_wait_for with a short delay (2-3 seconds) to allow
3D rendering, image decoding, or plot drawing to complete
- Use
browser_snapshot to verify the scene is fully rendered
- For 3D/WebGL content, wait 3-5 seconds — the first render is slower
6. Take the Screenshot
Always capture only the element being documented — never the full page.
Use browser_snapshot to locate the exact element reference for the panel,
dialog, or UI component being documented, then pass it as the target parameter
to browser_take_screenshot. This crops the output to the element only and
excludes surrounding chrome, sidebars, and browser UI.
Use browser_take_screenshot with:
type: "png" (always)filename: Target path in the docs images directorytarget: Element reference from browser_snapshot — required
Example:
target: "panel[data-panelid='gauge']" ← from browser_snapshot
filename: "docs/docs/visualization/panels/images/gauge-panel.png"
Only omit target when the subject of documentation is the full application
layout itself (e.g., a page documenting the workspace overview).
7. Verify the Screenshot
After saving:
- Confirm the file exists at the expected path
- Use
browser_snapshot to verify the UI state matches what was captured
- Ensure no debug overlays, developer tools, or dialogs are visible
Naming Conventions
| Screenshot Type | Pattern | Example |
|---|
| Panel overview | <panel-name>.png | gauge-panel.png |
| Panel with feature | <panel-name>-<feature>.png | 3d-custom-layers.png |
| Settings view | <panel-name>-settings.png | state-transitions-settings.png |
| UI interaction | <feature>-<action>.png | raw-messages-filtering.png |
| General feature | <feature-name>.png | search-panels.png |
All filenames: lowercase, hyphenated, .png extension.
Image Placement
Save screenshots to the nearest images/ subdirectory relative to the
markdown file that references them:
| Markdown Location | Image Directory |
|---|
docs/visualization/panels/*.md | docs/visualization/panels/images/ |
docs/visualization/*.md | docs/visualization/images/ |
docs/connecting-to-data/*.md | docs/connecting-to-data/images/ |
docs/*.md | docs/images/ |
guides/*.md | guides/images/ |
Create the images/ directory if it does not exist.
Troubleshooting
App not responding at localhost:8080
The Lichtblick web app is not running. Ask the user to start it:
cd <lichtblick-dir> && yarn web:serve
The first build takes 60-90 seconds. Subsequent hot-reloads are faster.
Blank or partially rendered 3D scene
3D content needs time to initialize WebGL and load assets.
Wait 3-5 seconds after data loads, then verify with browser_snapshot.
Data source dialog blocks the view
After loading a file, the dialog may remain open. Close it with
browser_press_key (Escape) or browser_click on the close button.
Panel shows "No data" or "Waiting for data"
Ensure a data file is loaded AND the panel's topic is configured.
Use browser_snapshot to inspect the panel state and topic settings.
File picker not available in web mode
The web app cannot access the local filesystem via a file dialog.
Use browser_drop (drag-and-drop) or URL-based data loading instead.
Screenshot contains debug overlays
Close any open developer tools, dismiss notification banners, and
ensure no modals are visible before taking the screenshot.
