- Performance & Rendering
-
Const-First: Every widget that can be const MUST be const .
-
Lazy Rendering: Use SliverList.builder or SliverGrid.builder for lists > 10 items.
-
Repaint Boundaries: Wrap complex animations in RepaintBoundary .
-
Isolate Parsing: Use compute() or Isolate for JSON > 1MB.
-
BuildContext Safety: Check mounted before using context across async gaps.
- Design Tokens (Theming)
Use AppColors , AppSpacing , AppRadius , and AppTypography . NEVER hardcode raw values.
-
Colors: Use context.colorScheme.primary or AppColors . Support light/dark modes.
-
Spacing: Use AppSpacing.sm (8), AppSpacing.md (16), etc. Use SizedBox for gaps.
-
Radius: Use AppRadius.md (12) for consistent rounding.
-
Typography: Use context.textTheme.bodyMedium . Support text scaling.
- Reusable Components
-
Single Responsibility: Each component has one clear purpose.
-
Parameterization: Expose parameters for customization.
-
Complexity: Extract widgets or code blocks used multiple times into core/views/widgets .
-
Keys: Assign Key('feature_action_id') to interactive widgets for test access.
- Widget & Interaction Patterns
-
Extraction: STRICTLY prohibit private _build*() methods. Extract into separate widget classes.
-
Slivers: Prefer CustomScrollView with Slivers for non-trivial scrollable layouts.
-
FAB: Use Floating Action Buttons for primary positive actions (Add, Create).
-
Scroll Padding: Add dynamic bottom padding when a FAB or BottomBar is present to prevent overlap.
-
Sheets vs Screens: Prefer full Scaffold screens over ModalBottomSheet for complex forms.
- Adaptive & Responsive Design
-
Mobile First: Design for mobile, then adapt for tablet (600-840 ) and desktop (>840 ).
-
Measure & Branch: Use MediaQuery.sizeOf(context) for layout decisions; LayoutBuilder for widget constraints.
-
Rules: Never lock orientation. Support keyboard navigation and hover effects.
- UI States & Accessibility
-
States: Always handle Loading, Error, and Empty states with clear messaging.
-
Accessibility: Include Semantics labels. Ensure 48x48 dp touch targets. WCAG AA contrast.