🔗Boxxy Theme Engine & API

Boxxy decouples Terminal Palettes (the 16 ANSI colors and canvas background inside the terminal grid) from Application Chrome Themes (crates/themes/src/app_theme.rs and resources/themes/boxxy_skeleton.css).

All widgets below are rendered live in HTML and CSS using Boxxy's exact design tokens, borders, shadows, and padding rules. Use the Live Theme & Accent Playground toolbar to switch themes or override the accent color across every widget on this page in real time.

---

🔗The 4-Layer GTK CssProvider Cascade

Boxxy styles application chrome using four prioritized GTK 4 CssProvider layers so custom themes can be toggled or hot-reloaded at runtime without restarting the application:

Layer	GTK Priority	Source	Lifecycle	Responsibility
Layer 1 (Base)	600 (PRIORITY_APPLICATION)	resources/style.css	Always loaded	Base widget geometry, spacing, layout rules, and fallback @define-color tokens for Legacy Adwaita.
Layer 1b (Palette)	610 (PRIORITY_APPLICATION + 10)	build.rs (generate_gtk_css)	Loaded when a terminal palette is selected	Terminal-coupled .terminal-header and .claw-drawer colors when running in Legacy Adwaita mode.
Layer 2 (Skeleton)	800 (PRIORITY_USER)	resources/themes/boxxy_skeleton.css	Loaded only in Boxxy Theme mode	Playful neo-brutalist outlines (@boxxy_ink), tactile offset drop-shadows (@boxxy_shadow), capsule navigation pills, and active button press states.
Layer 3 (Theme Tokens)	810 (PRIORITY_USER + 10)	AppThemeColors::to_gtk_css()	Loaded only in Boxxy Theme mode	Defines all semantic @define-color variables from the active built-in or community .toml theme.
Layer 4 (Accent Override)	820 (PRIORITY_USER + 20)	generate_accent_override_css()	Loaded when a custom accent is set	Overrides @accent_color, @accent_bg_color, and auto-contrasted @accent_fg_color on top of any active theme.

---

🔗Official Built-in Palettes (Boxxy Dark & Boxxy Light)

Token (AppThemeColors)	Boxxy Dark (boxxy-dark)	Boxxy Light (boxxy-light)	Surface Role
window_bg	#1d1d20	#ecfafb	Primary window, dialog, and Claw overlay drawer canvas background.
window_fg	#f2f4f2	#111418	Primary text and icon foreground on window_bg.
sidebar_bg	#2e2e32	#ffffff	Left sidebar (AI Chat, Claw, Bookmarks, Colors) and Preferences navigation sidebar.
sidebar_fg	#f2f4f2	#111418	Text and icon foreground on sidebar_bg.
card_bg	#26262a	#ffffff	Tactile buttons, unselected tabs, preference cards, entries, and linked button strips inside menus.
card_fg	#f2f4f2	#111418	Text and icon foreground on card_bg.
headerbar_bg	#1d1d20	#ffffff	Main content headerbar, dialog headerbars, and non-frosted terminal headerbar.
headerbar_fg	#f2f4f2	#111418	Text and icon foreground on headerbar_bg.
popover_bg	#2e2e32	#ffffff	Matches sidebar_bg. Used by the terminal right-click menu, hamburger menu, command palette, and autocomplete popover.
popover_fg	#f2f4f2	#111418	Text and icon foreground on popover_bg.
accent	#7ec868	#00acc1	Selected tabs, active sidebar rows, active switcher buttons, suggested-action buttons, checked switches, and focus rings.
accent_fg	#0d140a	#0d1117	High-contrast ink text and icons rendered on top of accent surfaces.
ink_border	#050505	#111418	Crisp 2px neo-brutalist outlines and structural pane dividers (@boxxy_ink).
shadow	#050505	#111418	Solid offset drop-shadows (@boxxy_shadow).

---

🔗Complete @define-color Variable Catalog & Component Mapping

Components never hardcode hex or RGB values for surfaces, borders, or semantic states. Every stylesheet rule references the semantic @define-color variables below:

CSS Variable	Source Field / Formula	Where It Is Used
@window_bg_color	colors.window_bg	Main window background, dialog sheets (@dialog_bg_color), Claw overlay drawer background (.claw-drawer), OSD overlays, bookmark preview frames, and avatar status badges.
@window_fg_color	colors.window_fg	Primary text inside windows, dialogs (@dialog_fg_color), Claw overlay conversation rows, and OSD overlays.
@sidebar_bg_color	colors.sidebar_bg	Left workspace sidebar (.sidebar-toolbar, .sidebar-pane) and the Preferences navigation sidebar.
@sidebar_fg_color	colors.sidebar_fg	All text, icons, and .sidebar-header inside the left sidebar and Preferences sidebar.
@headerbar_bg_color	colors.headerbar_bg	Main window headerbar (.content-header), .terminal-header, and dialog headerbars.
@headerbar_fg_color	colors.headerbar_fg	Titles, buttons, and icons inside .terminal-header, .content-header, and dialog headerbars.
@card_bg_color	colors.card_bg	Unselected terminal tabs, standard tactile buttons, preference boxed-list groups, search & text entries, Claw message bar (.boxxy-msgbar), diagnosis/diff viewer cards, character selector pills, status pills, and linked button strips inside menus (popover.menu box.linked).
@card_fg_color	colors.card_fg	Text, labels, and icons inside all @card_bg_color widgets above.
@popover_bg_color	colors.popover_bg	Terminal right-click menu (popover.terminal-menu), hamburger menu (popover.menu), command palette, search popover, and @file autocomplete popover.
@popover_fg_color	colors.popover_fg	Menu items (modelbutton) and labels inside all popovers.
@accent_bg_color	colors.accent	Selected terminal tab, selected sidebar row, active sidebar switcher button, pressed tactile buttons, .suggested-action buttons, hovered popover menu items, checked switches & checkboxes, selected character pills, and theme tag pills.
@accent_fg_color	colors.accent_fg	High-contrast text and icons inside all @accent_bg_color surfaces.
@accent_color	colors.accent	Focus outlines on search entries, text inputs, and the Claw message bar (.boxxy-msgbar:focus-within), plus bookmark variable chips and Vibe badges.
@boxxy_ink	colors.ink_border	2px solid outlines on tabs, sidebar rows, tactile buttons, window controls, entries, boxed lists, cards, popovers, dialogs, switches, checkboxes, and structural pane dividers.
@boxxy_shadow	colors.shadow	Hard-edge offset drop-shadows (2px 3px 0px, 3px 4px 0px, 4px 5px 0px) on tactile buttons, selected sidebar pills, boxed lists, cards, popovers, and dialogs.
@boxxy_surface_hover	mix(@card_bg_color, @accent_bg_color, 0.82)	Vibrant hover background (82% accent + 18% card, paired with @accent_fg_color ink text) for unselected tabs, unselected sidebar rows, tactile buttons, character selector pills, and What's New stat tiles.
@destructive_bg_color	Dark: #c01c28 · Light: #e01b24	Destructive action buttons (.destructive-action), error progress bars, avatar remove badge hover, and diff deletion ratio bars.
@success_bg_color	Dark: #26a269 · Light: #2ec27e	Terminal progress bars, model ready status titles, What's New hero badge, and diff addition counters/bars.

---

🔗Visual Hierarchy: Shadow vs. Non-Shadow Matrix

Component	Has @boxxy_shadow?	Shadow Offset	Rationale
Sidebar Switcher Buttons (viewswitcher > button)	Yes	2px 3px 0px @boxxy_shadow	Top-level mode switchers (AI Chat, Claw, Bookmarks, Colors) sit in the spacious sidebar header with a 2px inter-button gap and act as tactile physical toggles.
Sidebar & Command Palette Rows (.navigation-sidebar > row:selected, :hover, .menu-open)	Yes	2px 3px 0px @boxxy_shadow	Lifts the active or hovered conversation, command palette item, bookmark, or preferences category above the flat list. Depresses to 1px 1px 0px on click.
Terminal Tabs (tabbar tab, tabbar tab:selected)	No (box-shadow: none)	none	Tabs live inside the compact 28px tab bar strip. Keeping box-shadow: none (while retaining the 2px @boxxy_ink outline and @accent_bg_color active fill) prevents bottom shadow clipping inside AdwTabBox.
Standalone Tactile Buttons (headerbar button, windowcontrols > button, dialog button)	Yes	2px 3px 0px @boxxy_shadow	Primary interactive buttons. Depress by translate(1px, 1px) with 1px 1px 0px @boxxy_shadow when clicked.
Popover Linked Button Container (popover.menu box.linked)	Yes (Container only)	2px 3px 0px @boxxy_shadow	The outer segmented bar (Copy | Copy Link, split/close bar) casts a single unified shadow.
Individual Linked Buttons (popover.menu box.linked > button.model)	No (box-shadow: none)	none	Inner segments are separated by border-right: 2px solid @boxxy_ink inside the shared container; per-segment shadows would overlap adjacent buttons.
Preference Groups & Cards (listbox.boxed-list, .card)	Yes	3px 4px 0px @boxxy_shadow	Large elevated content containers.
Popovers & Dialog Sheets (popover > contents, dialog sheet)	Yes	4px 5px 0px @boxxy_shadow	Highest elevation layer floating above the window canvas.

---

🔗Community Theme .toml API Specification

Users and community authors can drop .toml files into ~/.config/boxxy-terminal/themes/ (or $BOXXY_CONFIG_DIR/themes/). On first launch, Boxxy seeds README.md, cotton-candy.toml, and bauhaus.toml into this folder. While Preferences → Themes is open, Boxxy polls the folder every 500 ms (using a zero-I/O (filename, mtime, size) metadata stamp) and live-reloads any edits immediately.

🔗Full .toml Schema

[meta]
name = "Cotton Candy"                                  # Optional (defaults to filename stem with spaces)
author = "nukeop"                                      # Optional (defaults to "community")
description = "Soft pastels in baby pink and blue"     # Optional (defaults to "")
mode = "light"                                         # Optional: "light" or "dark" (auto-detected from window_bg luminance if omitted)
tags = ["pastel", "pink", "cute"]                      # Optional: up to 6 tags (first 3 shown as pills in Preferences)

[colors]
# --- REQUIRED (3 fields) ---
window_bg = "#fff5f8"
window_fg = "#1e1b24"
accent    = "#ff7eb6"

# --- OPTIONAL (11 fields — automatically derived if omitted) ---
sidebar_bg   = "#fce8ef"   # Defaults to `window_bg`
sidebar_fg   = "#1e1b24"   # Defaults to `window_fg`
card_bg      = "#ffffff"   # Defaults to `window_bg`
card_fg      = "#1e1b24"   # Defaults to `window_fg`
headerbar_bg = "#fce8ef"   # Defaults to `sidebar_bg`
headerbar_fg = "#1e1b24"   # Defaults to `sidebar_fg`
popover_bg   = "#fce8ef"   # Defaults to `sidebar_bg` (matches sidebar surface!)
popover_fg   = "#1e1b24"   # Defaults to `sidebar_fg`
accent_fg    = "#1e1b24"   # Defaults to `contrast_fg_for_hex(accent)` (#ffffff or #111418)
ink_border   = "#1e1b24"   # Defaults to "#07080c" (dark mode) or "#111418" (light mode)
shadow       = "#1e1b24"   # Defaults to `ink_border`

🔗Automatic Fallback Derivation Chain

A valid community theme only requires 3 colors (window_bg, window_fg, accent). All remaining tokens derive automatically in parse_community_theme_toml():

window_bg ──┬──► sidebar_bg ──┬──► headerbar_bg
            │                 └──► popover_bg
            └──► card_bg

window_fg ──┬──► sidebar_fg ──┬──► headerbar_fg
            │                 └──► popover_fg
            └──► card_fg

accent ────────► accent_fg (via relative luminance: < 0.38 → #ffffff, >= 0.38 → #111418)

mode (is_dark) ► ink_border (#07080c if dark, #111418 if light) ──► shadow

🔗Security & Validation (sanitize_hex_color)

• Every color string in [colors] (and any user custom_accent_color) is validated through sanitize_hex_color(raw: &str) -> Option<String>.
• Only exact 6-digit (#RRGGBB) or 8-digit (#RRGGBBAA) ASCII hexadecimal strings are accepted.
• Any invalid hex or CSS injection attempt (e.g., #ffffff; @import ... or arbitrary CSS rules) returns None, guaranteeing community themes can never break widget geometry or inject arbitrary CSS.

---