When a writing agent should leave the page without a figure

ArcBlockAug 9, 2026

On this site, an agent that writes an article or a document does not start by generating images. It starts by locking the argument, then asks a narrower question: does any place in this piece need a figure so a careful reader can understand something faster or more safely?

Often the honest answer is no. That is not a failure of “rich content.” It is the default we want.

When the answer is yes, the agent does not improvise. It follows a small pipeline that is now part of the writing skills.

The pipeline

Fallback in words: outline → visual-plan → zero or more kind-specific skills (visual-diagram, visual-illustration, visual-screenshot) → body text that includes a fallback even if the file fails → publish.

Flow from outline through visual-plan and kind-specific skills to published body with fallback

The SVG is derived from a committed structured graph; the graph is the authority.

What each skill does

Skill	Job	Does not do
`visual-plan`	Decide whether each section needs a figure; write `visuals/plan.yaml`	Generate pixels
`visual-diagram`	Structured graph → sanitized SVG	Treat AI freehand art as architecture truth
`visual-illustration`	Brief → candidate art; human review before publish	Encode metrics, fake UI, or architecture
`visual-screenshot`	Real product capture + version + date	AI mock of the product

This article is itself a test of that pipeline: it has a plan with two slots, a generated diagram from a graph source, and a decorative illustration from a brief.

When a figure makes sense

Finish this sentence without hand-waving:

At this point the reader needs to grasp X. Without a figure they would likely miss Y. The authority for what the figure shows is Z. If the file fails to load, they can still read W.

Then pick one kind:

If the core is…	Kind	Source
Relationships or step order	diagram	Versioned graph (nodes, edges, ids)
Quantities or a dataset	chart	Real numbers + a table fallback
How a product UI looks now	screenshot	Real capture with version and time
Mood or metaphor	illustration	Brief that forbids smuggling facts into the art
Same-site or allowed embed	embed	Existing site embed rules

If you cannot name X, Y, Z, and W, do not create a slot.

When zero figures is the right call

Skip figures when a table or short list already carries the structure; when the claim is a definition better said in prose; when you would only decorate empty space; when the only “source” would be a model inventing architecture or product chrome; when you are tempted to retrofit old posts for looks alone.

Bulk-illustrating the archive is out of scope. Historical articles stay historical.

How to run it when writing

For a new article or doc:

Finish the argument map or page outline.
Run visual-plan → visuals/plan.yaml (empty slots allowed).
Write body fallbacks for every slot that remains.
For each slot, run the matching skill and commit graph/brief, rendition, and manifest under visuals/.
Keep the file under visuals/renditions/, upload it (media-upload / gh-upload-media.sh), and embed the published https:// URL in Markdown (object-local relative paths currently 404 on the article route).
Illustration stays candidate until a human signs off on the PR.

Scaffold:

bash .claude/skills/visual-plan/scripts/init_visuals.sh \
  blocklets/arcblock/content/articles/<slug> article <slug>

Diagram render:

python3 .claude/skills/visual-diagram/scripts/graph_to_svg.py \
  path/to/visuals/<slot>.graph.json \
  -o path/to/visuals/renditions/<slot>.svg

What this is not

Not a rule that every post becomes a magazine. Not permission for arbitrary HTML, SVG scripts, or iframes in Markdown. Not a claim that every future chart path is finished.

It is a writing-time gate with working skills: plan explicitly, render by kind, keep fallbacks, and allow “no figure” as success.

When it is a poor fit

Free-form canvas or heavy motion: use a design or video path.
Live product proof without an environment to capture UI: state the limit; do not invent a screenshot.
Frozen historical docs: do not “refresh” them with new generated art that pretends to be period-accurate.