bb-theme-authoring

# 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 ```sh 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. ```css :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 ```sh 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).