Theme Colors

DocuBook comes with a config-driven theme system that lets you switch between color presets or define custom colors — all from docu.json. Each preset includes both light and dark modes with full variable coverage.

Config-Driven Themes

Set your theme in docu.json using the themes.colors field. The system supports preset names and custom hex values.

Quick Start

{
  "themes": {
    "colors": "default"
  }
}

Switch to another preset:

{
  "themes": {
    "colors": "freshlime"
  }
}

Use a custom brand color:

{
  "themes": {
    "colors": {
      "primary": "#FF5733"
    }
  }
}

The system automatically generates all 24 CSS variables (background, foreground, primary, accent, daisyUI tokens, etc.) for both light and dark modes from a single primary color. No need to hand-craft every variable.

Note: Only primary is configurable when using custom hex. The entire 24-variable palette (light + dark) is auto-generated from it.

Available Presets

CLI Override

Override the theme without editing docu.json using the --theme flag:

flame dev --theme freshlime
flame build --theme coffee
flame preview --theme default

This is useful for testing themes quickly across all commands (dev, build, preview).

How It Works

Themes are powered by @docubook/themes-colors, a separate package that ships:

• JSON data — preset theme variables and syntax tokens, CDN-ready via jsdelivr
• Resolver — maps docu.json config to actual theme values (preset lookup or custom hex → HSL)
• CSS generator — produces the complete @layer base block with :root and .dark variable sets

Architecture

graph TD
    CONFIG["docu.json<br/><small>themes.colors</small>"]
    PRESET["Preset name<br/><small>e.g. 'default'</small>"]
    CUSTOM["Custom hex<br/><small>{ primary: '#FF5733' }</small>"]
    RESOLVE["resolveTheme()<br/><small>preset lookup or hex → HSL</small>"]
    SCALE["generateThemeCss()<br/><small>24 CSS vars · light + dark</small>"]
    SYNTAX_KEYS["generateSyntaxScale()<br/><small>12 syntax tokens</small>"]
    SYNTAX_CSS["generateSyntaxCss()<br/><small>syntax highlighting CSS</small>"]
    BUNDLE["CSS variables<br/><small>injected into bundle</small>"]

    CONFIG --> PRESET
    CONFIG --> CUSTOM
    PRESET --> RESOLVE
    CUSTOM --> RESOLVE
    RESOLVE --> SCALE
    RESOLVE --> SYNTAX_KEYS
    SYNTAX_KEYS --> SYNTAX_CSS
    SCALE --> BUNDLE
    SYNTAX_CSS --> BUNDLE

The theme CSS is compiled into the same bundle as Tailwind globals and injected as inline <style> for FOUC prevention.

Token Coverage

Each preset includes 24 CSS variables per mode (root + dark):

Plus 12 syntax tokens (keyword, function, punctuation, comment, string, constant, annotation, boolean, number, tag, attrName, attrValue) for code highlighting.