Describe meaning. Generate the visual.
Visual Workbench is a metadata-driven visual modeling engine for processes, plans, data flows, checkpoints, handoffs, dependencies and relationships. The source of truth is Markdown + structured metadata; layout and presentation are generated automatically.
Open the live generated gallery.
The goal is not to be another drawing tool. It is a small visual language, method library and rendering engine that lets humans and agents describe what things are and how they relate, then produces consistent, business-readable views.
From a repository checkout, install the locked dependencies and render an executive view from the committed synthetic handoff example:
npm ci --ignore-scripts --no-audit --no-fund \
&& npm run build \
&& node dist/cli.js validate examples/order-fulfillment-lanes.md \
&& node dist/cli.js render examples/order-fulfillment-lanes.md \
--view executive \
--output /tmp/visual-workbench-proof.svgExpected artifact: a non-empty /tmp/visual-workbench-proof.svg showing the executive order-fulfilment path generated without source coordinates. Compare it with the public generated example, or follow the release-pinned walkthrough to verify the release digest.
This proof uses synthetic example data. It demonstrates validation and deterministic rendering for the supported source distribution; it does not certify production data, guarantee that a view answers every audience's question, or replace human review.
Most diagram-as-code tools still make authors think like diagram designers: boxes, arrows, shapes and layout hints. Visual Workbench moves the authoring layer up one level.
Semantic source
│
├── process / handoff view
├── executive view
├── data view
├── controls view
└── exceptions view
│
▼
automatic business visual
A model contains no x/y coordinates and no manually chosen colors.
---
visual:
title: Order fulfillment
kind: handoff
groups:
- id: business
label: Business
order: 1
- id: platform
label: Platform
order: 2
nodes:
- id: request
label: Order approved
type: outcome
group: business
- id: validate
label: Validate payload
type: checkpoint
group: platform
- id: available
label: Order available
type: outcome
group: business
status: success
edges:
- from: request
to: validate
type: data
- from: validate
to: available
type: flow
views:
- id: executive
focus: executive
kind: process
---The package is not published to the npm registry. The supported v0.1 path is to run it from a checked-out repository with Node.js 20 or later:
git clone https://github.com/dkharlanau/visual-workbench.git
cd visual-workbench
npm ci
npm run build
node dist/cli.js render examples/order-fulfillment-lanes.md -o handoffs.svg
node dist/cli.js render examples/order-fulfillment-lanes.md --view executive -o executive.svg
node dist/cli.js render-views examples/supply-chain.md --output-dir .artifacts/viewsFor the pinned tag, expected digest, and release boundary, use the golden quickstart.
Markdown + semantic metadata
↓
Zod validation
↓
Graphology semantic graph
↓
Named view projection
↓
Visual method policy
↓
ELK.js global graph layout
↓
lane projection + edge rerouting
↓
Visual Workbench visual grammar
├── SVG
└── standalone HTML
- Graphology keeps the semantic graph independent from layout and rendering.
- ELK.js establishes the global graph structure and flow.
- Visual Workbench lane composition preserves ELK's global sequence while placing nodes into semantic ownership lanes and rebuilding orthogonal routes.
- Custom SVG rendering keeps the business-facing visual grammar under our control.
- A future Cytoscape.js adapter can provide interactive exploration without becoming the source of truth.
process, checkpoint-flow, data-flow, system-flow, plan, roadmap, timeline, handoff, dependency-map, relationship.
kind is not just a label. Each method maps to a layout policy. Directed flows use layered layouts while relationship maps switch to a non-hierarchical stress layout.
Named views answer different questions from the same semantic source. Built-in focus presets are all, executive, flow, data, controls and exceptions. A view can override the visual method and apply semantic filters.
When a view hides an intermediate node, Visual Workbench contracts the hidden directed path so the visible business flow remains connected instead of producing disconnected boxes.
See named views.
groups turn ownership, systems or responsibility boundaries into swimlanes. For left-to-right flows the lanes are horizontal; for top-to-bottom flows they become vertical automatically. Every node must belong to a lane when lane groups are active.
Named views automatically remove lanes that become empty after projection.
See semantic groups and swimlanes.
stages express ordered planning periods such as Now, Next, Pilot and Scale. The renderer derives bands, spacing and edge routes; authors assign meaning without drawing columns. Every node must belong to a stage while stages are active. Stages and lane groups cannot be combined in one model yet.
node dist/cli.js render examples/product-roadmap.md -o product-roadmap.svg
node dist/cli.js render examples/product-roadmap.md --view outcomes -o roadmap-outcomes.svgNamed views can use includeStages and excludeStages to focus on selected periods. See the metadata language and the complete roadmap example.
Nodes: step, system, data, role, decision, checkpoint, milestone, outcome, risk, note.
Relationships: flow, data, dependency, relation, control, exception.
Status is semantic (neutral, success, warning, danger, muted). The renderer owns the actual presentation.
AGENTS.md defines the core rule: do not draw; model meaning. Reusable skills in skills/ teach agents to choose a method, build a compact semantic source and define views or lanes only when they improve the reader's question.
The JSON Schema at schemas/visual-workbench.schema.json is intended for IDE validation and agent tooling.
src/
schema.ts metadata language
parser.ts Markdown/YAML ingestion + diagnostics
model.ts Graphology semantic graph
views.ts named-view projection + path contraction
methods.ts visual method policies
layout.ts ELK adapter + base graph geometry
lanes.ts semantic lane projection + orthogonal rerouting
stages.ts ordered roadmap stage composition + routing
themes.ts presentation tokens
renderers/ SVG + standalone HTML
cli.ts render / views / render-views / validate / inspect
examples/ process, plan, roadmap, data, supply-chain and handoff models
docs/ methodology, language, views, groups, architecture and roadmap
schemas/ machine-readable metadata contract
skills/ reusable visual-thinking agent skills
tests/ parser, method, view, lane and rendering tests
- Model meaning, never coordinates.
- Prefer one clear reading path over visual completeness.
- Treat data, controls and exceptions as first-class objects.
- Keep normal flow visually dominant; make exceptions visible without making the whole canvas red.
- Choose the visual method from the question the reader needs answered.
- Generate multiple views from one semantic model instead of duplicating sources.
- Preserve meaningful connectivity when a view hides intermediate detail.
- Use lanes for meaningful partitions such as ownership or system boundaries, not decoration.
- Use stages for meaningful planning periods, not manually drawn columns.
- Let agents produce or transform metadata, but keep final rendering deterministic.
See methodology, language, architecture, visual methods, named views, groups and roadmap.
- Enterprise Architecture Composer emits native coordinate-free Visual Workbench Markdown. The pinned compatibility workflow generates a real architecture and renders all four named views; it is evidence for the tested revisions only.
- Project Evidence Graph remains the traceability source for the read-only Project Evidence adapter. Visual Workbench preserves evidence references but does not revalidate them.
- Mapping as Code can emit a semantic data-flow projection as described in the mapping integration guide. Mapping rules remain owned by the producer.
- Process as Code owns process steps, roles, gates, and transitions. A Visual Workbench view may render a bounded coordinate-free projection, but it does not become the process contract or imply a native adapter where none is tested.
- Interface as Code owns operational integration contracts, including retry, recovery, monitoring, and ownership semantics. Visual Workbench may present selected systems, data, and controls while keeping the upstream contract authoritative.
- Reconciliation as Code owns reconciliation controls and retained run evidence. A visual projection can expose selected checkpoints and outcomes, but it does not execute controls or verify evidence.
- Cutover Graph owns cutover tasks, dependencies, timing, readiness, and contingency state. Any Visual Workbench projection should remain bounded and preserve stable source references rather than copying cutover semantics.
- Agent-Ready Web Profile can describe the public gallery, manifest and schema as discoverable web surfaces. It does not validate visual semantics.
- AI CV Builder may link to a published visual as evidence, but there is no direct model exchange between the projects.
v0.1 source distribution. Semantic Markdown → validated graph → named semantic views → method-specific ELK layout → semantic swimlanes or roadmap stages → SVG/HTML is implemented and exercised by the public generated gallery. npm publication is not part of the current distribution contract. Next: timeline-specific date grammar, visual regression, cluster views and an interactive workbench.
Release resources: v0.1.2 notes · release and compatibility policy · golden quickstart · 15-minute usability test · contributing and feedback · changelog
MIT. See LICENSE.
Created and maintained by Dzmitryi Kharlanau, an SAP consultant and system analyst working across enterprise architecture, data, integration, operations, and practical AI.