DEV Community: Zoe

Building modern Flutter UIs with Hux: A comprehensive guide to Hux widgets

Zoe — Sat, 01 Nov 2025 15:41:45 +0000

Hux UI is a modern Flutter package that provides a comprehensive set of beautifully designed, accessible, and customizable widgets.

In this technical deep-dive, we'll explore every widget in the Hux ecosystem, their implementation details, and how to leverage them in your Flutter applications.

Architecture & Design Philosophy
Buttons
Input Components
Cards & Containers
Navigation Components
Feedback & Status
Data Visualization
Overlays & Dialogs
Utility Components
Theming System

Architecture & Design Philosophy

Hux UI is built on three core principles:

1. Design Token System

Hux uses a sophisticated token-based theming system via HuxTokens that provides semantic color values. These tokens automatically adapt to light/dark themes and respect custom Material 3 seed colors:

// Tokens automatically adapt to theme
HuxTokens.primary(context)          // Primary color (respects seed colors)
HuxTokens.surfacePrimary(context)   // Surface colors
HuxTokens.borderPrimary(context)    // Border colors
HuxTokens.textPrimary(context)      // Text colors

2. WCAG AA Accessibility

All components meet WCAG 2.1 AA contrast requirements. The HuxWCAG utility class centralizes contrast calculations:

HuxWCAG.getContrastingTextColor(
  backgroundColor: myColor,
  context: context,
)

3. Material 3 Integration

Hux seamlessly integrates with Flutter's Material 3 design system, supporting custom seed colors while maintaining backward compatibility.

Buttons

HuxButton

The HuxButton widget is one of the most feature-rich components in Hux, supporting multiple variants, sizes, and states.

Variants:

primary - Solid button with primary color background
secondary - Solid button with secondary styling
outline - Transparent background with border
ghost - Transparent background, no border

Sizes:

small - 32px height, compact padding
medium - 40px height, standard padding (default)
large - 48px height, generous padding

Width Behaviors:

hug - Adapts to content (default)
expand - Fills available width
fixed - Specific width via widthValue

Technical Implementation:

Theme-aware colors: Automatically uses HuxTokens.primary(context) or custom primaryColor
WCAG-compliant text: Automatically calculates contrasting text color
Custom hover effects: Uses HuxTokens.surfaceHover(context) for hover states
Icon support: Supports prefix icons with proper spacing
Loading states: Shows CircularProgressIndicator when isLoading is true
Icon-only mode: Square buttons when using icon with zero-width child

HuxButton(
  onPressed: () => print('Clicked'),
  variant: HuxButtonVariant.primary,
  size: HuxButtonSize.medium,
  width: HuxButtonWidth.expand,
  icon: LucideIcons.save,
  isLoading: false,
  primaryColor: Colors.deepOrange, // Optional custom color
  child: Text('Save Changes'),
)

Input Components

HuxInput

Enhanced text input with consistent styling, validation support, and theme adaptation.

Features:

Automatic theme adaptation (light/dark)
Built-in validation support
Prefix and suffix icon support
Helper and error text
Consistent 40px height across all sizes
Customizable icon sizes and widths

Implementation Details:

The component uses Flutter's TextFormField with custom InputDecoration. It maintains consistent padding (18px horizontal, 12px vertical) and uses HuxTokens for all color values:

HuxInput(
  label: 'Email Address',
  hint: 'Enter your email',
  prefixIcon: Icon(LucideIcons.mail),
  keyboardType: TextInputType.emailAddress,
  validator: (value) {
    if (value?.isEmpty ?? true) return 'Email is required';
    if (!value!.contains('@')) return 'Invalid email format';
    return null;
  },
  onChanged: (value) => print('Email: $value'),
)

HuxDateInput

Specialized date input with automatic formatting and integrated calendar picker.

Features:

Automatic date formatting (MM/DD/YYYY)
Integrated date picker dialog
Input validation
Theme-aware styling

HuxDateInput(
  label: 'Birth Date',
  initialDate: DateTime.now(),
  firstDate: DateTime(1900),
  lastDate: DateTime.now(),
  onDateSelected: (date) => print('Selected: $date'),
)

HuxCheckbox

Interactive checkbox with custom styling, labels, and validation support.

Features:

Multiple sizes (small, medium, large)
Label and helper text support
Error state handling
WCAG AA compliant contrast ratios
Custom checkmark colors

HuxCheckbox(
  label: 'I agree to the terms',
  helperText: 'Required to continue',
  value: isChecked,
  onChanged: (value) => setState(() => isChecked = value!),
  size: HuxCheckboxSize.medium,
)

HuxRadio

Radio button controls for single selection from groups, with support for different value types.

Features:

Consistent sizing across theme changes
Theme adaptation
Support for any value type (String, int, custom objects)
Grouped selection management

HuxRadio<String>(
  value: 'option1',
  groupValue: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  label: 'Option 1',
)

HuxSwitch

Toggle switch with smooth animations between on/off states.

Features:

Smooth animation transitions
Theme-aware colors
Disabled state support
Custom on/off colors

HuxSwitch(
  value: isEnabled,
  onChanged: (value) => setState(() => isEnabled = value),
  label: 'Enable notifications',
)

HuxToggle

Toggle button group for selecting multiple options or a single option from a set.

Features:

Single and multiple selection modes
Customizable sizes
Theme integration
Icon and text support

HuxToggle(
  options: ['Option A', 'Option B', 'Option C'],
  selectedOptions: ['Option A'],
  onSelectionChanged: (selected) => print(selected),
  allowMultiple: true,
)

Cards & Containers

HuxCard

Flexible card component with optional header, title, subtitle, and action buttons.

Features:

Customizable padding and margins
Optional title, subtitle, and actions
Tap handling support
Theme-aware borders and backgrounds
Border radius: 12px

Technical Implementation:

Uses Card widget with custom styling. Background colors use HuxTokens.surfacePrimary(context) and borders use HuxTokens.borderPrimary(context).

HuxCard(
  title: 'Card Title',
  subtitle: 'Card subtitle with additional info',
  action: IconButton(
    icon: Icon(LucideIcons.moreVertical),
    onPressed: () => {},
  ),
  child: Text('Card content goes here'),
  onTap: () => print('Card tapped'),
)

Navigation Components

HuxTabs

Organize content into multiple panels with tab navigation. Three visual variants:

Default - Underline indicator
Pill - Background indicator
Minimal - No indicator

Features:

Icons, badges, and custom content support
Multiple sizes (small, medium, large)
Scrollable tabs for mobile
Full accessibility support
Built-in theme integration

Implementation:

Uses Flutter's TabController with custom tab bar styling. Tab tokens include:

tabActiveBackground / tabInactiveBackground
tabActiveText / tabInactiveText
tabHoverBackground
tabIndicator

HuxTabs(
  variant: HuxTabsVariant.pill,
  size: HuxTabsSize.medium,
  tabs: [
    HuxTab(label: 'Home', icon: LucideIcons.home),
    HuxTab(label: 'Settings', icon: LucideIcons.settings),
  ],
  children: [
    HomeView(),
    SettingsView(),
  ],
)

HuxSidebar

Complete navigation sidebar component for app-wide navigation.

Features:

HuxSidebarItem with automatic selection state
Optional header and footer sections
Customizable width and padding
Theme-aware styling with hover states
Perfect for dashboard applications

HuxSidebar(
  header: Text('My App'),
  items: [
    HuxSidebarItem(
      label: 'Dashboard',
      icon: LucideIcons.layoutDashboard,
      onTap: () => navigate('/dashboard'),
    ),
    HuxSidebarItem(
      label: 'Settings',
      icon: LucideIcons.settings,
      onTap: () => navigate('/settings'),
    ),
  ],
  footer: HuxSidebarItem(
    label: 'Logout',
    icon: LucideIcons.logOut,
    onTap: () => logout(),
  ),
)

HuxBreadcrumbs

Hierarchical navigation component with theme-aware styling.

Features:

Two variants: default_ (text /) and icon (chevron)
Three sizes: small, medium, large
Overflow handling with maxItems
Custom overflowIndicator support

HuxBreadcrumbs(
  items: ['Home', 'Products', 'Electronics', 'Laptops'],
  variant: HuxBreadcrumbsVariant.icon,
  onItemTap: (index, item) => print('Tapped: $item'),
  maxItems: 3,
)

Feedback & Status

HuxBadge

Status indicators and notification counters with semantic variants.

Variants:

primary, secondary, success, warning, destructive
Sizes: small, medium, large

Implementation:

Uses WCAG AA contrast ratios automatically calculated via HuxWCAG.getContrastingTextColor().

HuxBadge(
  label: 'New',
  variant: HuxBadgeVariant.success,
  size: HuxBadgeSize.medium,
)

HuxAlert

Persistent alert messages with semantic variants and dismissal support.

Variants:

info, success, warning, destructive

Features:

Optional icons
Dismissible alerts
Theme-aware colors

HuxAlert(
  variant: HuxAlertVariant.success,
  title: 'Success!',
  message: 'Operation completed successfully.',
  showIcon: true,
  onDismiss: () => print('Alert dismissed'),
)

HuxSnackbar

Temporary notification messages (typically 3-5 seconds) with semantic variants.

Implementation:

Provides a convenient extension method on BuildContext:

context.showHuxSnackbar(
  variant: HuxSnackbarVariant.success,
  message: 'Changes saved successfully!',
  action: SnackBarAction(
    label: 'Undo',
    onPressed: () => undo(),
  ),
)

HuxTooltip

Contextual help and information with customizable positioning and timing.

Features:

Automatic light/dark theme adaptation
Customizable positioning (preferBelow, verticalOffset)
Support for any icon library
Custom colors and timing

HuxTooltip(
  message: 'This is a helpful tooltip',
  icon: LucideIcons.info,
  preferBelow: false,
  verticalOffset: 16.0,
  child: Icon(LucideIcons.helpCircle),
)

Data Visualization

HuxChart

Data visualization component with line and bar chart support.

Chart Types:

Line Charts: HuxChart.line() - Time series, trends, continuous data
Bar Charts: HuxChart.bar() - Categorical data, comparisons

Features:

Integration with cristalyse (or custom chart libraries)
Customizable colors
Title and subtitle support
Animated transitions
Responsive sizing

Technical Implementation:

The chart widget accepts data as a list of maps with specified xField and yField keys. It handles data transformation and rendering internally.

HuxChart.line(
  data: [
    {'x': 1, 'y': 10},
    {'x': 2, 'y': 20},
    {'x': 3, 'y': 15},
  ],
  xField: 'x',
  yField: 'y',
  title: 'Sales Over Time',
  subtitle: 'Monthly data',
  primaryColor: HuxTokens.primary(context),
)

Overlays & Dialogs

HuxDialog

General-purpose dialog with modern design and multiple size variants.

Features:

Built-in close button with ghost styling
Support for title, subtitle, content, and actions
Size variants: small, medium, large, fullscreen
Consistent Hux design system integration

Implementation:

Uses Flutter's Dialog widget with custom styling. Close button uses HuxButton with ghost variant.

showHuxDialog(
  context: context,
  title: 'Confirm Action',
  subtitle: 'This action cannot be undone',
  content: Text('Are you sure you want to proceed?'),
  actions: [
    HuxButton(
      onPressed: () => Navigator.of(context).pop(false),
      variant: HuxButtonVariant.secondary,
      child: Text('Cancel'),
    ),
    HuxButton(
      onPressed: () => Navigator.of(context).pop(true),
      child: Text('Confirm'),
    ),
  ],
);

showHuxDatePickerDialog

Modern date picker dialog with month/year selection.

Features:

Month/year navigation
Theme-aware styling
Responsive calendar grid
Smart date range validation

final DateTime? selectedDate = await showHuxDatePickerDialog(
  context: context,
  initialDate: DateTime.now(),
  firstDate: DateTime(2020),
  lastDate: DateTime(2030),
);

showHuxTimePickerDialog

Clean time picker with hour/minute dropdowns.

Features:

Hour/minute dropdown selectors
12/24 hour format support
Theme integration

final TimeOfDay? selectedTime = await showHuxTimePickerDialog(
  context: context,
  initialTime: TimeOfDay.now(),
);

HuxContextMenu

Right-click context menus with smart positioning.

Components:

HuxContextMenu - Main container
HuxContextMenuItem - Individual menu items
HuxContextMenuDivider - Visual separators

Features:

Smart positioning (avoids screen edges)
Cross-platform support
Proper web context menu handling
Icon support
Disabled and destructive states

Technical Implementation:

Uses Flutter's GestureDetector for right-click detection and custom overlay for positioning. On web, properly handles context menu events.

HuxContextMenu(
  menuItems: [
    HuxContextMenuItem(
      text: 'Copy',
      icon: LucideIcons.copy,
      onTap: () => copyToClipboard(),
    ),
    HuxContextMenuItem(
      text: 'Paste',
      icon: LucideIcons.clipboard,
      onTap: () => pasteFromClipboard(),
      isDisabled: true,
    ),
    const HuxContextMenuDivider(),
    HuxContextMenuItem(
      text: 'Delete',
      icon: LucideIcons.trash2,
      onTap: () => delete(),
      isDestructive: true,
    ),
  ],
  child: Container(
    padding: EdgeInsets.all(20),
    child: Text('Right-click me!'),
  ),
)

HuxDropdown

Dropdown menu component with search, multi-select, and custom item widgets.

Features:

Single and multi-select modes
Search/filter functionality
Custom item widgets
Theme-aware styling
Keyboard navigation

Advanced Feature:

The useItemWidgetAsValue parameter allows displaying custom widgets as the selected value, enabling rich content in selections (icons, badges, custom layouts).

HuxDropdown<String>(
  items: ['Option 1', 'Option 2', 'Option 3'],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  label: 'Select an option',
  searchable: true,
)

Utility Components

HuxLoading

Customizable loading indicators with theme awareness.

Variants:

HuxLoading - Simple spinner
HuxLoadingOverlay - Full-screen overlay

Sizes:

small - 16px
medium - 24px (default)
large - 32px

// Simple loading indicator
HuxLoading(size: HuxLoadingSize.medium)

// Loading overlay
HuxLoadingOverlay(
  isLoading: true,
  message: 'Loading data...',
  child: YourContent(),
)

HuxAvatar

Circular user images with initials fallback and gradient variants.

Features:

Network image support with caching
Initials fallback
Custom colors
Beautiful gradient variants
Multiple sizes

HuxAvatar(
  name: 'John Doe',
  imageUrl: 'https://example.com/avatar.jpg',
  size: HuxAvatarSize.medium,
  useGradient: true,
  gradientVariant: HuxAvatarGradient.bluePurple,
)

HuxAvatarGroup

Display multiple avatars with overlapping or spaced layouts.

Features:

Overlap or spaced layouts
maxVisible limit with overflow indicator
Consistent sizing

HuxAvatarGroup(
  avatars: [
    HuxAvatar(name: 'Alice'),
    HuxAvatar(name: 'Bob'),
    HuxAvatar(name: 'Charlie'),
  ],
  overlap: true,
  maxVisible: 3,
)

HuxPagination

Navigate through pages with intelligent ellipsis handling.

Features:

Previous/next arrow buttons with disabled states
Configurable maximum pages to show
Theme-aware styling
WCAG AA compliant contrast ratios
Compact button design

HuxPagination(
  currentPage: 5,
  totalPages: 20,
  onPageChanged: (page) => print('Page $page'),
  maxPagesToShow: 7,
)

HuxCommand

Powerful command palette for quick access to actions and navigation.

Features:

Keyboard shortcuts (CMD+K on Mac, Ctrl+K on Windows/Linux)
Real-time search and filtering
Keyboard navigation (arrow keys, Enter)
Customizable commands with icons, shortcuts, categories
Global keyboard shortcuts via HuxCommandShortcuts.wrapper

Technical Implementation:

The command palette uses a searchable list with fuzzy matching. It maintains focus management and handles keyboard events for navigation and execution.

final commands = [
  HuxCommandItem(
    id: 'toggle-theme',
    label: 'Toggle Theme',
    description: 'Switch between light and dark mode',
    shortcut: '⌘⇧T',
    icon: LucideIcons.sun,
    category: 'View',
    onExecute: () => toggleTheme(),
  ),
  HuxCommandItem(
    id: 'settings',
    label: 'Settings',
    description: 'Open application settings',
    shortcut: '⌘,',
    icon: LucideIcons.settings,
    category: 'Preferences',
    onExecute: () => openSettings(),
  ),
];

// Show command palette
showHuxCommand(
  context: context,
  commands: commands,
  placeholder: 'Type a command or search...',
);

// Or wrap app for global shortcuts
HuxCommandShortcuts.wrapper(
  commands: commands,
  child: MaterialApp(home: MyHomePage()),
)

Theming System

HuxTheme

Pre-configured light and dark themes with Material 3 seed color support.

Setup:

MaterialApp(
  theme: HuxTheme.lightTheme,
  darkTheme: HuxTheme.darkTheme,
  themeMode: ThemeMode.system,
  home: MyHomePage(),
)

Custom Seed Colors

Hux automatically detects and uses Material 3 seed colors:

MaterialApp(
  theme: HuxTheme.lightTheme.copyWith(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.deepPurple,
    ),
  ),
  // All Hux components automatically use the custom primary color
)

HuxTokens

Semantic design tokens that adapt to themes:

// Color tokens
HuxTokens.primary(context)
HuxTokens.surfacePrimary(context)
HuxTokens.borderPrimary(context)
HuxTokens.textPrimary(context)
HuxTokens.textSecondary(context)

// Component-specific tokens
HuxTokens.buttonPrimaryHover(context)
HuxTokens.tabActiveBackground(context)
HuxTokens.surfaceHover(context)

HuxColors

Comprehensive color palette with semantic names:

HuxColors.primary
HuxColors.success
HuxColors.warning
HuxColors.destructive
HuxColors.black90
HuxColors.white
// ... and many more

Best Practices

1. Always Use HuxTokens

When building custom components that integrate with Hux, use HuxTokens instead of hardcoded colors:

Container(
  color: HuxTokens.surfacePrimary(context), // ✅ Good
  // color: Colors.white, // ❌ Bad - won't adapt to dark mode
)

2. Leverage WCAG Utilities

Use HuxWCAG for custom contrast calculations:

final textColor = HuxWCAG.getContrastingTextColor(
  backgroundColor: myCustomColor,
  context: context,
);

3. Consistent Sizing

Follow Hux's sizing patterns:

Buttons: 32px (small), 40px (medium), 48px (large)
Inputs: 40px (all sizes)
Icons: 16px (small), 18px (medium), 20px (large)

4. Theme-Aware Development

Always test components in both light and dark themes. Hux components automatically adapt, but custom code should too.

Wrap up

Hux UI gives you a full set of production-ready components that already do things right: proper accessibility, consistent theming, and layouts that just work.

You can build real products with it, not just prototypes. Whether it’s a small form or a complex dashboard, Hux handles the boring parts so you can focus on the logic.

If you care about accessibility, want your app to look good in both light and dark mode, and don’t want to rebuild buttons ever again, give it a try!

flutter pub add hux

💡 Resources

And if you end up using it, tell me what you built, or what’s missing.
Always happy to make Hux better for teams shipping products faster.

Hux UI: A Flutter component library that actually solves your frontend problems

Zoe — Mon, 07 Jul 2025 09:04:02 +0000

I'm originally a UX designer who recently started doing frontend development, and I quickly realized a pattern in the amount of time wasted refining the UI of every component.
You know the ones: shipping a text field without proper error states, buttons that look terrible in dark mode, loading spinners that don't match anything else in your app.

So I built the Hux UI to handle the stuff we always end up implementing anyway, but properly.

What's the Point?

Instead of copying the same button component between projects (and inevitably forgetting some edge case), you get components that:

Work out of the box - No spending 2 hours styling a basic button
Handle accessibility automatically - WCAG AA contrast calculations built in
Adapt to themes properly - Light/dark mode without the headaches
Include the stuff you forget - Error states, loading states, proper sizing

Quick Start

flutter pub add hux

Wrap your app:

MaterialApp(
  theme: HuxTheme.lightTheme,
  darkTheme: HuxTheme.darkTheme,
  home: YourApp(),
)

Start using components:

HuxButton(
  onPressed: _handleSubmit,
  isLoading: _isSubmitting,
  primaryColor: Colors.blue, // Text color auto-calculated for readability
  child: Text('Submit'),
)

What's Different?

Smart defaults instead of setting up everything yourself:

// This handles loading states, proper sizing, theme adaptation
HuxButton(
  onPressed: () {},
  isLoading: true, // Automatically shows spinner, disables button
  child: Text('Save'),
)

// vs fighting with this every time:
ElevatedButton(
  onPressed: isLoading ? null : () {},
  child: isLoading 
    ? SizedBox(width: 20, height: 20, child: CircularProgressIndicator())
    : Text('Save'),
)

Accessibility without the research:
The contrast calculation system automatically picks readable text colors:

HuxButton(
  primaryColor: Color(0xFF1A5F7A), // Dark blue
  child: Text('Button'), // Text will be white for readability
)

HuxButton(
  primaryColor: Color(0xFFE8F4F8), // Light blue  
  child: Text('Button'), // Text will be black for readability
)

Forms that don't suck:

HuxTextField(
  label: 'Email',
  hint: 'Enter your email', // Built in, won't forget it
  prefixIcon: Icon(Icons.email),
  validator: (value) => value?.contains('@') == true ? null : 'Invalid email',
  // Error states, focus states, sizing all handled
)

Component Overview

HuxButton - Primary/secondary/outline/ghost variants, auto-contrast, loading states
HuxTextField - Labels, hints, validation, icons, proper error styling
HuxCard - Consistent containers with optional headers and actions
HuxLoading - Spinners and overlays that match your theme
HuxChart - Line/bar charts with proper theming (uses cristalyse under the hood)
HuxContextMenu - Right-click menus with smart positioning

When to use this

Good fit if you:

Want to stop rebuilding basic components
Care about accessibility but don't want to become a WCAG expert
Need consistent theming across light/dark mode
Ship MVPs regularly and want things to look good by default

Maybe not if you:

Need heavily customized components with unique behaviors
Already have a comprehensive design system
Prefer building everything from scratch

Technical Notes

Built on Material 3 foundation
Uses semantic design tokens (not hardcoded colors)
All components use WCAG AA contrast calculations
Theme-aware from the ground up
Minimal dependencies (cristalyse for charts, feather icons, google fonts)

Real Example

Here's a login form that would take 30+ minutes to style properly from scratch:

Form(
  child: Column(
    children: [
      HuxTextField(
        label: 'Email',
        hint: 'Enter your email',
        prefixIcon: Icon(FeatherIcons.mail),
        keyboardType: TextInputType.emailAddress,
        validator: (value) {
          if (value?.isEmpty ?? true) return 'Email required';
          if (!value!.contains('@')) return 'Invalid email';
          return null;
        },
      ),
      SizedBox(height: 16),
      HuxTextField(
        label: 'Password',
        hint: 'Enter your password',
        prefixIcon: Icon(FeatherIcons.lock),
        obscureText: true,
        validator: (value) => 
          value?.length ?? 0 < 6 ? 'Password too short' : null,
      ),
      SizedBox(height: 24),
      HuxButton(
        onPressed: _login,
        isLoading: _isLoading,
        child: Text('Sign In'),
      ),
    ],
  ),
)

Everything just works - proper spacing, theme adaptation, error states, loading handling.

Try it

The library is small enough to understand quickly but handles enough edge cases that you'll actually save time. Perfect for prototypes, MVPs, or when you just want to focus on your app logic instead of styling buttons for the hundredth time.

flutter pub add hux

What problems do you always end up solving when building Flutter UIs? Let me know if there are common patterns I should add!

If this saved you some time, I'd really appreciate your support:

👍 Upvote Hux UI on Product Hunt and Peerlist
🐦 Follow me on Twitter for updates on new components and features
💼 Connect on LinkedIn and Peerlist
📝 Read more about my thoughts on design & product on Substack

🔗 Links:

Building WCAG-Compliant Flutter Components: Automating Contrast Calculations

Zoe — Mon, 07 Jul 2025 08:12:36 +0000

While building Hux UI, I kept running into the same accessibility problem: buttons with custom colors that had terrible text contrast. You'd pick a nice brand color, slap white text on it, and suddenly your button was unreadable.

Instead of manually checking contrast ratios every time, I decided to build a system that handles this automatically. Here's how I implemented WCAG-compliant contrast calculations in Flutter.

The Problem with Manual Contrast Checking

Most design systems punt on this problem. They give you preset color combinations that work, but the moment you use a custom brand color, you're on your own.

// This could be completely unreadable
Container(
  color: myBrandColor, // Could be any color
  child: Text('Button Text', style: TextStyle(color: Colors.white)),
)

The WCAG Algorithm

WCAG defines contrast ratio as the luminance difference between two colors. The formula is:

contrast = (lighter + 0.05) / (darker + 0.05)

Where luminance is calculated using the sRGB color space with gamma correction. For normal text, you need at least 4.5:1 contrast ratio for AA compliance.

Implementation in Flutter

Here's how I implemented the contrast calculation system:

/// Calculates the relative luminance of a color according to WCAG guidelines
double _getRelativeLuminance(Color color) {
  // Convert RGB values to 0-1 range
  final r = color.r / 255.0;
  final g = color.g / 255.0;
  final b = color.b / 255.0;

  // Apply gamma correction
  final rLinear = r <= 0.03928 ? r / 12.92 : pow((r + 0.055) / 1.055, 2.4);
  final gLinear = g <= 0.03928 ? g / 12.92 : pow((g + 0.055) / 1.055, 2.4);
  final bLinear = b <= 0.03928 ? b / 12.92 : pow((b + 0.055) / 1.055, 2.4);

  // Calculate relative luminance using ITU-R BT.709 coefficients
  return 0.2126 * rLinear + 0.7152 * gLinear + 0.0722 * bLinear;
}

/// Calculates contrast ratio between two colors
double _calculateContrastRatio(Color color1, Color color2) {
  final luminance1 = _getRelativeLuminance(color1);
  final luminance2 = _getRelativeLuminance(color2);

  final lighter = luminance1 > luminance2 ? luminance1 : luminance2;
  final darker = luminance1 > luminance2 ? luminance2 : luminance1;

  return (lighter + 0.05) / (darker + 0.05);
}

The tricky part is the gamma correction. sRGB colors aren't linear - they use a gamma curve to match how displays work. You have to convert to linear RGB before calculating luminance.

Automatic Text Color Selection

Now I can automatically pick the best text color:

Color _getContrastingTextColor(Color backgroundColor, BuildContext context) {
  final whiteContrast = _calculateContrastRatio(
    backgroundColor, 
    HuxTokens.textInvert(context)
  );
  final blackContrast = _calculateContrastRatio(
    backgroundColor, 
    HuxTokens.textPrimary(context)
  );

  // Choose the color with better contrast
  return whiteContrast > blackContrast
      ? HuxTokens.textInvert(context)
      : HuxTokens.textPrimary(context);
}

This runs every time a button renders, automatically ensuring WCAG AA compliance regardless of the background color.

Semantic Design Tokens

The other technical challenge was building a theme system that works in both light and dark mode. Instead of hardcoding colors, I built semantic tokens:

class HuxTokens {
  /// Primary text color that adapts to light/dark theme
  static Color textPrimary(BuildContext context) {
    final isDark = Theme.of(context).brightness == Brightness.dark;
    return isDark ? HuxColors.white : HuxColors.black;
  }

  /// Surface color for elevated components
  static Color surfaceElevated(BuildContext context) {
    final isDark = Theme.of(context).brightness == Brightness.dark;
    return isDark ? HuxColors.black70 : HuxColors.white;
  }
}

Every component uses these tokens instead of raw colors. When you switch themes, everything adapts automatically without any component-level changes.

Performance Considerations

You might worry about calculating contrast ratios on every render, but:

It's fast: The math is just basic arithmetic, no expensive operations
It's necessary: The alternative is manually checking every color combination
It's cached: Flutter's widget rebuilding is smart about when this actually runs

Real-World Usage

In the actual component, it looks like this:

ButtonStyle _getButtonStyle(BuildContext context) {
  final effectivePrimaryColor = primaryColor ?? HuxTokens.primary(context);
  final foregroundColor = _getContrastingTextColor(effectivePrimaryColor, context);

  return ButtonStyle(
    backgroundColor: WidgetStateProperty.all(effectivePrimaryColor),
    foregroundColor: WidgetStateProperty.all(foregroundColor),
    // ... other styles
  );
}

No matter what color you pass in, the text will be readable.

Testing the Algorithm

I tested this against the WebAIM contrast checker to make sure my implementation matches the WCAG spec. The results are identical.

You can test it yourself:

HuxButton(
  primaryColor: Color(0xFF6366F1), // Any color
  child: Text('Always Readable'),
  onPressed: () {},
)

Why This Matters

Accessibility shouldn't be an afterthought. By building it into the component layer, developers get WCAG compliance without having to think about it.

The contrast calculation runs automatically, the semantic tokens handle theme switching, and your app stays accessible regardless of design changes.

The Trade-offs

Pros:

Zero cognitive overhead for developers
Guaranteed WCAG AA compliance
Works with any color combination
Adapts to theme changes automatically

Cons:

Slight computation cost (negligible in practice)
Less control over exact text colors (though you probably don't want that control)

Try It Out

The system is part of Hux UI, but the algorithms are standalone. You could implement this in any Flutter project:

flutter pub add hux

Have you implemented accessibility features in your component libraries? I'm curious about other approaches to this problem!

🔗 Links:

DEV Community: Zoe

Building modern Flutter UIs with Hux: A comprehensive guide to Hux widgets

Table of Contents

Architecture & Design Philosophy

1. Design Token System

2. WCAG AA Accessibility

3. Material 3 Integration

Buttons

HuxButton

Input Components

HuxInput

HuxDateInput

HuxCheckbox

HuxRadio

HuxSwitch

HuxToggle

Cards & Containers

HuxCard

Navigation Components

HuxTabs

HuxSidebar

HuxBreadcrumbs

Feedback & Status

HuxBadge

HuxAlert

HuxSnackbar

HuxTooltip

Data Visualization

HuxChart

Overlays & Dialogs

HuxDialog

showHuxDatePickerDialog

showHuxTimePickerDialog

HuxContextMenu

HuxDropdown

Utility Components

HuxLoading

HuxAvatar

HuxAvatarGroup

HuxPagination

HuxCommand

Theming System

HuxTheme

Custom Seed Colors

HuxTokens

HuxColors

Best Practices

1. Always Use HuxTokens

2. Leverage WCAG Utilities

3. Consistent Sizing

4. Theme-Aware Development

Wrap up

💡 Resources

Hux UI: A Flutter component library that actually solves your frontend problems

What's the Point?

Quick Start

What's Different?

Component Overview

When to use this

Technical Notes

Real Example

Try it

Building WCAG-Compliant Flutter Components: Automating Contrast Calculations

The Problem with Manual Contrast Checking

The WCAG Algorithm

Implementation in Flutter

Automatic Text Color Selection

Semantic Design Tokens

Performance Considerations

Real-World Usage

Testing the Algorithm

Why This Matters

The Trade-offs

Try It Out