Theme System

Theme System

The UI bundle provides 7 complete themes implemented via CSS custom properties on the data-theme HTML attribute. Theme preference persists across sessions via cookie. A two-part FOUC prevention strategy ensures the page never flashes with the wrong theme.

Theme Registry

Theme Slug Accent Colors Notes

Dark (default)

dark

#0077B6 medical blue

Default theme, professional medical/tech aesthetic

Catppuccin Mocha

catppuccin

#89b4fa blue, #f9e2af yellow

Based on the Catppuccin Mocha palette

Light

light

#0077B6 blue, #f59e0b amber

Clean light mode for bright environments

Royal

royal

#9D4EDD purple, #E040FB magenta

Deep purple/magenta with crown star icon

Aurora

aurora

#00d9a0 green, #7df9ff cyan, #a78bfa violet

Northern Lights gradient inspiration

Ocean

ocean

#0ea5e9 sky blue, #22d3ee cyan

Deep sea blues with bioluminescent accents

Ember

ember

#f97316 orange, #fbbf24 amber

Warm hearth with fire gradient for deep focus

CSS Custom Properties Architecture

All themes are defined in src/css/domus-theme.css (2,383 lines). Each theme is scoped under a [data-theme="slug"] attribute selector:

[data-theme="dark"] {
  --bg-primary: #1a1a1a;
  --bg-secondary: #252525;
  --text-primary: #e0e0e0;
  --accent-primary: #0077B6;
  --accent-secondary: #00B4D8;
}

Every theme defines the full variable set: backgrounds, text colors, accent colors, code block styling, table styling, admonition colors, sidebar gradients, and component-level overrides. This ensures zero visual leakage between themes.

Cookie Persistence

  • Cookie name: antora-theme

  • Expiry: 1 year (max-age=31536000)

  • Flags: SameSite=Lax, path=/

  • Default: dark (when no cookie exists)

  • Helpers: getCookie() / setCookie() in src/js/vendor/domus-ui.js

FOUC Prevention

Two-part strategy prevents Flash of Unstyled Content on page load:

Part 1 — Early theme detection (src/partials/head-styles.hbs):

An inline <script> block executes before the CSS <link> tag. It reads the antora-theme cookie and sets data-theme on <html> immediately:

(function() {
  var t = getCookie('antora-theme') || 'dark';
  document.documentElement.setAttribute('data-theme', t);
})();

Part 2 — CSS gating:

The CSS rule html:not([data-theme]) { visibility: hidden; } hides the page until the data-theme attribute is applied. Once the inline script sets it, the page becomes visible with the correct theme already active.

Theme Toggle UI

Implemented in src/js/vendor/domus-ui.js (lines 36-59):

  • Position: Fixed, bottom-right corner (24px offset)

  • Style: Glassmorphism pill with backdrop blur, gradient background, 1px semi-transparent border

  • Behavior: Click cycles through all 7 themes sequentially

  • Display: SVG icon + label (e.g., moon icon + "Dark")

  • Each theme has a unique SVG icon: moon, smiley face, sun, star, checkmark gradient, waves, fire gradient

Adding a New Theme

  1. Define a [data-theme="newname"] block in src/css/domus-theme.css with all required CSS custom properties

  2. Add 'newname' to the themes array in src/js/vendor/domus-ui.js

  3. Add an SVG icon to themeIcons object

  4. Add a display label to themeLabels object

  5. Rebuild: npx gulp bundle

Source Files

File Lines Purpose

src/css/domus-theme.css

2,383

All 7 theme definitions + premium styling (gold sidebars, exec tables, code blocks)

src/js/vendor/domus-ui.js

182

Theme toggle logic, icon/label cycling (lines 22-59)

src/partials/head-styles.hbs

12

FOUC prevention inline script + CSS link tag