Custom Themes

​

Extending Neo’s 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

• Brand colors (brand, fgOnBrand)
• Optional spacing, radius, or typography adjustments
• Nullable button/checkbox overrides on NeoColors when you need global widget tinting

• Semantic colors (success, warning, danger)
• Ink ladders, fills, borders, and surface colors
• Cross-platform visual consistency

​

Project Structure

lib/
  theming/
    palettes/
      my_app_palette.dart
    themes/
      my_app_themes.dart

​

Creating Your Themes

import 'package:neo/neo.dart';
import '../palettes/my_app_palette.dart';

NeoTheme myAppLightTheme() {
  final base = NeoTheme.light();
  return base.copyWith(
    colors: base.colors.copyWith(
      brand: MyAppPalette.brand,
      fgOnBrand: NeoPalette.pureWhite,
      buttonPrimaryBg: MyAppPalette.brand,
    ),
    radii: base.radii.copyWith(
      medium: 12,
      large: 20,
    ),
  );
}

NeoTheme myAppDarkTheme() {
  final base = NeoTheme.dark();
  return base.copyWith(
    colors: base.colors.copyWith(
      brand: MyAppPalette.brand,
      fgOnBrand: NeoPalette.pureWhite,
      buttonPrimaryBg: MyAppPalette.brand,
    ),
    radii: myAppLightTheme().radii,
  );
}

​

Using Your Custom Themes

class MyApp extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return NeoApp(
      title: "My App",
      lightTheme: myAppLightTheme(),
      darkTheme: myAppDarkTheme(),
      routerConfig: AppRouter().config(),
    );
  }
}

​

Mixing Neo and Custom Colors

NeoTheme myAppLightTheme() {
  final base = NeoTheme.light();
  return base.copyWith(
    colors: base.colors.copyWith(
      brand: MyAppPalette.brand,
      fgOnBrand: NeoPalette.pureWhite,
      fillSubtle: NeoPalette.lightBlack.withValues(alpha: 0.05),
      fillStrong: NeoPalette.lightBlack.withValues(alpha: 0.20),
    ),
  );
}

​

Best Practices

​

Theme Architecture

• Start from NeoTheme.light() / NeoTheme.dark() 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 copyWith on NeoTheme and NeoColors to preserve Neo’s tested 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