RCA-2026-03-24-001: Prevention

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

Related

  • CR: adoc UI Parity

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

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