Imagebox: Image Infobox Rules and Examples

An imagebox pairs one image with one focused explanation so readers process them as a single editorial unit. The image may carry evidence that the text interprets, or it may illustrate an idea that the text explains completely. The author must declare which job it performs because that choice controls the copy, alternative text, caption, structured data, and whether the element still works without sight.

This is the content-image variant: the visible date and status are evidence, while the adjacent text interprets their relationship. If the image were merely a decorative calendar, the text would need to make the entire freshness point independently and the image would use empty alternative text.

Why this element matters

Readers do not process a picture and a distant paragraph as one idea automatically. When an image appears without an explicit textual relationship, they must decide what to inspect, why it matters, and whether it supports the surrounding claim. An imagebox reduces that uncertainty by putting one visual and one explanation inside a clear boundary. The title names the point; the image shows it; the text tells the reader what to notice or understand.

The psychological benefit is joint attention: the design directs attention to a visual object while the copy establishes its relevance. A chart crop might suggest a rise, volatility, or a date boundary; the adjacent explanation selects the relevant reading.

Machine extractability is the ability of software to isolate a content unit without losing the relationship among its parts. A semantic imagebox exposes an image, accessible description, caption, heading, explanation, and declared image role in one container. Text must still contain the claim: computer vision must not be the only route to a number, instruction, limitation, or conclusion.

The element writing rules govern the shared directive syntax, body mapping, paths, and precedence. This page takes precedence where it defines the imagebox-specific distinction between content and illustration, its permitted fields, and its one-image limit.

When to use it

Use an imagebox when one image and one explanation have a direct, necessary relationship and neither deserves a full standalone section. Strong uses include a focused interface crop paired with an interpretation, a product detail paired with an explanation of why it affects fit, a process photograph paired with a quality-control rule, or a simple conceptual illustration paired with a concise explanation.

First decide whether the image is content or illustration:

• Content image: the reader must inspect the image to verify a claim, identify a feature, compare a state, or understand a visual fact. The text names the relevant detail and explains its significance. Alt text is meaningful, and a caption is normally present.
• Illustrative image: the image reinforces tone, memory, or comprehension, but the adjacent text provides the complete claim. Removing the image makes the block less engaging, not less accurate. Alt text is empty unless the illustration itself communicates additional information.

Use the removal test. If a failed image request removes evidence or makes the explanation incomplete, declare role=content. If it removes only visual reinforcement, declare role=illustration.

Near-miss cases are common:

• Use a standalone image when the visual needs the full reading width and the text only identifies it.
• Use an annotated screenshot when readers must locate multiple interface regions.
• Use a table for repeated comparison criteria, a diagram for a system or sequence, and a gallery for peer images.
• Use ordinary prose when the visual merely repeats a sentence.

Do not use an imagebox to make a weak section look designed. A stock photograph of people pointing at a laptop does not explain “collaboration,” and a generic robot does not make a claim about artificial intelligence more concrete. If the image could be swapped for an unrelated image with no change to the copy, the pairing has no editorial contract.

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 imagebox immediately after the paragraph that introduces the claim or concept it develops. In a procedure, place it after the action and before its success check, so visual evidence does not interrupt the instruction.

It may sit directly below an H2 only when its internal title is more specific. Keep a citation or qualification beside the claim it limits; never insert the imagebox between them.

It must not sit directly beside another imagebox, gallery, full-width figure, video, table, or two-column infobox. Insert interpretation between visual containers, combine true peers, or create separate subsections.

Do not place it inside a bullet, step, callout, table cell, accordion, or clickable card. Do not put a call to action inside the block or between its image and explanation.

On desktop, the image may appear before or after the text. On mobile, preserve a predictable source, keyboard, and screen-reader order; do not rely on conflicting CSS reordering.

Anatomy

The anatomy is defined by meaning rather than color, shadow, or column width.

1. Container: Groups exactly one figure and one explanation as a single editorial unit.
2. Image: Shows evidence or supplies illustration according to the declared role.
3. Alternative text: Communicates the relevant visual purpose for a content image; it is empty for a redundant decorative illustration.
4. Caption: Identifies what a content image shows and supplies essential context such as state, date, or scale.
5. Title: States the insight or subject, not the filename or a generic label such as “Example.”
6. Explanation: Tells the reader what to notice, why it matters, and any limitation on the interpretation.
7. Credit: Names the creator or source when rights, provenance, or editorial policy requires it.
8. Reading order: Preserves a coherent figure-and-text relationship when two columns collapse to one.

The explanation must refer to the subject directly rather than using coordinates such as “the image on the left.” Position changes across breakpoints, translations, and syndication. “The stale status and update date identify the review target” remains true everywhere.

Stay Updated on AI Visibility Trends

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

Email address

Subscribe

Design examples

The design system supports four role-and-position combinations. None changes the content requirements.

Content image, image start

Use this default when readers should inspect evidence before its interpretation.

Content image, image end

Use this when the explanation must establish a lens before the evidence.

Illustration, image start

Use this when a concept-specific visual improves recognition while text carries the full meaning.

Illustration, image end

Use this when the explanation is primary and the illustration acts as a visual close.

Narrow viewport behavior

Every variant becomes one column without horizontal scrolling or meaning-changing crops. The caption stays attached to its figure.

Parameters

The content contract separates editorial meaning from presentation. Width ratios, gaps, borders, backgrounds, radius, shadows, and breakpoints belong to the renderer.

Publish src only after the asset exists. A pending capture uses a screenshot comment and screenshotsPending = true. role has no default because silently treating evidence as decoration creates an accessibility failure.

The first body heading becomes title; everything after it becomes content. The body permits paragraphs, emphasis, inline code, and one contextual link. It rejects lists, nested headings, tables, media, buttons, forms, quotes, accordions, and components.

Syntax and code examples

All three notations preserve the same role, image, title, explanation, caption, credit, and reading order. These are portable adapter contracts; they do not imply that an unregistered local shortcode or block already exists.

Portable Markdown directive

:::imagebox{src="/cdn-assets/seo-playbook/examples/freshness-status.png" role=content position=image-start alt="Freshness report row showing a stale status beside an update date of 12 February 2026" caption="The stale status is evaluated against the recorded update date."}
## See why the page needs review

The visible update date explains why the audit classified this URL as stale. Verify whether the page has changed since that date before assigning a rewrite.
:::

The sample path demonstrates syntax only. Production validation must reject it until that asset exists.

Hugo shortcode

{{< imagebox src="/cdn-assets/seo-playbook/examples/freshness-status.png" role="content" position="image-start" alt="Freshness report row showing a stale status beside an update date of 12 February 2026" caption="The stale status is evaluated against the recorded update date." >}}
## See why the page needs review

The visible update date explains why the audit classified this URL as stale. Verify whether the page has changed since that date before assigning a rewrite.
{{< /imagebox >}}

The adapter uses named parameters only. Until registered, use a semantic <figure> followed by prose. The adapter validates the asset and preserves directive body mapping.

WordPress block

<!-- wp:amicited/imagebox {"src":"/cdn-assets/seo-playbook/examples/freshness-status.png","role":"content","position":"image-start","alt":"Freshness report row showing a stale status beside an update date of 12 February 2026","caption":"The stale status is evaluated against the recorded update date."} -->
<figure class="wp-block-image">
  <img src="/cdn-assets/seo-playbook/examples/freshness-status.png" alt="Freshness report row showing a stale status beside an update date of 12 February 2026">
  <figcaption>The stale status is evaluated against the recorded update date.</figcaption>
</figure>
<div class="imagebox__content">
  <h2>See why the page needs review</h2>
  <p>The visible update date explains why the audit classified this URL as stale. Verify whether the page has changed since that date before assigning a rewrite.</p>
</div>
<!-- /wp:amicited/imagebox -->

WordPress should expose one Media field and a constrained text region. If unavailable, use native Image, Heading, and Paragraph blocks; preserve meaning even without side-by-side layout.

Examples

Good example: the image is evidence

This works because the image proves two physical details and the copy explains their operational consequence. The title states the insight, the caption identifies the visible evidence, and the explanation remains specific without attempting to inventory the entire photograph.

Bad example: generic decoration presented as proof

Work smarter with clear data
Image: a generic person smiling at a laptop beside colorful charts.
Our innovative platform transforms data into actionable insights so every team can unlock better decisions and achieve more.

This fails because neither half contributes verifiable information. The image could advertise any software product, while the copy contains broad outcomes without a mechanism, interface detail, constraint, or example. The pairing creates visual prominence but no meaning a reader or machine can extract. Replace it with a focused product state and an explanation of one decision it supports, or remove the imagebox and write the claim as ordinary prose with evidence.

Schema markup and accessibility

An imagebox has no dedicated Schema.org type. Its text remains part of the enclosing page entity. A content image may be an ImageObject when it has a stable contentUrl, accurate caption, dimensions, and required credit or license metadata. Decorative illustrations do not need a separate entity.

Page-level schema may reference the same representative image. A product-detail photograph may feed the visible product’s image property, but a chart crop does not become Dataset and a screenshot does not become SoftwareApplication.

Use one <figure> and <figcaption> plus a labelled explanatory region. Set intrinsic width and height; responsive output must not scroll horizontally or crop the named detail.

Alternative text names a content image’s relevant subject, state, and decisive detail. Do not begin “image of,” duplicate the caption, or stuff keywords. Redundant illustrations use alt=""; omitting the attribute may expose the filename.

Do not rely on position, color, or pixels alone. Repeat decisive numbers, labels, warnings, and conclusions in text. Keep links keyboard reachable, never make the whole box one link, preserve source order, and test at 200% zoom.

Writing rules

Write the explanation before selecting the image, then choose the narrowest crop that preserves necessary context.

• Write a title of 3–10 words that states the insight, subject, or relationship. Avoid “Image,” “Overview,” “Learn more,” and “See it in action.”
• Keep explanatory copy to 40–140 words in one or two paragraphs. The element supports one point, not a miniature article.
• Keep captions to 5–25 words. Identify what is shown and the context necessary to interpret it; put reasoning in the body.
• Use 40–180 characters for meaningful alternative text, with 250 as a hard maximum. Prefer accuracy over filling the range.
• Include exactly one image and no more than one contextual text link. Link only when a destination materially deepens the explanation.
• Use one voice and tense across title, caption, and body. Prefer concrete nouns and verbs over promotional adjectives.
• State the limitation beside the interpretation when the image shows only one state, date, crop, device, or example.

Never put a list, table, testimonial, price, form, media, download, button, multi-step instruction, disclaimer, or call to action inside. Do not use two images, embed essential copy in pixels, expose customer data, or publish artwork with unknown rights.

Avoid writing “as you can see.” A reader may not see the image, and even a sighted reader needs to know what observation matters. State it directly: “The locking tab sits flush when the connector is fully inserted.”

Post types that use it

The rows below are driven by the postTypes frontmatter. “Use” describes a suitable role, not a requirement to force an imagebox into every page.

QA checklist

Before publication, verify the complete element:

• The image and explanation make one point and belong in one editorial unit.
• role is explicitly content or illustration, chosen with the removal test.
• The source file exists, is approved, and uses no private data, unknown rights, or placeholder asset.
• The title states the insight in 3–10 words and the body explains it in 40–140 words.
• A content image has meaningful alternative text and a concise caption; a redundant illustration uses empty alt text.
• The text states every decisive number, label, instruction, warning, and conclusion that cannot depend on sight.
• The caption identifies the image without duplicating the body or alternative text.
• Any required creator, source, license, or credit link is accurate and visible.
• The block contains one image, one explanation, and at most one contextual text link.
• It contains no nested list, table, media, button, form, call to action, or interactive card.
• It does not replace a better annotated screenshot, comparison, diagram, gallery, or full-width figure.
• Desktop and mobile layouts preserve semantic source order, caption attachment, and keyboard order.
• The meaningful crop survives responsive resizing, 200% zoom, and image-loading failure.
• Width and height reserve space, while lazy loading does not delay an above-the-fold image.
• Structured data, if emitted, matches visible content and does not describe decoration as a separate entity.
• Portable Markdown, Hugo, and WordPress mappings retain the same role, fields, and meaning.

FAQ

The academy template renders the five reviewed questions stored in this page’s [[faq]] frontmatter. They cover the content-versus-illustration test, decorative alternative text, descriptive scope, calls to action, and ImageObject schema.

An imagebox succeeds when the reader can answer two questions immediately: “What does this image contribute?” and “Why does that contribution matter here?” If either answer is vague, strengthen the relationship or remove the box.