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.

Navigation, Breadcrumbs, Panels, and Section Titles

Global navigation is a full-width surface above the inset page content. Overview and detail pages keep their level-one page title available to assistive technology while omitting a separate visible title strip. Creator and project detail-page titles are shown in the breadcrumb area.

Navigation and breadcrumb presentation use these public theme variables:

• --theme-text-strong: current navigation item
• --theme-navigation-bg: navigation-bar background
• --theme-navigation-border: navigation-bar bottom border
• --theme-navigation-border-width: navigation-bar bottom-border width
• --theme-breadcrumb-separator: navigation and breadcrumb separators

Panels and section titles use these public theme variables:

• --theme-panel-bg: shared panel background
• --theme-panel-border: default overview and detail-panel border color
• --theme-panel-border-width: default overview and detail-panel border width
• --theme-panel-radius: shared panel corner radius
• --theme-section-title-bg: section-title background
• --theme-section-title-text: section-title text
• --theme-section-title-padding-*: section-title padding
• --theme-section-bg: section box background
• --theme-section-border: section box border color
• --theme-section-border-width: section box border width
• --theme-section-radius: section box corner radius
• --theme-section-divider: divider color below section titles

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.

Pagination and Audio Tracks

Themes can refine pagination and audio-track presentation without replacing component CSS:

• --theme-pagination-button-radius: pagination-button corner radius; the shared default is square
• --theme-track-separator: separator color between audio tracks
• --theme-track-separator-width: separator width; the shared default is 0, so separators are opt-in

Track background, hover, and playing states continue to use the existing --theme-track-* color variables.

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.