██╗   ██╗ ██████╗ ██╗  ██╗  █████╗
██║   ██║██╔═══██╗╚██╗██╔╝ ██╔══██╗
██║   ██║██║   ██║ ╚███╔╝  ███████║
╚██╗ ██╔╝██║   ██║ ██╔██╗  ██╔══██║
 ╚████╔╝ ╚██████╔╝██╔╝ ██╗ ██║  ██║
  ╚═══╝   ╚═════╝ ╚═╝  ╚═╝ ╚═╝  ╚═╝

✦ What is Voxa?

Voxa is a principal-architect level Flutter foundation package — a complete ecosystem to bootstrap production apps with best-in-class theming, networking, components, and animations. Stop re-building the foundation. Ship what matters.

┌─────────────────────────────────────────────────────────────┐
│                      YOUR APPLICATION                       │
├──────────────┬──────────────┬──────────────┬────────────────┤
│  voxa_theme  │ voxa_network │ voxa_widgets │ voxa_motion    │
├──────────────┴──────────────┴──────────────┴────────────────┤
│                       voxa_bootstrap                        │
└─────────────────────────────────────────────────────────────┘

📦 Core Modules

🎨 Theme & Design Tokens

Type-safe, Material You ready, beautifully persistent.

Built on Material 3 and flex_color_scheme, Voxa's theme system is designed for real-world apps.

// Access any token anywhere in your widget tree
final tokens = context.tokens;

// Use tokens in your widgets
final widget = Padding(
  padding: EdgeInsets.all(tokens.spacingMd),
  child: Container(
    borderRadius: tokens.radiusMd,
  ),
);

🌐 Networking

Enterprise-grade Dio stack. Resilient by default.

Request  ──►  Auth Interceptor  ──►  Retry Interceptor
         ──►  Logging           ──►  Timing
         ──►  Token Refresh (401 auto-queue)
         ──►  Standardized Failure mapping

• Auto token refresh — 401 responses trigger silent refresh with request queuing
• Interceptors — Auth, Retry, Logging, and Request Timing pre-wired
• Failure classes — NetworkFailure, ServerFailure, BadRequestFailure mapped from DioException
• Fully mockable — http_mock_adapter integration for clean tests

class UserService extends BaseApiService {
  UserService(super.dio);

  Future<User> getUser() => request(() async {
    final response = await dio.get('/user');
    return User.fromJson(response.data);
  });
}

🧱 UI Components

Token-aware. Production-ready. Zero boilerplate.

All components automatically adapt to your active theme tokens — no manual styling needed.

✨ Animations & Motion

Fluid. Physics-based. One-line. Powered by flutter_animate.

// Chain animations with expressive extensions
final animatedText = Text('Hello, Voxa!')
  .voxaFadeIn()
  .voxaSlideIn();

• Extension API — apply animations declaratively on any widget
• Custom Physics — bouncy and elastic drag interactions built-in

🚀 Application Bootstrap

One line to rule them all.

void main() async {
  await VoxaBootstrap.initialize(environment: VoxaEnvironment.development);
}

This single call:

• ✅ Configures global Flutter error handlers
• ✅ Initializes Talker for environment-aware logging (Dev vs Prod)
• ✅ Sets up generic local storage
• ✅ Prepares the app for first frame

🚀 Quick Start

1 · Add the dependency

# pubspec.yaml
dependencies:
  voxa_core: ^latest

2 · Bootstrap in main.dart

import 'package:flutter/material.dart';
import 'package:dynamic_color/dynamic_color.dart';
import 'package:flex_color_scheme/flex_color_scheme.dart';
import 'package:hooks_riverpod/hooks_riverpod.dart';
import 'package:voxa_core/voxa_core.dart';

void main() async {
  await VoxaBootstrap.initialize(environment: VoxaEnvironment.development);
  runApp(const ProviderScope(child: VoxaApp()));
}

class VoxaApp extends HookConsumerWidget {
  const VoxaApp({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final themeConfig = ref.watch(voxaThemeControllerProvider);

    return DynamicColorBuilder(
      builder: (ColorScheme? lightDynamic, ColorScheme? darkDynamic) {
        return MaterialApp(
          title: 'My Voxa App',
          debugShowCheckedModeBanner: false,
          theme: VoxaThemeBuilder.build(
            brightness: Brightness.light,
            tokens: VoxaTokens.light,
            scheme: themeConfig.colors.scheme,
            colorScheme: themeConfig.colors.useDynamicColor ? lightDynamic : null,
          ),
          darkTheme: VoxaThemeBuilder.buildDark(
            tokens: VoxaTokens.dark,
            scheme: themeConfig.colors.scheme,
            colorScheme: themeConfig.colors.useDynamicColor ? darkDynamic : null,
          ),
          themeMode: themeConfig.themeMode,
          home: const HomePage(),
        );
      },
    );
  }
}

3 · Use components & tokens

class HomePage extends HookConsumerWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final tokens = context.tokens;

    return Scaffold(
      body: Padding(
        padding: EdgeInsets.all(tokens.spacingMd),
        child: Column(
          children: [
            // Animated badge
            const VoxaBadge(text: 'Enterprise Ready')
              .voxaFadeIn()
              .voxaSlideIn(),

            SizedBox(height: tokens.spacingLg),

            // Themed card with inputs
            VoxaCard(
              child: Column(
                children: [
                  const VoxaTextField(
                    label: 'Username',
                    prefix: Icon(Icons.person),
                  ),
                  SizedBox(height: tokens.spacingMd),
                  VoxaButton(
                    text: 'Submit',
                    onPressed: () => VoxaLogger.info('Submitted!'),
                  ),
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }
}

🌍 Networking Setup

// 1. Implement your token manager
class MyTokenManager implements TokenManager {
  @override
  Future<String?> getAccessToken() async { /* ... */ }

  @override
  Future<String?> refreshToken() async { /* ... */ }
}

// 2. Create the Dio client
final dio = ApiClientFactory.create(
  config: ApiConfig.development(baseUrl: 'https://api.example.com'),
  tokenManager: MyTokenManager(),
);

// 3. Build type-safe services
class UserService extends BaseApiService {
  UserService(super.dio);

  Future<User> getUser(String id) => request(() async {
    final response = await dio.get('/users/$id');
    return User.fromJson(response.data);
  });
}

🔐 Automatic Log Redaction

Sensitive fields are automatically stripped from logs in all environments.

void logSnippet() {
  VoxaLogger.json({
    'token':    'eyJhbGc...',  // → [REDACTED]
    'password': 'hunter2',    // → [REDACTED]
    'user_id':  'u_8842',     // → visible ✓
  });
}

Works via Talker integration — no extra setup needed.

🧪 Testing

Voxa ships with first-class testing helpers so your widgets and services are always testable.

// Widget tests
void testSnippet() {
  testWidgets('VoxaButton renders correctly', (tester) async {
    await tester.pumpApp(const VoxaButton(text: 'Test'));
    expect(find.text('Test'), findsOneWidget);
  });
}

// Network mocks
final mockDio = ApiClientFactory.createMock(
  handlers: [
    MockHandler.get('/users/1', response: {'id': 1, 'name': 'Ada'}),
  ],
);

Use VoxaTestApp to wrap widgets for golden tests or full integration widget tests — tokens, theme, and providers are all configured automatically.

⚠️ State Management: GetX Compatibility

Voxa uses Riverpod (hooks_riverpod) internally for theme state. If your app uses GetX, here's what you need to know:

Required setup for GetX apps:

void main() async {
  await VoxaBootstrap.initialize(environment: VoxaEnvironment.development);

  // REQUIRED: wrap GetMaterialApp with ProviderScope
  runApp(const ProviderScope(child: MyGetXApp()));
}

📁 Project Structure

voxa_core/
├── bootstrap/           # App initialization & error handling
├── theme/               # Theme builder, tokens, and controller
│   └── tokens/          # Spacing, radius, chart, gamification tokens
├── network/             # Dio client, interceptors, failure types
├── components/          # All production-ready UI widgets
└── animations/          # Animation extensions and physics engine

🛠️ Requirements