Getting Started

Installation

Requirements

Install

uv add chirp-ui

pip install chirp-ui

uv add "bengal-chirp[ui]"
# or
pip install "bengal-chirp[ui]"

Verify Installation

import chirp_ui
print(chirp_ui.__version__)  # e.g. "0.11.0"

Apply the chirp-theme Bengal Theme

The samechirp-uipackage also ships chirp-theme, a static-first Bengal theme. If you build a documentation or marketing site with Bengal, you can adopt the theme without a separate install —uv add chirp-uiregisters it through the bengal.themes entry point (chirp-theme = "bengal_themes.chirp_theme").

Point your Bengal site config at the theme by settingtheme.name:

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

Then build and serve the site:

uv run bengal build
uv run bengal serve

Why Bengal >=0.3.3? chirp-theme'sbase.htmlcalls library_asset_tags() to inject the component library's chirpui.css. That hook lands in Bengal 0.3.3. On older Bengal the call is skipped and the base CSS never loads, so spacing and grid layout collapse in the footer and top bar. Pinbengal>=0.3.3to be safe.

For the theme's architecture, ownership model, and parity policy, see [chirp-theme].

Next Steps

• [Apply chirp-theme] — Adopt the static-first Bengal theme on your own site
• [Components] — Browse layout, UI, forms, and streaming components
• [Theming] — Customize with CSS variables
• [App Shell] — Build dashboard layouts with sidebar and breadcrumbs

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.

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