1. 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.

2. 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.

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.

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.

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.

States: Always handle Loading, Error, and Empty states with clear messaging.
Accessibility: Include
```
Semantics
```
labels. Ensure 48x48 dp touch targets. WCAG AA contrast.