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

# Custom Themes

> Create custom themes that reflect your brand identity using the standard Neo project structure and design patterns.

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](/theming/palettes#custom-brand-colors):

<CodeGroup>
  ```dart lib/theming/themes/my_app_theme_light.dart lines theme={null}
  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,
    );
  }
  ```
</CodeGroup>

## Creating Your Dark Theme

Create a matching dark theme that extends Neo's dark theme:

<CodeGroup>
  ```dart lib/theming/themes/my_app_theme_dark.dart lines theme={null}
  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;
  }
  ```
</CodeGroup>

## Using Your Custom Themes

Apply your custom themes in your app's main file:

<CodeGroup>
  ```dart lib/main.dart lines theme={null}
  class MyApp extends ConsumerWidget {
    @override
    Widget build(BuildContext context, WidgetRef ref) {
      return NeoApp(
        title: "My App",
        defaultLightTheme: MyAppThemeLight(),
        defaultDarkTheme: MyAppThemeDark(),
        routerConfig: AppRouter().config(),
      );
    }
  }
  ```
</CodeGroup>

## Mixing Neo and Custom Colors

You can combine your custom colors with Neo's built-in colors:

<CodeGroup>
  ```dart lib/theming/themes/my_app_theme_light.dart lines theme={null}
  @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,
  );
  ```
</CodeGroup>

## 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