flutter-ui

---
name: flutter-ui
description: Use when creating design token systems, theme definitions, reusable UI components, or accessible widget layouts.
metadata:
    platforms: "flutter"
    languages: "dart"
    category: "ui"
---

# 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`.
-   **Impeller Rendering**: Impeller is the default rendering engine for iOS and Android. Ensure custom canvas paints are optimized and do not rely on Skia-specific behaviors.
-   **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.

# 3. 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.

# 4. 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.
-   **Pop Handling**: NEVER use the deprecated `WillPopScope` widget. Use the standard `PopScope` widget to intercept or block back-navigation.
-   **Sheets vs Screens**: Prefer full `Scaffold` screens over `ModalBottomSheet` for complex forms.

# 5. Adaptive & Responsive Design and Common Fixes

-   **Mobile First**: Design for mobile, then adapt for tablet (`600-840dp`) and desktop (`>840dp`). Use `MediaQuery.sizeOf(context).width`.
-   **Layout Builder**: Use `LayoutBuilder` when widget rendering depends on the immediate parent's constraints, not the whole screen.
-   **Safe Area & Android 15**: Wrap main layouts in `SafeArea` to avoid device notches and system bar overlays. Since Android 15 enforces edge-to-edge rendering by default, use `MediaQuery.paddingOf(context)` or `SafeArea` to prevent widgets from clipping under the system status or navigation bars.
-   **Modular UI Imports**: Flutter 3.44+ decouples `material` and `cupertino` from the core framework. In pure structural widgets, import only `package:flutter/widgets.dart` to maintain clear library separation.
-   **Overflow Fixes**:
    -   `A RenderFlex overflowed...`: Typically means a widget is demanding more space than available in a `Row` or `Column`. Wrap the offending widget in `Expanded` or `Flexible`.
    -   `Vertical viewport was given unbounded height`: Often happens when nesting scrollable views (like `ListView` inside `Column`). Use `Expanded` on the `ListView` or set `shrinkWrap: true`.
-   **Rules**: Never lock orientation unless strictly required by a unique feature. Support keyboard navigation and hover effects for desktop users.

# 6. Responsive Layout Patterns

## LayoutBuilder vs MediaQuery

| Tool | Use When | Returns |
|---|---|---|
| `MediaQuery.sizeOf(context)` | Layout depends on **screen size** (app-level breakpoints) | `Size` of the screen |
| `LayoutBuilder` | Layout depends on **parent constraints** (widget-level) | `BoxConstraints` from parent |

**Rule**: Use `MediaQuery` for page-level layouts. Use `LayoutBuilder` for reusable components that adapt to their container.

## Breakpoint Conventions

| Window Class | Width | Layout | Columns |
|---|---|---|---|
| Compact | < 600dp | Single column, bottom nav | 4 |
| Medium | 600-840dp | Two-pane, navigation rail | 8 |
| Expanded | > 840dp | Multi-pane, side navigation | 12 |

## Adaptive Layout Pattern
```dart
Widget build(BuildContext context) {
  final width = MediaQuery.sizeOf(context).width;
  return switch (width) {
    < 600 => const MobileLayout(),
    < 840 => const TabletLayout(),
    _ => const DesktopLayout(),
  };
}
```

## Constraint Widgets

| Widget | Behavior | Use When |
|---|---|---|
| `Expanded` | Fill ALL remaining space in `Row`/`Column` | Child should stretch |
| `Flexible` | Allow child to be SMALLER than remaining space | Child has natural size |
| `FractionallySizedBox` | Size as fraction of parent (e.g., 0.5 = 50%) | Proportional layouts |
| `ConstrainedBox` | Set min/max constraints | Bounded flexibility |
| `SizedBox` | Fixed absolute dimensions | Known exact size |

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