Custom Themes

cr4te includes built-in themes and can add custom themes during a build.

Custom themes are ordinary CSS files kept outside the creator library. Select their folder explicitly with --themes-dir:

cr4te build -i path/to/Creators -o path/to/site --themes-dir path/to/themes

The theme-folder path is intentionally not stored in the JSON configuration. This keeps shared configuration files portable and makes the external theme dependency explicit.

Try the Bundled Theme

The repository includes Amber Terminal as an example custom theme:

cr4te build -i data/example/Musicians -o output/example-site --domain music --themes-dir data/example/themes

Theme Folder

Place theme CSS files directly inside one folder:

themes/
|-- amber-terminal.css
|-- my-theme.css

Theme discovery is not recursive. Subfolders are ignored.

The filename stem becomes the theme ID and display name. Filenames must use lowercase letters, numbers, and single hyphens:

my-theme.css       valid
My Theme.css       invalid
my_theme.css       invalid

my-theme.css appears as My Theme in the generated site's theme selector.

Required Selector

Each file must define a class matching its filename:

.theme-my-theme {
  --theme-page-bg: #101014;
  --theme-text: #f2f2f0;
  --theme-accent: #9bc7ff;
}

Themes only need to override the variables they want to change. Default values for the public theme variables come from assets/css/tokens.css in the generated site.

Header and Panel Colors

The generated header and outer panels use these public theme variables:

• --theme-text-strong: current navigation item and detail-page title
• --theme-breadcrumb-separator: navigation and breadcrumb separators
• --theme-panel-border: default overview and detail-panel border color
• --theme-panel-border-width: default overview and detail-panel border width

The overview and detail layouts inherit the panel border values through --theme-overview-border / --theme-overview-border-width and --theme-layout-column-border / --theme-layout-column-border-width. Override those specialized variables only when a theme needs different borders for those layouts.

When one custom variable depends on another optional variable, provide a CSS fallback:

.theme-my-theme {
  --theme-border: var(--my-border-color, #cccccc);
}

Build Behavior

• Built-in and custom themes use the same generated-site asset path and theme selector.
• Frozen Aurora remains the default theme.
• A custom theme cannot replace a built-in theme with the same ID.
• Invalid or duplicate theme files are reported and skipped during a normal build.
• --strict aborts on the first invalid or duplicate theme file.
• Supplying a missing path or a path that is not a directory always aborts before build side effects.

Custom theme CSS is trusted input. It is copied into the generated site and can apply normal CSS rules beyond theme variables.

Output

Selected themes are copied to:

site/assets/css/themes/

The generated pages load every discovered theme so visitors can switch between them.