Annotated Screenshots: Rules and Examples

An annotated screenshot shows a real interface state and identifies the exact regions a reader needs to notice. The image carries numbered markers; the page carries the matching text legend. That separation is the element: neither an unmarked product image nor labels baked into pixels satisfies the contract.

Content freshness audit, filtered to one tracked URL.

1. Tracked URL: Confirms that the review applies to the intended page rather than the whole domain.
2. Status filter: Narrows the table to pages that require an editorial decision.
3. Result date: Shows when the underlying audit record was last refreshed.

The capture is pending, so the comment is a production capture specification rather than a broken image reference. Once the asset exists, the image, caption, and numbered legend render as one semantic figure.

Why this element matters

Readers use a product image to answer a spatial question: “Which control, value, or state does this instruction mean?” Dense interfaces contain navigation, filters, labels, data, badges, and actions that may all look equally important. An unannotated screenshot asks the reader to reverse-engineer the author’s attention. Numbered markers reduce that search to a direct match between a visible location and a short explanation.

The element also replaces fragile coordinate language. “Use the control on the right” becomes wrong when a toolbar wraps; “choose the status filter marked 2” remains usable while the capture is current.

Machine extractability means software can isolate and reuse the useful meaning of a content unit. Computer vision may recognize interface text, but it cannot reliably infer why one of twenty controls matters to this procedure. A visible, ordered legend creates explicit marker-to-explanation pairs that search systems, translation tools, accessibility software, and content audits can process as text. The image supplies spatial evidence; the legend supplies searchable meaning. This follows the broader element writing rules : content remains typed and portable even when its renderer changes.

Never bake the legend into pixels. Pixel text cannot be translated, searched, selected, or corrected without editing the artwork. It is also invisible to a screen reader, software that announces digital content to people who cannot see the screen. Only marker numbers belong in the image.

When to use it

Use an annotated screenshot when the reader must identify a specific region in a real interface and words alone leave more than one plausible target. It is required when two controls have similar names, an important state is subtle, a result must be interpreted in its surrounding context, or a visual configuration cannot be represented faithfully in prose. It is also useful when a product page makes a concrete interface claim that the image can prove.

A screenshot is optional when the instruction already names a unique, visible control and the interaction is conventional. “Select Save changes” normally needs no image when the page contains one such button. It becomes required if the same screen has Save draft, Save view, and Save changes, and choosing the wrong one changes the outcome.

A screenshot is harmful when it adds weight without resolving uncertainty. Do not add one for decoration or to repeat text that is clearer in a table. Fourteen screenshots in a fourteen-step guide create fourteen interruptions, mobile zoom problems, and stale assets. Capture the ambiguous steps; let precise verbs carry routine ones.

Near misses include:

• A full dashboard used to explain one icon: crop to the smallest region that preserves orientation. A marker lost in a wide interface does not reduce search effort.
• A screenshot used as numeric evidence: repeat the decisive value in text or a table. Pixels cannot be the only accessible copy of a claim.
• A screenshot of a menu before it opens: capture the state the reader needs to inspect. The closed state proves the product exists but not which choice to make.
• A screenshot containing customer records: replace them with stable demo data before capture. Blurring is easy to miss.
• A diagram disguised as a screenshot: use a diagram for abstract relationships. Interface realism helps only when the interface matters.

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 figure after the paragraph or step that first asks the reader to inspect the interface. In a procedure, put it after the action and before the success state or troubleshooting, so the reader locates the control before verifying the result.

Keep the image, caption, and legend together. A heading may introduce the group, but another paragraph, callout, advertisement, or page break must not separate the capture from its numbered explanations. A caption identifies the whole screen and context; it does not carry an instruction that belongs in the prose or replace the legend.

Do not place two full-width screenshots together. Insert the explanation that distinguishes them, or create one labelled comparison when both states must be evaluated together. Keep screenshots away from unrelated calls to action, dense tables, and galleries.

Repeat the element only when each occurrence answers a different spatial question. Prefer one focused figure; otherwise give separate crops distinct filenames and purposes.

Anatomy

The anatomy capture demonstrates the visible and textual parts of one complete element. Explanatory labels remain in the rendered legend rather than becoming part of the source image.

Rendered legend

1. Context boundary: Includes enough surrounding interface to identify the page and location, but excludes unrelated navigation and empty space.
2. Numbered marker: Uses a high-contrast circle and an integer, not color alone, to connect a region to its legend entry.
3. Target region: Marks the smallest complete control, value, or state needed for the explanation; it never covers the target’s label.
4. Orientation landmark: Preserves one stable heading, tab, or panel label so the reader can find the same area in the live product.
5. Caption: Names the screen, state, and scenario in visible text below the image.
6. Legend: Uses an ordered list whose numbers exactly match the markers and whose entries explain significance, not merely appearance.

Marker numbers start at 1 and follow legend order. Use two to six per image; one suits a difficult target, while more than six usually signals an overbroad capture.

Stay Updated on AI Visibility Trends

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

Email address

Subscribe

Design examples

The supported variants change crop and viewport, not the annotation policy. Every variant uses demo data, numbered image markers, an external text legend, and a visible caption.

Focused control: Preferred for a single ambiguous action. Preserve one orientation label so the crop does not become an anonymous rectangle.

Workflow state: Use when the relationship among an input, a status, and a result matters. Keep unrelated global navigation out of frame.

URL in context: The only standard variant that includes browser chrome, meaning the browser’s own tabs, address bar, and controls. Include only the address bar and necessary permission or security indicator.

Mobile state: Capture the actual narrow layout when the interaction changes at mobile width. Do not shrink a wide desktop screen and call it a mobile example.

Parameters

The parameters form the portable content contract. Visual values such as marker color, border thickness, and caption typography belong to the renderer and are not author fields.

The screenId identifies the product surface independently of its filename, so a release can find different crops of content-freshness-audit. The alt.yaml file stays simple: one filename followed by one folded alt-text string.

Syntax and code examples

Each notation preserves the same metadata, caption, markers, and image–caption–legend reading order.

Portable Markdown directive

:::annotated-screenshot{src="/images/seo-playbook/elements/annotated-screenshot/workflow-state.webp" viewport=1440 density="2x" screenId="content-freshness-audit" captureDate="2026-08-27"}
Content freshness audit filtered to one tracked URL.

1. **Tracked URL:** Confirms which page the audit evaluates.
2. **Status filter:** Limits the results to pages awaiting review.
3. **Result date:** Shows when the audit data was refreshed.
:::

The adapter resolves alt from the folder’s alt.yaml. A missing filename key is a publish failure, not permission to copy the caption.

Hugo shortcode mapping

{{< annotated-screenshot src="/images/seo-playbook/elements/annotated-screenshot/workflow-state.webp" viewport="1440" density="2x" screenId="content-freshness-audit" captureDate="2026-08-27" >}}
Content freshness audit filtered to one tracked URL.

1. **Tracked URL:** Confirms which page the audit evaluates.
2. **Status filter:** Limits the results to pages awaiting review.
3. **Result date:** Shows when the audit data was refreshed.
{{< /annotated-screenshot >}}

This is an adapter contract, not a registered shortcode. Until an approved renderer and asset exist, use the established semantic-figure pipeline or leave the prescribed capture comment. Do not substitute a renderer that drops the legend or freshness fields.

WordPress block or shortcode

[annotated_screenshot src="workflow-state.webp" viewport="1440" density="2x" screen_id="content-freshness-audit" capture_date="2026-08-27"]
[caption]Content freshness audit filtered to one tracked URL.[/caption]
[marker number="1" label="Tracked URL"]Confirms which page the audit evaluates.[/marker]
[marker number="2" label="Status filter"]Limits the results to pages awaiting review.[/marker]
[marker number="3" label="Result date"]Shows when the audit data was refreshed.[/marker]
[/annotated_screenshot]

A WordPress block may expose the fields as controls, but it must store marker descriptions as text.

Examples

Good: one ambiguous state, three useful markers

Content freshness review for demo.example/pricing/.

1. Tracked URL: Verifies that the result belongs to the pricing page selected in the instruction.
2. Needs review: Identifies the exact filter that removes current pages from the work queue.
3. Last refreshed: Prevents the editor from treating an old audit result as a current diagnosis.

This works because each marker answers a decision, the crop preserves orientation, and the legend explains consequences not visible in pixels. The demo domain is clearly non-customer data.

Bad: a labelled product poster

The bad version explains an entire dashboard at once. Eight arrows cross, labels obscure controls, and baked-in promotion gives no action. Browser bookmarks create privacy risk, customer names make approval uncertain, no screen identifier supports updates, and mobile scaling makes targets unreadable.

Repair it by selecting one task, using approved demo data, cropping to its panel, and keeping only necessary markers. Move explanations into a text legend, add contextual alt text , and record the screen identifier and date.

Schema markup and accessibility

An annotated screenshot has no special Schema.org type. It may populate an Article’s image property or an ImageObject with accurate contentUrl, caption, width, and height. Do not invent marker properties; keep the legend visible.

Use native figure semantics: one <figure> containing the <img>, a <figcaption>, and the ordered legend. The caption names the whole screen and state. The image’s alt attribute describes what the screen shows in this context; it should not start with “screenshot of,” because the image element already announces itself. The legend supplies the detailed numbered explanations, so repeating all six entries in alt text creates a long, duplicate announcement.

Target 80–180 characters, with 250 as the ceiling. Name the product area, state, and marked purpose: “Content freshness audit filtered to one tracked URL, with markers on the status filter and last-refreshed date.” Do not transcribe the interface, stuff keywords, or use the filename. This informative image normally needs nonempty alt text.

Marker numbers must be readable without color. Use high contrast against both light and dark interface regions, keep their visual size consistent, and do not cover labels or values. The legend uses an ordered list in normal document order; avoid ARIA, or Accessible Rich Internet Applications, roles that turn static content into an alert or interactive widget. An aria-describedby relationship is optional only when testing shows it improves navigation without causing the visible legend to be announced twice.

At narrow widths, responsive design must preserve meaning. Scale a wide image only while markers and targets remain legible; otherwise provide a focused crop or genuine mobile capture. Never cause page-level horizontal scroll or require zoom. Caption and legend wrap below.

Content and capture rules

Consistency makes screenshots comparable and replaceable. Capture desktop product screens at a fixed 1440 CSS-pixel viewport and 2x pixel density, often called Retina density, which records two device pixels for each CSS pixel. Capture genuine mobile states at 390 CSS pixels and 2x density. Use the approved product theme consistently within a guide; do not alternate light and dark mode unless the theme difference is the subject.

Use demo data only: no real names, email addresses, domains, billing details, tokens, prompts, or results. Inspect sidebars, recent items, autofill, notifications, and avatars before capture.

Exclude browser chrome unless a URL, permission, or browser control is the point. Hide tabs, bookmarks, extensions, downloads, profiles, and notifications. Capture after loading; close irrelevant tooltips and show a cursor only when essential.

Store source captures under cdn-assets/seo-playbook/elements/annotated-screenshot/. Use lowercase kebab-case names based on screen and state, such as freshness-audit-needs-review.webp; never use final, new, v2, a person’s name, or a date as the filename. The stable name lets the asset be replaced without rewriting every page. Use WebP for normal delivery, preferably a lossless setting when small interface text must remain crisp. Use PNG only when the production pipeline demonstrates that WebP harms text or transparency. Do not use JPEG for UI captures with fine text and sharp edges.

Render at no more than 1600 CSS pixels wide; a 1440-pixel 2x source may be 2880 physical pixels. Preserve aspect ratio and intrinsic dimensions. Optimization supports image SEO , but compression must not blur text or markers.

Every asset folder contains alt.yaml with one entry per filename:

freshness-audit-needs-review.webp: >-
  AmICited content freshness audit filtered to one tracked URL, with numbered markers on the review status and last-refreshed date.

The key matches the filename exactly; the value is alt text, not a caption or legend. Placeholders, stock dashboards, and nonexistent image references are prohibited. Pending captures use only a SCREENSHOT comment and screenshotsPending = true.

Freshness and re-shoot policy

Screenshots age silently when a depicted control moves or changes name. Treat each capture as a view of a registered screen: screenId joins product changes to assets, while capture date identifies the recorded state.

A UI change triggers a re-shoot when it moves or renames a marked target, changes the state the legend explains, alters the navigation path needed to reach it, removes a preserved orientation landmark, or makes the old image likely to send the reader to the wrong control. Re-shoot the complete figure set for that screen, including focused and mobile variants. A color-token change, spacing adjustment, or unrelated sidebar addition does not require automatic replacement unless the screenshot now conflicts visibly with the live experience or accessibility standard.

When a screen changes, search for its screenId, then its folder and filename to catch legacy uses. Replace stable files, review alt.yaml, and inspect every affected legend. Do not rename replacement files and strand older references.

The product-screen owner signals changes; the content owner accepts replacements. Re-capture with the same demo fixture, viewport, density, and theme. Review screenshots during every substantive page refresh.

Post types that use it

The postTypes frontmatter is the registered join. Each type uses the same element contract but applies a different requirement threshold.

Case studies require an extra boundary: either obtain explicit permission to show real customer information or rebuild the interface with clearly disclosed demo data and treat it as a workflow illustration, not result evidence. Redaction is not a substitute for consent or a controlled fixture.

QA checklist

A reviewer checks communication and maintenance risk before visual polish.

• Purpose: The figure resolves one spatial ambiguity or proves one visible interface claim.
• Necessity: Routine steps remain text; the page does not assign one screenshot to every step by default.
• Real state: The capture shows the exact open menu, selected filter, result, or error discussed in the copy.
• Demo data: No customer, employee, account, browser, token, prompt, or billing information is visible.
• Capture consistency: Viewport, 2x density, theme, interface state, and browser-chrome rule match the standard.
• Focused crop: Enough context remains for orientation, but unrelated interface areas do not compete with the target.
• Markers: There are one to six continuous numbers, each high contrast, legible, and clear of labels and values.
• External legend: Every marker has one matching ordered-list entry in page text; no legend wording is baked into pixels.
• Caption: The figure has a concise visible caption naming its screen, state, and scenario.
• Alt text: The folder’s alt.yaml contains an exact filename key and a contextual description within the target length band.
• Mobile behavior: The target and markers remain legible without page-level horizontal scroll or required zoom; otherwise a focused crop exists.
• File contract: Path, lowercase kebab-case name, format, dimensions, and intrinsic size follow the delivery standard.
• Freshness: screenId and capture date are recorded, the live UI still matches, and all references can be found by text search.
• Portable parity: Markdown, Hugo, and WordPress representations preserve the same asset, caption, marker order, and legend wording.
• No broken asset: A real image path appears only after the file exists; pending captures remain comments and keep screenshotsPending = true.

FAQ

The academy template renders the five reviewed questions stored in this page’s [[faq]] frontmatter. They cover screenshot frequency, external legends, alt-text length, re-shoot triggers, and the browser-chrome exception.