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.