Customization Guide

Overview

Nebux Design System is built with customization in mind. You can create fully custom themes, override specific colors, customize typography, and extend components to match your brand.

Creating Custom Themes

Using Standard Themes

The quickest way to get started is with the standard Material 3-inspired themes:

import 'package:flutter/material.dart';
import 'package:nebux_design_system/nebux_design_system.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: NebuxTheme.createThemeData(
        isDark: false,
        colors: NebuxColors.standardLight(),
        fontSize: NebuxFontSize.standard(),
        typography: NebuxTypography.standard(),
      ),
      darkTheme: NebuxTheme.createThemeData(
        isDark: true,
        colors: NebuxColors.standardDark(),
        fontSize: NebuxFontSize.standard(),
        typography: NebuxTypography.standard(),
      ),
      home: const HomeScreen(),
    );
  }
}

Using Color Themes

For automatic light/dark theme switching:

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    final colorThemes = NebuxColorThemes.standard();
    final brightness = MediaQuery.platformBrightnessOf(context);

    return MaterialApp(
      theme: NebuxTheme.createThemeData(
        isDark: brightness == Brightness.dark,
        colors: colorThemes.getColorsByBrightness(brightness),
        fontSize: NebuxFontSize.standard(),
        typography: NebuxTypography.standard(),
      ),
      home: const HomeScreen(),
    );
  }
}

Custom Colors

Method 1: Define Custom Color Palette

Create a completely custom color palette:

final customColors = NebuxColors(
  // Brand colors
  primary: Color(0xFF6200EE),
  secondary: Color(0xFF03DAC6),
  secondaryVariant: Color(0xFF018786),
  
  // Backgrounds and surfaces
  background: Color(0xFFFFFBFE),
  surface: Color(0xFFFFFFFF),
  cardColor: Color(0xFFF5F5F5),
  
  // Text colors
  textPrimary: Color(0xFF000000),
  textSecondary: Color(0xFF666666),
  
  // Action colors
  actionPrimary: Color(0xFF6200EE),
  actionSecondary: Color(0xFF03DAC6),
  
  // Semantic colors
  success: Color(0xFF4CAF50),
  warning: Color(0xFFFFC107),
  error: Color(0xFFB00020),
  info: Color(0xFF2196F3),
  disabled: Color(0xFFBDBDBD),
  
  // Utility colors
  divider: Color(0xFFE0E0E0),
  overlay: Color(0x52000000),
  focus: Color(0xFF6200EE),
  white: Color(0xFFFFFFFF),
  black: Color(0xFF000000),
  
  // Gradients
  primaryGradient: LinearGradient(
    colors: [Color(0xFF6200EE), Color(0xFF03DAC6)],
    begin: Alignment.topLeft,
    end: Alignment.bottomRight,
  ),
  secondaryGradient: LinearGradient(
    colors: [Color(0xFF03DAC6), Color(0xFF00BCD4)],
  ),
);

final theme = NebuxTheme.createThemeData(
  isDark: false,
  colors: customColors,
  fontSize: NebuxFontSize.standard(),
  typography: NebuxTypography.standard(),
);

Method 2: Extend Standard Colors

Modify specific colors while keeping the rest:

final standardColors = NebuxColors.standardLight();
final brandedColors = standardColors.copyWith(
  primary: Color(0xFF6200EE),
  actionPrimary: Color(0xFF6200EE),
  focus: Color(0xFF6200EE),
);

Method 3: Load from JSON

Define your colors in a JSON file:

colors.json

{
  "primary": "#6200EE",
  "secondary": "#03DAC6",
  "secondaryVariant": "#018786",
  "background": "#FFFBFE",
  "surface": "#FFFFFF",
  "textPrimary": "#000000",
  "textSecondary": "#666666",
  "actionPrimary": "#6200EE",
  "actionSecondary": "#03DAC6",
  "cardColor": "#F5F5F5",
  "divider": "#E0E0E0",
  "overlay": "#52000000",
  "focus": "#6200EE",
  "success": "#4CAF50",
  "warning": "#FFC107",
  "error": "#B00020",
  "info": "#2196F3",
  "disabled": "#BDBDBD",
  "white": "#FFFFFF",
  "black": "#000000",
  "primaryGradient": {
    "colors": ["#6200EE", "#03DAC6"]
  },
  "secondaryGradient": {
    "colors": ["#03DAC6", "#00BCD4"]
  }
}

Load in your app:

import 'dart:convert';
import 'package:flutter/services.dart';

Future<NebuxColors> loadCustomColors() async {
  final jsonString = await rootBundle.loadString('assets/colors.json');
  final jsonMap = json.decode(jsonString);
  return NebuxColors.fromJson(jsonMap);
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  NebuxColors? _customColors;

  @override
  void initState() {
    super.initState();
    loadCustomColors().then((colors) {
      setState(() => _customColors = colors);
    });
  }

  @override
  Widget build(BuildContext context) {
    if (_customColors == null) {
      return const CircularProgressIndicator();
    }

    return MaterialApp(
      theme: NebuxTheme.createThemeData(
        isDark: false,
        colors: _customColors!,
        fontSize: NebuxFontSize.standard(),
        typography: NebuxTypography.standard(),
      ),
      home: const HomeScreen(),
    );
  }
}

For TOML configuration support, see the Advanced Usage Guide.

Custom Typography

Using Google Fonts

The standard typography uses Google Fonts Montserrat:

final typography = NebuxTypography.standard();

Using Custom Font Family

Use any font family (local or Google Fonts):

final customTypography = NebuxTypography.custom('Roboto', null);

// With package fonts
final packageTypography = NebuxTypography.custom('CustomFont', 'my_package');

Overriding Individual Styles

Customize specific text styles:

final customTypography = NebuxTypography.withOverrides(
  heading: GoogleFonts.playfairDisplay(
    fontSize: 24,
    fontWeight: FontWeight.bold,
    height: 1.2,
  ),
  paragraph: GoogleFonts.openSans(
    fontSize: 16,
    fontWeight: FontWeight.w400,
    height: 1.5,
  ),
);

Typography from Material Theme

Map from an existing Material ThemeData:

final materialTheme = ThemeData.light();
final typography = NebuxTypography.fromThemeData(materialTheme);

Typography Roles

Nebux defines 10 typography roles:

Role	Purpose	Default Size	Weight
`heading`	Page titles, primary headers	18px	600
`section`	Section headers	14px	500
`content`	Articles, descriptions	12px	400
`paragraph`	Default body text	14px	400
`caption`	Captions, metadata	10px	400
`label`	Small labels, status	10px	500
`primaryAction`	Primary buttons	14px	700
`secondaryAction`	Secondary buttons	14px	600
`formInput`	Input text fields	14px	400
`placeholder`	Input placeholders	14px	400 (italic)

Custom Font Sizes

final customFontSize = NebuxFontSize(
  small: 10.0,
  medium: 12.0,
  large: 14.0,
  extraLarge: 16.0,
  heading4: 18.0,
  heading3: 20.0,
  heading2: 24.0,
  heading1: 32.0,
);

final theme = NebuxTheme.createThemeData(
  isDark: false,
  colors: NebuxColors.standardLight(),
  fontSize: customFontSize,
  typography: NebuxTypography.standard(),
);

Extending Components

Custom Button Styles

class BrandedButton extends StatelessWidget {
  final String text;
  final VoidCallback onPressed;

  const BrandedButton({
    super.key,
    required this.text,
    required this.onPressed,
  });

  @override
  Widget build(BuildContext context) {
    return NbxButton(
      text: text,
      onPressed: onPressed,
      styleConfig: ButtonStyleConfig(
        variant: ButtonVariant.filled,
        backgroundColor: context.nebuxColors.primary,
        foregroundColor: context.nebuxColors.white,
        borderRadius: BorderRadius.circular(24), // Pill-shaped
        textStyle: context.nebuxTypography.primaryAction.copyWith(
          fontSize: 16,
          letterSpacing: 1.2,
        ),
      ),
    );
  }
}

Custom Input Fields

class BrandedTextField extends StatelessWidget {
  final String label;
  final String? hintText;
  final TextEditingController? controller;

  const BrandedTextField({
    super.key,
    required this.label,
    this.hintText,
    this.controller,
  });

  @override
  Widget build(BuildContext context) {
    return NbxTextFieldWidget(
      NbxInputParameters(
        labelText: label,
        hintText: hintText,
        inputType: NbxInputType.text,
        borderRadius: BorderRadius.circular(16),
        filled: true,
        fillColor: context.nebuxColors.surface,
      ),
      controller: controller,
    );
  }
}

Theme Switching

Implement dynamic theme switching:

class ThemeProvider extends ChangeNotifier {
  ThemeMode _themeMode = ThemeMode.light;

  ThemeMode get themeMode => _themeMode;

  void toggleTheme() {
    _themeMode = _themeMode == ThemeMode.light 
        ? ThemeMode.dark 
        : ThemeMode.light;
    notifyListeners();
  }
}

// In your app
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return ChangeNotifierProvider(
      create: (_) => ThemeProvider(),
      child: Consumer<ThemeProvider>(
        builder: (context, themeProvider, _) {
          return MaterialApp(
            themeMode: themeProvider.themeMode,
            theme: NebuxTheme.createThemeData(
              isDark: false,
              colors: NebuxColors.standardLight(),
              fontSize: NebuxFontSize.standard(),
              typography: NebuxTypography.standard(),
            ),
            darkTheme: NebuxTheme.createThemeData(
              isDark: true,
              colors: NebuxColors.standardDark(),
              fontSize: NebuxFontSize.standard(),
              typography: NebuxTypography.standard(),
            ),
            home: const HomeScreen(),
          );
        },
      ),
    );
  }
}

Advanced Usage

JSON/TOML configuration and theme interpolation

Migration Guide

Migrate from other design systems

Context Extensions

Access theme properties easily

Get Started

Core Concepts

Components

Extensions & Utilities

Guides

Overview

Creating Custom Themes

Using Standard Themes

Using Color Themes

Custom Colors

Method 1: Define Custom Color Palette

Method 2: Extend Standard Colors

Method 3: Load from JSON

Custom Typography

Using Google Fonts

Using Custom Font Family

Overriding Individual Styles

Typography from Material Theme

Typography Roles

Custom Font Sizes

Extending Components

Custom Button Styles

Custom Input Fields

Theme Switching

Advanced Usage

Migration Guide

Context Extensions

Get Started

Core Concepts

Components

Extensions & Utilities

Guides

Documentation Index

​Overview

​Creating Custom Themes

​Using Standard Themes

​Using Color Themes

​Custom Colors

​Method 1: Define Custom Color Palette

​Method 2: Extend Standard Colors

​Method 3: Load from JSON

​Custom Typography

​Using Google Fonts

​Using Custom Font Family

​Overriding Individual Styles

​Typography from Material Theme

​Typography Roles

​Custom Font Sizes

​Extending Components

​Custom Button Styles

​Custom Input Fields

​Theme Switching

​Related Pages

Advanced Usage

Migration Guide

Context Extensions

Overview

Creating Custom Themes

Using Standard Themes

Using Color Themes

Custom Colors

Method 1: Define Custom Color Palette

Method 2: Extend Standard Colors

Method 3: Load from JSON

Custom Typography

Using Google Fonts

Using Custom Font Family

Overriding Individual Styles

Typography from Material Theme

Typography Roles

Custom Font Sizes

Extending Components

Custom Button Styles

Custom Input Fields

Theme Switching

Related Pages