Diagrams and Illustrations: Explain How a Mechanism Works

A diagram shows how named parts connect, what moves between them, and what outcome those relationships produce. Use it when readers need several relationships at once, while keeping the explanation available as text.

How a page becomes retrievable: source pages pass through extraction and normalization before their useful passages reach an answer index.

1. Source pages provide HTML, headings, images, and structured fields.
2. Extract and normalize removes presentation noise while preserving text, hierarchy, entities, and relationships.
3. Answer index stores retrievable passages that can be matched to a later question.
4. The first arrow carries the page representation into processing; the second carries normalized, searchable passages into the index.

The drawing makes the flow visible at a glance. The caption and numbered explanation carry the same meaning without the image. That two-channel contract distinguishes an explanatory diagram from decorative artwork.

Why this element matters

Prose can force readers to remember several parts before revealing how they relate. A diagram externalizes that model: nodes show parts, connectors show relationships, and boundaries show scope. It is most useful when order alone is insufficient. A sentence can say that a crawler fetches a page, a parser extracts content, and an index stores passages; a diagram can also show failure points, parallel routes, and feedback. It reduces reconstruction effort, not the need for precise wording.

A diagram can also mislead faster than prose. An unlabeled arrow may mean causation, transfer, sequence, or association; a loop may falsely imply automatic feedback. Every relationship needs an explicit, defensible meaning.

Machine extractability is the ability of software to isolate a content unit without losing its meaning. Search systems, translation tools, screen readers, and AI retrieval systems cannot be expected to reconstruct a mechanism from pixels. Optical character recognition may recover labels, but not what an arrow or boundary means. A title, caption, structured nodes and connectors, and visible text equivalent make the mechanism extractable without computer vision.

The shared element writing rules set the precedence rule: choose an element by the job the passage performs, not by its heading or appearance. This page takes precedence for diagram-specific fields, density limits, text-equivalent requirements, and accessibility behavior. If the content’s job is to explain a mechanism visually, use the diagram element rather than a generic image with an improvised caption.

When to use it

Use a diagram when the conclusion depends on seeing at least two relationships together. Strong uses include a process with branches or feedback, a system whose components exchange data, a lifecycle that returns to an earlier state, a causal chain with an intervening factor, or a conceptual model whose boundaries matter. The reader should be able to answer a concrete question from the drawing, such as “Where can this process fail?” or “Which component sends the normalized record?”

Apply the prose test first: write the mechanism in three to eight sentences. If it has no cross-reference, branch, loop, or spatial relationship, prose is probably better. A diagram earns its space when an accurate text equivalent is cognitively expensive to assemble.

Near misses are common:

• Use a step list for executable actions; arrows cannot replace prerequisites, success checks, or recovery instructions.
• Use a comparison table for repeated attributes across alternatives. An unlabeled two-axis picture hides criteria.
• Use a decision tree for routes chosen by explicit conditions. A general flow explains movement, not a decision.
• Use an annotated screenshot to locate controls in a real interface. A redraw loses that evidence.
• Use a chart when quantitative scale encodes values. A decorative rising arrow must not imply measured growth.
• Use an inline image to depict an object, place, or result rather than a mechanism.

Do not use a diagram as decoration or boxed repetition. Mark hypothetical, disputed, conditional, or simplified relationships in both image and text.

Ready to Monitor Your AI Visibility?

Track how AI chatbots mention your brand across ChatGPT, Perplexity, and other platforms.

Get Started Contact

Where to place it

Place the diagram after the paragraph that introduces the mechanism and question. Follow it with the visible text equivalent, then interpretation, evidence, limitations, or actions.

Keep title, image, caption, key, and text equivalent in one figure region. Nothing may separate the image from its explanation. Put a longer equivalent directly after it under “In text”.

A diagram may not sit directly beside another full-width diagram, chart, video, image gallery, dense table, or screenshot. Insert explanatory prose before the next dense visual. Do not place it inside a table cell, list item, accordion, callout, clickable card, or figure.

For procedures, put an overview before the first action, not between coupled steps. In arguments, place it after the mechanism claim and before evidence. On product pages, place it after the capability explanation, never above the direct answer just to look technical.

Anatomy

The anatomy describes meaning, not styling. Box shadows, illustration style, arrow thickness, corner radius, and background color belong to the renderer or art direction.

1. Title: Names the mechanism or question in three to ten words.
2. Scope statement: Defines what the diagram includes, excludes, or simplifies in one sentence.
3. Node: Represents one component, state, actor, input, or outcome.
4. Node label: Uses a concrete noun phrase, not an unexplained abbreviation.
5. Connector: Represents one declared relationship between two nodes.
6. Connector label: Names that relationship with a verb or transferred object, such as “sends events” or “produces passages.”
7. Direction marker: Shows the reading or transfer direction without relying on placement alone.
8. Boundary: Groups items that share ownership, phase, environment, or scope.
9. Key: Defines any line pattern, symbol, or color that changes meaning.
10. Caption: States the principal conclusion rather than repeating the title.
11. Source note: Identifies the evidence or owner when the model is derived from research, policy, or a proprietary system.
12. Text equivalent: Restates every meaning-bearing node, connector, direction, condition, boundary, and exception in readable order.

Stay Updated on AI Visibility Trends

Get the latest insights on AI mentions, brand monitoring, and optimization strategies.

Email address

Subscribe

Design examples

Every variant requires a title, caption, text equivalent, and explicit connector meanings. Choose the simplest variant that answers the question.

Linear process flow

Use three to seven stages when the mechanism moves mainly in one direction. Label what moves between stages; do not rely on arrows alone. If the reader must execute the stages, pair the overview with a separate step list.

System map

Use three to nine components when ownership, interfaces, or data exchange matters more than chronology. Boundaries identify environments or teams; crossing lines signal a need to regroup or split the view.

Causal chain

Use this for a cause, intermediate mechanism, and outcome. Mark conditions and uncertainty. Arrows must never turn correlation into causation; prose and sources must support every causal claim.

Lifecycle loop

Use a loop only when output becomes a later input. Number stages and state the restart trigger; a decorative circle falsely implies repetition.

Overview with detail inset

Use one inset when a component needs detail but depends on system context. Repeat its label. More than one inset usually needs a separate diagram.

On mobile, stack linear diagrams in reading order. A system map may become a simplified overview plus numbered relationships. Never require horizontal page scrolling or zoom for meaning.

Parameters

The content model stores the mechanism. Coordinates, colors, font sizes, icon choices, connector routing, and responsive breakpoints belong to the renderer or source artwork.

source is required for external research, standards, regulated processes, or adapted models. Each node and connector must appear in the text equivalent; prose may combine repetition.

Syntax and code examples

The three mappings preserve the same fields. Example asset paths describe the production contract; they must not appear as live image references until those files exist.

Portable Markdown directive

:::diagram{variant=process src="/cdn-assets/seo-playbook/examples/content-pipeline.svg" alt="Three-stage flow from source pages through extraction and normalization to an answer index"}
## How a page becomes retrievable

The model covers content processing after a page has been fetched.

::item{id=source-pages}
### Source pages

Provide HTML, headings, images, and structured fields.
::
::item{id=extract-normalize}
### Extract and normalize

Preserve useful text, hierarchy, entities, and relationships.
::
::item{id=answer-index}
### Answer index

Stores passages that can be matched to a question.
::
::relationship{from=source-pages to=extract-normalize label="sends page representation" kind=flow}
::relationship{from=extract-normalize to=answer-index label="produces retrievable passages" kind=flow}

Normalized passages reach the answer index only after useful structure is preserved.

### In text

Source pages send their page representation to extraction and normalization. That stage preserves useful text, hierarchy, entities, and relationships, then produces retrievable passages for the answer index.
:::

The first heading maps to title; the next paragraph maps to scope; item directives define nodes; relationship directives define connectors; the paragraph after them maps to caption; and the In text section maps to textEquivalent.

Hugo shortcode mapping

{{< diagram variant="process" src="/cdn-assets/seo-playbook/examples/content-pipeline.svg" alt="Three-stage flow from source pages through extraction and normalization to an answer index" >}}
## How a page becomes retrievable
{{< diagram-node id="source-pages" label="Source pages" >}}Provides page content.{{< /diagram-node >}}
{{< diagram-node id="extract-normalize" label="Extract and normalize" >}}Preserves useful structure.{{< /diagram-node >}}
{{< diagram-node id="answer-index" label="Answer index" >}}Stores passages.{{< /diagram-node >}}
{{< diagram-relationship from="source-pages" to="extract-normalize" label="sends page representation" kind="flow" >}}
{{< diagram-relationship from="extract-normalize" to="answer-index" label="produces retrievable passages" kind="flow" >}}
### In text
Source pages send content for extraction and normalization, which produces passages for the answer index.
{{< /diagram >}}

Named parameters are used exclusively. This is a portable adapter specification, not a claim that these shortcodes are registered in the current theme. Until an approved renderer exists, publish a semantic figure through the established image pipeline and keep its text equivalent in normal page content.

WordPress block

<!-- wp:amicited/diagram {"variant":"process","src":"/cdn-assets/seo-playbook/examples/content-pipeline.svg","alt":"Three-stage flow from source pages through extraction and normalization to an answer index"} -->
<figure>
  <h2>How a page becomes retrievable</h2>
  <img src="/cdn-assets/seo-playbook/examples/content-pipeline.svg"
       alt="Three-stage flow from source pages through extraction and normalization to an answer index">
  <figcaption>Normalized passages reach the answer index only after useful structure is preserved.</figcaption>
  <div class="diagram-text-equivalent">
    <h3>In text</h3>
    <p>Source pages send content for extraction and normalization, which produces passages for the answer index.</p>
  </div>
</figure>
<!-- /wp:amicited/diagram -->

Store nodes and connectors as block attributes. Export must retain them and the text equivalent; a flattened image is not portable content.

Examples

Good: the drawing and prose make the same claim

The good version answers one question: how a submitted question becomes a supported answer. Four concrete nodes follow a clear direction. Connector labels distinguish routing from retrieval and composition. A dashed feedback path is defined in the key as optional human review, so it does not imply an automatic loop. The caption states the conclusion, and the adjacent text names every stage and transfer.

This gives visual readers a fast model while text carries the same mechanism and qualification. Machines receive named relationships without guessing from coordinates.

Bad: a persuasive tangle with no declared meaning

The bad version puts “AI” in the center and surrounds it with vague nouns such as content, data, users, trust, revenue, and growth. Unlabeled arrows point both ways, but the reader cannot tell whether they mean causation, exchange, sequence, or association. Color appears meaningful but has no key. The growth arrow implies improvement without data. Small labels become unreadable on mobile, and no prose explains the claimed mechanism.

Repair it by choosing one question, removing irrelevant nodes, naming connectors, separating causes from associations, and adding scope, caption, text equivalent, and sources. If only benefits remain, write a list.

Schema markup and accessibility

A diagram has no dedicated Schema.org type or independent rich-result eligibility. A meaningful diagram may populate Article.image or an ImageObject with accurate URL, caption, dimensions, creator, credit, copyright, and license data. Do not invent metadata or a relationship vocabulary; nodes and connectors remain visible content.

Use <figure> for image and caption. Alt text identifies the mechanism and conclusion rather than transcribing it. Aim for 40–180 characters and avoid “diagram of.” Example: “Three-stage flow from source pages through extraction and normalization to an answer index.”

The visible text equivalent includes every meaningful node, connector, condition, feedback trigger, boundary, key, and exception. Do not hide it in ARIA, hover text, metadata, or a closed accordion.

Pair color, icons, patterns, shape, and position with text labels. Maintain contrast, visible arrowheads, and a reading order matching the text equivalent. Real SVG text is useful, but does not replace visible prose.

At 320 CSS pixels, stack, simplify, or render a mobile view from the same data. Never remove nodes, crop connectors, or change reading order. Nearby text must retain all essential meaning without zoom.

Writing rules

Write and verify the text first, then draw only relationships it contains. This prevents visual polish from introducing claims.

• Give the diagram one question or mechanism. Do not combine architecture, workflow, benefits, and roadmap in one canvas.
• Use 3–9 primary nodes, with 12 as the maximum. Split an overloaded model into overview and detail figures.
• Label nodes with 1–6 concrete words. Define abbreviations on first use in page text and avoid internal team names that readers cannot interpret.
• Label every meaning-bearing connector with a verb phrase or transferred object of 1–6 words. “Sends events” is clearer than “integration.”
• Keep the caption to 8–30 words and make it state the conclusion or relationship the reader should retain.
• Keep the scope statement to one sentence. State exclusions or simplifications when omitting them could change interpretation.
• Keep the text equivalent to 50–250 words unless accuracy requires more.
• Use an explanatory, neutral tone. Separate what the system does from what it may do, should do, or is hypothesized to do.
• Mark uncertainty with words such as “may,” “conditional,” or “proposed,” and define dashed or dotted paths in the key.
• Never put paragraphs, citations, raw URLs, promotional slogans, precise evidence, or complete instructions inside the artwork. Put them in selectable page text.
• Never use icons without labels, color without a second cue, or arrows without declared meaning.
• Never imply scale, quantity, causal strength, certainty, or measured growth through size or direction unless the evidence and key support that encoding.
• Never publish a nonexistent asset path; keep pending artwork as a capture comment with screenshotsPending = true.

Post types that use it

The postTypes frontmatter is the registered join. Each listed post type uses the same diagram contract but at a different threshold.

QA checklist

• Purpose: One mechanism or flow is easier to grasp visually than from prose alone.
• Text first: The reviewed explanation predates the artwork; no unsupported relationship was added.
• Scope: Title and scope make boundaries, simplifications, and exclusions clear.
• Nodes: There are usually 3–9, each concrete and necessary.
• Connectors: Each has direction and a label; styles and colors have a key.
• Claims: Causation, automation, scale, strength, certainty, and growth are shown only when evidence supports them.
• Text equivalent: Visible text includes every node, relationship, condition, boundary, key, and exception.
• Caption: It states the conclusion in 8–30 words.
• Accessibility: Color is not the only cue; contrast, arrowheads, alt text, and reading order work.
• Mobile: Meaning survives at 320 CSS pixels without page-level scrolling or required zoom.
• Placement: Introductory context precedes the diagram; the caption and text equivalent stay attached; competing dense visuals do not sit beside it.
• Source: Research, standards, regulated processes, and adapted models have an accurate visible source or ownership note.
• Portability: All mappings preserve title, nodes, connectors, caption, and text equivalent.
• Asset safety: The file exists before a live path is published, rights are documented, and pending artwork remains a SCREENSHOT comment.
• Precedence: The block is typed as a diagram because its purpose matches this element, not because a generic image happened to look similar.

FAQ

The academy template renders the five reviewed questions stored in this page’s [[faq]] frontmatter. They cover the threshold for using a diagram, the mandatory text equivalent, alt-text scope, structured data, and node limits.