Skip to content

Poorgramer-Zack/dart-expert-skills / skills/flutter-expert

building-flutter-production-apps

Verified

Expert-level guidance for Flutter production applications: architecture decisions (Clean/Layered/Hexagonal/Feature-First), advanced state management (BLoC/Riverpod/GetX), performance optimization (eliminating jank, memory profiling, reducing rebuild overhead), code review with design pattern enforcement, scalability assessments, native platform integration (MethodChannel/EventChannel/FFI), complex UI challenges (custom render objects, slivers), testing strategies (unit/widget/integration/golden), CI/CD pipeline architecture, build optimization, and accessibility compliance. Triggers: 'architecture decision', 'design pattern', 'performance issue', 'code review', 'production problem', 'scaling concerns', 'best practices', 'technical debt', 'refactoring strategy'. Essential for complex enterprise apps, critical production debugging, architectural refactors, or when choosing between competing technical approaches.

references/layout.md

View on GitHub
---
name: "flutter-layout"
description: "How to build your app's layout using Flutter's layout widgets and constraint system"
metadata:
  last_modified: "2026-03-12 11:18:17 (GMT+8)"

---
## Goal
Constructs robust, responsive Flutter user interfaces by composing layout widgets, managing constraints, and implementing adaptive design patterns. Assumes the target environment has the Flutter SDK installed and the user is familiar with Dart syntax and state management fundamentals.

## Instructions

1. **Determine Layout Strategy (Decision Logic)**
   Analyze the UI requirements and select the appropriate base layout widgets using the following decision tree:
   *   **Is the content strictly 1-Dimensional?**
       *   Horizontal arrangement -> Use `Row`.
       *   Vertical arrangement -> Use `Column`.
   *   **Does the content need to overlap (Z-axis)?**
       *   Yes -> Use `Stack` with `Positioned` or `Align` children.
   *   **Does the content exceed the screen size?**
       *   Yes, 1D list -> Use `ListView`.
       *   Yes, 2D grid -> Use `GridView`.
       *   Yes, custom scroll effects -> Use `CustomScrollView` with Slivers.
   *   **Does the layout need to adapt to screen size changes?**
       *   Yes -> Use `LayoutBuilder` or `MediaQuery`.

2. **Apply the Golden Rule of Constraints**
   Enforce Flutter's core layout rule: *Constraints go down. Sizes go up. Parent sets position.* 
   When a widget requires a specific size, ensure its parent allows it. Use `ConstrainedBox` to inject specific constraints, but remember it only adds to the parent's constraints.
   ```dart
   // Example: Forcing a specific size within a flexible parent
   Center(
     child: ConstrainedBox(
       constraints: const BoxConstraints(
         minWidth: 70,
         minHeight: 70,
         maxWidth: 150,
         maxHeight: 150,
       ),
       child: Container(
         color: Colors.blue,
         width: 1000, // Will be constrained to 150 (max)
         height: 10,  // Will be constrained to 70 (min)
       ),
     ),
   )
   ```

3. **Implement Adaptive Layouts**
   For screens that must support both mobile and tablet/desktop form factors, implement a `LayoutBuilder` to branch the UI logic based on available width.
   ```dart
   class AdaptiveScreen extends StatelessWidget {
     const AdaptiveScreen({super.key});

     @override
     Widget build(BuildContext context) {
       return Scaffold(
         body: SafeArea(
           child: LayoutBuilder(
             builder: (context, constraints) {
               if (constraints.maxWidth > 600) {
                 return _buildWideLayout();
               } else {
                 return _buildNarrowLayout();
               }
             },
           ),
         ),
       );
     }

     Widget _buildWideLayout() {
       return Row(
         children: [
           const SizedBox(width: 250, child: Placeholder()), // Sidebar
           Container(width: 1, color: Colors.grey), // Divider
           const Expanded(child: Placeholder()), // Main Content
         ],
       );
     }

     Widget _buildNarrowLayout() {
       return const Column(
         children: [
           Expanded(child: Placeholder()), // Main Content
         ],
       );
     }
   }
   ```

4. **Compose Flex Layouts (Rows and Columns)**
   When using `Row` or `Column`, manage child sizing using `Expanded` (forces child to fill available space) or `Flexible` (allows child to be smaller than available space).
   ```dart
   Row(
     mainAxisAlignment: MainAxisAlignment.spaceEvenly,
     crossAxisAlignment: CrossAxisAlignment.center,
     children: [
       const Icon(Icons.star),
       Expanded(
         flex: 2,
         child: Container(color: Colors.red, height: 50),
       ),
       Flexible(
         flex: 1,
         child: Container(color: Colors.blue, height: 50),
       ),
     ],
   )
   ```

5. **Gather Context**
   **STOP AND ASK THE USER:** "What are the target devices (e.g., mobile, tablet, web) and specific breakpoint widths required for this layout?"

6. **Validate-and-Fix: Handle Unbounded Constraints**
   Verify that no `Expanded` or `Flexible` widgets are placed inside unbounded parents (like `ListView` or `SingleChildScrollView`). If a RenderFlex overflow occurs, implement the following fix:
   ```dart
   // INCORRECT: Expanded inside a scrollable view causes unbounded height errors.
   // SingleChildScrollView(child: Column(children: [Expanded(child: Container())]))

   // CORRECT: Use a bounded height or remove Expanded.
   // Alternatively, use CustomScrollView with SliverFillRemaining:
   CustomScrollView(
     slivers: [
       SliverToBoxAdapter(child: HeaderWidget()),
       SliverFillRemaining(
         hasScrollBody: false,
         child: ExpandedContentWidget(),
       ),
     ],
   )
   ```

## Constraints
*   Always wrap top-level screen content in a `SafeArea` to prevent overlap with system UI.
*   Never place an `Expanded` or `Flexible` widget inside a parent that provides unbounded constraints (e.g., `SingleChildScrollView`, `ListView`, or `Row` inside a horizontally scrolling view).
*   Do not use `Container` solely for padding; use the `Padding` widget for better performance.
*   Assume the user is using Material 3 (`useMaterial3: true` is default).
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 323kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 323kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 323kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall