Theming

Overview

Hux UI provides a comprehensive theming system based on design tokens that automatically adapt to light and dark modes. The theming system separates primitive colors from semantic tokens, following modern design system best practices.

Design System Reference: Explore the complete design system, including all colors, tokens, and component specifications in our Figma library.

Theme Configuration

Basic Setup

Configure light and dark themes in your app:

main.dart

import 'package:flutter/material.dart';
import 'package:hux/hux.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      
      // Use Hux UI themes
      theme: HuxTheme.lightTheme,
      darkTheme: HuxTheme.darkTheme,
      
      // Control theme mode
      themeMode: ThemeMode.system, // Follow system setting
      // themeMode: ThemeMode.light, // Force light mode
      // themeMode: ThemeMode.dark,  // Force dark mode
      
      home: MyHomePage(),
    );
  }
}

Dynamic Theme Switching

Implement theme switching in your app:

class ThemeProvider extends StatefulWidget {
  @override
  _ThemeProviderState createState() => _ThemeProviderState();
}

class _ThemeProviderState extends State<ThemeProvider> {
  ThemeMode _themeMode = ThemeMode.system;

  void toggleTheme() {
    setState(() {
      _themeMode = _themeMode == ThemeMode.light 
          ? ThemeMode.dark 
          : ThemeMode.light;
    });
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: HuxTheme.lightTheme,
      darkTheme: HuxTheme.darkTheme,
      themeMode: _themeMode,
      home: Scaffold(
        appBar: AppBar(
          actions: [
            IconButton(
              icon: Icon(_themeMode == ThemeMode.light 
                  ? FeatherIcons.moon 
                  : FeatherIcons.sun),
              onPressed: toggleTheme,
            ),
          ],
        ),
        body: YourContent(),
      ),
    );
  }
}

Design Tokens

Hux UI uses semantic design tokens through the HuxTokens class. These tokens automatically adapt to the current theme.

Text Tokens

// Primary text (black in light, white in dark)
Text(
  'Primary Text',
  style: TextStyle(color: HuxTokens.textPrimary(context)),
)

// Secondary text (70% opacity)
Text(
  'Secondary Text',
  style: TextStyle(color: HuxTokens.textSecondary(context)),
)

// Tertiary text (50% opacity)
Text(
  'Tertiary Text',
  style: TextStyle(color: HuxTokens.textTertiary(context)),
)

// Disabled text (30% opacity)
Text(
  'Disabled Text',
  style: TextStyle(color: HuxTokens.textDisabled(context)),
)

Surface Tokens

// Primary surface (main background)
Container(
  color: HuxTokens.surfacePrimary(context),
  child: YourContent(),
)

// Secondary surface (subtle background)
Container(
  color: HuxTokens.surfaceSecondary(context),
  child: YourContent(),
)

// Elevated surface (cards, modals)
Container(
  color: HuxTokens.surfaceElevated(context),
  child: YourContent(),
)

// Hover surface
Container(
  color: HuxTokens.surfaceHover(context),
  child: YourContent(),
)

Border Tokens

// Primary borders
Container(
  decoration: BoxDecoration(
    border: Border.all(color: HuxTokens.borderPrimary(context)),
  ),
  child: YourContent(),
)

// Secondary borders (more subtle)
Container(
  decoration: BoxDecoration(
    border: Border.all(color: HuxTokens.borderSecondary(context)),
  ),
  child: YourContent(),
)

Status Tokens

// Success colors
HuxAlert(
  variant: HuxAlertVariant.success,
  title: 'Success!',
  message: 'Operation completed successfully.',
)

// Destructive colors
HuxAlert(
  variant: HuxAlertVariant.destructive,
  title: 'Error',
  message: 'Something went wrong.',
)

Custom Colors

Using Preset Colors

Hux UI provides several preset colors for customization:

// Available preset colors
final presets = HuxColors.availablePresetColors;
// ['default', 'indigo', 'green', 'pink']

// Use preset colors in buttons
HuxButton(
  onPressed: () {},
  child: Text('Indigo Button'),
  primaryColor: HuxColors.getPresetColor('indigo'), // #665CFF
)

HuxButton(
  onPressed: () {},
  child: Text('Green Button'),
  primaryColor: HuxColors.getPresetColor('green'), // #2E7252
)

HuxButton(
  onPressed: () {},
  child: Text('Pink Button'),
  primaryColor: HuxColors.getPresetColor('pink'), // #DF1D54
)

Custom Colors

Use any custom color with Hux UI components:

HuxButton(
  onPressed: () {},
  child: Text('Custom Purple'),
  primaryColor: Color(0xFF6366F1),
)

HuxButton(
  onPressed: () {},
  child: Text('Custom Orange'),
  primaryColor: Colors.deepOrange,
)

Color Accessibility

Hux UI automatically ensures WCAG AA contrast compliance:

// Button text color is automatically calculated for optimal contrast
HuxButton(
  onPressed: () {},
  child: Text('Auto Contrast'), // Text color adapts to background
  primaryColor: Colors.purple, // Any background color
)

Advanced Theming

Custom Theme Extensions

Extend Hux themes with your own customizations:

final customLightTheme = HuxTheme.lightTheme.copyWith(
  // Override specific properties
  appBarTheme: HuxTheme.lightTheme.appBarTheme.copyWith(
    backgroundColor: Colors.blue.shade50,
  ),
  // Add custom color scheme
  colorScheme: HuxTheme.lightTheme.colorScheme.copyWith(
    secondary: Colors.blue,
  ),
);

final customDarkTheme = HuxTheme.darkTheme.copyWith(
  appBarTheme: HuxTheme.darkTheme.appBarTheme.copyWith(
    backgroundColor: Colors.blue.shade900,
  ),
  colorScheme: HuxTheme.darkTheme.colorScheme.copyWith(
    secondary: Colors.blue.shade300,
  ),
);

Theme-Aware Widgets

Create widgets that respond to theme changes:

class ThemeAwareWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final isDark = Theme.of(context).brightness == Brightness.dark;
    
    return Container(
      padding: EdgeInsets.all(16),
      decoration: BoxDecoration(
        color: HuxTokens.surfaceElevated(context),
        border: Border.all(color: HuxTokens.borderPrimary(context)),
        borderRadius: BorderRadius.circular(12),
      ),
      child: Column(
        children: [
          Icon(
            FeatherIcons.star,
            color: HuxTokens.iconPrimary(context),
          ),
          Text(
            'Theme Aware Content',
            style: TextStyle(color: HuxTokens.textPrimary(context)),
          ),
          Text(
            'Adapts to ${isDark ? 'dark' : 'light'} mode',
            style: TextStyle(color: HuxTokens.textSecondary(context)),
          ),
        ],
      ),
    );
  }
}

Best Practices

Use Semantic Tokens

Always use HuxTokens instead of hardcoded colors:

// ✅ Good - semantic tokens
Text(
  'Hello',
  style: TextStyle(color: HuxTokens.textPrimary(context)),
)

// ❌ Bad - hardcoded colors
Text(
  'Hello',
  style: TextStyle(color: Colors.black),
)

Test Both Themes

Always test your UI in both light and dark modes:

// Force different themes for testing
MaterialApp(
  theme: HuxTheme.lightTheme,
  darkTheme: HuxTheme.darkTheme,
  themeMode: ThemeMode.light, // Test light mode
  // themeMode: ThemeMode.dark, // Test dark mode
)

Consistent Spacing

Use consistent spacing that works with the theme:

// Use multiples of 4 or 8 for consistent spacing
EdgeInsets.all(16), // ✅ Good
EdgeInsets.symmetric(horizontal: 20, vertical: 12), // ✅ Good
EdgeInsets.all(13), // ❌ Inconsistent

Accessibility

Leverage automatic contrast calculation:

// Hux UI automatically ensures proper contrast
HuxButton(
  primaryColor: Colors.purple, // Any color
  child: Text('Button'), // Text color automatically calculated
)

Color Reference

Preset Colors

Name	Light Mode	Dark Mode	Hex Code
Default	Black	White	Dynamic
Indigo	Indigo	Indigo	`#665CFF`
Green	Green	Green	`#2E7252`
Pink	Pink	Pink	`#DF1D54`

Status Colors

Status	Purpose	Light Mode	Dark Mode
Success	Positive actions	Dark Green	Light Green
Destructive	Errors, warnings	Dark Red	Light Red

Token Categories

Text: Primary, Secondary, Tertiary, Disabled, Inverted
Surface: Primary, Secondary, Elevated, Hover
Border: Primary, Secondary, Destructive, Success
Button: Secondary Background, Secondary Text, Secondary Border
Icon: Primary, Secondary
Chart: Grid, Axis, Axis Text

Examples

Theme Switching

See how to implement dynamic theme switching

Custom Branding

Learn how to apply custom brand colors

Figma Library

Explore the complete design system in Figma

Accessibility

Ensure your themes meet accessibility standards

Advanced Customization

Deep dive into advanced theming techniques

Getting Started

Components

Advanced

Overview

Theme Configuration

Basic Setup

Dynamic Theme Switching

Design Tokens

Text Tokens

Surface Tokens

Border Tokens

Status Tokens

Custom Colors

Using Preset Colors

Custom Colors

Color Accessibility

Advanced Theming

Custom Theme Extensions

Theme-Aware Widgets

Best Practices

Color Reference

Preset Colors

Status Colors

Token Categories

Examples

Theme Switching

Custom Branding

Figma Library

Accessibility

Advanced Customization

​Overview

​Theme Configuration

​Basic Setup

​Dynamic Theme Switching

​Design Tokens

​Text Tokens

​Surface Tokens

​Border Tokens

​Status Tokens

​Custom Colors

​Using Preset Colors

​Custom Colors

​Color Accessibility

​Advanced Theming

​Custom Theme Extensions

​Theme-Aware Widgets

​Best Practices

​Color Reference

​Preset Colors

​Status Colors

​Token Categories

​Examples

Theme Switching

Custom Branding

Figma Library

Accessibility

Advanced Customization

Overview

Theme Configuration

Basic Setup

Dynamic Theme Switching

Design Tokens

Text Tokens

Surface Tokens

Border Tokens

Status Tokens

Custom Colors

Using Preset Colors

Custom Colors

Color Accessibility

Advanced Theming

Custom Theme Extensions

Theme-Aware Widgets

Best Practices

Color Reference

Preset Colors

Status Colors

Token Categories

Examples