@jeffrey2423/coding-standards 1.0.0

package/standards/mobile-flutter-standards.md

@@ -0,0 +1,1292 @@
+# Mobile Flutter Development Standards
+
+> **Note**: For shared architectural principles (Clean Architecture, DDD, design philosophy), refer to [architecture-patterns.md](./architecture-patterns.md). For design system (colors, typography, UX), refer to [technical-preferences-ux.md](./technical-preferences-ux.md).
+
+---
+
+## Technology Stack
+
+### Core Technologies
+
+| Category | Technology | Version | Notes |
+|----------|------------|---------|-------|
+| **SDK** | Flutter | 3.27+ | Stable channel only |
+| **Language** | Dart | 3.6+ | Sound null safety, records, patterns |
+| **State** | Riverpod | 3+ | Code-generated, annotation-based |
+| **Navigation** | GoRouter | 14+ | Declarative, deep-link ready |
+| **DI** | get_it + injectable | Latest | Service locator with code generation |
+| **HTTP** | Dio | 5+ | With interceptors |
+| **Local DB** | Drift | 2+ | Type-safe SQLite, reactive streams |
+| **Secure Storage** | flutter_secure_storage | 9+ | Keychain / Keystore backed |
+| **Models** | Freezed + json_serializable | Latest | Immutable models, sealed classes |
+| **Validation** | formz | Latest | Type-safe form field validation |
+| **Testing** | flutter_test + mocktail | Latest | Unit, widget, integration |
+
+### Development Tools
+
+| Tool | Purpose |
+|------|---------|
+| `flutter analyze` | Static analysis (strict) |
+| `dart format` | Code formatting |
+| `build_runner` | Code generation (Freezed, Riverpod, Drift) |
+| `flutter_gen` | Type-safe asset generation |
+| `very_good_cli` | Project scaffolding and CI |
+| `patrol` | Integration and end-to-end testing |
+
+---
+
+## Architecture
+
+### Style: Clean Architecture + DDD + Feature-First
+
+Same layered philosophy as the backend and frontend standards. Business logic drives every decision. Dependencies always point inward.
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  PRESENTATION LAYER                   │
+│      Widgets, Pages, Riverpod UI providers            │
+└──────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌──────────────────────────────────────────────────────┐
+│                  APPLICATION LAYER                    │
+│      Use cases, state notifiers, mappers              │
+└──────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌──────────────────────────────────────────────────────┐
+│                 INFRASTRUCTURE LAYER                  │
+│      Repository implementations, APIs, local DB       │
+└──────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌──────────────────────────────────────────────────────┐
+│                    DOMAIN LAYER                       │
+│      Entities, value objects, repository interfaces   │
+└──────────────────────────────────────────────────────┘
+```
+
+### Folder Structure
+
+```
+lib/
+├── main.dart                         # App entry point
+├── app/
+│   ├── app.dart                      # MaterialApp / CupertinoApp
+│   ├── router/
+│   │   └── app_router.dart           # GoRouter configuration
+│   ├── providers/
+│   │   └── app_providers.dart        # Root Riverpod overrides
+│   └── di/
+│       ├── injection.dart            # get_it setup
+│       └── injection.config.dart     # Generated by injectable
+│
+├── modules/                          # Business modules (DDD)
+│   ├── sales/
+│   │   ├── quotes/
+│   │   │   ├── cart/
+│   │   │   │   ├── domain/
+│   │   │   │   │   ├── entities/
+│   │   │   │   │   │   └── cart_item.dart
+│   │   │   │   │   ├── repositories/
+│   │   │   │   │   │   └── i_cart_repository.dart
+│   │   │   │   │   ├── value_objects/
+│   │   │   │   │   │   └── quantity.dart
+│   │   │   │   │   └── failures/
+│   │   │   │   │       └── cart_failure.dart
+│   │   │   │   ├── application/
+│   │   │   │   │   ├── use_cases/
+│   │   │   │   │   │   ├── add_to_cart.dart
+│   │   │   │   │   │   └── remove_from_cart.dart
+│   │   │   │   │   └── providers/
+│   │   │   │   │       └── cart_provider.dart
+│   │   │   │   ├── infrastructure/
+│   │   │   │   │   ├── repositories/
+│   │   │   │   │   │   └── cart_repository.dart
+│   │   │   │   │   ├── datasources/
+│   │   │   │   │   │   ├── cart_remote_datasource.dart
+│   │   │   │   │   │   └── cart_local_datasource.dart
+│   │   │   │   │   └── models/
+│   │   │   │   │       └── cart_item_model.dart
+│   │   │   │   └── presentation/
+│   │   │   │       ├── pages/
+│   │   │   │       │   └── cart_page.dart
+│   │   │   │       └── widgets/
+│   │   │   │           └── cart_item_widget.dart
+│   │   │   └── products/
+│   │   └── billing/
+│   ├── inventory/
+│   └── users/
+│
+├── shared/
+│   ├── widgets/                      # Reusable UI widgets
+│   │   ├── app_button.dart
+│   │   ├── app_text_field.dart
+│   │   └── loading_skeleton.dart
+│   ├── extensions/                   # Dart extensions
+│   │   ├── context_extensions.dart
+│   │   └── string_extensions.dart
+│   ├── utils/
+│   │   ├── validators.dart
+│   │   └── formatters.dart
+│   ├── theme/
+│   │   ├── app_theme.dart
+│   │   ├── app_colors.dart
+│   │   ├── app_typography.dart
+│   │   └── app_spacing.dart
+│   ├── constants/
+│   │   └── app_constants.dart
+│   └── failures/
+│       └── failure.dart              # Base failure sealed class
+│
+├── core/
+│   ├── network/
+│   │   ├── dio_client.dart
+│   │   └── interceptors/
+│   │       ├── auth_interceptor.dart
+│   │       └── logging_interceptor.dart
+│   ├── storage/
+│   │   ├── secure_storage.dart
+│   │   └── app_database.dart        # Drift database
+│   └── services/
+│       └── analytics_service.dart
+│
+└── l10n/                             # Localization
+    ├── app_en.arb
+    └── app_es.arb
+
+test/
+├── modules/
+│   └── sales/
+│       └── quotes/
+│           └── cart/
+│               ├── domain/
+│               ├── application/
+│               └── infrastructure/
+├── shared/
+└── helpers/
+    └── test_helpers.dart
+
+integration_test/
+└── features/
+    └── cart_flow_test.dart
+```
+
+---
+
+## Domain Layer
+
+### Entities
+
+Entities are immutable. Use `Freezed` for boilerplate elimination and value equality.
+
+```dart
+// modules/sales/quotes/cart/domain/entities/cart_item.dart
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'cart_item.freezed.dart';
+
+@freezed
+class CartItem with _$CartItem {
+  const CartItem._(); // Custom methods require private constructor
+
+  const factory CartItem({
+    required String id,
+    required String productId,
+    required String productName,
+    required int quantity,
+    required double unitPrice,
+  }) = _CartItem;
+
+  double get totalPrice => unitPrice * quantity;
+  bool get isValid => quantity > 0 && unitPrice > 0;
+}
+```
+
+### Value Objects
+
+Value objects enforce business invariants at construction time and return failures, never throw.
+
+```dart
+// modules/sales/quotes/cart/domain/value_objects/quantity.dart
+import 'package:dartz/dartz.dart';
+import '../failures/cart_failure.dart';
+
+class Quantity {
+  final Either<CartFailure, int> value;
+
+  factory Quantity(int input) {
+    return Quantity._(
+      input >= 1
+          ? right(input)
+          : left(const CartFailure.invalidQuantity()),
+    );
+  }
+
+  const Quantity._(this.value);
+
+  int getOrCrash() => value.fold(
+        (f) => throw Exception('Unvalidated quantity: $f'),
+        (v) => v,
+      );
+
+  bool isValid() => value.isRight();
+}
+```
+
+### Failures (Sealed Classes)
+
+Use Dart 3 sealed classes for exhaustive failure modeling. Never throw domain exceptions.
+
+```dart
+// modules/sales/quotes/cart/domain/failures/cart_failure.dart
+sealed class CartFailure {
+  const CartFailure();
+}
+
+class InvalidQuantity extends CartFailure {
+  const InvalidQuantity();
+}
+
+class ProductNotFound extends CartFailure {
+  final String productId;
+  const ProductNotFound(this.productId);
+}
+
+class CartLimitExceeded extends CartFailure {
+  final int maxItems;
+  const CartLimitExceeded(this.maxItems);
+}
+
+class ServerFailure extends CartFailure {
+  final String message;
+  const ServerFailure(this.message);
+}
+```
+
+### Repository Interfaces
+
+```dart
+// modules/sales/quotes/cart/domain/repositories/i_cart_repository.dart
+import 'package:dartz/dartz.dart';
+import '../entities/cart_item.dart';
+import '../failures/cart_failure.dart';
+
+abstract interface class ICartRepository {
+  Future<Either<CartFailure, List<CartItem>>> getCartItems();
+  Future<Either<CartFailure, CartItem>> addItem({
+    required String productId,
+    required int quantity,
+  });
+  Future<Either<CartFailure, Unit>> removeItem(String itemId);
+  Future<Either<CartFailure, Unit>> clearCart();
+  Stream<List<CartItem>> watchCartItems();
+}
+```
+
+---
+
+## Application Layer
+
+### Use Cases
+
+Each use case is a single callable class. One use case per file.
+
+```dart
+// modules/sales/quotes/cart/application/use_cases/add_to_cart.dart
+import 'package:dartz/dartz.dart';
+import 'package:injectable/injectable.dart';
+import '../../domain/entities/cart_item.dart';
+import '../../domain/failures/cart_failure.dart';
+import '../../domain/repositories/i_cart_repository.dart';
+import '../../domain/value_objects/quantity.dart';
+
+@injectable
+class AddToCart {
+  final ICartRepository _repository;
+
+  const AddToCart(this._repository);
+
+  Future<Either<CartFailure, CartItem>> call({
+    required String productId,
+    required int quantity,
+  }) async {
+    final quantityVO = Quantity(quantity);
+
+    if (!quantityVO.isValid()) {
+      return left(const InvalidQuantity());
+    }
+
+    return _repository.addItem(
+      productId: productId,
+      quantity: quantityVO.getOrCrash(),
+    );
+  }
+}
+```
+
+### Riverpod Providers (State Notifiers)
+
+Use `@riverpod` annotation with code generation. `AsyncNotifier` for async state, `Notifier` for sync.
+
+```dart
+// modules/sales/quotes/cart/application/providers/cart_provider.dart
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import '../../domain/entities/cart_item.dart';
+import '../../domain/failures/cart_failure.dart';
+import '../use_cases/add_to_cart.dart';
+import '../use_cases/remove_from_cart.dart';
+
+part 'cart_provider.g.dart';
+
+@Riverpod(keepAlive: true)
+class CartNotifier extends _$CartNotifier {
+  late final AddToCart _addToCart;
+  late final RemoveFromCart _removeFromCart;
+
+  @override
+  Future<List<CartItem>> build() async {
+    _addToCart = ref.read(addToCartProvider);
+    _removeFromCart = ref.read(removeFromCartProvider);
+
+    // Watch reactive stream from local DB
+    final repository = ref.read(cartRepositoryProvider);
+    ref.listen(
+      Stream.fromFuture(repository.getCartItems().then(
+        (e) => e.fold((_) => <CartItem>[], (v) => v),
+      )).asStream().asBroadcastStream(),
+      (_, __) {},
+    );
+
+    final result = await repository.getCartItems();
+    return result.fold(
+      (failure) => throw _mapFailure(failure),
+      (items) => items,
+    );
+  }
+
+  Future<void> addItem({
+    required String productId,
+    required int quantity,
+  }) async {
+    state = const AsyncLoading();
+    final result = await _addToCart(
+      productId: productId,
+      quantity: quantity,
+    );
+    state = result.fold(
+      (failure) => AsyncError(_mapFailure(failure), StackTrace.current),
+      (_) => AsyncData([...state.valueOrNull ?? [], _]),
+    );
+  }
+
+  Exception _mapFailure(CartFailure failure) => switch (failure) {
+        InvalidQuantity() => Exception('La cantidad debe ser mayor a cero'),
+        ProductNotFound(:final productId) =>
+          Exception('Producto $productId no encontrado'),
+        CartLimitExceeded(:final maxItems) =>
+          Exception('El carrito no puede tener más de $maxItems artículos'),
+        ServerFailure(:final message) => Exception(message),
+      };
+}
+```
+
+---
+
+## Infrastructure Layer
+
+### Models (DTO + JSON)
+
+```dart
+// modules/sales/quotes/cart/infrastructure/models/cart_item_model.dart
+import 'package:freezed_annotation/freezed_annotation.dart';
+import '../../domain/entities/cart_item.dart';
+
+part 'cart_item_model.freezed.dart';
+part 'cart_item_model.g.dart';
+
+@freezed
+class CartItemModel with _$CartItemModel {
+  const CartItemModel._();
+
+  const factory CartItemModel({
+    required String id,
+    @JsonKey(name: 'product_id') required String productId,
+    @JsonKey(name: 'product_name') required String productName,
+    required int quantity,
+    @JsonKey(name: 'unit_price') required double unitPrice,
+  }) = _CartItemModel;
+
+  factory CartItemModel.fromJson(Map<String, dynamic> json) =>
+      _$CartItemModelFromJson(json);
+
+  factory CartItemModel.fromDomain(CartItem entity) => CartItemModel(
+        id: entity.id,
+        productId: entity.productId,
+        productName: entity.productName,
+        quantity: entity.quantity,
+        unitPrice: entity.unitPrice,
+      );
+
+  CartItem toDomain() => CartItem(
+        id: id,
+        productId: productId,
+        productName: productName,
+        quantity: quantity,
+        unitPrice: unitPrice,
+      );
+}
+```
+
+### Repository Implementation
+
+```dart
+// modules/sales/quotes/cart/infrastructure/repositories/cart_repository.dart
+import 'package:dartz/dartz.dart';
+import 'package:injectable/injectable.dart';
+import '../../domain/entities/cart_item.dart';
+import '../../domain/failures/cart_failure.dart';
+import '../../domain/repositories/i_cart_repository.dart';
+import '../datasources/cart_remote_datasource.dart';
+import '../datasources/cart_local_datasource.dart';
+
+@LazySingleton(as: ICartRepository)
+class CartRepository implements ICartRepository {
+  final CartRemoteDatasource _remote;
+  final CartLocalDatasource _local;
+
+  const CartRepository(this._remote, this._local);
+
+  @override
+  Future<Either<CartFailure, List<CartItem>>> getCartItems() async {
+    try {
+      final local = await _local.getCartItems();
+      if (local.isNotEmpty) return right(local);
+
+      final remote = await _remote.getCartItems();
+      await _local.cacheCartItems(remote);
+      return right(remote.map((m) => m.toDomain()).toList());
+    } on NetworkException catch (e) {
+      return left(ServerFailure(e.message));
+    } catch (_) {
+      return left(const ServerFailure('Error inesperado'));
+    }
+  }
+
+  @override
+  Future<Either<CartFailure, CartItem>> addItem({
+    required String productId,
+    required int quantity,
+  }) async {
+    try {
+      final model = await _remote.addItem(
+        productId: productId,
+        quantity: quantity,
+      );
+      await _local.saveItem(model);
+      return right(model.toDomain());
+    } on NetworkException catch (e) {
+      return left(ServerFailure(e.message));
+    }
+  }
+
+  @override
+  Future<Either<CartFailure, Unit>> removeItem(String itemId) async {
+    try {
+      await _remote.removeItem(itemId);
+      await _local.deleteItem(itemId);
+      return right(unit);
+    } on NetworkException catch (e) {
+      return left(ServerFailure(e.message));
+    }
+  }
+
+  @override
+  Future<Either<CartFailure, Unit>> clearCart() async {
+    try {
+      await _remote.clearCart();
+      await _local.clearAll();
+      return right(unit);
+    } on NetworkException catch (e) {
+      return left(ServerFailure(e.message));
+    }
+  }
+
+  @override
+  Stream<List<CartItem>> watchCartItems() =>
+      _local.watchCartItems().map((items) => items.map((m) => m.toDomain()).toList());
+}
+```
+
+### Dio HTTP Client
+
+```dart
+// core/network/dio_client.dart
+import 'package:dio/dio.dart';
+import 'package:injectable/injectable.dart';
+import 'interceptors/auth_interceptor.dart';
+import 'interceptors/logging_interceptor.dart';
+
+@singleton
+class DioClient {
+  late final Dio dio;
+
+  DioClient(AuthInterceptor authInterceptor) {
+    dio = Dio(
+      BaseOptions(
+        baseUrl: const String.fromEnvironment('API_BASE_URL'),
+        connectTimeout: const Duration(seconds: 10),
+        receiveTimeout: const Duration(seconds: 30),
+        contentType: 'application/json',
+      ),
+    );
+
+    dio.interceptors.addAll([
+      authInterceptor,
+      LoggingInterceptor(),
+      RetryInterceptor(dio: dio, retries: 3),
+    ]);
+  }
+}
+```
+
+---
+
+## Presentation Layer
+
+### Pages
+
+Pages are thin orchestrators. They connect Riverpod state to the widget tree and handle routing.
+
+```dart
+// modules/sales/quotes/cart/presentation/pages/cart_page.dart
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
+import '../../application/providers/cart_provider.dart';
+import '../widgets/cart_item_widget.dart';
+import '../../../../shared/widgets/loading_skeleton.dart';
+import '../../../../shared/widgets/error_view.dart';
+
+class CartPage extends ConsumerWidget {
+  const CartPage({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final cartState = ref.watch(cartNotifierProvider);
+
+    return Scaffold(
+      appBar: AppBar(title: const Text('Carrito')),
+      body: switch (cartState) {
+        AsyncLoading() => const LoadingSkeleton(),
+        AsyncError(:final error) => ErrorView(
+            message: error.toString(),
+            onRetry: () => ref.invalidate(cartNotifierProvider),
+          ),
+        AsyncData(:final value) when value.isEmpty => const _EmptyCart(),
+        AsyncData(:final value) => ListView.builder(
+            itemCount: value.length,
+            itemBuilder: (context, index) => CartItemWidget(
+              item: value[index],
+              onRemove: (id) => ref
+                  .read(cartNotifierProvider.notifier)
+                  .removeItem(id),
+            ),
+          ),
+      },
+      bottomNavigationBar: _CartSummaryBar(
+        onCheckout: () => context.push('/sales/checkout'),
+      ),
+    );
+  }
+}
+```
+
+### Widgets
+
+```dart
+// modules/sales/quotes/cart/presentation/widgets/cart_item_widget.dart
+import 'package:flutter/material.dart';
+import '../../domain/entities/cart_item.dart';
+
+class CartItemWidget extends StatelessWidget {
+  final CartItem item;
+  final void Function(String id) onRemove;
+
+  const CartItemWidget({
+    super.key,
+    required this.item,
+    required this.onRemove,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return ListTile(
+      key: ValueKey(item.id),
+      title: Text(item.productName),
+      subtitle: Text('Cantidad: ${item.quantity}'),
+      trailing: Row(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          Text('\$${item.totalPrice.toStringAsFixed(2)}'),
+          IconButton(
+            icon: const Icon(Icons.delete_outline),
+            tooltip: 'Eliminar del carrito',
+            onPressed: () => onRemove(item.id),
+          ),
+        ],
+      ),
+    );
+  }
+}
+```
+
+---
+
+## Navigation (GoRouter)
+
+```dart
+// app/router/app_router.dart
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+part 'app_router.g.dart';
+
+@riverpod
+GoRouter appRouter(AppRouterRef ref) {
+  final isAuthenticated = ref.watch(authStateProvider);
+
+  return GoRouter(
+    initialLocation: '/dashboard',
+    redirect: (context, state) {
+      final loggedIn = isAuthenticated.valueOrNull ?? false;
+      final isAuthRoute = state.matchedLocation.startsWith('/auth');
+
+      if (!loggedIn && !isAuthRoute) return '/auth/login';
+      if (loggedIn && isAuthRoute) return '/dashboard';
+      return null;
+    },
+    routes: [
+      GoRoute(
+        path: '/auth/login',
+        builder: (context, state) => const LoginPage(),
+      ),
+      ShellRoute(
+        builder: (context, state, child) => AppShell(child: child),
+        routes: [
+          GoRoute(
+            path: '/dashboard',
+            builder: (context, state) => const DashboardPage(),
+          ),
+          GoRoute(
+            path: '/sales/quotes',
+            builder: (context, state) => const QuotesPage(),
+            routes: [
+              GoRoute(
+                path: 'cart',
+                builder: (context, state) => const CartPage(),
+              ),
+            ],
+          ),
+          GoRoute(
+            path: '/inventory/products',
+            builder: (context, state) => const ProductsPage(),
+          ),
+        ],
+      ),
+    ],
+  );
+}
+```
+
+---
+
+## Design System
+
+Mirrors the shared design tokens from `technical-preferences-ux.md`.
+
+### Colors
+
+```dart
+// shared/theme/app_colors.dart
+import 'package:flutter/material.dart';
+
+abstract final class AppColors {
+  // Primary brand: #0E79FD
+  static const primary50  = Color(0xFFEFF8FF);
+  static const primary100 = Color(0xFFDBF0FF);
+  static const primary200 = Color(0xFFBFE3FF);
+  static const primary300 = Color(0xFF93D2FF);
+  static const primary400 = Color(0xFF60B6FF);
+  static const primary500 = Color(0xFF0E79FD); // Main
+  static const primary600 = Color(0xFF0B6AE6);
+  static const primary700 = Color(0xFF0959C2);
+  static const primary800 = Color(0xFF0E4A9E);
+  static const primary900 = Color(0xFF123F80);
+  static const primary950 = Color(0xFF11274D);
+
+  // Tertiary brand: #154ca9
+  static const tertiary700 = Color(0xFF154CA9); // Main
+
+  // Secondary brand: #000000
+  static const secondary950 = Color(0xFF000000); // Main
+
+  // Surfaces
+  static const backgroundLight  = Color(0xFFFFFFFF);
+  static const surfaceLight      = Color(0xFFF8FAFC); // slate-50
+  static const borderLight       = Color(0xFFE2E8F0); // slate-200
+
+  static const backgroundDark    = Color(0xFF020617); // slate-950
+  static const surfaceDark       = Color(0xFF0F172A); // slate-900
+  static const borderDark        = Color(0xFF334155); // slate-700
+
+  // Semantic
+  static const success = Color(0xFF22C55E); // green-500
+  static const warning = Color(0xFFF59E0B); // amber-500
+  static const error   = Color(0xFFEF4444); // red-500
+  static const info    = Color(0xFF06B6D4); // cyan-500
+}
+```
+
+### Typography
+
+Only 3 Inter weights are available per `technical-preferences-ux.md`.
+
+```dart
+// shared/theme/app_typography.dart
+import 'package:flutter/material.dart';
+
+abstract final class AppTypography {
+  static const _fontFamily = 'Inter';
+
+  static const h1 = TextStyle(fontFamily: _fontFamily, fontSize: 36, fontWeight: FontWeight.w700, height: 1.2);
+  static const h2 = TextStyle(fontFamily: _fontFamily, fontSize: 30, fontWeight: FontWeight.w700, height: 1.2);
+  static const h3 = TextStyle(fontFamily: _fontFamily, fontSize: 24, fontWeight: FontWeight.w600, height: 1.3);
+  static const h4 = TextStyle(fontFamily: _fontFamily, fontSize: 20, fontWeight: FontWeight.w600, height: 1.3);
+  static const h5 = TextStyle(fontFamily: _fontFamily, fontSize: 18, fontWeight: FontWeight.w500, height: 1.4);
+  static const h6 = TextStyle(fontFamily: _fontFamily, fontSize: 16, fontWeight: FontWeight.w500, height: 1.4);
+
+  static const bodyLarge  = TextStyle(fontFamily: _fontFamily, fontSize: 18, fontWeight: FontWeight.w400, height: 1.6);
+  static const body       = TextStyle(fontFamily: _fontFamily, fontSize: 16, fontWeight: FontWeight.w400, height: 1.6);
+  static const bodySmall  = TextStyle(fontFamily: _fontFamily, fontSize: 14, fontWeight: FontWeight.w400, height: 1.5);
+  static const caption    = TextStyle(fontFamily: _fontFamily, fontSize: 12, fontWeight: FontWeight.w300, height: 1.4);
+
+  static const label      = TextStyle(fontFamily: _fontFamily, fontSize: 14, fontWeight: FontWeight.w500, height: 1.4);
+  static const buttonLg   = TextStyle(fontFamily: _fontFamily, fontSize: 16, fontWeight: FontWeight.w600, height: 1.0);
+  static const buttonSm   = TextStyle(fontFamily: _fontFamily, fontSize: 14, fontWeight: FontWeight.w500, height: 1.0);
+  static const badge      = TextStyle(fontFamily: _fontFamily, fontSize: 12, fontWeight: FontWeight.w700, height: 1.0);
+}
+```
+
+### Theme
+
+```dart
+// shared/theme/app_theme.dart
+import 'package:flutter/material.dart';
+import 'app_colors.dart';
+import 'app_typography.dart';
+
+abstract final class AppTheme {
+  static ThemeData get light => ThemeData(
+        useMaterial3: true,
+        fontFamily: 'Inter',
+        colorScheme: ColorScheme.fromSeed(
+          seedColor: AppColors.primary500,
+          brightness: Brightness.light,
+          primary: AppColors.primary500,
+          secondary: AppColors.tertiary700,
+          error: AppColors.error,
+          surface: AppColors.surfaceLight,
+        ),
+        scaffoldBackgroundColor: AppColors.backgroundLight,
+        appBarTheme: const AppBarTheme(
+          backgroundColor: AppColors.backgroundLight,
+          foregroundColor: Colors.black,
+          elevation: 0,
+          titleTextStyle: AppTypography.h5,
+        ),
+        elevatedButtonTheme: ElevatedButtonThemeData(
+          style: ElevatedButton.styleFrom(
+            backgroundColor: AppColors.primary500,
+            foregroundColor: Colors.white,
+            textStyle: AppTypography.buttonLg,
+            minimumSize: const Size(0, 48),
+            shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(8)),
+          ),
+        ),
+        inputDecorationTheme: InputDecorationTheme(
+          border: OutlineInputBorder(
+            borderRadius: BorderRadius.circular(8),
+            borderSide: const BorderSide(color: AppColors.borderLight),
+          ),
+          labelStyle: AppTypography.label,
+        ),
+        textTheme: const TextTheme(
+          displayLarge: AppTypography.h1,
+          displayMedium: AppTypography.h2,
+          displaySmall: AppTypography.h3,
+          headlineMedium: AppTypography.h4,
+          headlineSmall: AppTypography.h5,
+          titleLarge: AppTypography.h6,
+          bodyLarge: AppTypography.bodyLarge,
+          bodyMedium: AppTypography.body,
+          bodySmall: AppTypography.bodySmall,
+          labelLarge: AppTypography.buttonLg,
+          labelSmall: AppTypography.badge,
+        ),
+      );
+
+  static ThemeData get dark => ThemeData(
+        useMaterial3: true,
+        fontFamily: 'Inter',
+        colorScheme: ColorScheme.fromSeed(
+          seedColor: AppColors.primary500,
+          brightness: Brightness.dark,
+          primary: AppColors.primary400,
+          secondary: AppColors.tertiary700,
+          error: AppColors.error,
+          surface: AppColors.surfaceDark,
+        ),
+        scaffoldBackgroundColor: AppColors.backgroundDark,
+      );
+}
+```
+
+---
+
+## Local Database (Drift)
+
+```dart
+// core/storage/app_database.dart
+import 'package:drift/drift.dart';
+import 'package:drift/native.dart';
+import 'package:injectable/injectable.dart';
+import 'package:path_provider/path_provider.dart';
+import 'package:path/path.dart' as p;
+import 'dart:io';
+
+part 'app_database.g.dart';
+
+// Table definitions follow snake_case automatically
+class CartItems extends Table {
+  TextColumn get id           => text()();
+  TextColumn get productId    => text()();
+  TextColumn get productName  => text()();
+  IntColumn  get quantity     => integer()();
+  RealColumn get unitPrice    => real()();
+
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+@DriftDatabase(tables: [CartItems])
+@singleton
+class AppDatabase extends _$AppDatabase {
+  AppDatabase() : super(_openConnection());
+
+  @override
+  int get schemaVersion => 1;
+
+  Future<List<CartItemData>> getAllCartItems() =>
+      select(cartItems).get();
+
+  Stream<List<CartItemData>> watchAllCartItems() =>
+      select(cartItems).watch();
+
+  Future<int> upsertCartItem(CartItemsCompanion item) =>
+      into(cartItems).insertOnConflictUpdate(item);
+
+  Future<int> deleteCartItem(String id) =>
+      (delete(cartItems)..where((t) => t.id.equals(id))).go();
+
+  Future<int> clearAllCartItems() =>
+      delete(cartItems).go();
+
+  static QueryExecutor _openConnection() {
+    return LazyDatabase(() async {
+      final dir = await getApplicationDocumentsDirectory();
+      final file = File(p.join(dir.path, 'app.db'));
+      return NativeDatabase.createInBackground(file);
+    });
+  }
+}
+```
+
+---
+
+## Dependency Injection
+
+```dart
+// app/di/injection.dart
+import 'package:get_it/get_it.dart';
+import 'package:injectable/injectable.dart';
+import 'injection.config.dart';
+
+final getIt = GetIt.instance;
+
+@InjectableInit(
+  initializerName: 'init',
+  preferRelativeImports: true,
+  asExtension: true,
+)
+Future<void> configureDependencies() async => getIt.init();
+```
+
+Annotate classes with `@injectable`, `@singleton`, `@lazySingleton`, `@factoryMethod` as appropriate. Run `dart run build_runner build --delete-conflicting-outputs` to regenerate.
+
+---
+
+## Testing Standards
+
+### Strategy
+
+| Type | Tool | Coverage Target | What to Test |
+|------|------|-----------------|--------------|
+| **Unit** | `flutter_test` + `mocktail` | > 80% | Entities, value objects, use cases |
+| **Widget** | `flutter_test` | Medium | Key widgets and user interactions |
+| **Integration** | `patrol` | Low | Critical user journeys end-to-end |
+
+### Unit Test Example
+
+```dart
+// test/modules/sales/quotes/cart/application/use_cases/add_to_cart_test.dart
+import 'package:dartz/dartz.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:mocktail/mocktail.dart';
+
+class MockCartRepository extends Mock implements ICartRepository {}
+
+void main() {
+  late MockCartRepository mockRepository;
+  late AddToCart useCase;
+
+  setUp(() {
+    mockRepository = MockCartRepository();
+    useCase = AddToCart(mockRepository);
+  });
+
+  group('AddToCart', () {
+    test('returns CartItem when quantity is valid', () async {
+      const productId = 'prod-1';
+      const quantity = 2;
+      final item = CartItem(
+        id: 'item-1',
+        productId: productId,
+        productName: 'Test Product',
+        quantity: quantity,
+        unitPrice: 10.0,
+      );
+
+      when(() => mockRepository.addItem(
+            productId: productId,
+            quantity: quantity,
+          )).thenAnswer((_) async => right(item));
+
+      final result = await useCase(
+        productId: productId,
+        quantity: quantity,
+      );
+
+      expect(result, right(item));
+      verify(() => mockRepository.addItem(
+            productId: productId,
+            quantity: quantity,
+          )).called(1);
+    });
+
+    test('returns InvalidQuantity failure when quantity is zero', () async {
+      final result = await useCase(productId: 'prod-1', quantity: 0);
+
+      expect(result, left(const InvalidQuantity()));
+      verifyNever(() => mockRepository.addItem(
+            productId: any(named: 'productId'),
+            quantity: any(named: 'quantity'),
+          ));
+    });
+  });
+}
+```
+
+### Widget Test Example
+
+```dart
+// test/modules/sales/quotes/cart/presentation/widgets/cart_item_widget_test.dart
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('CartItemWidget', () {
+    testWidgets('displays product name and total price', (tester) async {
+      const item = CartItem(
+        id: '1',
+        productId: 'p1',
+        productName: 'Producto Test',
+        quantity: 2,
+        unitPrice: 50.0,
+      );
+
+      var removedId = '';
+
+      await tester.pumpWidget(
+        MaterialApp(
+          home: Scaffold(
+            body: CartItemWidget(
+              item: item,
+              onRemove: (id) => removedId = id,
+            ),
+          ),
+        ),
+      );
+
+      expect(find.text('Producto Test'), findsOneWidget);
+      expect(find.text('\$100.00'), findsOneWidget);
+
+      await tester.tap(find.byIcon(Icons.delete_outline));
+      await tester.pump();
+
+      expect(removedId, '1');
+    });
+  });
+}
+```
+
+---
+
+## Error Handling
+
+### Global Errors
+
+Register a `FlutterError.onError` and `PlatformDispatcher.instance.onError` handler in `main.dart`:
+
+```dart
+// main.dart
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  FlutterError.onError = (details) {
+    // Log to Crashlytics / Sentry
+    FirebaseCrashlytics.instance.recordFlutterFatalError(details);
+  };
+
+  PlatformDispatcher.instance.onError = (error, stack) {
+    FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
+    return true;
+  };
+
+  await configureDependencies();
+  runApp(
+    ProviderScope(
+      child: const App(),
+    ),
+  );
+}
+```
+
+### UI-Level Error Handling
+
+Use `AsyncValue`'s pattern matching (as shown in the page example above). Never expose raw exception messages to the UI. Map domain failures to user-friendly Spanish strings in the notifier.
+
+---
+
+## Security Standards
+
+| Concern | Solution |
+|---------|---------|
+| Token storage | `flutter_secure_storage` (Keychain/Keystore) |
+| Certificate pinning | `dio_certificate_pinner` |
+| Screenshot prevention | `FlutterWindowManager.addFlags` (Android) |
+| Root/jailbreak detection | `flutter_jailbreak_detection` |
+| Sensitive data in logs | Redact with `LoggingInterceptor` |
+| Obfuscation | `flutter build --obfuscate --split-debug-info` |
+
+---
+
+## Performance Standards
+
+| Strategy | Implementation |
+|----------|---------------|
+| Const widgets | Mark all stateless leaf widgets `const` |
+| List virtualization | Always use `ListView.builder`, never `Column` for dynamic lists |
+| Image caching | `cached_network_image` with disk cache |
+| State granularity | Use `select()` on providers to prevent unnecessary rebuilds |
+| Build profiling | `flutter run --profile` + DevTools |
+| Isolates | Offload heavy computation with `compute()` |
+| App startup | Defer non-critical initialization after first frame |
+
+---
+
+## Localization
+
+All user-visible text must be in Spanish. Code, logs, comments, and git commits stay in English (same rule as frontend and backend standards).
+
+```yaml
+# pubspec.yaml
+flutter:
+  generate: true
+
+# l10n.yaml
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+```
+
+```json
+// lib/l10n/app_es.arb
+{
+  "@@locale": "es",
+  "cartTitle": "Carrito",
+  "cartEmpty": "Tu carrito está vacío",
+  "addToCart": "Agregar al carrito",
+  "removeFromCart": "Eliminar del carrito",
+  "checkout": "Finalizar compra",
+  "errorGeneric": "Ha ocurrido un error. Intenta de nuevo.",
+  "errorNotFound": "El recurso solicitado no fue encontrado",
+  "loading": "Cargando..."
+}
+```
+
+---
+
+## Code Generation
+
+Run after every change to annotated classes:
+
+```bash
+dart run build_runner build --delete-conflicting-outputs
+```
+
+Files generated automatically (never edit manually):
+
+| Generator | Output |
+|-----------|--------|
+| `freezed` | `*.freezed.dart` |
+| `json_serializable` | `*.g.dart` (JSON) |
+| `riverpod_generator` | `*.g.dart` (providers) |
+| `injectable_generator` | `injection.config.dart` |
+| `drift_dev` | `*.g.dart` (DB) |
+| `flutter_gen` | `assets.gen.dart` |
+
+Add all `*.g.dart` and `*.freezed.dart` to `.gitignore` only if the project enforces generation in CI. Otherwise commit them for faster cold builds.
+
+---
+
+## pubspec.yaml Reference
+
+```yaml
+name: your_app
+description: Enterprise Flutter app
+
+environment:
+  sdk: '>=3.6.0 <4.0.0'
+  flutter: '>=3.27.0'
+
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_localizations:
+    sdk: flutter
+
+  # Architecture & DI
+  get_it: ^8.0.0
+  injectable: ^2.5.0
+  dartz: ^0.10.1
+
+  # State management
+  flutter_riverpod: ^2.6.0
+  riverpod_annotation: ^2.4.0
+
+  # Navigation
+  go_router: ^14.0.0
+
+  # Network
+  dio: ^5.7.0
+  connectivity_plus: ^6.0.0
+
+  # Local storage
+  drift: ^2.23.0
+  sqlite3_flutter_libs: ^0.5.0
+  flutter_secure_storage: ^9.2.0
+  shared_preferences: ^2.3.0
+
+  # Models
+  freezed_annotation: ^2.4.0
+  json_annotation: ^4.9.0
+
+  # Validation
+  formz: ^0.7.0
+
+  # UI
+  cached_network_image: ^3.4.0
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+  build_runner: ^2.4.0
+  freezed: ^2.5.0
+  json_serializable: ^6.8.0
+  riverpod_generator: ^2.4.0
+  injectable_generator: ^2.6.0
+  drift_dev: ^2.23.0
+  flutter_gen_runner: ^5.7.0
+  mocktail: ^1.0.4
+  patrol: ^3.13.0
+  very_good_analysis: ^6.0.0
+
+flutter:
+  uses-material-design: true
+  generate: true
+  fonts:
+    - family: Inter
+      fonts:
+        - asset: assets/fonts/Inter_18pt-Light.ttf
+          weight: 300
+        - asset: assets/fonts/Inter_18pt-Regular.ttf
+          weight: 400
+        - asset: assets/fonts/Inter_18pt-Bold.ttf
+          weight: 700
+  assets:
+    - assets/fonts/
+    - assets/images/
+    - assets/images/logos/
+```
+
+---
+
+## Implementation Checklist
+
+### Project Setup
+- [ ] Flutter 3.27+ stable channel
+- [ ] `very_good_analysis` lint rules configured
+- [ ] `l10n.yaml` and `.arb` files created
+- [ ] `get_it` + `injectable` wired in `main.dart`
+- [ ] `ProviderScope` wrapping the entire app
+- [ ] GoRouter with auth redirect guard
+- [ ] `AppTheme.light` and `AppTheme.dark` applied
+- [ ] Inter font family assets loaded
+- [ ] Brand colors in `AppColors` matching `technical-preferences-ux.md`
+- [ ] `build_runner` script added to `Makefile` or `justfile`
+
+### Per Feature
+- [ ] Domain entities with `Freezed`
+- [ ] Value objects with `Either` return
+- [ ] Sealed failure class
+- [ ] Repository interface in domain
+- [ ] Use case(s) with `@injectable`
+- [ ] `AsyncNotifier` provider with `@riverpod`
+- [ ] Infrastructure model with `fromDomain` / `toDomain`
+- [ ] Remote datasource using `DioClient`
+- [ ] Local datasource using `Drift` or `SecureStorage`
+- [ ] Repository implementation with `@LazySingleton(as: IRepository)`
+- [ ] Page using `ConsumerWidget`
+- [ ] Widgets separated from pages
+- [ ] Unit tests for use cases and value objects
+- [ ] Widget tests for key interactions
+
+### Quality
+- [ ] `flutter analyze` returns zero warnings
+- [ ] All user-visible strings in Spanish `.arb` files
+- [ ] No hardcoded colors or text sizes (use theme tokens)
+- [ ] `const` constructors on all leaf widgets
+- [ ] `ListView.builder` for all dynamic lists
+- [ ] Sensitive data only in `flutter_secure_storage`