Use and for image captions

Using a <p> tag as a caption is invisible to assistive technology as an image description. The <figure>/<figcaption> pattern creates a machine-readable relationship between an image and its caption, which screen readers surface to users. It also communicates to search engines that the caption describes the image, supporting image SEO.

Quick Reference

• Wrap image + visible caption pairs in <figure> with <figcaption> as a direct child
• <figcaption> must be the first or last child of <figure>
• Do not duplicate alt text in figcaption—alt is the fallback, figcaption is the visible description
• <figure> is appropriate for images, code blocks, diagrams, and charts—not every image

Check

Scan the codebase for images with adjacent visible text that acts as a caption (e.g., a or immediately below an describing it). Verify: 1) Such image-caption pairs are wrapped in . 2) The caption text is inside a element. 3) is a direct child of . 4) The alt text on the is not identical to the text—they serve different purposes. Flag any followed by descriptive text that is not structured as figure/figcaption.

Fix

For each image with an adjacent caption: 1) Wrap the and its caption text in a element. 2) Move the caption text into a element inside . 3) Review the alt attribute—if the figcaption already fully describes the image for sighted users, the alt can be shorter or empty (alt="") only if the figcaption alone is sufficient for screen readers too; otherwise keep a concise alt. 4) Position as the first or last child of . Show the corrected HTML.