RCA-2026-04-01-001: Antora Dark Theme CSS Coverage Gaps

1. Executive Summary

Antora documentation sites using a supplemental dark theme CSS displayed white containers bleeding through multiple UI elements: main content wrappers, toolbar/breadcrumbs, admonition inner tables, and the component version selector panel at the bottom of the left sidebar. Root cause: the supplemental CSS only targeted high-level elements (.doc, .doc-main, body) without covering the intermediate wrapper elements generated by the Antora default UI bundle. Additionally, admonition blocks rendered as HTML <table> elements inherited the general dark-theme table background instead of being transparent, and a flash-of-unstyled-content (FOUC) occurred because the theme toggle script executed in the footer rather than the <head>. Resolution: three targeted CSS additions covering all Antora wrapper containers, admonition table transparency, nav panel explore styling, and an inline <head> script for immediate dark-theme application.

2. Timeline

Time Event

2026-04-01 T0

Dark theme deployed with supplemental CSS covering body, navbar, nav, doc, toc, code blocks, tables, admonitions, footer

T0+5m

Visual inspection reveals white containers bleeding through on main content area, toolbar, and breadcrumbs

T0+10m

Root cause identified: Antora default UI generates intermediate wrapper elements (.body, .main, .content, .article, .toolbar) not covered by CSS

T0+15m

First fix deployed: dark-theme rules added for all wrapper containers + FOUC prevention script in <head>

T0+20m

Second visual inspection reveals remaining white on admonition inner tables and nav-panel-explore (component selector)

T0+25m

Second fix deployed: admonition table transparency + nav-panel-explore dark styling

T0+30m

Full visual verification passed — no remaining white bleed-through

3. Problem Statement

3.1. Symptoms

  • White background visible behind main content area despite .doc being styled

  • Toolbar strip (breadcrumbs + "Edit this Page" link) rendered in white

  • Admonition blocks showed white strips inside the styled outer container

  • Component/version selector at the bottom of the left sidebar was fully white

  • Brief white flash on page load before dark theme applied (FOUC)

3.2. Expected Behavior

All Antora UI elements should render with Catppuccin Mocha dark theme colors. No white should be visible when dark-theme is active.

3.3. Actual Behavior

The supplemental CSS only covered a subset of the Antora default UI’s DOM elements. Intermediate wrapper <div> elements retained their default white background-color, creating visible white strips and containers between the styled elements.

4. Root Cause

4.1. 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.

4.2. Technical Deep Dive

4.2.1. 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 ✓

4.2.2. 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.

4.2.3. 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>.

5. 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

6. Impact

6.1. Severity

Metric Value

Severity

P3 - Medium (Visual / UX)

Duration

~30 minutes

Users/Systems Affected

All visitors viewing site in dark theme

Data Loss

None

6.2. Business Impact

  • Documentation site appears unprofessional with inconsistent white-on-dark rendering

  • Open-source project credibility affected — first impression for new contributors

  • Same issue affects any Antora site using supplemental dark themes (applicable to work documentation)

7. Resolution

7.1. Immediate Actions

  1. Added dark-theme rules for all Antora wrapper containers:

    .dark-theme .body,
.dark-theme .main,
.dark-theme .main-content,
.dark-theme .content,
.dark-theme .article,
.dark-theme .doc,
.dark-theme .doc-main {
  background-color: var(--domus-base);
  color: var(--domus-text);
}

  2. Added toolbar, breadcrumbs, edit-this-page, home-link, and nav-toggle styling:

    .dark-theme .toolbar {
  background-color: var(--domus-base);
  border-bottom: 1px solid var(--domus-surface0);
}

.dark-theme .breadcrumbs a {
  color: var(--domus-subtext);
}

.dark-theme .edit-this-page a {
  color: var(--domus-subtext);
}

  3. Forced admonition inner table elements to transparent:

    .dark-theme .admonitionblock table,
.dark-theme .admonitionblock table tbody,
.dark-theme .admonitionblock table tr,
.dark-theme .admonitionblock table td {
  background-color: transparent !important;
  border: none;
}

  4. Styled the nav-panel-explore (component/version selector):

    .dark-theme .nav-panel-explore,
.dark-theme .nav-panel-explore .context,
.dark-theme .nav-panel-explore .components {
  background-color: var(--domus-mantle);
}

  5. Added FOUC prevention in head-meta.hbs:

    <script>
(function(){
  var s=localStorage.getItem('theme'),
      d=window.matchMedia('(prefers-color-scheme: dark)').matches;
  if(s==='dark'||(!s&&d))
    document.documentElement.classList.add('dark-theme')
})();
</script>

7.2. Verification

# Rebuild site
cd docs && npx antora antora-playbook.yml

# Serve and inspect
python3 -m http.server 8000 -d build/site

# Browser DevTools verification:
# 1. Open Elements panel
# 2. Inspect each container div for background-color
# 3. Confirm no element shows white (#fff or #fafafa)
# 4. Check admonition inner <table> shows transparent
# 5. Check nav-panel-explore at sidebar bottom
# 6. Hard refresh (Ctrl-Shift-R) to verify no FOUC

8. Preventive Measures

8.1. Short-term (This Week)

Action Owner Status

Create Antora dark theme CSS checklist covering all default UI classes

Evan

[ ] Pending

Apply same CSS fixes to any work Antora documentation sites

Evan

[ ] Pending

8.2. Long-term (This Quarter)

Action Owner Status

Build a reusable dark theme CSS template for all domus-* Antora sites

Evan

[ ] Pending

Document the complete Antora default UI DOM class hierarchy as a reference partial

Evan

[ ] Pending

Consider building a custom Antora UI bundle with native dark theme support instead of supplemental overrides

Evan

[ ] Pending

9. Detection

9.1. How was it detected?

  • Manual visual inspection after deploying new documentation pages

9.2. Detection Gap

Could have been caught earlier with a CSS coverage audit. A checklist of all Antora default UI classes would allow systematic verification instead of visual whack-a-mole.

10. Lessons Learned

10.1. What went well

  • Root cause was identified quickly (DOM inspection)

  • Fixes were surgical — no collateral styling damage

  • FOUC prevention was addressed proactively during the fix

10.2. What could be improved

  • CSS should have been authored against the Antora UI bundle DOM tree, not AsciiDoc content semantics

  • A browser DevTools inspection of the full element hierarchy should be standard practice before declaring a theme "complete"

  • Admonition rendering as <table> is a known AsciiDoc pattern — should be in a checklist

10.3. Key Takeaways

  1. Antora’s DOM is deeper than AsciiDoc’s output — .body > .main > .content > .article > .doc is five levels of wrappers, each with its own default background

  2. AsciiDoc admonitions are <table> elements — any global table styling will leak into admonitions unless explicitly overridden with transparent !important

  3. Theme scripts belong in <head>, not <footer> — a 3-line inline script prevents FOUC on every page load

  4. The nav-panel-explore is easy to miss — it only appears when the sidebar is scrolled to the bottom or when components exist

  5. Supplemental CSS is a game of coverage — the Antora default UI has ~30 class names that can carry background-color; missing even one creates a visible white gap

11. Antora Default UI Dark Theme Checklist

Reference checklist for applying a dark theme to the Antora default UI. Every class listed here must have an explicit background-color override:

  • body

  • .navbar, .navbar-item, .navbar-link, .navbar-burger

  • .body (main wrapper under navbar)

  • .nav-container, .nav, .nav-menu, .nav-link, .nav-text

  • .nav-panel-explore, .nav-panel-explore .context, .nav-panel-explore .components

  • .main

  • .toolbar

  • .breadcrumbs, .breadcrumbs a

  • .edit-this-page, .edit-this-page a

  • .home-link

  • .content

  • .article

  • .doc, .doc-main

  • .doc h1-h6, .doc a

  • .toc, .toc-menu, aside.toc, .toc a

  • code, pre, .listingblock pre, .literalblock pre

  • table, table th, table td, table tr:nth-child(even)

  • .admonitionblock (all variants: note, tip, warning, caution, important)

  • .admonitionblock table, tbody, tr, td (force transparent !important)

  • .footer, .footer a

  • .page-versions

  • .nav-toggle .icon (hamburger menu lines)

  • Scrollbar (::-webkit-scrollbar, -track, -thumb)

12. Related

13. Metadata

Field Value

RCA ID

RCA-2026-04-01-001

Author

Evan Rosado

Date Created

2026-04-01

Last Updated

2026-04-01

Status

Final

Category

Documentation / Frontend CSS

Review Date

2026-05-01