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

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.

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

Problem Statement

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)

Expected Behavior

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

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.

Impact

Severity

Metric Value

Severity

P3 - Medium (Visual / UX)

Duration

~30 minutes

Users/Systems Affected

All visitors viewing site in dark theme

Data Loss

None

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)

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