Theme & Appearance Management

Overview

All Butlers must adhere to the appearance API provided by The Butler. The core shell manages theme preferences (light/dark mode), color schemes, and design tokens. Your Butler receives theme information through the JS Bridge and must respect user preferences for a consistent, native experience.

Appearance API

The Butler provides a standardized appearance API that all Butlers must use. This ensures visual consistency across the platform and proper support for user preferences.

Get Current Theme

// Get current theme mode
const theme = await window.lifeButler.getTheme();
// Returns: { mode: 'light' | 'dark' | 'system', colors: {...} }

// Subscribe to theme changes
window.lifeButler.onThemeChange((theme) => {
  // Update your UI when theme changes
  updateButlerUI(theme);
});

Design Tokens & Colors

The appearance API provides semantic color tokens that automatically adapt to the current theme. Use these tokens instead of hardcoded colors to ensure proper contrast and accessibility.

// Get design tokens
const tokens = await window.lifeButler.getDesignTokens();
// Returns:
// {
//   colors: {
//     background: string,
//     foreground: string,
//     primary: string,
//     secondary: string,
//     accent: string,
//     muted: string,
//     border: string,
//     error: string,
//     warning: string,
//     success: string,
//     info: string
//   },
//   spacing: { ... },
//   typography: { ... },
//   borderRadius: { ... }
// }

// Use in your CSS or styles
document.documentElement.style.setProperty('--butler-primary', tokens.colors.primary);
document.documentElement.style.setProperty('--butler-background', tokens.colors.background);

CSS Custom Properties

The Butler injects CSS custom properties (CSS variables) into your Butler's container. You can use these in your stylesheets for automatic theme support.

/* Use CSS custom properties in your styles */
.butler-card {
  background-color: var(--butler-background);
  color: var(--butler-foreground);
  border: 1px solid var(--butler-border);
}

.butler-button {
  background-color: var(--butler-primary);
  color: var(--butler-primary-foreground);
}

.butler-text-muted {
  color: var(--butler-muted);
}

Initial Context

When your Butler loads, The Butler passes initial context including the current theme. Use this to render your UI correctly from the start.

// Initial context passed to your Butler
window.lifeButler.onReady((context) => {
  const { theme, locale, user } = context;
  // theme: { mode: 'light' | 'dark' | 'system', colors: {...} }
  // Initialize your UI with the theme
  initializeButler(theme);
});

Requirements

• Support both themes: Your Butler must support both light and dark modes. The appearance API will provide the current theme, and you must update your UI accordingly.
• Use design tokens: Always use the provided design tokens for colors, spacing, and typography. Do not hardcode colors or create custom color schemes that conflict with the platform.
• Listen for changes: Subscribe to theme change events and update your UI immediately when the user switches themes.
• Accessibility: Ensure sufficient color contrast ratios (WCAG AA minimum) in both themes. The design tokens are tested for accessibility, but verify custom UI elements.
• System preference: Respect the user's system preference when theme is set to "system". The appearance API handles this automatically.