Figure elements missing a figcaption

What Is This Issue

This issue checks whether images on your web pages are properly wrapped with semantic HTML elements (<figure> and <figcaption>) to provide context and meaning. When images are used to convey meaningful content, they should be wrapped in a <figure> element with a descriptive <figcaption>.

The audit verifies:

• Whether meaningful images are wrapped in <figure> elements
• Whether <figure> elements contain <figcaption> with descriptive text
• Whether images have appropriate alt attributes
• Whether <figure> elements are used correctly (not empty or misused)

A passing implementation should have:

• Meaningful images wrapped in <figure> with a <figcaption>
• Decorative images marked with alt=""
• <figure> elements that actually contain images
• Descriptive captions that explain the image context

Example of good implementation:

<figure>
  <img src="team-photo.jpg" alt="Company team at annual retreat" />
  <figcaption>
    The marketing team at our 2024 annual retreat in Austin, Texas.
  </figcaption>
</figure>

Example of decorative image (no caption needed):

<img src="decorative-border.png" alt="" />

Why Is This Important

Properly captioned images using <figure> and <figcaption> matter for several reasons:

• SEO and Rankings: Search engines use captions to understand image context and relevance. Images with descriptive captions are more likely to appear in image search results and can improve overall page relevance signals.

• Accessibility: Screen readers announce <figcaption> content to users, providing important context for images. This is especially critical for users who cannot see the image and rely on assistive technologies.

• User Experience: Captions help all users understand the purpose and context of images, especially when images contain data, show processes, or depict complex scenes.

• AI Search / AEO (Answer Engine Optimization): AI-powered search engines and voice assistants extract information from well-structured content. Semantic image captions help AI systems understand and potentially cite your visual content in answers.

• Indexability: Properly structured images with captions are easier for search engines to index and may appear in rich results or image carousels.

Resolving this issue improves your overall SEO health score by ensuring your visual content is accessible, well-described, and optimally structured for both search engines and users.

How XeoPix Detects This

XeoPix follows a clear process to identify images that lack proper semantic markup:

1. Fetches the page: XeoPix downloads the HTML content of the page (respecting robots.txt rules).

2. Finds all images: The crawler identifies all <img> elements in the static HTML (note: images added by JavaScript after page load won’t be detected in static checks).

3. Checks for <figure> wrapping: For each image, XeoPix checks whether it’s inside a <figure> element by looking at the parent elements in the HTML structure.

4. Validates captions: If an image is inside a <figure>, XeoPix checks whether that <figure> contains a <figcaption> element with actual text content.

5. Checks alt attributes: XeoPix reviews the alt attribute of each image to ensure it’s present and meaningful (or explicitly empty for decorative images).

6. Identifies decorative images: Images with alt="" are considered decorative and don’t require <figcaption>, though wrapping in <figure> is still preferred.

7. Flags issues: Based on these checks, XeoPix generates issues with appropriate severity:

   • CRITICAL: Images missing alt attributes (accessibility violation)
   • WARNING: Images inside <figure> but missing <figcaption>
   • SUGGESTION: Meaningful images not wrapped in <figure>

The detection works on static HTML delivered by the server. For pages that heavily use JavaScript to add images, XeoPix may recommend additional checks with rendering capability.

How To Fix

1. Wrap meaningful images in <figure>: For any image that conveys meaning or context, wrap it in a <figure> element.

2. Add descriptive <figcaption>: Include a concise, descriptive caption inside the <figure> element that explains the image’s context and relevance to the page content.

3. Use alt attributes correctly:

   • Add meaningful alt text for images that convey information
   • Use alt="" for purely decorative images (this tells screen readers to skip the image)

4. Convert existing captions: If you already have captions near images (e.g., in <p> tags), move them inside a <figcaption> within a <figure> element.

5. Fix empty <figure> elements: Ensure <figure> elements actually contain images. Remove empty <figure> wrappers or add the missing images.

6. Don’t overdo it: Only wrap images in <figure> when they need captions. Decorative images (icons, borders, background patterns) should not use <figure>.

7. Handle dynamic content: If images are added via JavaScript, ensure the initial HTML or the rendered output includes proper <figure> and <figcaption> structure.

Implementation example:

<!-- Before: Image without semantic markup -->
<img src="chart.png" />
<p>Figure 1: Sales growth over 2024</p>
 
<!-- After: Proper semantic markup -->
<figure>
  <img
    src="chart.png"
    alt="Bar chart showing 45% sales growth from Q1 to Q4 2024"
  />
  <figcaption>Figure 1: Sales growth over 2024</figcaption>
</figure>

What We Store

Storage Level

Page Level

Database Table / Prisma Model

PageSemanticElement

Stored Fields

Detection Dependencies

• HTML Document
• Image Analysis
• DOM Structure Analysis

Examples

Example 1: Image with proper semantic markup

Scenario: A chart image that conveys important data.

Problematic state (what fails):

<img src="sales-chart.png" />
<p>Figure 1: Sales growth over 2024</p>

Corrected state (what passes):

<figure>
  <img
    src="sales-chart.png"
    alt="Bar chart showing 45% sales growth from Q1 to Q4 2024"
  />
  <figcaption>Figure 1: Sales growth over 2024</figcaption>
</figure>

Example 2: Decorative image (no caption needed)

Scenario: A decorative border or icon that doesn’t convey meaning.

Problematic state (what fails):

<img src="decorative-border.png" alt="border image" />

Corrected state (what passes):

<img src="decorative-border.png" alt="" />

Example 3: Empty figure element

Scenario: A figure element without an image inside.

Problematic state (what fails):

<figure>
  <figcaption>Company logo</figcaption>
</figure>

Corrected state (what passes):

<figure>
  <img src="logo.png" alt="Company logo" />
  <figcaption>Company logo</figcaption>
</figure>

Unit Test

Test File

__tests__/seo-audit-checks/semanticHtml/issue-141-figure-figcaption-wrap.test.js

Purpose

This unit test validates that the SEO audit correctly detects whether images on a page are properly wrapped in <figure> elements with descriptive <figcaption> children, ensuring semantic HTML best practices for image presentation.

Tested Function

runSemanticHtml from toggleGroups/semanticHtml.js

Issue Information

• Issue Number: 142
• Issue Code: figure_figcaption_wrap
• Toggle Group: semanticHtml

Test Scenarios

Positive Test Cases

1. Images wrapped in <figure> with <figcaption> — When all images are properly wrapped in <figure> elements that contain <figcaption> children, no issue should be reported.
2. No images on page — When the page has no <img> elements, no issue should be reported.
3. Empty body — When the page has an empty <body>, no issue should be reported.

Negative Test Cases

1. Images not wrapped in <figure> elements — When images are placed directly inside a <div> without a <figure> wrapper, the issue should be reported with missingElement set to 'figure' and all unwrapped images listed in imagesWithoutFigure.
2. <figure> elements missing <figcaption> children — When <figure> elements contain images but lack <figcaption> children, the issue should be reported with missingElement set to 'figcaption' and the invalid figures listed in invalidFigureAudits.
3. Some images wrapped, some not — When some images are properly wrapped in <figure> with <figcaption> and others are not wrapped at all, the issue should be reported for the unwrapped images.

Boundary Cases

None specifically tested.

Edge Cases

1. Images without src or alt attributes — Images missing both src and alt attributes should still be detected as unwrapped images.
2. <figure> with multiple images but no <figcaption> — A <figure> containing multiple images but no <figcaption> should be reported as invalid.
3. Multiple <figure> elements with mixed validity — When some <figure> elements have <figcaption> and others do not, only the invalid ones should be reported.
4. Malformed HTML — Malformed HTML (unclosed tags) should not cause the function to throw an error, and the issue should still be detected.

Expected Outcome

Pass

The issue should be reported when:

• Images are present without a <figure> wrapper
• <figure> elements contain images but lack <figcaption> children
• Any combination of valid and invalid image/figure usage exists on the page

Fail

The issue should not be reported when:

• All images are properly wrapped in <figure> with <figcaption>
• The page contains no images at all
• The page has an empty body

Validation

• Correct issue detection — Verifies that images without <figure> wrappers or <figure> elements without <figcaption> trigger the issue with the correct missingElement value.
• No issue detection when expected — Verifies that properly structured images do not trigger the issue.
• Payload validation — Verifies that imagesWithoutFigure lists each unwrapped image’s src and alt, and invalidFigureAudits lists each invalid figure’s images.
• Error handling — Verifies that malformed HTML does not cause runtime errors.

Related Production Files

• toggleGroups/semanticHtml.js
• issueCodes.js
• utils/issues.js
• utils/context.js

Coverage Summary

• Covers positive case with all images properly wrapped
• Covers negative case with images missing <figure> wrapper
• Covers negative case with <figure> missing <figcaption> child
• Covers mixed scenario (partial compliance)
• Covers edge cases: no images, empty body, missing attributes, malformed HTML
• Covers multiple <figure> elements with mixed validity
• Covers <figure> with multiple images but no <figcaption>

References

• WHATWG HTML Living Standard - The <figure> element  — WHATWG
• MDN Web Docs - <figure>  — MDN
• WebAIM - Alternative Text  — WebAIM