colveor_ui 0.0.1

Themed Flutter UI toolkit with widgets, light/dark theming, go_router routing and base screen classes. The UI layer of Colveor.

colveor_ui

A Flutter UI foundation for Colveor apps. It wires up theming (light/dark), routing (go_router), state (flutter_riverpod) and responsive sizing (flutter_screenutil_plus), and ships a set of themed Vo* widgets.

Features

• App shell: ColveorApp sets up ProviderScope, your config and routes, and responsive sizing in one widget.

• Theming: extend VoTheme with your own colors, sizes, typography and component styles to get a full Material 3 ThemeData for light and dark mode. The selected theme mode is saved between launches.

• Routing: a GoRouter built from your route list and VoRoutingConfig.

• Base classes: VoWidget and VoState give screens direct access to theme, sizes, screen and navigation helpers.

• Widgets:

  Library	Contents
  widgets/buttons.dart	VoButton (primary, secondary, outline, text, danger, loading), VoIconButton
  widgets/inputs.dart	Text, password, search and select fields, phone input with country picker, PIN input, custom keyboard, form control
  widgets/display.dart	VoText (with tappable [links]), avatar, counter badge/text, country flag, divider
  widgets/feedback.dart	VoToast (success, error, warning, info, banner), feedback view, countdown action
  widgets/layout.dart	VoScaffold, VoAppBar, scrollable form, tiles
  widgets/overlay.dart	Bottom sheets, dialogs, searchable selectable lists
  widgets/page_flow.dart	Multi-step page flows with animated transitions
  widgets/dashboard.dart	Dashboard shell with drawer, end drawer and dock navigation

Installation

The package isn't on pub.dev, so add it as a path or git dependency:

dependencies:
  colveor_ui:
    path: ../colveor_ui

It requires Dart SDK ^3.12.2.

Usage

1. Configure the app

import 'package:colveor_ui/config.dart';

class AppConfig extends VoConfig {
  @override
  String get appName => 'My App';

  @override
  VoRoutingConfig get routing => const VoRoutingConfig(initialLocation: '/');
}

VoRoutingConfig also takes the router settings apps usually adjust. The redirect callback gets a Ref, so it can read your providers, and onInit re-runs it when they change:

VoRoutingConfig(
  initialLocation: '/splash',
  onInit: (ref, notifier) =>
      ref.listen(authProvider, (_, _) => notifier.notify()),
  redirect: (ref, context, state) =>
      ref.read(authProvider).isSignedIn ? null : '/login',
  observers: [MyAnalyticsObserver()],
  errorBuilder: (context, state) => const NotFoundScreen(),
  redirectLimit: 5,
  debugLogDiagnostics: true,
)

To navigate outside the widget tree, use ref.read(voRouterProvider), or voNavigatorKey for the root navigator and overlay.

VoConfig also has environment, initialCountryCode, favoriteCountries and feedback, all with defaults you can override. Set the environment at build time with --dart-define=FLAVOR=production.

2. Define the theme

Extend VoTheme. Every part has a default (DefaultColors, DefaultSizes, DefaultTypography, DefaultComponentTheme), so class AppTheme extends VoTheme {} already works. Override only what you want to brand:

import 'package:colveor_ui/theme.dart';
import 'package:flutter/material.dart';

class AppTheme extends VoTheme {
  @override
  VoColors get colors => const AppColors();

  @override
  VoTypography get typography => const AppTypography();
}

class AppColors extends VoColors {
  const AppColors({super.brightness});

  @override
  AppColors copyWith({Brightness? brightness}) =>
      AppColors(brightness: brightness ?? this.brightness);

  @override
  VoColorMode get primaryMode =>
      const VoColorMode(light: Color(0xFF4F46E5), dark: Color(0xFF818CF8));
}

class AppTypography extends VoTypography {
  const AppTypography({super.colors, super.sizes});

  @override
  String get bodyFontFamily => 'Inter';

  @override
  AppTypography copyWith({VoColors? colors, VoSizes? sizes}) =>
      AppTypography(colors: colors, sizes: sizes);
}

VoTheme.build passes the resolved brightness, colors and sizes to each part's copyWith, so every part must implement copyWith. To change the Material sub-themes (buttons, inputs, app bar, …), extend VoThemeData and return it from createThemeData.

3. Define routes

import 'package:colveor_ui/colveor_ui.dart';

List<RouteBase> appRoutes(VoConfig config) => [
  GoRoute(path: '/', builder: (_, _) => const HomeScreen()),
];

4. Run the app

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

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final config = AppConfig();
  await VoBootstrap.initialize(config: config);

  runApp(
    ColveorApp(
      config: config,
      appRoutes: appRoutes,
      builder: (context, colveor) => MaterialApp.router(
        theme: AppTheme().light,
        darkTheme: AppTheme().dark,
        themeMode: colveor.themeMode,
        routerConfig: colveor.router,
      ),
    ),
  );
}

Call colveor.toggleThemeMode() or colveor.setThemeMode(...) to change the theme. Inside a ConsumerWidget, use ref.toggleThemeMode() instead.

Building screens

import 'package:colveor_ui/colveor_ui.dart';
import 'package:colveor_ui/widgets/buttons.dart';
import 'package:colveor_ui/widgets/feedback.dart';
import 'package:colveor_ui/widgets/layout.dart';
import 'package:flutter/material.dart';

class HomeScreen extends VoWidget {
  const HomeScreen({super.key});

  @override
  Widget buildView(BuildContext context) => VoScaffold(
    appBar: AppBar(title: const Text('Home')),
    body: VoButton(
      label: 'Save',
      onPressed: () => VoToast.success(context, message: 'Saved'),
    ),
  );
}

Libraries

Import	Contents
package:colveor_ui/colveor_ui.dart	ColveorApp, VoBootstrap, ColveorRef, VoConfig, VoWidget / VoState, everything in routing.dart
package:colveor_ui/config.dart	VoConfig, Environment, VoFeedbackConfig, VoRoutingConfig
package:colveor_ui/routing.dart	VoRoutingConfig, voRouterProvider, voNavigatorKey, VoRouterNotifier, VoRouteObserver, plus GoRoute, ShellRoute, StatefulShellRoute, GoRouterState and context.go / push / pop from go_router
package:colveor_ui/theme.dart	VoTheme, colors, sizes, typography, component themes
package:colveor_ui/extensions.dart	Color, theme and toolkit extensions
package:colveor_ui/utils.dart	VoLogger, VoValidators, date / number / phone / text formatters
package:colveor_ui/widgets/*.dart	Widget groups (see Features)

Example

example/ is a complete app that shows the theme setup, routing, button variants, toasts and a light/dark toggle:

cd example
flutter run

Development

Riverpod providers, Freezed models and JSON serializers are generated. After changing an annotated file, run:

dart run build_runner build --delete-conflicting-outputs