Bravura Integration Checklist

Purpose

This checklist prevents common integration mistakes and ensures successful Bravura implementation.

Pre-Integration Research

✅ Step 1: Read Actual API Documentation

[ ] Read the actual component source code
[ ] Check __init__ method signatures
[ ] Review example usage in existing demos
[ ] Test with minimal example first

✅ Step 2: Verify Component Parameters

Theme Manager:


# CORRECT ✅
class AppWrapper:
    def __init__(self, root):
        self.root = root

app = AppWrapper(tk.Tk())
theme_manager = ProfessionalThemeManager(app)

Ambient Background:


# CORRECT ✅
AmbientBackground(
    parent_widget,
    width=int,
    height=int,
    enable_animation=bool,
    animation_speed="slow"/"medium"/"fast",
    particle_count=int,
    glow_effects=bool
)

# WRONG ❌ - These parameters don't exist:
# primary_color, secondary_color, tertiary_color, glow_intensity

✅ Step 3: Button Styling Requirements

Critical: Regular tk.Button Does NOT Respond to ttk.Style!

Wrong Approach ❌:


# This creates ILLEGIBLE gray buttons with white text!
button = ttk.Button(parent, text="Click Me")
# Theme applies but colors are wrong

Correct Approach ✅:


# Option 1: Use themed ttk.Button with proper configuration
style = ttk.Style()
style.configure('Custom.TButton',
    background='#20C6B7',
    foreground='#FFFFFF',
    borderwidth=0,
    focuscolor='none')
button = ttk.Button(parent, text="Click Me", style='Custom.TButton')

# Option 2: Use Bravura PremiumButton (requires import)
from bravura.components.premium_buttons import PremiumButton
button = PremiumButton(parent, text="Click Me", style="primary")

# Option 3: Manual tk.Button styling (less reliable)
button = tk.Button(parent,
    text="Click Me",
    bg='#20C6B7',
    fg='#FFFFFF',
    activebackground='#1AB5A6',
    activeforeground='#FFFFFF',
    relief='flat',
    borderwidth=0)

Integration Testing Checklist

✅ Visual Testing (REQUIRED)

[ ] Launch application and verify it displays
[ ] Check all text is readable
[ ] Verify buttons are visible and clickable
[ ] Test on target OS (Windows/Mac/Linux)
[ ] Screenshot before declaring success

✅ Component Testing

[ ] Theme manager applies without errors
[ ] Ambient background creates without errors
[ ] Canvas z-order is correct (background behind content)
[ ] Status bar displays correctly
[ ] All tabs are accessible

✅ Color Contrast Testing

[ ] Light text on dark backgrounds
[ ] Dark text on light backgrounds
[ ] Button text visible against button background
[ ] Minimum 4.5:1 contrast ratio (WCAG AA standard)

Common Pitfalls

❌ Pitfall 1: Assuming API Parameters

Problem: Writing code based on what you think the API should be

Solution: Always read the actual source code first

❌ Pitfall 2: tk.Button Background Changes

Problem: bg parameter doesn't work on Windows/Mac for ttk.Button

Solution: Use ttk.Style or custom tk.Button with explicit colors

❌ Pitfall 3: Canvas Z-Order

Problem: Calling canvas.lower() without arguments fails

Solution: Use canvas.tkraise() on foreground widgets instead

❌ Pitfall 4: Unicode in Logging

Problem: Windows file logging uses cp1252, can't handle emojis

Solution: Always specify encoding='utf-8' in FileHandler

❌ Pitfall 5: Theme Manager Initialization

Problem: Passing tk.Tk() directly instead of wrapper object

Solution: Create wrapper class with .root attribute

Required Test Script

Before declaring integration complete, run this test:


#!/usr/bin/env python3
"""
Minimal Bravura Integration Test
Run this BEFORE integrating into your app!
"""
import tkinter as tk
from tkinter import ttk

# Test 1: Theme Manager
try:
    from bravura.themes.theme_manager import ProfessionalThemeManager

    root = tk.Tk()
    root.title("Bravura Integration Test")
    root.geometry("600x400")

    class AppWrapper:
        def __init__(self, root):
            self.root = root

    app = AppWrapper(root)
    theme = ProfessionalThemeManager(app)
    theme.apply_theme("wigley_site")

    print("✅ Theme Manager: SUCCESS")
except Exception as e:
    print(f"❌ Theme Manager: FAILED - {e}")
    exit(1)

# Test 2: Create Visible Button
frame = ttk.Frame(root)
frame.pack(fill="both", expand=True, padx=20, pady=20)

# Create button with explicit visibility
button = tk.Button(
    frame,
    text="Test Button - Can You Read This?",
    bg='#20C6B7',
    fg='#FFFFFF',
    font=('Segoe UI', 12, 'bold'),
    padx=20,
    pady=10
)
button.pack(pady=20)

label = ttk.Label(
    frame,
    text="If this text and button are readable, theme is working!",
    font=('Segoe UI', 11)
)
label.pack(pady=10)

print("✅ Visual Test: Launch window and verify text is readable")
print("   - Can you read the button text?")
print("   - Can you read the label text?")
print("   - Is button background teal (#20C6B7)?")

root.mainloop()

Documentation Requirements

Before using any Bravura component:

Read the source: Open the actual .py file
Check examples: Look at existing demo usage
Test minimal: Create 10-line test script
Verify visually: Actually look at the window
Document findings: Note any gotchas

Integration Phases

Phase 1: Research (30 minutes)

Read component source code
Review existing examples
Note parameter requirements
List dependencies

Phase 2: Minimal Test (15 minutes)

Create standalone test script
Test component in isolation
Verify visual appearance
Document any issues

Phase 3: Integration (1-2 hours)

Integrate into target application
Test all features
Verify no regressions
Screenshot results

Phase 4: Documentation (30 minutes)

Document integration steps
Note any gotchas
Create troubleshooting guide
Update this checklist

Success Criteria

Integration is complete when:

✅ Application launches without errors
✅ All text is readable (good contrast)
✅ Buttons are visible and clickable
✅ Theme applies correctly
✅ No console errors
✅ Screenshots show professional appearance
✅ Original functionality preserved

Failure Indicators

Stop and fix if you see:

❌ Gray buttons with white text (illegible)
❌ Black text on dark backgrounds
❌ White text on light backgrounds
❌ Console errors during startup
❌ Missing widgets or blank areas
❌ Application crashes

---

Real-World Case Study: Hostinger Database Manager POC

The Wrong Way (What NOT to Do)

Attempt 1: Passive Integration


# Added Bravura methods but didn't use them properly
class MyApp:
    def __init__(self):
        # ❌ Forgot to call theme application
        pass

    def create_gui(self):
        # Created widgets first
        self.notebook = ttk.Notebook(...)
        # ❌ Added ambient background LAST (hidden behind widgets)
        self._create_ambient_background()

Result: 5988 lines, looked identical to original ❌

Mistakes Made:

❌ Never replaced button creation calls (74 instances untouched)
❌ Added ambient background after widgets (wrong z-order)
❌ Declared success without visual testing
❌ Violated every rule in this checklist

The Right Way (Proper Integration)

Attempt 2: Systematic Replacement


# 1. Systematically replaced ALL 74 button instances
OLD: ttk.Button(parent, text="Click", command=cmd)
NEW: self.create_styled_button(parent, "Click", cmd)

# 2. Applied theme immediately in __init__
def __init__(self, root):
    self.root = root
    self._apply_bravura_dark_theme()  # FIRST!

# 3. Created ambient background BEFORE widgets
def create_gui(self):
    self._create_ambient_background()  # FIRST!
    self.root.update_idletasks()
    self.notebook = ttk.Notebook(...)  # Then widgets on top

Result: 6222 lines, marketing-ready POC ✅

Success Criteria Met:

✅ 74 buttons replaced with teal styled versions
✅ Ambient background visible and animated
✅ Professional dark theme applied
✅ All functionality preserved
✅ Visually tested and verified

Lesson Learned

Every mistake made was explicitly warned against in this checklist:

Didn't read source → Wrong API usage
Didn't test visually → Missed broken appearance
Didn't replace buttons → Ugly standard buttons
Didn't check z-order → Hidden background

The Integration Checklist works! Following it prevents these mistakes.

---

Remember: If you can't read the text, your users can't either!

Test visually BEFORE declaring success!

---