---

💎 The Voxa Manifesto

Building enterprise apps usually involves reinventing the wheel: setting up Dio interceptors, configuring Riverpod, building a Theme system, and standardizing Spacing.

Voxa eliminates this "Foundational Fatigue" by providing a Battle-Tested Blueprint.

⚡ Why Voxa?

• Elite Architecture: Built on the principles of Clean Code and Atomic Design.
• Zero-Config Ecosystem: One import gets you the best of Flutter (Dio, Riverpod, Animate) pre-tuned for production.
• Visual Excellence: Every component is token-aware and motion-ready.
• Resilient by Nature: Automatic token refresh, global error mapping, and redacted logging.

---

🛠 The Ecosystem (Bundled & Exported)

Voxa implements a "Unified Export" strategy. You add one dependency to your pubspec.yaml, and get the world's best libraries pre-configured:

import 'package:voxa_core/voxa_core.dart'; // That's it.

Included Module	Powered By	Role in Voxa
State	hooks_riverpod	Reactive dependency injection & state orchestration.
Network	dio + retrofit	Resilient, interceptor-heavy API communication.
Design	flex_color_scheme	Industrial-strength Material 3 theme generation.
Motion	flutter_animate	Expressive, physics-based UI animations.
Logs	talker	Environment-aware, secure diagnostic logging.

---

🚀 Quick Start (30 Seconds to Launch)

1. The Bootstrap

Initialize the entire ecosystem (Storage, Logs, Error Tracking) before your app even mounts.

void main() async {
  // One line to rule them all
  await VoxaBootstrap.initialize(environment: VoxaEnvironment.development);
  
  runApp(const ProviderScope(child: MyVoxaApp()));
}

2. The Core Navigation

Voxa encourages a structured approach. Use the MainNavigationScreen pattern for complex apps.

class MyVoxaApp extends HookConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return MaterialApp(
      theme: VoxaThemeBuilder.buildLight(tokens: VoxaTokens.light),
      home: const MainNavigationScreen(), // Dashboard, Store, UI, Motion, Settings
    );
  }
}

3. The Power of Tokens

Stop hardcoding values. Use the context.tokens extension for everything.

@override
Widget build(BuildContext context) {
  return Container(
    padding: EdgeInsets.all(context.tokens.spacingMd),
    decoration: BoxDecoration(
      borderRadius: context.tokens.radiusLg,
      color: context.colorScheme.primaryContainer,
    ),
    child: const Text('Voxa Core').voxaFadeIn(), // Native animation extension
  );
}

---

📦 Core Modules

🎨 Design Tokens & Theming

Voxa's theme engine is type-safe and persistent.

• Dynamic Color: Support for Android 12+ (Monet) out of the box.
• Context Extensions: context.tokens, context.colorScheme, context.textTheme.
• Persistent Choice: User theme preferences are saved automatically.

🌐 Resilient Networking

Production-grade Dio client with pre-wired interceptors.

• Auto-Refresh: Silent 401 handling with request queuing.
• Redaction: Sensitive headers/data are automatically hidden from logs.
• Standardized Failures: Unified error mapping (No more catching DioException in UI).

✨ Motion Engine

Expressive animations via one-line extensions.

• .voxaFadeIn() / .voxaSlideIn() / .voxaScaleIn()
• Staggered list support.
• Physics-based dialog transitions.

📱 Responsive Framework

Build once, scale everywhere.

double width = context.value(mobile: 100.0, tablet: 200.0, desktop: 400.0);

---

🧩 Modular Architecture

Voxa is built like a precision machine. Each module can be configured but works perfectly by default.

voxa_core/
├── 🚀 bootstrap/      # App Lifecycle & Global Error Handling
├── 🎨 theme/          # Industrial Design System & Tokens
├── 🌐 network/        # Resilient API Stack & Interceptors
├── 🧱 components/     # Atomic UI Components (Card, Button, etc.)
├── ✨ animations/     # Motion Physics & Extension API
└── 📝 logging/        # Secure, Redacted Diagnostic Logs

---

📸 Screenshots & Showcase

---

🤝 Contributing

We love contributions! Whether it's a bug fix, a new feature, or better documentation.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

---

📜 License

Distributed under the MIT License. See LICENSE for more information.