RCA-2026-03-24-001: adoc Script UI Mismatch

Executive Summary

The adoc script (AsciiDoc to standalone HTML converter) produced output with visual discrepancies compared to the Domus Antora UI: gray badges instead of cyan, double borders on code blocks, no theme switching, and Tridactyl hint incompatibility. Root cause: CSS was written without direct reference to the domus-antora-ui source files, resulting in approximations that diverged from the brand identity. Resolution: Updated CSS to match exact hex colors (#0077b6), fixed border cascade, added theme switcher, and ensured pointer-events compatibility.

Timeline

Time Event

2026-03-24 ~09:00

User requested batch conversion of MDN AsciiDoc files

2026-03-24 ~09:15

User identified visual mismatch: "this still does not match the ui of my domus hub and spoke"

2026-03-24 ~09:20

Screenshots provided showing side-by-side comparison

2026-03-24 ~09:30

First fix: double border issue resolved

2026-03-24 ~09:45

User feedback: "just follow my ui because it still off…​ mine looks WAYYYY better"

2026-03-24 ~10:00

Second fix: gray badges → cyan badges

2026-03-24 ~10:15

Theme switcher added (dark/light/catppuccin)

2026-03-24 ~10:30

Tridactyl pointer-events fixed

2026-03-24 ~10:45

User confirmed: "yes this is better now let’s get back on track"

2026-03-24 ~11:00

MDN batch conversion started (10,872 files)

2026-03-24 ~22:15

Tridactyl hint misalignment reported - hints below/right of copy button

2026-03-24 ~22:20

Root cause: Copy button had no visible background (CSS not applying)

2026-03-24 ~22:25

Fix: Added !important flags, changed badge to dark grey, button to cyan filled

2026-03-24 ~22:30

User confirmed: Tridactyl working, styling matches Domus

Problem Statement

Symptoms

Round 1 (Morning)

  • Gray badges - Language badges (BASH, JSON, etc.) had gray background instead of cyan

  • Double borders - Code blocks showed two cyan borders (outer + inner)

  • No theme switching - Standalone HTML had no dark/light toggle

  • Tridactyl hints misaligned - Copy buttons didn’t receive keyboard hints

Round 2 (Evening)

  • Tridactyl hints still misaligned - Hints appeared below/right of copy button, not centered

  • Copy button invisible - Button had no visible background despite CSS specifying cyan

  • Badge color wrong - Badge was cyan when Domus uses dark grey

  • Copy feedback different - Toast styling differs from Domus (deferred to future)

Expected Behavior

Standalone HTML output should match docs.domusdigitalis.dev exactly:

  • Cyan badges (#0077b6) with white text

  • Single border on code block container

  • Theme switcher (dark/light/catppuccin)

  • All interactive elements receive Tridactyl hints

Actual Behavior

  • Badges used rgba(0,0,0,0.6) (dark gray)

  • Both .listingblock .content AND inner pre had borders

  • No theme toggle functionality

  • Copy buttons had pointer-events: none inherited from parent

Root Cause

5 Whys Analysis

Why # Question and Answer

1

Why did badges have wrong color?
Because: CSS used gray (rgba(0,0,0,0.6)) instead of cyan (#0077b6).

2

Why was gray used instead of cyan?
Because: Color was approximated from memory, not extracted from source.

3

Why wasn’t the source consulted?
Because: Assumption that "close enough" styling would suffice.

4

Why was "close enough" acceptable?
Because: Initial goal was functionality (copy button works), not pixel-perfect UI.

5

Why wasn’t pixel-perfect UI a requirement?
Because: Requirements weren’t explicitly documented; UI parity was implicit.

Root Cause Statement

CSS styling was written without referencing the actual domus-antora-ui source files. Colors, borders, and interactive element properties were approximated rather than copied from the authoritative source, resulting in visual drift from brand identity.

Contributing Factors

Factor Description Preventable?

No design tokens reference

The adoc script has no import of domus-antora-ui variables

Yes

Visual testing gap

Side-by-side comparison wasn’t done during development

Yes

Incremental drift

Each styling iteration moved further from source

Yes

awk/shell limitations

Embedding complex CSS in shell makes maintenance harder

Partially

Impact

Severity

Metric Value

Severity

P3 (cosmetic)

Duration

~1 hour (discovery to resolution)

Files Affected

~4,700 (partial batch conversion before fix)

User Experience

Degraded - inconsistent branding

Business Impact

  • Inconsistent visual identity across documentation ecosystem

  • MDN conversion output didn’t match professional standards

  • Required rework of already-converted files

Resolution

Immediate Actions

  1. Read screenshots - Analyzed side-by-side comparison

  2. Identified specific CSS properties - border, background-color, pointer-events

  3. Fixed double border - Removed border from inner pre

  4. Changed badge colors - rgba(0,0,0,0.6) → #0077b6

  5. Added theme switcher - localStorage-persisted theme toggle

  6. Fixed Tridactyl - Added pointer-events: auto and z-index: 10

CSS Fixes Applied

Round 1 Fixes

/* BEFORE: Double border */
.doc .listingblock .content { border: 1px solid #0077b6; }
.doc .listingblock pre { border: 1px solid #0077b6; } /* DUPLICATE */

/* AFTER: Single border */
.doc .listingblock .content { border: 1px solid #0077b6; }
.doc .listingblock .content pre { border: none !important; }

Round 2 Fixes

/* BEFORE: Cyan badge (wrong), invisible button */
.doc .source-toolbox .source-lang { background: #0077b6; }
.doc .source-toolbox .copy-button { background: #0077b6; } /* Not applying */

/* AFTER: Dark grey badge, cyan filled button with !important */
.doc .source-toolbox .source-lang {
  background: #333 !important;
  color: #cdd6f4 !important;
}
.doc .source-toolbox .copy-button {
  background: #0077b6 !important;
  padding: 0.35rem !important;
}

Verification

# Generate test HTML
adoc /tmp/test-copy.adoc

# Visual verification in browser
firefox /tmp/test-copy.html

# Compare with production
firefox https://docs.domusdigitalis.dev/captures/codex/bash/xargs.html

Preventive Measures

Short-term (This week)

Action Owner Status

Document exact hex codes from domus-antora-ui

Evan

[ ] Pending

Create CSS variable reference file

Evan

[ ] Pending

Add pre-commit visual diff check

Evan

[ ] Pending

Long-term (This quarter)

Action Owner Status

Extract adoc CSS to separate file (not embedded in shell)

Evan

[ ] Pending

Create adoc script unit tests with visual regression

Evan

[ ] Pending

Document design tokens in domus-antora-ui README

Evan

[ ] Pending

Detection

How was it detected?

User visual inspection. Side-by-side comparison of:

  • adoc output: /tmp/test-copy.html

  • Production: docs.domusdigitalis.dev

User quote: "just follow my ui because it still off…​ mine looks WAYYYY better"

Detection Gap

Should have:

  1. Established reference screenshots during initial development

  2. Automated visual diff testing

  3. Extracted colors directly from domus-antora-ui source

Lessons Learned

What went well

  • Quick identification via screenshot comparison

  • Iterative fixes with user feedback

  • Final result matches production exactly

What could be improved

  • Consult source files before approximating

  • Visual QA before declaring "done"

  • Document design tokens explicitly

Key Takeaways

  1. Never approximate brand colors - Always extract exact hex values from source

  2. CSS specificity cascades - Inner elements inherit/override parent borders

  3. pointer-events matters - Browser extensions rely on proper event propagation

  4. Side-by-side testing is mandatory - "Looks okay" is not "matches exactly"

  5. Use !important when fighting specificity wars - Embedded CSS in shell scripts competes with theme CSS

  6. Verify in actual browser - CSS that "should work" often doesn’t due to cascade

Deferred Items

Item Description Priority

Copy toast styling

Toast feedback differs from Domus (different position, no speech bubble arrow)

P3

Toast background color

Currently cyan; Domus uses var(--doc-font-color) (dark grey)

P3

CLI Mastery: CSS Debugging Patterns

# Extract hex colors from CSS file
grep -oE '#[0-9A-Fa-f]{6}' site.css | sort -u

# Find all border properties
grep -E 'border.*:' site.css | head -20

# Extract specific class styling
awk '/\.source-toolbox/,/\}/' site.css

# Compare two CSS files for differences
diff <(grep -oE '#[0-9A-Fa-f]{6}' old.css | sort -u) \
     <(grep -oE '#[0-9A-Fa-f]{6}' new.css | sort -u)

Related

  • CR: adoc UI Parity

  • dotfiles-optimus: base/bin/.local/bin/adoc

  • domus-antora-ui: src/css/ (source of truth)

Metadata

Field Value

RCA ID

RCA-2026-03-24-001

Author

Evan Rosado

Date Created

2026-03-24

Status

Final

Category

Tooling / Visual QA