UTA DevHub
UI Development/Theme Management

Theme Management

Core architecture and concepts for theme implementation in the React Native application.

Theme Management

Executive Summary

This document outlines the theme management architecture of our application, which provides a flexible foundation for consistent styling, multi-brand support, and runtime theming capabilities. The theme system is deeply integrated with our initialization architecture, particularly the Pre-UI stage, to ensure proper theme application before any visual content is displayed to the user.

Purpose & Scope

This guide serves as the primary reference for understanding and working with our theme system. Its purpose is to:

  • Define the core theme architecture and organization of theme assets
  • Explain how themes are loaded during application initialization
  • Provide a conceptual overview of multi-brand and white-label support
  • Document the core APIs and hooks for consuming theme values

This document is intended for all developers working on UI components, styling, or brand-specific implementations. It covers both the technical architecture of the theme system and the design principles that guide its implementation.

Theme Structure Organization

Our theme system follows a hierarchical organization with clear separation of concerns:

The theme system is built around a clear file organization pattern. Here's the file structure with the responsibilities of each file:

Core style files contain:

core/shared/styles/
├── theme.ts         # Base theme and theme composition
├── typography.ts    # Text styles and font definitions
├── layout.ts        # Layout constants and utilities
├── shadows.ts       # Shadow styles for different elevations
├── mixins.ts        # Reusable style patterns
└── index.ts         # Barrel exports

Core Components

The theme system consists of these primary components:

  1. Base Theme Definition

    • Core color palette, spacing, radius values
    • Light and dark mode variations
    • Typography scales and text styles

  2. Theme Provider

    • React Context for theme distribution
    • Mode selection (light, dark, system)
    • Theme composition and overrides

  3. White Label Configuration

    • Brand-specific theme overrides
    • Dynamic theme switching
    • Integration with app initialization

  4. Theme Hooks and Utilities

    • useTheme hook for component access
    • Responsive styling utilities
    • Theme switching mechanisms

Design Principles

Our theme management system follows these core design principles:

  • (Do ✅) Single Source of Truth

    • Theme values should be defined once and consumed throughout the application
    • Component styles should derive from theme values, not hardcoded constants

  • (Do ✅) Composition over Inheritance

    • Themes are composed by merging base themes with specific overrides
    • This allows for flexible theme customization without duplication

  • (Do ✅) Platform Agnostic Base

    • Core theme definitions should be platform-agnostic
    • Platform-specific adaptations occur at the component level

  • (Don't ❌) Couple Themes to UI Components

    • Theme definitions should not reference specific UI components
    • This ensures the theme system can evolve independently of the component library

Integration with Initialization Architecture

The theme system is integrated with our application's initialization architecture, specifically during the Pre-UI stage. This ensures that the appropriate theme is loaded and applied before any UI components are rendered.

Theme Initialization Flow

Theme Switching Mechanism

For detailed implementation of theme initialization, refer to the Theme Implementation.

Implementation Guides

Theme Implementation

Detailed guide for implementing the theme system in components, including provider setup and hook usage.

White-Label Themes

Implementation guide for white-label theming, brand-specific configurations, and dynamic theme switching.

Architecture References

App Initialization

Learn how the theme system integrates with the application initialization flow.

Core Architecture

Overall system architecture including state management and how theming fits into the application structure.

Project Structure

Learn where theme files are located in the project and how they're organized.

UI Component Patterns

Guidelines for creating themed UI components that properly consume theme values.

Assets Management

Learn how assets like images and icons integrate with the theming system.

Summary

The theme management system provides a flexible, performant foundation for styling our application with multi-brand support. By loading theme configurations during the Pre-UI stage, we ensure consistent styling from the very first rendered component.

Key principles to remember:

  • Theme and white-label configuration are loaded during Pre-UI initialization
  • Theme system is hierarchical (base → mode → brand → device)
  • Components access theme values via the useTheme hook
  • White-label support enables runtime switching between brands

Advanced Topics

Advanced splash screen implementations including custom animations, abstractions, and performance optimization

Theme Implementation

Practical guide for implementing the theme system in components, including provider setup and hooks.

On this page