flutter

Flutter Standards

P0 — Design System Enforcement (CRITICAL)

Zero tolerance for hardcoded design values.

Before any UI work, identify the project's Theme Archetype by checking main.dart:

• Theme-Driven: VThemeData(...).toThemeData() → use Theme.of(context).textTheme
• Token-Driven: Use static tokens (VTypography.*) only when no global theme bridge exists or when defining the theme itself

Rules:

• Colors: Use tokens (VColors.*, AppColors.*). Never Color(0xFF...) or Colors.red.
• Spacing: Use tokens (VSpacing.*). Never magic numbers like 16 or 24.
• Typography: Prefer Theme.of(context).textTheme.* for adaptive UI. Use VTypography.* only for theme definitions. Never inline TextStyle.
• Borders: Use tokens (VBorders.*). Never raw BorderRadius.circular(n).
• Components: Use DLS widgets (VButton) over raw Material widgets (ElevatedButton) when available.

Detail → refs/design-system.md

P0 — Error Handling (CRITICAL)

• Repositories return Either<Failure, T> — no exceptions propagate to UI or BLoC.
• Catch in Infrastructure only — convert DioException / external errors to typed Left(Failure).
• Fold in BLoC — .fold(failure, success) to emit states. No try/catch in BLoC.
• Typed failures — @freezed union failures (e.g., UnauthorizedFailure). Never Left('string').
• Crashlytics routing — all catch blocks route via AppLogger.error(...) for observability.
• on Type catch — never bare catch without on.

Detail → refs/error-handling.md

P1 — Widgets (OPERATIONAL)

• State: Use StatelessWidget by default. StatefulWidget only for local state/controllers.
• Composition: Extract UI into small, atomic const widgets.
• Theming: Use Theme.of(context). No hardcoded colors.
• Layout: Use Flex + Gap/SizedBox.
• Widget Keys: All interactive elements must use keys from widget_keys.dart.
• File Size: If a UI file exceeds ~80 lines, extract sub-widgets into private classes.
• Specialized:
  • SelectionArea: For multi-widget text selection.
  • InteractiveViewer: For zoom/pan.
  • ListWheelScrollView: For pickers.
  • IntrinsicWidth/Height: Avoid unless strictly required; for overlays prefer Stack + FractionallySizedBox.
• Large Lists: Always use ListView.builder.