How do I describe a complex diagram that cannot be explained in one short alt text?

Split the job into two parts: a short alternative that identifies the image and directs readers to its detailed explanation, and a longer description available in the document. W3C WAI recommends this approach for complex images, with the longer account covering essential visual information such as relationships. [S1]

For example, if a hypothetical diagram shows how a request moves through three teams, the short alt text could say, “Diagram of a request moving through three teams; detailed explanation follows.” The full description can explain the sequence, decision points, and any branches that matter. These details are placeholders for your actual diagram—not a claim about what yours contains.

One straightforward pattern is to group the image with a clearly labeled, visible description. The label and explanation below are sample wording; replace them with content that accurately describes your image.

<figure>
  <img src="[diagram-file]"
       alt="Diagram of a request moving through three teams; detailed explanation follows.">
  <figcaption>
    <h2>Detailed explanation of the request-flow diagram</h2>
    <p>The request begins with [stage one]. It then moves to [stage two].
       If [condition], it continues to [stage three]; otherwise, it [alternative path].</p>
  </figcaption>
</figure>

WAI describes grouping an image and its detailed content in a figure as one option. It also describes using a clearly named nearby link or identifying where the description appears in the alt text. [S1] This example uses a heading so the explanation has an explicit, meaningful label. Ensure the description is available to readers, not hidden as a substitute for document content.

Write for the information someone needs to understand the diagram. Start with its purpose, then explain the meaningful sequence, relationships, branches, or comparisons. Include labels or values when they change the meaning; skip decorative details that do not help explain it. For a process diagram, a short numbered sequence may be clearer than describing each arrow in turn.

A planning draft might look like this:

1. Purpose: “[What this diagram explains].”
2. Main path: “[Starting point] leads to [next stage], then [outcome].”
3. Relationships or branches: “When [condition], [path A]; otherwise, [path B].”
4. Important labels: “[Explain any label or symbol needed to understand the paths].”

Check the draft against the image: it should preserve the key information and connections without adding claims the diagram does not show.

For a description that needs headings, tables, or other structural relationships, don’t rely on aria-describedby as the only way to provide it. WAI notes that this association is exposed as continuous text, without those structural relationships, and advises using it only when the description is text-only and does not need headings or tables. [S1] Keep the detailed explanation available in the document so readers can use its structure. The source explains these patterns, but it does not determine which description is best for your particular diagram; that depends on the information your image conveys.