Chapter 9: Embedded Content & Images

figure and figcaption Elements

Semantic media encapsulation: self-contained content units, caption positioning, document flow relocation, and multi-asset figures.

LEARNING OBJECTIVES ⌵

Understand the semantic definition and WHATWG specification rules of the <figure> and <figcaption> elements.
Differentiate between an image's accessible alternative text (alt) and its visible caption (<figcaption>).
Master the syntax rules for placing <figcaption> as either the first or last child of a <figure>.
Encapsulate non-image content (code listings, ASCII diagrams, data tables, quotes) inside semantic <figure> elements.
Understand how assistive technologies (Screen Readers) expose the figure landmark role and its accessible caption label.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine reading a physical scientific textbook or an issue of National Geographic.

As you read a paragraph about volcanic eruptions, the text says: (See Figure 4.2 for magma chamber cross-section).

On the next page, or in a sidebar box, you see a bordered box containing a detailed geological diagram. Directly underneath the diagram is a printed italicized text box that reads:

Figure 4.2: Subduction zone magma chamber cross-section showing tectonic plate boundary.

Notice two key architectural characteristics:

Self-Contained Unit: The diagram and its caption form a complete, independent unit of knowledge.
Relocatable: If the magazine editor moved Figure 4.2 to the appendix, the main text of the article would still make complete sense without grammatical interruption.

+-------------------------------------------------------------+
|  MAIN ARTICLE BODY TEXT                                     |
|  The subduction zone creates intense friction...            |
|                                                             |
|  +-------------------------------------------------------+  |
|  | <figure>                                              |  |
|  |   [ GEOLOGICAL CROSS-SECTION DIAGRAM ]                |  |
|  |                                                       |  |
|  |   <figcaption>                                        |  |
|  |     Figure 4.2: Magma chamber cross-section           |  |
|  |   </figcaption>                                       |  |
|  | </figure>                                             |  |
|  +-------------------------------------------------------+  |
|                                                             |
|  ...as demonstrated in recent seismic surveys.              |
+-------------------------------------------------------------+

In HTML5, <figure> is the semantic container that represents self-contained flow content, optionally associated with a <figcaption>.

Technical Deep Dive & Specifications

The WHATWG HTML Specification Rules

<figure>: Represents any self-contained content (images, diagrams, photos, code snippets, quotes, math formulas) that is referenced from the main text, but could be moved to another part of the document (or an appendix) without affecting the flow of the document.
- Permitted Parents: Any element that accepts flow content.
- ARIA Role: figure (Implicit).
<figcaption>: Represents a caption or legend for the rest of the contents of its parent <figure> element.
- Syntax Constraint: Must be either the very first child OR the very last child of the <figure>.
- Quantity Constraint: At most one <figcaption> per <figure>.
- ARIA Mapping: Automatically computes as the accessible label (aria-labelledby) for the parent figure role in the Accessibility Tree.

   VALID FIGCAPTION POSITION (TOP):        VALID FIGCAPTION POSITION (BOTTOM):
   <figure>                                <figure>
     <figcaption>Caption</figcaption>        <img src="..." alt="...">
     <img src="..." alt="...">             <figcaption>Caption</figcaption>
   </figure>                               </figure>

[!CAUTION] Placing <figcaption> in the middle of a figure (e.g. between two images) is invalid HTML5 syntax. It must strictly be the first or last child.

`alt` Attribute vs. `<figcaption>`: The Crucial Difference

Feature	`alt` Attribute	`<figcaption>` Element
Visibility	Invisible to sighted users (unless image breaks).	Visible text rendered directly on the web page.
Purpose	Non-visual text substitute for the image.	Explanatory context, legend, citation, or attribution.
Target Audience	Screen readers, search bots, broken image states.	Sighted readers and screen reader users alike.
Allowed Content	Plain text string only (no HTML tags).	Full HTML flow content (links, `<strong>`, `<em>`, `<code>`).

Figures Beyond Images: Code Listings & Data Tables

<figure> is not restricted to images. It is the semantic container for any relocatable asset:

<!-- Semantic Code Listing Figure -->
<figure>
  <figcaption><code>Listing 3.1:</code> Rust Async Channel Implementation</figcaption>
  <pre><code class="language-rust">
async fn process_messages(mut rx: Receiver<Message>) {
    while let Some(msg) = rx.recv().await {
        println!("Received: {:?}", msg);
    }
}
  </code></pre>
</figure>

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL example.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Line 47 (<figure class="editorial-figure">): Wraps the media and its description in a single semantic landmark node with the implicit ARIA role of figure.
Line 48–53 (<img ...>): The primary visual payload. Contains its own distinct, non-visual description in the alt attribute.
Line 54–57 (<figcaption>): The human-readable visible caption, including strong figure numbering (Figure 1.1) and photo attribution.

Expected Browser Render Output

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Semantic Figure & Figcaption Showcase</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
      line-height: 1.6;
      max-width: 740px;
      margin: 2rem auto;
      padding: 0 1rem;
      background-color: #f8fafc;
      color: #1e293b;
    }
    .editorial-figure {
      margin: 2rem 0;
      background: white;
      border: 1px solid #e2e8f0;
      border-radius: 12px;
      padding: 1rem;
      box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.05);
    }
    .editorial-figure img {
      width: 100%;
      height: auto;
      border-radius: 8px;
      display: block;
    }
    .editorial-figure figcaption {
      margin-top: 0.75rem;
      font-size: 0.9rem;
      color: #475569;
      border-top: 1px solid #f1f5f9;
      padding-top: 0.75rem;
    }
    .editorial-figure figcaption strong {
      color: #0f172a;
    }
  </style>
</head>
<body>

<article>
    <h1>The James Webb Infrared Revelations</h1>
    <p>
      Recent observations of the Carina Nebula have revealed hundreds of previously 
      unseen infant stars cloaked inside thick interstellar dust clouds.
    </p>

<figure class="editorial-figure">
      <img 
        src="https://images.unsplash.com/photo-1614728894747-a83421e2b9c9?auto=format&fit=crop&w=800&q=80" 
        alt="Cosmic cliffs of glowing orange gas clouds and bright blue stars in the Carina Nebula"
        width="800"
        height="450"
      >
      <figcaption>
        <strong>Figure 1.1:</strong> The Cosmic Cliffs of NGC 3324 captured in near-infrared light. 
        <em>Credit: NASA, ESA, CSA, and STScI.</em>
      </figcaption>
    </figure>

<p>
      By detecting longer wavelengths of infrared radiation, the observatory penetrates 
      obscuring gas pillars to illuminate stellar birthplaces.
    </p>
  </article>

</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

+-------------------------------------------------------------+
| The James Webb Infrared Revelations                         |
|                                                             |
| Recent observations of the Carina Nebula have revealed...   |
|                                                             |
| +---------------------------------------------------------+ |
| | [ HIGH-RES INFRARED NEBULA IMAGE ]                      | |
| | ------------------------------------------------------- | |
| | Figure 1.1: The Cosmic Cliffs of NGC 3324 captured in   | |
| | near-infrared light. Credit: NASA, ESA, CSA, and STScI. | |
| +---------------------------------------------------------+ |
|                                                             |
| By detecting longer wavelengths of infrared radiation...    |
+-------------------------------------------------------------+

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Multi-Image Comparison Figure

Instructions:

Create a single <figure> container that presents a side-by-side comparison of two satellite images (Before & After reforestation).
Place two <img> elements side by side inside the <figure>.
Add a <figcaption> at the top of the figure that clearly explains what the two images depict.
Ensure both images have distinct alt attributes describing their individual visual states.
Use CSS Grid or Flexbox to place both images on a 2-column horizontal row.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Multi-Asset Figure Challenge — Complete Solution</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      padding: 2rem;
      background: #f1f5f9;
    }
    .comparison-figure {
      background: white;
      max-width: 800px;
      margin: 0 auto;
      padding: 1.5rem;
      border-radius: 12px;
      border: 1px solid #cbd5e1;
      box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.05);
    }
    .comparison-figure figcaption {
      font-weight: 600;
      color: #0f172a;
      margin-bottom: 1rem;
      font-size: 1.1rem;
    }
    .image-grid {
      display: grid;
      grid-template-columns: 1fr 1fr;
      gap: 1rem;
    }
    .image-grid img {
      width: 100%;
      height: auto;
      border-radius: 6px;
      display: block;
    }
    .label {
      font-size: 0.85rem;
      color: #64748b;
      margin-top: 0.5rem;
      text-align: center;
    }
  </style>
</head>
<body>

  <main>
    <!-- Multi-Image Figure with Top Figcaption -->
    <figure class="comparison-figure">
      <!-- 1. Top Figcaption (First child) -->
      <figcaption>
        Figure 3: Satellite comparison of Costa Rican rainforest canopy regeneration between 2006 and 2026.
      </figcaption>

      <!-- 2. Media Assets -->
      <div class="image-grid">
        <div>
          <img 
            src="https://images.unsplash.com/photo-1542273917363-3b1817f69a2d?auto=format&fit=crop&w=400&q=80" 
            alt="Sparse brown deforestation patches in valley landscape (Year 2006)"
            width="400"
            height="300"
          >
          <p class="label">2006: Deforested State</p>
        </div>

        <div>
          <img 
            src="https://images.unsplash.com/photo-1448375240586-882707db888b?auto=format&fit=crop&w=400&q=80" 
            alt="Dense vibrant green tropical forest canopy covering entire valley (Year 2026)"
            width="400"
            height="300"
          >
          <p class="label">2026: Restored Canopy</p>
        </div>
      </div>
    </figure>
  </main>

</body>
</html>

Why this works:

A <figure> can contain multiple media children grouped under a single shared caption.
Placing <figcaption> as the very first child is compliant with the WHATWG specification.
Both images retain individual accessible alt descriptions, avoiding screen reader ambiguity.

⚠️ Common Pitfalls

Placing <figcaption> Outside of <figure>: A <figcaption> element is only valid when nested directly inside a <figure>. Using <figcaption> inside a standard <div> or <section> is invalid HTML.
Multiple <figcaption> Elements: Writing more than one <figcaption> inside a single <figure> is invalid. If you have multiple images, wrap their sub-labels in <p> or <span> and keep one primary <figcaption>.
Using <figure> for Purely Decorative Graphics: Do not wrap every decorative background flourish or social media icon inside <figure>. Reserve <figure> for self-contained informational content.
Duplicating alt Text Verbatim in <figcaption>: Sighted screen reader users will hear the exact same sentence read twice in immediate succession. Ensure alt describes the raw visual data and <figcaption> provides editorial context.

💡 Pro Tips

Default Browser Margins: Browsers apply a default user-agent style margin: 1em 40px; on <figure> elements. Always reset figure { margin: 0; } in your CSS reset stylesheets to prevent unwanted indentation.
Accessibility Tree Pairing: When a screen reader navigates to a <figure>, it announces: "Figure, [Figcaption Text]". This provides effortless landmark navigation for research papers and textbooks.
Non-Image Figure Use Cases: Use <figure> for interactive data visualizations (<canvas> or <svg>), audio/video clips with transcripts, blockquotes with citations, or syntax-highlighted code blocks.

📌 Key Takeaways

<figure> represents self-contained, relocatable content (images, code, tables, charts).
<figcaption> provides a visible caption and must be either the first or last child of <figure>.
There can be at most one <figcaption> per <figure>.
A single <figure> can group multiple related images or charts under one unified caption.
alt is the non-visual text substitute; <figcaption> is the visible editorial context.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

Where is `<figcaption>` allowed to appear within a `<figure>` element according to the HTML5 specification?

Topic: HTML Fundamentals

? Question 2 / 3

What is the primary difference between the `alt` attribute and the `<figcaption>` element?

Topic: HTML Fundamentals

? Question 3 / 3

Can a `<figure>` element contain content other than images?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The WHATWG HTML Specification Rules

alt Attribute vs. <figcaption>: The Crucial Difference

Figures Beyond Images: Code Listings & Data Tables

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Multi-Image Comparison Figure

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Where is <figcaption> allowed to appear within a <figure> element according to the HTML5 specification?

What is the primary difference between the alt attribute and the <figcaption> element?

Can a <figure> element contain content other than images?

`alt` Attribute vs. `<figcaption>`: The Crucial Difference

Where is `<figcaption>` allowed to appear within a `<figure>` element according to the HTML5 specification?

What is the primary difference between the `alt` attribute and the `<figcaption>` element?

Can a `<figure>` element contain content other than images?