# Themes

URL: /bengal/docs/build-sites/customize/themes/
Section: themes
Description: Use, customize, or create themes

---

> For a complete page index, fetch /bengal/llms.txt.

Themes are complete design packages. Use one as-is, customize it, or build your own.

Note

Do I need this? Yes when switching, customizing, or authoring themes. For a
first override, see Swizzle tutorial (/bengal/docs/tutorials/theming/swizzle-default-theme/)
or Customize the Default Theme (/bengal/docs/build-sites/customize/themes/customize/).

Customize Themes

Customize existing themes without breaking updates

(/bengal/docs/build-sites/customize/themes/customize/)

Theme Library Assets

Package reusable Kida components with CSS and JavaScript for Bengal themes

(/bengal/docs/build-sites/customize/themes/library-assets/)

## Theme Resolution

flowchart TB
A[Request: header.html]
B{Your templates/?}
C{Theme templates/?}
D{Bengal default?}
E[Use your file]
F[Use theme file]
G[Use default file]

A --> B
B -->|Found| E
B -->|Not found| C
C -->|Found| F
C -->|Not found| D
D --> G

Your files always win. Override only what you need.

## Choose Your Approach

🎨 Use Default

Effort: None

Works out of the box. Set colors via CSS variables.

✏️ Customize

Effort: Low-Medium

Override specific templates. No forking required.

🏗️ Create New

Effort: High

Full control. Start from scratch or fork existing.

## Bundled Themes

Theme
Use when

`default`
You want Bengal's built-in documentation theme with no extra packages.

Bengal bundles a single`default`theme. For component-library themes such as
the external Chirp UI theme, install the theme package and point`theme`at it;
the package supplies its own templates and assets through the theme library
asset contract below.

Theme authors can package reusable component systems with theme library asset
contracts (./library-assets/). Bengal will load the package templates, emit the
declared CSS/JS in both dev and static builds, and warn or fail when rendered
HTML references missing local assets.

## Quick Reference

- Use a Theme (#)

- CSS Variables (#)

- Override Template (#)

toml
TOML

```
# bengal.toml
[build]
theme = "default"
```

css
CSS

```
/* static/css/custom.css */
:root {
  --color-primary: #3b82f6;
  --color-background: #0f172a;
  --font-family-base: "Inter", sans-serif;
}
```
Include in your template:

html
HTML

```
<link rel="stylesheet" href="{{ asset_url('css/custom.css') }}">
```
Or store the path in `[theme.config]`and reference it:

toml
TOML

```
[theme.config]
custom_css = ["css/custom.css"]
```
Then in your template:

html
HTML

```
{% for css_file in theme.config.custom_css %}
<link rel="stylesheet" href="{{ asset_url(css_file) }}">
{% end %}
```

tree-sitter-query
TREE-SITTER-QUERY

```
your-project/
└── templates/
    └── partials/
        └── header.html  # Your version wins
```
Use `bengal theme swizzle --template-path partials/header.html`to copy the original, then modify as needed.

## Theme Contents

Directory
Purpose

`templates/`
HTML templates (Kida)

`static/`
CSS, JS, images

`assets/`
Processed assets

`theme.toml`
Theme configuration

Tip

Start minimal: Override CSS variables first. Only copy templates when you need structural changes. The less you override, the easier upgrades will be.

## In This Section

Customize Themes (/bengal/docs/build-sites/customize/themes/customize/)

Customize existing themes without breaking updates

Theme Library Assets (/bengal/docs/build-sites/customize/themes/library-assets/)

Package reusable Kida components with CSS and JavaScript for Bengal themes

Related Pages

Templating (/bengal/docs/build-sites/customize/templating/)

Kida template engine, layouts, inheritance, and partials

Related

Assets (/bengal/docs/build-sites/customize/assets/)

CSS, JavaScript, images, and fonts

Related

Build Sites (/bengal/docs/build-sites/)

Write, structure, customize, and extend your Bengal site

Related

Theming (/bengal/docs/build-sites/customize/)

Templates, assets, and visual customization

Related

Template Cookbook (/bengal/docs/build-sites/customize/recipes/)

Common templating patterns and Bengal-specific features

Related

persona-themer (/bengal/tags/persona-themer/)