Custom Branding Theme Guide

Overview

The Custom Branding theme is an Enterprise-tier theme designed to be easily customized with your company's brand colors while maintaining professional aesthetics and excellent readability.

Key Features:

• ✅ Modern slate blue/indigo design with premium feel
• ✅ Easy color customization for your brand
• ✅ Ambient background animations (Enterprise feature)
• ✅ Professional typography and spacing
• ✅ Full component support (buttons, panels, progress bars, etc.)

Usage

Basic Usage

from bravura.themes import ProfessionalThemeManager

# Initialize theme manager
theme_manager = ProfessionalThemeManager(self)

# Apply custom branding theme
theme_manager.apply_theme("custom")

Note: The custom theme is only available with Enterprise licenses. Other tiers will see this theme filtered out.

Default Color Palette

The custom theme comes with a professional indigo/slate color scheme by default:

Element	Color	Hex	Usage
Primary Accent	Rich Indigo	`#4F46E5`	Primary buttons, borders, focus states
Secondary Accent	Cyan	`#06B6D4`	Secondary actions, highlights
Brand Accent	Amber	`#F59E0B`	Tertiary accent, warnings
Background	Slate Dark	`#1E293B`	Main window background
Surfaces	Slate Medium	`#334155`	Panels, cards, buttons
Text Primary	Pure White	`#FFFFFF`	Main text content
Text Secondary	Blue Gray	`#E2E8F0`	Labels, descriptions
Success	Emerald	`#059669`	Success states, confirmations
Warning	Amber	`#D97706`	Warnings, cautions
Error	Red	`#DC2626`	Errors, destructive actions

High-Contrast Panel Colors

The custom theme also includes specialized panel background colors for visual hierarchy:

Element	Color	Hex	Usage
Input Panel	Light Gray	`#E8E8E8`	Form sections, settings areas
Progress Panel	Lighter Gray	`#F5F5F5`	Progress tracking, status updates
Results Panel	Medium Gray	`#ECECEC`	Output displays, results

These panel colors provide subtle visual separation between different functional areas of your application and can be customized to match your brand (see Customizing Panel Colors below).

Customizing Brand Colors

Method 1: Direct Theme Modification (Recommended)

The easiest way to customize the theme for your brand is to modify the theme definition directly:

# In your application startup code
from bravura.themes.theme_manager import PROFESSIONAL_THEMES

# Override custom theme colors with your brand
PROFESSIONAL_THEMES["custom"].update({
    "brand_primary": "#FF6B00",        # Your primary brand color (orange)
    "brand_secondary": "#00C4FF",      # Your secondary brand color (blue)
    "brand_accent": "#FFD700",         # Your accent color (gold)

    # Update other colors to match
    "accent_color_1": "#FF6B00",       # Primary buttons/focus
    "accent_color_2": "#00C4FF",       # Secondary highlights
    "button_bg": "#FF6B00",            # Primary button background
    "border_color": "#FF6B00",         # Borders and separators
    "log_fg": "#00C4FF",               # Log text color

    # Optional: Customize panel colors for visual hierarchy
    "panel_input_bg": "#FFF5E6",       # Light orange tint
    "panel_progress_bg": "#E6F7FF",    # Light blue tint
    "panel_results_bg": "#FFFACD",     # Light gold tint
})

# Now apply the customized theme
theme_manager.apply_theme("custom")

Method 2: Create Custom Theme Variant

For more control, create your own theme variant:

from bravura.themes.theme_manager import PROFESSIONAL_THEMES

# Define your custom brand theme
PROFESSIONAL_THEMES["my_brand"] = {
    "name": "My Company Brand",
    "description": "Custom theme with My Company branding",
    "tier": "enterprise",

    # Your brand colors
    "brand_primary": "#FF6B00",
    "brand_secondary": "#00C4FF",
    "brand_accent": "#FFD700",

    # Map to button/UI colors
    "button_bg": "#FF6B00",
    "button_fg": "#ffffff",
    "hover_bg": "#FF8533",            # Lighter orange
    "active_bg": "#CC5600",           # Darker orange

    # Text colors
    "text_main": "#FFFFFF",
    "text_secondary": "#E0E0E0",

    # Backgrounds
    "background_primary": "#1A1A1A",   # Dark background
    "background_secondary": "#2A2A2A", # Slightly lighter

    # Accents
    "accent_color_1": "#FF6B00",      # Primary accent (your orange)
    "accent_color_2": "#00C4FF",      # Secondary accent (your blue)

    # Sliders and controls
    "slider_trough": "#2A2A2A",

    # Logs
    "log_bg": "#000000",
    "log_fg": "#00C4FF",              # Blue log text

    # Borders
    "border_color": "#FF6B00",        # Orange borders

    # States
    "success_color": "#00FF00",
    "warning_color": "#FFD700",       # Gold warning
    "error_color": "#FF0000",

    # High-contrast panels (optional - for visual hierarchy)
    "panel_input_bg": "#FFF5E6",      # Light orange tint
    "panel_progress_bg": "#E6F7FF",   # Light blue tint
    "panel_results_bg": "#FFFACD",    # Light gold tint

    # Glass/glow effects (optional)
    "brand_glow": "rgba(255, 107, 0, 0.12)",
    "glass_custom": "rgba(42, 42, 42, 0.9)",
}

# Apply your custom theme
theme_manager.apply_theme("my_brand")

Method 3: Runtime Color Override

For dynamic branding based on user preferences:

def apply_custom_branding(theme_manager, primary_color, secondary_color):
    """Apply custom brand colors at runtime."""

    # Get current custom theme
    custom_theme = PROFESSIONAL_THEMES["custom"]

    # Update with dynamic colors
    custom_theme.update({
        "brand_primary": primary_color,
        "brand_secondary": secondary_color,
        "accent_color_1": primary_color,
        "accent_color_2": secondary_color,
        "button_bg": primary_color,
        "border_color": primary_color,
    })

    # Reapply theme to refresh UI
    theme_manager.apply_theme("custom")

# Example: User selects their company colors
user_primary = "#8B4789"    # Purple
user_secondary = "#FFB347"  # Peach
apply_custom_branding(theme_manager, user_primary, user_secondary)

Special Features

1. Ambient Background (Enterprise Only)

The custom theme automatically enables ambient background animations with your brand colors:

# Ambient background is automatically created when applying custom theme
theme_manager.apply_theme("custom")

# The background will use your brand_primary color in its glows
# Customize glow colors by setting:
PROFESSIONAL_THEMES["custom"]["brand_glow"] = "rgba(255, 107, 0, 0.12)"

2. Glass Panels

Glass panels adapt to your custom theme:

from bravura.components import GlassPanel

# Glass panels automatically use custom theme colors
panel = GlassPanel(
    parent,
    elevation=2,
    blur_amount=10
)
# Will use glass_custom color from theme

3. Premium Buttons

Premium buttons automatically adopt your brand colors:

from bravura.components import PremiumButton

# Primary button uses brand_primary color
button = PremiumButton(
    parent,
    text="Start",
    command=start_action,
    style="primary",
    theme_tokens=theme_manager.get_current_theme_colors()
)

Color Guidelines

When customizing brand colors, follow these guidelines for best results:

Contrast Requirements

Ensure adequate contrast ratios for accessibility:

• Text on dark backgrounds: Use colors with >70% lightness
• Text on light backgrounds: Use colors with <30% lightness
• Buttons: Primary color should have >4.5:1 contrast ratio with white text

Customizing Panel Colors

The high-contrast panel colors (panel_input_bg, panel_progress_bg, panel_results_bg) provide visual hierarchy by distinguishing different functional areas. When customizing:

Best Practices:

• Keep panel colors subtle - aim for 5-10% lightness difference from main background
• Maintain consistent tint direction - all lighter or all darker than main background
• Use your brand color family - tint panel colors with your primary/secondary colors
• Test readability - ensure labels and text remain clearly readable on panel backgrounds

Example Color Relationships:

# Light theme with orange brand
"background_primary": "#FFFFFF",      # Pure white
"panel_input_bg": "#FFF5E6",          # Subtle orange tint (warmest)
"panel_progress_bg": "#FFFAF0",       # Very subtle orange (neutral)
"panel_results_bg": "#FFF8E7",        # Light orange (warm)

# Dark theme with blue brand
"background_primary": "#1A1A1A",      # Dark gray
"panel_input_bg": "#1C1E26",          # Subtle blue tint
"panel_progress_bg": "#1D1F28",       # Slightly lighter
"panel_results_bg": "#1B1D25",        # Medium tint

Hover/Active Colors

Premium buttons automatically calculate hover/active states:

• Hover: 10% darker than base color
• Active: 20% darker than base color

For custom themes, you can manually specify hover colors if you want precise control.

Color Harmony

For professional appearance:

1. Limit palette: Use 2-3 brand colors maximum
2. Complementary or analogous: Choose colors that work well together
3. Consistent usage: Use same color for same purposes throughout
4. Semantic colors: Keep success=green, error=red, warning=amber

Complete Example

Here's a complete example of customizing the theme for "Acme Corporation":

from bravura.themes import ProfessionalThemeManager
from bravura.themes.theme_manager import PROFESSIONAL_THEMES

class AcmeApp:
    def __init__(self):
        self.root = tk.Tk()
        self.root.title("Acme Corporation - Data Analyzer")

        # Initialize theme manager
        self.theme_manager = ProfessionalThemeManager(self)

        # Customize for Acme brand (purple and gold)
        PROFESSIONAL_THEMES["custom"].update({
            "brand_primary": "#6B46C1",        # Acme Purple
            "brand_secondary": "#F6B645",      # Acme Gold
            "brand_accent": "#F6B645",         # Gold accent

            # Apply purple to primary elements
            "accent_color_1": "#6B46C1",
            "button_bg": "#6B46C1",
            "border_color": "#6B46C1",

            # Apply gold to secondary elements
            "accent_color_2": "#F6B645",
            "log_fg": "#F6B645",

            # Custom glow for ambient background
            "brand_glow": "rgba(107, 70, 193, 0.12)",
        })

        # Apply Acme-branded theme
        self.theme_manager.apply_theme("custom")

        # Your UI components will now use Acme colors
        self.setup_ui()

    def setup_ui(self):
        # All components automatically use Acme brand colors
        from bravura.components import PremiumButton

        PremiumButton(
            self.root,
            text="Start Analysis",
            command=self.start,
            style="primary",  # Will be purple
            theme_tokens=self.theme_manager.get_current_theme_colors()
        ).pack(pady=20)

if __name__ == "__main__":
    app = AcmeApp()
    app.root.mainloop()

Troubleshooting

Theme Not Available

Error: "custom" theme not in available themes

Solution: Custom theme requires Enterprise license. Check your license tier:

from bravura.config import get_current_license_tier

tier = get_current_license_tier()
print(f"Current tier: {tier}")  # Should be "enterprise"

Colors Not Updating

Problem: Changed PROFESSIONAL_THEMES but colors didn't update

Solution: Make sure to reapply theme after modifying:

# After modifying PROFESSIONAL_THEMES
theme_manager.apply_theme("custom")  # Reapply to refresh

Buttons Still Use Default Colors

Problem: Buttons created before theme change keep old colors

Solution: Pass theme_tokens when creating buttons:

# ✗ Wrong - uses default colors
button = PremiumButton(parent, text="Button")

# ✓ Correct - uses current theme
button = PremiumButton(
    parent,
    text="Button",
    theme_tokens=theme_manager.get_current_theme_colors()
)

Best Practices

1. Set theme early: Apply custom theme before creating UI widgets
2. Pass theme_tokens: Always pass theme_tokens to premium components
3. Test readability: Verify text is readable on all backgrounds
4. Consistent colors: Use same brand colors throughout your app
5. Document colors: Keep a record of your brand color choices

See Also

• Theme Manager API Reference
• Premium Button Customization
• Creating Custom Themes
• Enterprise Features