/bb-theme-authoring

name: bb-theme-authoring
description: "Create or edit BB color themes and inspect them in the Theme Preview panel."

Authoring a bb theme

A bb theme is one CSS file that overrides the app's CSS custom properties. bb discovers custom themes on disk and the **Theme Preview** panel shows every resolved token, its validation state, and an app mock that repaints as you edit. Work in a split: your agent thread on one side, Theme Preview on the other. Nothing needs a restart.

Theme Preview is visualization and validation only. It never creates, writes, forks, repairs, or deletes a theme resource. Create and update `theme.css` from the separate agent thread; use the existing `bb theme` commands to locate, inspect, and activate themes. Validation reports inconsistent or inaccessible results, but it never changes authored values.

Where themes live

bb theme dir          # the custom-theme directory, e.g. ~/.bb/theme

One directory per theme, one file inside it:

<theme dir>/<name>/theme.css

`<name>` is the theme id: lowercase, letters, digits and dashes, a single path segment. Create the directory and the file and it is listed immediately — the Theme Preview dropdown picks it up on its next catalog refresh while the panel is open, and `bb theme list` shows it at once.

File shape

Two top-level blocks. Light values in `:root, .light`, dark values in `.dark`. Every declaration is a `--token: value;` custom property.

:root, .light {
  --canvas: #f4f4f4;
  --ink: #0a0a0a;
  --primary: #2e6f95;
  --primary-foreground: #ffffff;
}

.dark {
  --canvas: #1a1a1a;
  --ink: #dbd8d1;
  --primary: #9db6c6;
  --primary-foreground: #0a0a0a;
}

You only need to declare what you change; everything else derives from bb's base theme. The anchors that drive the most are `--canvas`, `--ink`, `--primary` and `--sidebar`.

Tokens worth knowing

| group | tokens | | --- | --- | | Surfaces | `--canvas` `--sidebar` `--card` `--popover` `--secondary` `--muted` `--surface-recessed-solid` `--surface-scrim` | | Ink | `--ink` (body) `--foreground` `--muted-foreground` `--subtle-foreground` `--readback-foreground` `--sidebar-foreground` | | Accent and state | `--primary` `--primary-foreground` `--file-accent` `--timeline-accent` `--surface-selected` `--state-hover` `--state-active` `--sidebar-accent` | | Status | `--success` `--warning` `--warning-text` `--destructive` `--destructive-text` `--pr-merged` `--diff-added` `--diff-removed` | | Lines | `--border` `--border-hairline` `--border-seam` `--sidebar-border` `--input` `--ring` | | Type | `--font-sans` `--font-mono` `--font-terminal` (declare once in `:root`) |

How bb uses them (from bb's own components, so you can predict the result): sidebar rows hover with `--sidebar-accent`, the open thread's row is `--state-active`, the default button is `--foreground` on `--background` (bb has no primary-filled button; `--primary` is links, focus and accents), the composer sits on the canvas with a 1px `--border`, code blocks and message bubbles are a faint recessed wash with `--border-seam`. The integrated terminal uses `--font-terminal`, independently of `--font-mono`.

Element-scoped blocks are allowed — for example `.dark .fixed.bg-sidebar { … }` to give only the sidebar a different value — but keep palette values in the two top-level blocks so tooling can read them.

Apply and iterate

bb theme set <name>   # activate it app-wide
bb theme show         # what is active now

Or activate it from the Theme Preview dropdown and use the adjacent mode control to check light and dark. Once active, **every save of `theme.css` repaints the app and the preview automatically** while the panel is open (the plugin watches the active theme's file and re-applies it). Edit in the agent thread, glance at the split, edit again.

Verify before you call it done

In Theme Preview, read the Style sheet measurements:

• **Ink rows show a WCAG ratio** against the surface they sit on; the floor is

4.5:1 for body text. The ratios are representative measurements, not a theme-level accessibility verdict.

• **Status rows** show their ratio against the tinted surface where they are

painted.

• **Surfaces** with an amber outline are overridden inside the sidebar scope —

make sure that is intentional.

• Check both modes with the dropdown, and the Split and Settings views, not

just Thread.

Treat failures as authoring guidance. Fix them in `theme.css` from the agent thread; Theme Preview does not block or automatically adjust the theme.

Keep dark-mode text below ~12:1 on near-black surfaces; higher blooms on OLED.

For manifest-contributed themes, read [references/plugin-themes.md](references/plugin-themes.md).