Skip to main content

Documentation Index

Fetch the complete documentation index at: https://neo.tvk.company/llms.txt

Use this file to discover all available pages before exploring further.

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
Last modified on October 10, 2025