RCA-2026-04-01-001: Analysis

Root Cause

5 Whys Analysis

Why # Question and Answer

1

Why did white containers appear despite having a dark theme CSS?
Because: Several Antora DOM elements had no dark-theme background-color override

2

Why were those elements missed?
Because: The CSS was written by targeting visible content elements (.doc, .navbar, .toc) without mapping the full Antora default UI DOM tree

3

Why wasn’t the full DOM tree mapped?
Because: The Antora default UI bundle generates intermediate wrapper elements (.body, .main, .content, .article, .toolbar) that are invisible in the page structure but carry their own background-color

4

Why didn’t the initial developer inspect the full element hierarchy?
Because: CSS was authored against the AsciiDoc content semantics (doc, admonition, table) rather than the Antora UI bundle’s generated HTML structure

5

Why is there no reference for the Antora default UI DOM tree?
Because: The Antora default UI bundle documentation focuses on Handlebars partials, not the resulting CSS class hierarchy. The full class tree must be discovered via browser DevTools inspection

Root Cause Statement: The supplemental dark theme CSS targeted AsciiDoc content elements and high-level layout components without covering the intermediate wrapper elements generated by the Antora default UI bundle. Additionally, AsciiDoc renders admonitions as <table> elements which inherited the general dark-theme table background instead of being transparent within their styled parent container.

Technical Deep Dive

Antora Default UI DOM Hierarchy

The Antora default UI generates the following nesting structure. Bold elements were missing dark-theme rules:

<html>                          ← .dark-theme applied here
  <body>                        ← styled ✓
    <nav class="navbar">        ← styled ✓
    <div class="body">          ← MISSING
      <div class="nav-container">   ← styled ✓
        <div class="nav-panel-explore">  ← MISSING
      <div class="main">        ← MISSING
        <div class="toolbar">   ← MISSING
          <nav class="breadcrumbs">  ← MISSING
          <div class="edit-this-page">   ← MISSING
        <div class="content">   ← MISSING
          <article class="doc"> ← styled ✓
          <aside class="toc">   ← styled ✓
    <footer>                    ← styled ✓

Admonition Table Inheritance

AsciiDoc admonitions render as:

<div class="admonitionblock note">   <!-- styled ✓ -->
  <table>                            <!-- inherited general table bg -->
    <tbody>
      <tr>                           <!-- inherited tr:nth-child bg -->
        <td class="icon">            <!-- styled ✓ -->
        <td class="content">         <!-- styled ✓ -->

The general .dark-theme table rule set background-color: var(--domus-mantle) and .dark-theme table tr:nth-child(even) set background-color: var(--domus-crust). These applied inside admonitions, creating visible color differences against the admonition’s own var(--domus-mantle) background.

FOUC (Flash of Unstyled Content)

The theme toggle JavaScript lived exclusively in footer-scripts.hbs, executing after the full page rendered. On dark-preference systems, the page briefly displayed in white before the script added .dark-theme to <html>.

Contributing Factors

Factor Description Preventable?

No DOM tree reference

Antora does not document its full CSS class hierarchy

No (upstream)

Content-first CSS authoring

CSS targeted AsciiDoc semantic classes instead of UI bundle structural classes

Yes

Admonition table reuse

AsciiDoc’s <table> rendering of admonitions is non-obvious

Yes

Footer-only theme script

No <head> script for early theme application

Yes