RCA-2026-04-01-001: Prevention

Preventive Measures

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

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

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

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

Detection

How was it detected?

Manual visual inspection after deploying new documentation pages

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.

Lessons Learned

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

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

Key Takeaways

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
AsciiDoc admonitions are <table> elements — any global table styling will leak into admonitions unless explicitly overridden with transparent !important
Theme scripts belong in <head>, not <footer> — a 3-line inline script prevents FOUC on every page load
The nav-panel-explore is easy to miss — it only appears when the sidebar is scrolled to the bottom or when components exist
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

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: