Standalone JS+CSS library to create interactive storyboards: screens connected by SVG arrows, with a diagram-as-code side panel. Zero runtime dependencies, importable via CDN.
FlowBoard renders a pannable/zoomable canvas of screens (cards) grouped into epics (a screen can belong to several) and linked by arrows (bold journey steps, light navigation links). Alongside the canvas sits a Flow-ML editor — a tiny, readable text format that is the single source of truth for the board:
- Type in the panel → the diagram updates.
- Drag, resize, hide, or wire screens on the canvas → the text rewrites itself.
This two-way binding (think dbdiagram.io / Mermaid, but for storyboards) means a board is just a short text document you can version, diff, copy, and paste.
!name = My App
@auth, t=Authentication, c=#6366f1
@admin, t=Admin, c=#e76f51
:login, t=Login, p=form, f=phone, e=auth, x=120, y=80
:home, t=Dashboard, p=dashboard, f=desktop, e="auth admin", x=560, y=80 # in 2 epics
login -> home, l=Login OK, k=main # bold: a step of the journey
home -> login, l=Logout, k=nav # light: menu / back link (ignored by the auto-layout)
login --> home # dashed = secondary path
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/snowpact/html-flow-board@main/flowboard.css">
<script src="https://cdn.jsdelivr.net/gh/snowpact/html-flow-board@main/flowboard.js"></script>Pin a release for stability: replace @main with a tag, e.g. @v0.5.0. Use flowboard.min.js
in production.
Download flowboard.js (or flowboard.min.js) and flowboard.css and include them.
<link rel="stylesheet" href="flowboard.css">
<script src="flowboard.js"></script>
<div id="app"></div>
<script>
FlowBoard.init({
container: '#app',
project: {
name: "My Storyboard",
epics: [
{ id: "auth", label: "Authentication", color: "#6366f1" }
],
screens: [
{ id: "login", title: "Login", epic: "auth", preset: "form", format: "phone" },
{ id: "home", title: "Home", epic: "auth", preset: "dashboard", format: "desktop",
notes: "US-1.1" }
],
arrows: [
{ from: "login", to: "home", label: "Login OK" }
]
}
});
</script>On first load FlowBoard renders your project, then serializes it into the Flow-ML panel and
persists the text in localStorage. From then on, the saved text is what loads (see
Persistence).
The left panel is a small editor with a line-number gutter, syntax highlighting, and a
? cheat-sheet that documents the syntax in the same colors. Flow-ML is line-based and uses
short, comma-separated attributes.
| Line | Meaning |
|---|---|
!name = My App |
Project name (directive) |
@auth, t=Authentication, c=#6366f1 |
Epic — a group, with a color |
:login, t=Login, p=form, f=phone, e=auth |
Screen (note the : prefix) — e="auth admin" for several epics |
``` … ``` (fenced block under a screen) |
Raw HTML body (rendered when preset is custom) |
login -> home, l=ok |
Arrow (solid) — add k=main / k=nav for its weight |
login --> home |
Arrow (dashed) |
# anything |
Comment (ignored) |
Each line is identified by its first character — : screen, @ epic, ! directive, # comment,
or an ->/--> for an arrow — so a screen and an arrow are never ambiguous at a glance.
A screen line starts with : then its id, followed by key=value attributes (any order):
| Key | Meaning | Example |
|---|---|---|
t |
Title | t=Login or t="My screen" |
p |
Preset (body skeleton); omit ⇒ custom |
p=form |
f |
Format (proportions) | f=phone |
e |
Epic id — or several, space-separated (the first one colors the header) | e=auth, e="auth admin" |
n |
Note (shown in the footer) | n="US-1.1" |
x y |
Position on the canvas | x=120, y=80 |
h |
Hidden flag (no value) | … , h |
sz w hg |
Legacy size / width / height (px) | w=400, hg=300 |
@id followed by t= (label) and c= (CSS color, e.g. c=#6366f1).
from -> to (solid) or from --> to (dashed), with optional attributes:
| Key | Meaning |
|---|---|
l |
Label on the arrow |
fs |
From side — source anchor (see Anchors) |
ts |
To side — target anchor |
k |
Weight: main (a journey step — bold, drawn on top) or nav (menu / back link — thin, ignored by the auto-layout). Absent ⇒ standard |
d |
Detail: a code line drawn as chips under the label (split on ·), e.g. d="POST /v1/update · UPDATE_CLOTURE" — turns the label into a card |
n |
Note: a muted line under the detail |
c |
Tint of the label / card: indigo amber green red grey teal pink or any CSS color |
A fenced block immediately after a screen line becomes that screen's HTML body (rendered with
the custom preset). Use the fb-* wireframe classes inside:
:prefs, t=Settings
```
<div class="fb-text title">Preferences</div>
<div class="fb-input">Email</div>
<div class="fb-btn">Save</div>
```
The fence auto-grows (CommonMark style) if your content itself contains a ``` line, so HTML/
Markdown bodies round-trip safely.
Values containing a space, comma, quote, or backslash are wrapped in "…". Inside quotes,
newlines/quotes/backslashes are escaped (\n, \", \\) so any value survives a round-trip on a
single line. You normally never type this by hand — the serializer does it for you.
p= selects the screen body. custom (the default) renders your HTML content; the rest render a
neutral grey wireframe skeleton — handy for sketching before the real markup exists.
custom · blank · form · list · table · dashboard · cardgrid ·
detail · auth · feed · settings · kanban · modal · gallery · nav
Right-click an empty part of the canvas → Create a screen to pick a preset from a visual grid.
Right-click a screen → Change layout to swap its preset. Switching presets never destroys the
HTML you authored — it is kept in the model and reused if you switch back to custom.
f= sets a screen's proportions:
Every format is a minimum — the card grows past it to fit its content (never clips, never scrolls).
| Format | Min size (w × h) |
|---|---|
desktop |
460 × 280 |
phone |
260 × 480 |
square |
360 × 360 |
So a custom HTML body bigger than the format simply makes the card larger.
- Drag to pan — grab the background and move (in Drag mode); wheel to pan, Ctrl+wheel to zoom.
- Mode switch (bottom-right) — Drag (pan) vs Select (cursor). Keys:
V/H/Esc. - Select mode — rubber-band multi-select, click / Cmd-click to toggle, move a group rigidly.
- Drag screens — free repositioning; positions live in the Flow-ML text.
- Anchor dots — hover a screen to reveal anchors, click-drag to create a new arrow.
- Arrow popup (click an arrow) — edit label, swap direction, toggle dashed, cycle the weight (Std → Main → Nav), delete.
- Hover a screen — its arrows are highlighted, every other arrow fades.
- Screen popup (right-click) — change layout/format, toggle its epics (several allowed), edit title, hide/show, delete.
- Epic picker (toolbar) — All screens or focus one epic: only its screens stay, laid out along their arrows and numbered in reading order; your real layout is kept aside and restored (and is what gets saved). Type to filter, ↑ ↓ Enter Esc. Manage epics (add / rename / recolor / delete) sits at the bottom of the menu.
- Notes switch — show / hide screen notes. Spacing − / + — loosen or tighten every gap of the current arrangement around what you are looking at.
- Auto-layout — cycle Flow (journey columns, nav arrows ignored, crossings reduced, crowded columns split) / Epics (one row per epic) / Grid. Generous default gaps leave room for labels.
- Arrow labels — wrapped (≤ 3 lines) and placed on the curve, sliding along it to avoid screens and other labels.
- Dotted grid — constant on-screen size at any zoom; excluded from PNG export.
- Code panel — syntax highlighting, line-number gutter, current-line indicator, a
copy-to-clipboard button, and a
?cheat-sheet. - Export PNG · Reset (restores the default layout + visibility; your text stays the source of truth).
| Field | Type | Description |
|---|---|---|
config.container |
string | HTMLElement |
CSS selector or DOM element |
config.project |
Project |
Initial board (see below) |
config.state |
State? |
Optional restore blob; takes priority over any saved Flow-ML doc |
| Field | Type | Description |
|---|---|---|
name |
string |
Project name (also the localStorage key prefix) |
epics |
Epic[] |
Logical screen groupings |
screens |
Screen[] |
Screens |
arrows |
Arrow[] |
Connections |
| Field | Type | Description |
|---|---|---|
id |
string |
Unique id |
label |
string |
Name shown in the epic picker |
color |
string |
CSS color (screen header, header dots, picker) |
| Field | Type | Description |
|---|---|---|
id |
string |
Unique id |
title |
string |
Header title |
epic |
string |
Primary epic id (drives the header color) |
epics |
string[] |
Every epic the screen belongs to (primary first), when more than one — the others show as dots in the header |
preset |
PresetId |
Body skeleton; absent ⇒ custom |
format |
"desktop" | "phone" | "square" |
Min proportions — the card grows past them to fit content |
notes |
string |
Footer annotation (togglable) |
content |
string |
Raw HTML body (used by the custom preset) |
hidden |
boolean |
Hidden via the eye toggle |
size |
"sm" | "md" | "lg" | "xl" |
Legacy width (240/320/400/520px); prefer format |
| Field | Type | Description |
|---|---|---|
from / to |
string |
Source / destination screen id |
label |
string |
Text on the arrow |
dashed |
boolean |
Dashed style |
kind |
"main" | "nav" |
Weight: journey step (bold) or navigation link (light); absent ⇒ standard |
detail |
string |
Code line drawn as chips under the label (card) |
note |
string |
Muted line under the detail |
color |
string |
Tint of the label / card (palette name or CSS color) |
fromSide / toSide |
string |
Anchor sides (see below) |
Restore a specific board snapshot. When passed, it takes priority over any saved Flow-ML doc.
| Field | Type | Description |
|---|---|---|
positions |
{ [id]: { x, y } } |
Screen positions |
hiddenScreens |
{ [id]: true } |
Hidden screens |
arrows |
Arrow[] |
Arrow set |
zoom / panX / panY |
number |
Viewport |
Flow-ML is the source of truth. Keys are namespaced by project name:
| Key | Holds |
|---|---|
fb-<name>-flowml |
The whole board, as Flow-ML text |
fb-<name>-zoom |
Viewport (zoom, panX, panY) — kept separate from the doc |
Notes:
- The storage key is pinned to the
nameyou pass toinit(), so editing!name =in the panel changes the displayed title without orphaning the saved document. - On reload, a saved
fb-<name>-flowmldoc supersedes the passedconfig.project— unless you pass an explicitconfig.state, which always wins. - Boards saved with the older per-feature keys (
-pos,-hidden,-arrowmods) are migrated to a Flow-ML doc on first load, then the legacy keys are removed.
Each screen exposes 16 anchor points. By default FlowBoard picks the best side; drag an arrow
endpoint handle (or set fs=/ts= in Flow-ML) to pin one.
- Left / right — 5 positions each at 1/6…5/6 of the height:
left-top,left-upper,left-middle,left-lower,left-bottom(same forright-*).left/right⇒ the middle. - Top / bottom — 3 positions each at 1/4, 1/2, 3/4 of the width:
top-left,top,top-right(same forbottom-*).
When several arrows connect the same pair, they auto-spread across sub-positions to avoid overlap.
Use these inside a screen's custom content (or a fenced Flow-ML block) to sketch UI.
Structure — .fb-bar .fb-card .fb-row (.spread .wrap) .fb-sep .fb-section-label
Forms — .fb-input .fb-btn (.outline .danger .secondary .small)
Data — .fb-table .fb-stat-card .fb-list .fb-list-item .fb-badge (.green/.blue/.orange/.red/.purple) .fb-chip
Media & UI — .fb-img .fb-grid-images .fb-icon (.round .lg) .fb-avatar (.sm) .fb-richtext .fb-tabs/.fb-tab (.active) .fb-progress/.fb-progress-fill
Text — .fb-text (.title .subtitle .small .muted)
Helpers — .fb-flex-1 .fb-gap-4/.fb-gap-8 .fb-mt-4/.fb-mt-8
The Flow-ML engine is the hot path (the highlighter re-runs on every keystroke), so it's kept
allocation-light and O(n). Indicative means on a synthetic board (npm run bench, vitest + jsdom):
| Op | 50 screens | 200 screens | 500 screens |
|---|---|---|---|
serialize |
~0.03 ms | ~0.11 ms | ~0.27 ms |
parse |
~0.08 ms | ~0.30 ms | ~0.75 ms |
highlight |
~0.13 ms | ~0.50 ms | ~1.2 ms |
Text → diagram rebuilds are debounced (300 ms) and screens are inserted via a DocumentFragment
(one reflow). A transient/empty edit never wipes the board.
On the canvas: arrow labels are measured on a detached canvas (cached) instead of getBBox()
(no forced layout per label), drag redraws are coalesced to one per animation frame, and hover
emphasis only touches the hovered screen's arrows (the fade is a single CSS class).
Teach Claude Code to generate FlowBoard storyboards. One command installs (or updates) the skill:
npx github:snowpact/html-flow-boardIt asks where to install:
- this project →
./.claude/skills/flowboard(shared with the repo) - your account →
~/.claude/skills/flowboard(available everywhere)
Skip the prompt with --project or --user. Re-run the command any time to update the skill
to the latest version (it overwrites the installed SKILL.md). The skill source lives in
skills/flowboard/SKILL.md.
npm run dev # watch-rebuild src/ + static server on :3000 (loads the built bundle)
npm run build # bundle src/ -> flowboard.js + flowboard.min.js (tsup/esbuild)
npm run typecheck # tsc --noEmit (the type gate; CI-enforced)
npm test # build, then run the vitest + jsdom suite
npm run test:watch # vitest watch
npm run bench # vitest bench (Flow-ML serialize/parse/highlight + rebuild)Source is TypeScript in src/ (one module per responsibility); a build step bundles it to a single
browser IIFE. The committed flowboard.js / flowboard.min.js must match the source — CI fails
if they're stale. See CLAUDE.md for the module map.
| File | Description |
|---|---|
flowboard.js / flowboard.min.js |
Build outputs (committed, served on the CDN) |
flowboard.css |
Library styles (all classes prefixed fb-) |
src/ |
TypeScript source |
index.html |
GitHub Pages demo |
*.test.js, bench/ |
vitest suites + benchmarks |
MIT