Documd Visuals skill

documd visuals

Routing for every diagram, chart, card and layout this document pipeline can render.

Figures are text, in place. A fence (plantuml · vega · echarts · infographic) or bare HTML written into the Markdown is the figure: the viewer draws it live, the block stays editable, and nothing is pre-rendered, built or exported first. documd is optional — export and verification only.

Iron rules

1. Allowed fences — plantuml / puml · vega · vega-lite · echarts · infographic, plus bare HTML — which is how system architecture diagrams, cards and page layouts are drawn.
2. Nothing outside that list. A fence the list does not name is a bug, not a lesser option — there is no second-tier engine.
3. One diagram per fence. Do not put two engines in one block, and never nest fences.
4. **HTML is bare, never ```html** — a fenced block becomes an image. Start from a real file rather than inventing one: layered-with-wings.md for a system, executive-brief-summary.md for a card.
5. Inline the data. vega / vega-lite / echarts must carry their own values / series data; external URLs are unreliable on the export path.
6. State the reading in the copy. Every figure answers one question — put it in the prose or the block's title.
7. Pick a theme, then colour from it. Colours come from one of the themes indexed in styles/palette.md; copy that theme's block for your engine and take every value from it — a hex picked by hand, or two themes in one figure, is a bug. Charts pass the categorical ramp in order; cards use one accent plus neutrals.

Route by goal

Find the reader's goal, open the goal guide, pick an example. Engines are suggestions; the guide and examples are authoritative.

A — data & metrics

Goal	Trigger keywords	Engines	Read
service-reliability	latency · p95/p99 · SLO · SLA · error budget · burn rate · availability · uptime · reliability	echarts vega infographic	goals/service-reliability.md
ops-monitoring	incident load · alert volume · outliers · anomalies · service scorecard · support volume	echarts vega infographic	goals/ops-monitoring.md
delivery-throughput	throughput · cycle time · lead time · velocity · capacity · staffing · backlog · WIP · rank movement	echarts vega infographic	goals/delivery-throughput.md
goal-and-status-reporting	OKR · KPI · target vs actual · goal attainment · status board · dashboard · scorecard	echarts vega infographic html-css	goals/goal-and-status-reporting.md
product-metrics	conversion · funnel · adoption · retention · churn · activation · signup · cohorts · experiment	echarts infographic	goals/product-metrics.md
business-reporting	quarterly results · revenue · ARR · revenue mix · margin · periodic results · forecast	infographic vega echarts	goals/business-reporting.md
go-to-market	pipeline · channel · partner · partner tiers · market entry · sales funnel · SWOT · campaigns	echarts infographic	goals/go-to-market.md
cost-and-budget	cost · spend · budget · cloud bill · savings · cost reduction · capex · unit economics	echarts infographic vega	goals/cost-and-budget.md
data-exploration	correlation · distribution · regression · outlier detection · missing data · small multiples · density	vega echarts	goals/data-exploration.md

B — process & systems

Goal	Trigger keywords	Engines	Read
engineering-operations	standup · sprint ritual · team rhythm · on-call · coverage · shift handover · deploy cadence · checklist	infographic vega echarts	goals/engineering-operations.md
incident-management	incident · postmortem · escalation · triage · runbook · change request · launch readiness · review	infographic echarts html-css	goals/incident-management.md
process-and-workflow	approval · workflow · swimlane · SOP · process map · BPMN · gate · procurement	plantuml infographic	goals/process-and-workflow.md
software-design	class · domain model · component · package · layering · use case · object · C4 container · SysML	plantuml	goals/software-design.md
software-behaviour	state machine · lifecycle · sequence · interaction · messaging · event flow · EIP · deployment	plantuml	goals/software-behaviour.md
dependencies-and-relations	dependency · call graph · impact analysis · coupling · ownership · causality · fishbone	plantuml vega echarts infographic	goals/dependencies-and-relations.md
system-architecture	system architecture · layer stack · zones · pipeline stages · service catalog · request path · connectors	html-css	goals/system-architecture.md

C — infrastructure & governance

Goal	Trigger keywords	Engines	Read
cloud-architecture	AWS · Azure · Kubernetes · container · serverless · IoT · edge · VPC · observability	plantuml infographic	goals/cloud-architecture.md
data-platform	ETL · lakehouse · warehouse · CDC · streaming · ingestion · catalog · ML pipeline · ER model	plantuml	goals/data-platform.md
network-topology	network · topology · DMZ · wireless · firewall · switch · packet · route · traffic	plantuml echarts	goals/network-topology.md
security-and-compliance	zero trust · IAM · encryption · threat model · trust boundary · controls · evidence · audit · compliance · risk	plantuml infographic html-css	goals/security-and-compliance.md
enterprise-architecture	ArchiMate · capability map · value stream · stakeholder map · business architecture	plantuml infographic	goals/enterprise-architecture.md
organization-and-roles	org chart · reporting line · workforce · capability coverage · capability maturity · handoffs · responsibilities	infographic vega echarts html-css	goals/organization-and-roles.md
people-and-hiring	hiring · headcount plan · interview loop · onboarding · career ladder · certifications · progression	infographic	goals/people-and-hiring.md

D — knowledge & expression

Goal	Trigger keywords	Engines	Read
knowledge-and-outline	mind map · outline · knowledge map · concept map · topics · word cloud	plantuml infographic vega echarts	goals/knowledge-and-outline.md
planning-and-roadmap	roadmap · milestone · timeline · Gantt · quarterly plan · release schedule · strategy focus	infographic vega plantuml html-css	goals/planning-and-roadmap.md
migration-and-rollout	migration · cutover · rollout waves · phased delivery · programme · work breakdown	plantuml infographic	goals/migration-and-rollout.md
comparison-and-selection	compare · versus · build or buy · decision record · quadrant · vendor selection · trade-off · priority	infographic html-css	goals/comparison-and-selection.md
internal-documents	memo · brief · charter · abstract · policy · quote · principles	html-css infographic	goals/internal-documents.md
catalogues-and-inventories	catalogue · inventory · entitlements · offerings · standard tools · support tiers	infographic	goals/catalogues-and-inventories.md
customer-and-partner-comms	customer story · case study · sales brief · bulletin · announcement · partner brief · education module	html-css	goals/customer-and-partner-comms.md
theme-and-tone	print · photocopy · handout · low vision · large print · colour-blind · slide · projected · long-form	infographic echarts plantuml	goals/theme-and-tone.md

Engine cheat sheet

Engine	Reach for it when	Look elsewhere when
plantuml	UML/ArchiMate/BPMN semantics, brand and device icons (9,514 stencils), or a relationship graph that should lay itself out	It is a chart
vega / vega-lite	The data needs work first — join, window, fold, regression, density, facets, small multiples	One polished chart with heavy styling (echarts)
echarts	Report-grade chart or KPI dashboard: axes, series, thresholds, annotations, gauges	The data must be transformed first
infographic	A designed-looking board: roadmap, timeline, checklist, comparison, quadrant, knowledge map	Axes, several series or statistical shapes (echarts)
HTML/CSS	Cards, memos, overviews, page-level layouts	Another engine already renders that diagram

Details, limits and pitfalls: plantuml · echarts · vega · infographic · html-css.

Capability boundaries

These are not possible; pick the fallback instead of retrying.

Want	Fallback
3D / globe / WebGL charts (no echarts-gl)	2D echarts; scatter/graph for shape
Geographic maps (no bundled map data, no GeoJSON offline)	schematic rectangle layout, or an HTML/CSS region diagram
dataset.transform in ECharts (throws RangeError in 6.1.0)	sort and derive upstream, then dataset.source
Functions in an echarts option (parsed as JSON)	template strings ("{c}%"), per-item label objects
External data or images (data.url, remote URLs)	inline values, data URLs
PlantUML WBS / Salt / Timing / ditaa / JSON / YAML / EBNF / nwdiag / SDL / math (parse, draw nothing useful)	@startmindmap, a boxed rectangle tree, HTML/CSS mockups, or a code fence
Interactive charts (tooltip, zoom, brush)	annotate directly: labels, thresholds, callouts
Icons in vega / echarts	plantuml stencils
Free-form positioning in infographic	HTML/CSS for pixel control

Reading a document

To read a document in the browser or in VS Code, install docu.md Markdown Viewer: https://docu.md.

Exporting & verifying — optional

Authoring never needs this. The documd CLI converts a document or a diagram source to a file, extracts figures as images, and verifies that blocks render — for when the output is a file. Nothing to install: npx @markdown-viewer/documd in.md out.docx. Flags, formats and the npm-scope warning: converting.md.

When a block does not render

1. Fence in the allowed list? Exactly one block per figure?
2. Is it a listed anti-pattern in that engine's reference (see Engine cheat sheet) — or strict syntax (JSON for echarts/vega, no empty lines in bare HTML)?
3. Then switch to the alternative engine the goal guide names; most scenarios have two.
4. Or verify by rendering: npx @markdown-viewer/documd file.md --assets /tmp/figs.

Where everything lives

catalog/scenarios.md indexes every scenario with its domain, engines, tier and example path — start there; then goals/<domain>.md, engines/<engine>.md, examples/<domain>/<file>.md.