Project Manual
Contents

Create and Select Themes

On this page

Themes change the visual design without replacing generated HTML, responsive layout, accessibility behavior, or search JavaScript. The default ef-maris-dark theme matches the current dark desktop palette.

All languages in a build share the selected theme and core assets.

Select a theme#

Pass the theme name to Python:

python3 build.py --theme modus-operandi-tinted

Use the same name with Make:

make bundle THEME=modus-operandi-tinted
make offline-bundle THEME=modus-operandi-tinted
make example THEME=modus-operandi-tinted PORT=8080

Builder containers accept --theme modus-operandi-tinted. nginx images accept the build argument --build-arg THEME=modus-operandi-tinted.

Built-in themes#

Dark themes:

  • Ef Bio: ef-bio.
  • Ef Dream: ef-dream.
  • Ef Elea Dark: ef-elea-dark.
  • Ef Maris Dark: ef-maris-dark.
  • Ef Night: ef-night.
  • Ef Owl: ef-owl.
  • Ef Symbiosis: ef-symbiosis.
  • Modus Vivendi Tinted: modus-vivendi-tinted.
  • Terminal: terminal.

Light themes:

  • Ef Cyprus: ef-cyprus.
  • Ef Day: ef-day.
  • Modus Operandi Tinted: modus-operandi-tinted.
  • Paper: paper.

Add a theme#

Create a lowercase, hyphenated directory under themes/:

themes/
└── company/
    ├── theme.css
    └── mark.svg

The theme.css file is required. Other regular files and directories are optional. No registry or generator change is needed. Build the new theme with:

make bundle THEME=company

Mermaid Diagram Colors#

When --mermaid or Make's MERMAID=1 enables diagram rendering, the existing --theme or THEME selection also supplies diagram colors automatically:

make bundle-container THEME=paper MERMAID=1

This uses the optional Mermaid container toolchain. With the host Mermaid toolchain installed, use make offline-bundle THEME=paper MERMAID=1 for hosted and offline output. Theme-aware colors add no dependencies. Default builds still display escaped, searchable diagram source; the diagram palette is not read and the renderer is not looked up unless an enabled build encounters a diagram.

One shared mapping serves all 13 bundled themes and custom themes. There is no separate palette configuration or theme registry. The builder reads these seven properties from unconditional, top-level :root rules in theme.css:

  • --surface: diagram and panel background, plus edge-label backgrounds.
  • --surface-raised: node, actor, and activation fills.
  • --background: cluster, note, and label-box fills.
  • --text: general text, signal text, and note text.
  • --text-strong: node, title, actor, and other prominent labels.
  • --accent: node and actor borders, lines, and arrows.
  • --border: cluster, note, and label-box borders.

Also declare color-scheme: light or color-scheme: dark in an unconditional :root rule. Each color must be literal #rgb or #rrggbb; uppercase hex digits are accepted, and values are normalized to lowercase six-digit hex. The panel and SVG use the same concrete --surface color. Diagrams use JetBrains Mono Regular at 14px, independently of theme typography. The full font and its OFL license are embedded in each SVG for offline use, after the renderer loads that same font to measure labels.

This is a limited palette reader, not an arbitrary CSS parser. Palette values using CSS variable expressions, rgb(), or !important are unsupported, as are palette declarations in conditional rules, other selectors, or selector groups such as :root, body. These restrictions apply to the diagram palette, not to unrelated site styling.

If any required value is missing or unsupported, the entire diagram palette falls back to the previous neutral theme on a white panel. The builder emits one message on stderr per build and continues; it does not mix valid palette values with fallback colors or fail because of an unsupported palette.

The SVG filename hash includes diagram source, render configuration, font and license contents, and the renderer helper, so changed colors or typography get new filenames. Hosted and offline outputs reuse the rendered SVGs. Rebuild after changing themes or their palette values: dynamic CSS changes at runtime cannot recolor static diagrams. Mermaid frontmatter and configuration directives cannot override the renderer's global settings. Ordinary static flowchart styling is supported as described below. See Mermaid authoring for the supported static subset and accessible descriptions.

Authoring Color Reference#

Each bundled themes/<theme-name>/theme.css publishes six named colors for humans and LLMs creating illustrations: --palette-red, --palette-green, --palette-yellow, --palette-blue, --palette-magenta, and --palette-cyan. The selected stylesheet is also copied to assets/theme/theme.css in hosted and offline output. Read the values there rather than maintaining a separate palette list.

These literal hex declarations are an authoring reference, separate from UI roles such as --accent and --surface. They do not change automatic diagram coloring or create Mermaid variables. Custom themes can provide the same names, but they are optional: the renderer still reads only the seven UI colors and color-scheme listed above. Keep those required colors literal; replacing them with var(--palette-red) would trigger the neutral palette fallback.

For example, the named-color excerpt from ef-maris-dark/theme.css is:

:root {
  --palette-red: #ff6f6f;
  --palette-green: #41bf4f;
  --palette-yellow: #d0d24f;
  --palette-blue: #57b0ff;
  --palette-magenta: #f59acf;
  --palette-cyan: #2fd0db;
}

Its UI accent is #70a0ff, the upstream warmer blue, rather than the base blue above. Named hues and semantic roles are not interchangeable. Ef and Modus reference colors preserve the upstream base names at the pinned revisions in the stylesheet headers. Paper and Terminal use project-owned authoring palettes.

When choosing colors:

  1. Identify the selected theme and read its stylesheet and provenance comments.
  2. Use the default diagram colors for ordinary nodes and connections.
  3. For deliberate emphasis, copy a suitable literal hex value into the diagram.
  4. Check text against its fill and borders or arrows against their backgrounds.
  5. Use labels, shapes, or line styles as well as color to communicate meaning.

Prefer a colored border over a bright fill when it preserves readable text. The color names alone do not guarantee contrast on every surface. Review custom colors after changing themes; literal overrides stay fixed even when the rest of the diagram changes palette.

Style Individual Flowchart Elements#

Use ordinary Mermaid classDef and class statements for reusable node styles, style for a single node, and linkStyle for a connection. The following source uses fixed Ef Maris Dark colors; put it in a mermaid fence:

flowchart LR
    accTitle: Element color overrides
    accDescr: Prepare has a green border, Review and its incoming arrow are red, and Publish retains the theme defaults.
    A[Prepare] --> B[Review]
    B --> C[Publish]
    classDef attention fill:#2a3644,stroke:#ff6f6f,color:#eaedef,stroke-width:2px;
    class B attention
    style A stroke:#41bf4f,stroke-width:2px
    linkStyle 0 stroke:#ff6f6f,stroke-width:2px;

linkStyle 0 selects the first declared connection, including its arrowhead in the supported renderer. Indices start at zero; update them if you reorder connections. Elements without explicit overrides retain the selected theme's defaults. This example and its arrowhead are checked in hosted and offline SVGs with both dark and light themes; the explicit hex colors remain fixed.

Do not use var(--palette-red) inside Mermaid: SVG images do not inherit the page's CSS variables. Mermaid's plain CSS color name red also means the CSS named color, not this theme's red. No automatic warning or success classes are supplied. This guidance covers flowcharts; sequence diagrams have different styling syntax and do not use flowchart classDef or linkStyle commands.

Static color overrides do not relax SVG validation. Configuration directives, external resources, author font rules, scripts, and animation remain rejected.

Use theme assets#

Reference files beside the stylesheet with relative CSS URLs:

.site-title::before {
  background-image: url("./mark.svg");
}

Do not use /assets/ paths in theme CSS. Relative paths work for root hosting, project prefixes, and extracted offline ZIPs.

Shared typography#

All built-in themes use the same self-hosted JetBrains Mono font for body text, headings, navigation, search, and code. Light and light italic provide 300-weight reading text. Regular, italic, bold, and bold italic remain bundled for explicit normal and strong text, so typography does not require an installed font or internet connection.

The font files are pinned to JetBrains Mono version 2.304, matching the Omarchy Manual assets. They are distributed under the SIL Open Font License 1.1 in assets/fonts/OFL.txt.

The shared Omarchy scale responds from 10px to 16px for site text and from 13px to 16px for documentation text, with a 1.4 reading line height. H1, H2, and H3 headings use 175%, 130%, and 110% of the documentation text size. TOC section labels keep their local uppercase hierarchy.

Theme authors and licenses#

The Ef and Modus adaptations use exact semantic colors from the desktop theme renderer. Ef Themes 2.2.0 is pinned at commit 5cdb7dd361ad3b5d7310f94375a832cd94c182d8 and was resolved with Modus Themes commit 75aa3fa79efd04ddf7980a1d3ec0cef6e4f4af90. The Modus Tinted themes use that Modus revision directly. It declares package version 5.3.0 but is newer than the 5.3.0 tag.

The upstream author and maintainer is Protesilaos <info@protesilaos.com>. Copyright is held by the Free Software Foundation, Inc. Ef and Modus theme adaptations are licensed under GPL-3.0-or-later; each theme includes a NOTICE, and the full license is in assets/licenses/. Simple Docs code plus the terminal and paper themes remain MIT licensed. JetBrains Mono remains under the SIL Open Font License 1.1.

The ports preserve desktop semantic colors exactly. Those roles are reused on different web surfaces, so some muted text and search combinations fall below a 4.5:1 contrast ratio. Do not infer upstream accessibility guarantees for these adaptations.

Keep behavior shared#

Core rules remain in assets/manual.css, and search remains in assets/manual.js. A theme should set design variables and add focused visual overrides in theme.css. It cannot replace the core JavaScript.

The generator rejects invalid theme names, missing stylesheets, symlinks, special files, unsafe filenames, and theme paths that overlap generated output.

Return to the generating sites overview, use a theme in a Python build, a container build, or with the Make helpers. To change the manual name, header mark, or favicon, continue to customize branding.