Interactive Prototype Flows

Workflow Interactive Prototype Flows

agent stardesign

tags

workflowuidslinteractions

context

fragments/tags/inventory

Surface documents can include an interactive prototype player that links surfaces together into a clickable navigation flow. This is declared using two tags after all \{% surface %\} blocks in the same .ui.mdoc file.

Tags

\{% interactions %\}

Wraps one or more \{% clickable %\} tags and defines a named flow prototype.

Attribute	Required	Notes
id	yes	Unique id for this flow player (kebab-case, no prefix) — e.g. bookmark-management-flow
start	yes	Bare surface id of the first screen shown — e.g. bm-library

\{% clickable /%\}

Defines a single navigation link from an element on one surface to another surface.

Attribute	Required	Notes
from	yes	{surfaceId}.{elementId} — e.g. bm-library.open-btn
target	yes	Bare surface id of the destination screen — e.g. bm-detail
transition	no	Animation type: none (default), fade, slide, slide-back

Making DSL elements clickable

To make a DSL element a link target in from, give it an id attribute in the Pug block. The compiler emits this as a data-wf-id HTML attribute that the player uses for click delegation.

button(id="open-btn" variant="primary") Open

The from attribute then references it as {surfaceId}.{elementId}:

from="bm-library.open-btn"

Only elements with an id attribute are interactive — elements without one are ignored by the player.

Transition types

Value	Effect
none	Instant switch (default)
fade	Crossfade 0.2s
slide	Slide in from right (forward navigation)
slide-back	Slide in from left (backward navigation)

Use slide for forward navigation and slide-back for back/cancel actions. Use fade for overlay dismissal.

Example

\{% interactions id="bookmark-management-flow" start="bm-library" %\}
  \{% clickable from="bm-library.open-btn" target="bm-detail" transition="slide" /%\}
  \{% clickable from="bm-detail.back-btn" target="bm-library" transition="slide-back" /%\}
  \{% clickable from="bm-detail.delete-btn" target="bm-confirm-delete" transition="fade" /%\}
  \{% clickable from="bm-confirm-delete.cancel-btn" target="bm-detail" transition="slide-back" /%\}
  \{% clickable from="bm-confirm-delete.confirm-btn" target="bm-library" transition="fade" /%\}
\{% /interactions %\}

The compiler collects all referenced surfaces, renders them into the InteractivePlayer component, and validates all surface and element references.

Do’s and Don’ts

Do:

• Declare all referenced surfaces in the same .ui.mdoc file as the \{% interactions %\} block
• Place \{% interactions %\} after all \{% surface %\} blocks in the file
• Give every clickable element an id attribute in the Pug block
• Use slide for forward navigation and slide-back for back/cancel actions

Don’t:

• Reference surfaces from other files — all surfaces must be in the same .ui.mdoc file
• Place \{% interactions %\} before \{% surface %\} blocks
• Use from or target values that don’t match a declared \{% surface id="..." %\} in the same file
• Omit the start attribute or point it to a surface not declared in the same file

---

Definition of Done

• All interactions blocks placed after surface blocks in the same file
• All from/target references resolve to surfaces declared in the same file
• Start surface exists in the same file