​
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.

​
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

​
Color Reference

​
Preset Colors

NameLight ModeDark ModeHex Code
DefaultBlackWhiteDynamic
IndigoIndigoIndigo#665CFF
GreenGreenGreen#2E7252
PinkPinkPink#DF1D54

​
Status Colors

StatusPurposeLight ModeDark Mode
SuccessPositive actionsDark GreenLight Green
DestructiveErrors, warningsDark RedLight 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

Accessibility

Ensure your themes meet accessibility standards

Advanced Customization

Deep dive into advanced theming techniques