flutter-layout

name	flutter-layout
description	How to build your app's layout using Flutter's layout widgets and constraint system
metadata	{"model":"models/gemini-3.1-pro-preview","last_modified":"Fri, 27 Feb 2026 00:24:00 GMT"}

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.

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

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

   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:

   // 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).