Theming Deep Dive

chirp-theme is a static-first Bengal theme packaged in the chirp-uiproject. It takes the visual language from theb-sitemarketing shell and adapts it to Bengal's documentation and content templates: warm paper surfaces, phosphor dark mode, cyan and amber accents, crisp radii, and an editorial docs chrome.

Thechirp-uidocs site uses this theme directly, so the package gets exercised on a real Bengal site rather than living as a disconnected example.

Quickstart: Adopt It on a Bengal Site

If you have a Bengal site, applying chirp-theme is three steps. No separate theme package — the theme ships inside chirp-ui and registers through the bengal.themesentry point.

1. Install (this also installs the theme).

uv add chirp-ui
# or
pip install chirp-ui

chirp-uideclares the theme entry point chirp-theme = "bengal_themes.chirp_theme", so Bengal discovers it automatically once the package is installed. You also need Bengal >=0.3.3 (for thelibrary_asset_tags()hook described below); add it as a build dependency if it is not already present:

uv add "bengal>=0.3.3"

2. Set the theme in your site config.

# config/_default/theme.yaml  (or the theme block in bengal.toml)
theme:
  name: "chirp-theme"

3. Build and serve.

uv run bengal build
uv run bengal serve

That is enough to render a Bengal docs or marketing site with chirp-theme's shell, typography, and dark mode.

Requires Bengal >=0.3.3 —library_asset_tags(). chirp-theme's base.html calls Bengal's library_asset_tags()to inject the component library's bundledchirpui.css(the base tokens, reset, layout grid, and component styles). That hook ships in Bengal 0.3.3. On older Bengal the call is silently skipped,chirpui.cssnever loads, and the page renders with collapsed spacing and a broken grid in the footer and top bar. If your theme looks unstyled, check your Bengal version first.

A new-user adoption checklist also lives on the [Installation] page.

Enable It

Set the active Bengal theme in your site configuration:

theme:
  name: "chirp-theme"

What v1 Includes

• A packaged Bengal theme entry point:chirp-theme = "bengal_themes.chirp_theme"
• A standalone theme package with its own shell templates, partials, and assets
• Static-first templates forbase.html, home.html, page.html, doc/home.html, doc/list.html, and doc/single.html
• Retained core parity templates forblog/shell.html, blog/list.html, blog/single.html, post.html, search.html, and 404.html
• Retained taxonomy/archive/author, learning/content, autodoc/API reference, shortcode/embed, root alias, and utility templates listed in the parity matrix

Design Scope

v1 focuses on:

• docs sites
• product/marketing pages
• content-heavy static sites

v1 does not try to reproduce every Chirp application-shell pattern inside Bengal. The goal is a strong static-site shell first, with enough coverage to grow into a credible Bengal default-v2 candidate over time.

Ownership Model

chirp-theme is owned by the chirp-uiproject and should behave like a real, installable Bengal theme package, not a thin overlay on Bengal default.

That means the package itself should own:

• the shell templates
• theme partials/macros
• the canonicalassets/css/style.cssentrypoint
• any JS, icons, fonts, favicons, or manifests referenced by the shell

Thechirp-uidocs site is the acceptance target for that contract, so the theme is continuously dogfooded on a real Bengal site.

In the current cutover, "standalone" means the package owns the full runtime surface. The theme currently vendors the Bengal default asset and partial baseline intochirp-theme, then layers the chirp-themeshell and styling on top. The next phase is to replace more of that inherited baseline with more opinionatedchirp-ui-driven patterns.

Longer-Term Direction

The broader goal is to build a better and more comprehensive alternative to the historical Bengal default theme using modernchirp-ui, Kida, and Alpine-era patterns. The original default theme carries early-project CSS and template conventions;chirp-themeis the place to reach parity, simplify the old patterns, and then go beyond them.

That evolution happens from a standalone package baseline, not through continued runtime dependence on Bengal default internals.

Parity Policy

chirp-themetreats Bengal default's broad output coverage as the long-term target, but it does not treat the copied default templates and CSS as the target implementation.

• Retained: shell, docs, generic pages, blog/post, search, 404, taxonomy/archive/authors, learning/content, autodoc/reference/API-hub, shortcodes/embeds, root aliases, and utility pages
• Retained surfaces should be rebuilt with Chirp UI-native templates and tokens rather than preserved as copied default-theme implementations
• Deferred: niche graph/data-table/experimental UI until an output contract needs them

The repo-level parity matrix indocs/theming/chirp-theme-parity-matrix.mdis the source of truth for those decisions.

The canonical source guide is docs/theming/chirp-theme.md.

Bengal theme controls anatomy

The packagedchirp-themeships static-site controls for appearance menus, search, mobile navigation, docs navigation, table-of-contents tracking, and content tabs.

These are Bengal theme partial and asset hooks, not registry-owned Chirp UI component macros. App-level component contracts still come from the Chirp UI component registry, macros, generated CSS, and manifest.

The full rendered contract, selectors, browser-owned behavior, JavaScript exports, and proof locations live in the canonical source guide: docs/theming/bengal-theme-anatomy.md.

UI layers & terms

This page aligns with the Chirp guide: UI layers & shell regions (same concepts; Chirp owns thechirp.shell_regionsconstants).

Quick glossary

Avoid: using "chrome" alone for the whole app frame — say app shell, site shell, or topbar/sidebar.

Chirpmount_pageslayouts

Filesystem_layout.html files that extend app_shell_layout should declare {# target: body #}, an explicit {# domain: ... #}, and {# outlet: main #} so Chirp can:

• decide which links should boost together from shared domain ancestry
• matchHX-Target: #mainfor intra-domain app-shell navigation
• return HTML that still includes#page-content for hx-select

Minimal pattern:

{# target: body #}
{# domain: workspace #}
{# shell: workspace #}
{# outlet: main #}
{% extends "chirpui/app_shell_layout.html" %}

See the Chirp guide Filesystem routing for the routing-side contract.

chirp-ui responsibilities

• app_shell_layout.html — Defines the shell DOM, registers no extra Python; pairs with Chirp’s use_chirp_ui(app).
• Shell coherence script — Clears#chirp-shell-actions in htmx:beforeSwapwhen the response includes a shell-actions OOB, so users never see one frame of new page + stale actions (htmx runs primary swap before OOB).

Response boundaries

Application pages normally use three nested HTMX targets:

Server code should inspectHX-Targetbefore choosing a response shape. A genericHX-Requestcheck is not enough: shell navigation and route-tab navigation are both HTMX requests, but they have different owners.

Related docs

• Repo: docs/fundamentals/ui-layers.md (duplicate reference for editors)
• Repo: docs/components/shell-tabs-contract.md (route-tab and response-shape checklist)
• docs/fundamentals/layout-overflow.md — keeping the main column stable
• docs/COMPONENT-OPTIONS.md — components; distinguishes surface chrome from shell