Flow-file format
A flow-file (flows/<name>.flow.yaml) is the YAML description of one user
task and the source of truth for execution. It is Zod-validated on every
parse; unknown keys are rejected, so a typo fails loudly instead of being
ignored. This page covers every field.
Top-level keys
Section titled “Top-level keys”| Key | Required | What it is |
|---|---|---|
name | yes | The flow's name. Output lands under docs/<name>/, so it is a path segment: it starts with a letter or digit, then letters, digits, ., _ and -, contains no .., does not end in ., is not a Windows device name (con, nul, com1, lpt1 and so on) and is at most 64 characters (extends follows the same rule). |
extends | no | Name of another flow whose steps run first. See merge semantics. |
environment | no | Deterministic execution environment. See environment. |
matrix | no | Expands the flow into one variant per locale, color scheme and viewport. See matrix. |
redactions | no | Areas masked on every screenshot this flow produces, halt shots included. |
prerequisites | no | Preconditions the flow assumes, as a list of { key: value } records (string or boolean values), e.g. { logged_in_as: editor } or { feature_flag: "recap.enabled" }. Documentation for the reader and the agent; not executed. |
locators | no | Named canonical locators, referenced from steps as $name. One selector per name; no fallback lists. |
steps | yes | The ordered step list (at least one). |
The top half of a typical flow, before any steps:
name: invite-userextends: login # the login flow's steps run firstprerequisites: - { logged_in_as: admin } # documentation, not executedlocators: invite_button: '[data-testid="invite-user"]:visible' email_field: '[name="email"]'Every step:
| Field | Required | What it is |
|---|---|---|
id | yes | Unique step id (unique across the whole extends merge). Names the screenshot, the write-up, and the halt artifacts. |
action | yes | One of the action types. |
optional | no | Best-effort step: if the action, wait_for, or success throws, skip and continue instead of halting. For conditionally-present UI - a confirm modal that sometimes appears, a first-run tooltip, a cookie banner. A skipped optional step emits no screenshot or annotation. Prefer this over a permissive comma-selector that no-ops on one branch. |
timeout_ms | no | How long, in ms, the step waits for its target (100 to 30000). Unset keeps Playwright's 30 s default, so flows without it run as before. Set it on an optional step so a missing target is skipped in seconds, e.g. 1500. On a wait step it bounds wait_for: { selector } when that has no timeout_ms of its own, and with wait_for: settled it is that wait's budget. Rejected on steps where it would bound nothing. |
target | no | Locator ref ($name) or inline selector. Optional for actions like navigate (which uses value), wait, or show. |
value | no | The action payload: text for fill, file path for upload, key for press, path or URL for navigate, option for select. |
wait_for | no | What to wait for after the action settles. See wait forms. |
success | no | Post-step success criterion. Execution halts if it fails - no selector fallbacks; drift is a signal. See success forms. |
annotation | no | A single callout on this step's screenshot. Shorthand for a one-element annotations array. |
annotations | no | Multiple callouts on the same screenshot, rendered as numbered badges (1, 2, ...). Mutually exclusive with annotation. |
redactions | no | Extra redactions for this step's screenshots, additive on top of the flow-level list. |
only | no | Variants this step runs for; the others skip it. Needs a matrix. |
skip | no | Variants this step is dropped from. Needs a matrix. |
Action types
Section titled “Action types”navigate, click, fill, upload, press, hover, select, check,
uncheck, wait, hide, show.
navigatetakesvalue(a path resolved against the workspace'sapp_url, or an absolute URL) - nottarget.click,hover,check,uncheck,hidetaketarget.fill,select,uploadtaketargetplusvalue.presstakesvalue(the key);targetis optional (focused element when absent).waitis a bare step that just runs itswait_for.hidesetsvisibility: hiddenon every elementtargetmatches, for the rest of the flow or until ashow. The element keeps its box, so the layout around it does not move, and it stays out of every later screenshot. It waits for a match to exist and halts if none does, unless the step isoptional. Hiding a shadow host hides its content, sotarget: nextjs-portalremoves the Next.js dev overlay badge from the shots.showundoeshide: with atarget, thehidethat used that same selector; with none, everyhide.hidematches in the main frame, including open shadow roots, and does not reach into iframes. It marks matches with the reserved attributedata-docsxai-hidden; do not use that attribute in the app under documentation.
One step of each shape:
steps: - { id: open, action: navigate, value: /settings/team, wait_for: load } - { id: add, action: click, target: $invite_button } - { id: email, action: fill, target: $email_field, value: "sam@example.com" } - { id: role, action: select, target: $role_select, value: "Editor" } - { id: avatar, action: upload, target: $avatar_input, value: ./fixtures/avatar.png } - { id: submit, action: press, value: Enter } - { id: peek, action: hover, target: $member_row } - { id: notify, action: check, target: $notify_box } - { id: settle, action: wait, wait_for: network_idle } - { id: badge, action: hide, target: nextjs-portal, optional: true, timeout_ms: 1500 } - { id: badge-back, action: show }wait_for forms
Section titled “wait_for forms”wait_for: network_idle # named primitivewait_for: load # named primitivewait_for: element_stable # polls the step target's bounding box until stable (10s budget)wait_for: settled # fonts loaded, visible images loaded, layout still (step timeout_ms, default 10s)wait_for: { selector: $done_marker } # wait for an element to appear (~30s default)wait_for: { selector: $done_marker, timeout_ms: 180000 } # per-step override for slow backend opswait_for: { timeout_ms: 800 } # blind sleep - last resort, for animations, not stateelement_stable needs a step target to watch; without one it waits on
nothing (lint rule R009). settled needs no target: it waits for web fonts to
finish loading, the images in the viewport to load and the layout of the
visible elements to hold still across consecutive frames, within the step's
timeout_ms (default 10 s, any action). If the page never settles the step
halts with [page never settled: ...] and a message naming what kept moving. The selector form takes a locator ref or inline
selector; timeout_ms is the override for multi-minute backend operations.
success forms
Section titled “success forms”success: { visible: $recap_panel } # element is visiblesuccess: { hidden: $spinner } # no visible matchsuccess: { url_matches: "/dashboard/reports" } # current URL matches the regexsuccess: { text_contains: { selector: $status, text: "Published" } } # element text containsA failed success halts the run with the actual state in the message (the
current URL, how many elements matched, the actual text). Prefer
text_contains on content that only appears in the target state over
structural selectors that may match stale or hidden poppers.
Annotations
Section titled “Annotations”StepAnnotation, used by both annotation and annotations[]:
| Field | Required | What it is |
|---|---|---|
copy | yes | The callout text the reader sees. |
arrow | no | Arrow placement: top-left, top-right, bottom-left, bottom-right, top, bottom, left, right. |
nudge | no | { x, y } pixel offset applied to the callout and arrow after placement; the halo stays on the target. Use it when two callouts on one screenshot would overlap - small values (5 to 40 px) typically suffice. |
target | no | Override: the locator to anchor the halo and arrow to. Default is the step's target. Use this when the step's action transitions the UI - the action target unmounts, and you want to highlight an element that exists in the resulting state. |
placement | no | Burner placement settings, all optional: inside (callout inside a target big enough to hold it), side (top, bottom, left, right: try only that side), align (start, center, end along the edge), pin_arrow (nudge moves only the callout), max_width (120 to 560 px), obstacle_radius (CSS px, 0 to 2000) and obstacle_limit (1 to 40) for the obstacle scan. Copied onto the annotation record; the interactive viewer ignores it. |
copy_by_locale | no | Callout text per locale, keyed by BCP-47 tag, e.g. { es: "Haz clic aqui" }. copy stays required and is the fallback. See matrix. |
only, skip | no | Variants this callout is kept for or dropped from. Same selector as on a step. |
With annotations: (plural), each entry gets a 1-based numbered badge so the
reader sees up front that there is more than one thing to look at.
The two shapes side by side:
# One callout, anchored to the step's own target:annotation: { copy: "Invite a teammate from here", arrow: top-right }
# Several numbered callouts; the first re-anchors via `target` because the# click unmounts the button, and `nudge` separates two nearby callouts:annotations: - { copy: "Send the invite", target: $invite_button, arrow: top, nudge: { x: -30, y: 0 } } - { copy: "The pending row appears here", target: $pending_row, arrow: left }Environment
Section titled “Environment”All fields optional; applied at browser-context creation, so the whole flow runs under them. This block is what makes replays byte-identical:
environment: clock: "2030-01-02T03:04:05Z" # freeze the page clock at this ISO-8601 instant locale: en-GB # BCP-47 language tag timezone: Europe/Amsterdam # IANA timezone viewport: desktop # preset or { width: W, height: H } color_scheme: dark # light | dark reduced_motion: trueViewport presets: desktop is 1440x900, tablet is 834x1112, mobile is
390x844. With extends, environment merges per-key and the child flow
wins - a child can pin just viewport for a responsive variant and inherit
the parent's clock, or override just locale for a locale replay. On
CDP-attached runs the attached Chrome owns its context, so only the clock
applies; the engine logs one stderr warning listing the skipped fields.
Matrix
Section titled “Matrix”A matrix expands one flow-file into a set of variants, so a desktop and a mobile
walk, a light and a dark theme, or an English and a Spanish pass need one file
instead of one copy each. Each axis is optional, at least one is required:
matrix: locales: [en-US, es-ES] color_schemes: [light, dark] viewports: - { name: desktop-1280, width: 1280, height: 800 } - mobile # a preset: desktop, tablet or mobileThe flow runs once per combination: 2 x 2 x 2 = 8 variants here. Each list holds
1 to 64 unique entries and the product may not pass 64; a bigger matrix is a
parse error that names the sizes. A viewport is a preset name or
{ width, height }, optionally with a name (lowercase letters, digits and
dashes, and not screenshots, halts or a Windows device name such as con,
because the name is a directory). Without a name a size is called
<width>x<height>.
Each variant overrides the flow's environment on the axes the matrix names and
keeps the rest, so clock, timezone and reduced_motion apply to every
variant. The variant id joins the axes that are present, in this order:
<locale>.<color_scheme>.<viewport>, for example es-ES.dark.mobile.
Expansion order is locales, then color schemes, then viewports, each in the
order you wrote them, so two runs of one file produce the same variants in the
same order.
Steps and callouts per variant
Section titled “Steps and callouts per variant”only and skip take a map from axis (viewport, color_scheme, locale) to a
list of values. A clause matches a variant when every axis it names matches;
within one list any value matches. only keeps the matching variants, skip
drops them. A locale value matches a variant exactly or by language, so es
matches es-ES. A value that no matrix entry can match is a parse error.
steps: - id: board action: wait target: $title annotations: - target: $title copy: The board shows every task as a card. copy_by_locale: { es: El tablero muestra cada tarea como una tarjeta. } - target: $view_tabs copy: Switch between the board, the backlog and the full list. skip: { viewport: [mobile] } # the tab bar is hidden on mobile - target: $chip copy: Narrow the list by who holds each task. only: { viewport: [mobile] } - id: open-menu action: click target: $menu_button only: { viewport: [mobile] } # the menu button exists on mobile onlycopy_by_locale picks the callout text for the variant's locale: the exact tag
first, then its language, then copy. The locale is the matrix locale, or
environment.locale when the flow has no matrix locales. Anything else that
differs by variant, such as an arrow side, is written as two callouts with only
on each. A variant that ends up with no steps is an error.
Output layout
Section titled “Output layout”Without a matrix nothing changes: docs/<flow>/screenshots/<step>.png,
docs/<flow>/annotations.json and docs/<flow>/halts/. With a matrix every
variant has its own directory:
docs/<flow>/<variant>/screenshots/<step>.pngdocs/<flow>/<variant>/annotations.jsondocs/<flow>/<variant>/halts/<step>.pngThe variant's annotations.json carries a variant object after flow:
{ id, locale, color_scheme, viewport: { name, width, height } }, with the keys
of the axes the matrix has. docsxai render and docsxai burn treat each
<flow>/<variant> as a flow. docsxai run starts one browser session per
variant; --variant <id> runs a single one, and --cdp cannot run a matrix flow
because the attached browser owns its viewport, scheme and locale. A halt names
the variant: [variant es-ES.dark.mobile] step "tap" (click) failed at ....
docsxai lint lists the variants (R015) and warns about a copy_by_locale key no
variant locale uses (R016). docsxai flow-tree prints them next to the flow, and
docsxai diagnose --variant <id> diagnoses one. matrix is not inherited
through extends: the merged flow expands by the child's own matrix, and a
parent step's only or skip is checked against it. export playwright does not
support a matrix flow yet.
Redactions
Section titled “Redactions”Flow-level redactions apply to every screenshot the flow produces - halt
shots included; per-step redactions are additive. Masks are applied before
any pixel hits disk, with deterministic fills, so they never break
reproducibility:
redactions: - { selector: $api_key_field } # element's bounding box at capture time - { selector: $billing_total, style: pixelate } # 16-px mosaic instead of the default solid box - { region: { x: 10, y: 80, width: 220, height: 40 } } # fixed rect in CSS pixelsstyle is box (solid black, the default) or pixelate. A selector that
matches nothing at capture time is skipped with a stderr warning - redacting
an absent element is vacuously satisfied, never a halt. An annotation
anchored to a redacted element would point at a black box; lint rule R010
flags that.
extends merge semantics
Section titled “extends merge semantics”extends: <name> names another flow whose steps run first (resolved at run
time against flows/<name>.flow.yaml). The merge rules:
- The parent's
locatorsandprerequisitesare merged in; this flow wins on name collisions. - Step ids must be unique across the merge; collisions are a resolution error.
environmentmerges per-key, child wins.redactionsconcatenate (parent's plus this flow's).matrixis the child's own; a parent's matrix is not inherited.- Chains are allowed (A extends B extends C); cycles are rejected.
run --stop-afteroperates on the merged step list, so it can target a parent step too.
The typical use is a shared preamble: put the multi-step "get to the right
place" walk in its own flow with no annotations, and have each dependent flow
start with extends: preamble. The un-annotated parent adds zero doc noise,
and iterating on a child's steps stays cheap.
A complete annotated example
Section titled “A complete annotated example”name: publish-postextends: login # the login flow's steps run firstenvironment: clock: "2030-01-02T03:04:05Z" viewport: desktop color_scheme: lightredactions: - { selector: $account_email } # masked on every screenshot, halt shots includedprerequisites: - { logged_in_as: editor }locators: new_post: '[data-testid="new-post"]:visible' editor_body: '[data-testid="editor-body"]' publish_button: '[data-testid="publish"]' live_banner: '[data-testid="live-banner"]' confirm_ok: '[data-testid="confirm-ok"]' account_email: '[data-testid="account-email"]'steps: - id: open-editor action: click target: $new_post wait_for: { selector: $editor_body } success: { visible: $editor_body } annotation: { copy: "Start a new post from anywhere", arrow: top-right }
- id: write-draft action: fill target: $editor_body value: "Release notes, June" wait_for: element_stable
- id: publish action: click target: $publish_button wait_for: { selector: $live_banner, timeout_ms: 120000 } # publishing is a slow backend op success: { visible: $live_banner } annotations: # two numbered callouts on one screenshot - { copy: "Publish ships the post", target: $publish_button, arrow: top, nudge: { x: -30, y: 0 }, } - { copy: "The live banner confirms it", target: $live_banner, arrow: left }
- id: dismiss-confirm action: click target: $confirm_ok optional: true # the modal only appears sometimes wait_for: { selector: $confirm_ok }
- id: confirm-live action: navigate value: /posts wait_for: load success: { text_contains: { selector: "body", text: "Release notes, June" } }Validate with docsxai lint, visualise the extends graph with
docsxai flow-tree, and see Troubleshooting
when a step halts.