Skip to main content

Documentation Index

Fetch the complete documentation index at: https://synapsync.mintlify.app/llms.txt

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

​
Overview

This guide helps you migrate from other design systems to Nebux, and also covers migration between different versions of Nebux Design System.

​
Migrating from Material Design

Nebux is built on top of Flutter’s Material Design but provides additional theming capabilities.

​
Theme Setup

import 'package:flutter/material.dart';

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        primaryColor: Colors.blue,
        colorScheme: ColorScheme.light(
          primary: Colors.blue,
          secondary: Colors.cyan,
        ),
      ),
      home: const HomeScreen(),
    );
  }
}

​
Accessing Theme Colors

Widget build(BuildContext context) {
  final colorScheme = Theme.of(context).colorScheme;
  
  return Container(
    color: colorScheme.primary,
    child: Text(
      'Hello',
      style: Theme.of(context).textTheme.headlineMedium,
    ),
  );
}

​
Typography Mapping

Material TextThemeNebux TypographyNotes
headlineMediumheadingPage titles, primary headers
titleLargesectionSection headers
bodyLargecontentArticles, descriptions
bodyMediumparagraphDefault body text
bodySmallcaptionCaptions, metadata
labelLargelabelSmall labels, status
labelLarge (bold)primaryActionButton text
labelLarge (semibold)secondaryActionSecondary button text
bodyMediumformInputInput text
bodyMedium (italic)placeholderPlaceholder text

​
Migrating from Custom Themes

​
From Theme Classes

If you have custom theme classes: 
// Your existing custom theme
class MyCustomTheme {
  final Color primaryColor;
  final Color backgroundColor;
  final TextStyle headingStyle;
  // ...
}

// Convert to Nebux
final nebuxColors = NebuxColors(
  primary: myCustomTheme.primaryColor,
  background: myCustomTheme.backgroundColor,
  secondary: myCustomTheme.secondaryColor,
  // Map remaining colors
  // ...
);

final nebuxTypography = NebuxTypography.withOverrides(
  heading: myCustomTheme.headingStyle,
  paragraph: myCustomTheme.bodyStyle,
  // Map remaining styles
);

​
From JSON/YAML Configuration

Nebux supports JSON configuration out of the box. See the Advanced Usage Guide for TOML support. 
// Load your existing JSON theme
final colors = NebuxColors.fromJson(yourJsonMap);

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

​
Version Migration

​
v0.3.1 → v1.0.0

Typography Changes: All typography roles now include height and letterSpacing values aligned with Material Design 3. 
// Before (v0.3.1)
final typography = NebuxTypography.withOverrides(
  heading: GoogleFonts.montserrat(
    fontSize: 18,
    fontWeight: FontWeight.w600,
  ),
);

// After (v1.0.0)
// height and letterSpacing are now included by default
final typography = NebuxTypography.withOverrides(
  heading: GoogleFonts.montserrat(
    fontSize: 18,
    fontWeight: FontWeight.w600,
    height: 1.2,          // Now included
    letterSpacing: -0.5,  // Now included
  ),
);
Typography Mapping Fixes: 
// The following mappings were corrected in v1.0.0:
// heading: labelLarge → headlineMedium
// section: labelMedium → titleLarge
// label: labelSmall → labelLarge

// No action needed if using standard factories
final typography = NebuxTypography.standard();

// If using fromThemeData(), verify mappings:
final typography = NebuxTypography.fromThemeData(themeData);

​
v0.2.0 → v0.3.0

Translation Loading (Country Picker): Translation loading is now async, but the public API is unchanged. 
// Before and After - No changes needed
MaterialApp(
  localizationsDelegates: [
    CountryLocalizations.delegate,
    // ...other delegates
  ],
)
Removed APIs:
  • CountryProvider → Use CountryDecoder instead
  • AlphaScroller widget → Removed (was unused)

​
v0.1.18 → v0.2.0

InputParameters Context Removal: 
NbxTextFieldWidget(
  NbxInputParameters(
    context: context,  // ❌ Removed
    isRequired: false,
    inputType: NbxInputType.text,
    labelText: 'Search',
  ),
)
NbxNetworkImage Restructuring: 
NbxNetworkImage(
  imageUrl: 'https://example.com/image.png',
  memCacheWidth: 100,
  memCacheHeight: 100,
  fadeInDuration: Duration(milliseconds: 500),
  borderRadius: BorderRadius.circular(8),
  // ... 29 more parameters
)

​
v0.1.17 → v0.1.18

Validation API Changes: 
NbxTextFieldWidget(
  parameters: NbxInputParameters(
    customValidator: (value) => 
        value?.isEmpty == true ? 'Required' : null,
    showEyeIcon: true,
  ),
);
Suffix Icon Changes:
Old APINew APINotes
showEyeIcon: truesuffixIconType: NbxSuffixIconType.eyeFor password fields
showCancelIcon: truesuffixIconType: NbxSuffixIconType.cancelClear button
showSuffixIcon: truesuffixIconType: NbxSuffixIconType.eye or .cancelChoose specific type
forceShowSuffixIcon: trueN/ASuffix icon now always visible when type is set

​
v0.0.11 → v0.0.12

Button Component Refactoring: 
NbxButton(
  text: 'Submit',
  onPressed: () {},
  variant: ButtonVariant.filled,
  backgroundColor: Colors.blue,
  foregroundColor: Colors.white,
  borderRadius: BorderRadius.circular(12),
  isLoading: false,
  enabled: true,
  isSelected: false,
  isExpanded: true,
)
The legacy constructor NbxButton.legacy() is available for backward compatibility but is deprecated.

​
Breaking Changes Summary

1

v1.0.0

  • Typography now includes height and letterSpacing by default
  • Typography role mappings corrected (heading → headlineMedium, etc.)
2

v0.3.0

  • Translation loading is now async (no consumer changes needed)
  • Removed CountryProvider (use CountryDecoder)
  • Removed AlphaScroller widget
3

v0.2.0

  • NbxInputParameters no longer accepts context parameter
  • NbxNetworkImage restructured with config classes
  • cacheManager now properly typed as BaseCacheManager?
4

v0.1.18

  • customValidator → validator + onValidationResult
  • Suffix icon boolean flags → suffixIconType enum
5

v0.0.12

  • NbxButton refactored with config classes
  • Button variant naming: primary → filled, secondary → text
6

v0.0.9

  • isDisabled → enabled (inverted boolean)

​
Version History

Nebux Design System follows Semantic Versioning:
  • Patch (0.0.x): Bug fixes and documentation
  • Minor (0.x.0): New features, deprecations (with 1+ minor version runway)
  • Major (x.0.0): Breaking changes, removed deprecated APIs
Current stable version: 1.0.2 Key milestones:
  • 1.0.0 (Stable release): 81%+ test coverage, frozen public API
  • 0.3.0: Async translation loading, component cleanup
  • 0.2.0: API surface stabilization, config class architecture
  • 0.1.18: Validation API improvements
  • 0.0.12: Button component modernization
For full version history, see the CHANGELOG.md in the source repository.

​
Migration Checklist

1

Update Dependencies

Update your pubspec.yaml:
dependencies:
  nebux_design_system: ^1.0.2
Run flutter pub get
2

Review Breaking Changes

Check the breaking changes for versions between your current and target version
3

Update Theme Initialization

Replace Material theme setup with Nebux theme
4

Update Theme Access

Replace Theme.of(context) with context.nebuxColors and context.nebuxTypography
5

Run Tests

Ensure all tests pass. Use NebuxTypography.custom('Roboto', null) in tests to avoid Google Fonts network calls
6

Verify UI

Check that colors, typography, and spacing render correctly

​
Need Help?

If you encounter issues during migration:
  1. Check the CHANGELOG.md for detailed version notes
  2. Review the examples in the source repository
  3. Open an issue on GitHub

​
Related Pages

Customization Guide

Learn how to customize themes and components

Advanced Usage

JSON/TOML configuration and best practices

Quickstart

Get started with Nebux Design System