Theme And Visual Design

unaltraweb supports system, light, coffee and dark theme settings. The modes are part of the user interface and are covered by the template render smoke tests.

Modes

• Light: high-contrast default reading mode for normal pages and profile sites.
• Coffee: warm brown reading mode for manuals, long-form documentation and course material.
• Dark: dark mode with matching integration state for embedded libraries and generated diagrams.

The switch rotates through:

system -> light -> coffee -> dark -> system

system follows the browser preference and resolves to light or dark.

Data Attributes

The active theme state is exposed on <html>:

<html data-theme-setting="cafe" data-theme="cafe" data-theme-integration="light" data-site-profile="unaltremanual">

Use these attributes for local CSS and automated checks. Do not infer the active profile from URLs.

Local Sass Overrides

Create _sass/_site-custom.scss in the child site. It is imported after the core styles.

:root {
  --global-theme-color: #2f6f5e;
  --global-hover-color: #2f6f5e;
}

html[data-theme="cafe"] {
  --global-theme-color: #6f4e1f;
}

html[data-site-profile="unaltremanual"] .manual-sidebar {
  border-color: var(--global-theme-color);
}

Custom Coffee Palette

Use CSS custom properties to customize a built-in mode without changing the theme switcher:

html[data-theme="cafe"] {
  --global-bg-color: #2a1d16;
  --global-card-bg-color: #34251d;
  --global-text-color: #f4e8da;
  --global-text-color-light: #c8ad94;
  --global-theme-color: #d39a5f;
  --global-hover-color: #d39a5f;
  --global-divider-color: rgba(211, 154, 95, 0.28);
}

Adding a fifth switcher mode is a core-theme change: extend assets/js/theme.js, the header toggle icons and the Sass selectors together. For normal child sites, override light, cafe or dark with _sass/_site-custom.scss instead.

JavaScript Event

Local scripts can observe theme changes:

document.addEventListener("unaltraweb:themechange", (event) => {
  console.log(event.detail.theme, event.detail.themeSetting);
});

Diagram Surfaces

Manual Mermaid figures receive diagram surfaces tuned for light, coffee and dark modes. Keep source diagrams simple and let the render pipeline generate theme-compatible SVGs.

Testing Themes

The template Playwright smoke test reloads pages with each theme in local storage and checks the resulting attributes and CSS variables.

make test SITE_PROFILE=unaltreselfie
make screenshots

Screenshots generated by make screenshots are copied into assets/img/screenshots/ with make docs-screenshots.