Skip to main content
Most Neo projects create custom themes to match their brand identity. This involves creating your own palette and theme files that extend Neo’s base theming system.

​
Extending Neo’s Default Themes

Neo provides two exceptional built-in themes - NeoThemeLight and NeoThemeDark - that are carefully designed for accessibility, consistency, and cross-platform compatibility. Instead of building themes from scratch, you should extend these default themes and only override the tokens you need to customize. Benefits of Extending Default Themes:
  • Automatically inherit Neo’s color combinations
  • Maintain consistency with Neo’s design system
  • Reduce maintenance burden by leveraging tested color relationships
  • Focus only on your brand customizations rather than rebuilding everything
What You Typically Customize:
  • Brand colors (fgBrand, bgBrand, bgBrandHover, etc.)
  • Optional spacing, radius, or typography adjustments
What Neo Handles for You:
  • Semantic colors (success, warning, danger)
  • Neutral grays and surface colors
  • Cross-platform visual consistency

​
Project Structure

The standard Neo theming structure organizes your custom colors and themes: 
lib/
  theming/
    palettes/
      my_app_palette.dart
    themes/
      my_app_theme_light.dart
      my_app_theme_dark.dart

​
Creating Your Light Theme

Create a light theme that extends Neo’s light theme and overrides only your brand colors: 
import 'package:flutter/widgets.dart';
import 'package:neo/neo.dart';
import '../palettes/my_app_palette.dart';

@immutable
class MyAppThemeLight extends NeoThemeLight {
  @override
  NeoColorTokens get colors => super.colors.copyWith(
    // Only override your brand colors
    fgBrand: MyAppPalette.brand500,
    bgBrand: MyAppPalette.brand500,
    bgBrandHover: MyAppPalette.brand600,
  );

  // Optional: Override other token categories
  @override
  NeoRadiusTokens get radii => super.radii.copyWith(
    medium: 12, // More rounded corners
    large: 20,
  );
}

​
Creating Your Dark Theme

Create a matching dark theme that extends Neo’s dark theme: 
import 'package:flutter/widgets.dart';
import 'package:neo/neo.dart';
import '../palettes/my_app_palette.dart';

@immutable
class MyAppThemeDark extends NeoThemeDark {
  @override
  NeoColorTokens get colors => super.colors.copyWith(
    // Only override your brand colors
    fgBrand: MyAppPalette.brand500,
    bgBrand: MyAppPalette.brand500,
    bgBrandHover: MyAppPalette.brand600,
  );

  // Share the same non-color customizations
  @override
  NeoRadiusTokens get radii => MyAppThemeLight().radii;
}

​
Using Your Custom Themes

Apply your custom themes in your app’s main file: 
class MyApp extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return NeoApp(
      title: "My App",
      defaultLightTheme: MyAppThemeLight(),
      defaultDarkTheme: MyAppThemeDark(),
      routerConfig: AppRouter().config(),
    );
  }
}

​
Mixing Neo and Custom Colors

You can combine your custom colors with Neo’s built-in colors: 
@override
NeoColorTokens get colors => super.colors.copyWith(
  // Use your brand colors
  fgBrand: MyAppPalette.brand500,
  bgBrand: MyAppPalette.brand500,
  bgBrandHover: MyAppPalette.brand600,
  
  // Use Neo's neutral grays for non-brand elements
  bgSecondary: NeoPalette.gray100,
  fgSecondary: NeoPalette.gray500,
);

​
Best Practices

​
Theme Architecture

  • Extend NeoThemeLight and NeoThemeDark instead of building from scratch
  • Keep brand colors in separate palette files for organization
  • Follow the standard lib/theming/ folder structure
  • Always create both light and dark theme variants

​
Customization Approach

  • Start minimal - override only brand colors initially
  • Use Neo’s semantic colors unless you have specific brand requirements
  • Leverage super.colors.copyWith() to preserve Neo’s tested color relationships
  • Test thoroughly in both light and dark modes

​
Brand Integration

  • Use your brand’s established color palette with Neo’s naming conventions
  • Ensure sufficient contrast ratios for accessibility compliance
⌘I