Adaptive Layout

Adapt to the space you are given, never to the device you think you are on. A phone in a foldable's front display, a resized desktop window, and a tablet in split-screen all defeat

Platform.isX

checks — but they all report their real constraints. Branch on width, not hardware.

Read the reference for the task at hand:

```
references/window-size-classes.md
```
— the Material 3 window size-class breakpoints as a shared vocabulary, the
```
WindowSizeClass
```
enum pattern,
```
MediaQuery.sizeOf
```
/
```
paddingOf
```
/
```
viewInsetsOf
```
vs
```
.of
```
, readable max-width, SafeArea and display cutouts, keyboard insets, orientation, foldable hinge awareness.
```
references/list-detail-and-navigation.md
```
— single-pane-navigate vs side-by-side two-pane, choosing the navigation affordance by width and coordinating with the go_router shell, keeping selection state in a Notifier so both panes agree.

Run

scripts/check_adaptive.sh

before a PR.

Non-negotiable rules

Adapt by constraints/size, never by device or platform. No
```
Platform.isAndroid
```
/
```
Platform.isIOS
```
/
```
kIsWeb
```
to pick a layout. Use
```
LayoutBuilder
```
(local box constraints) or
```
MediaQuery.sizeOf(context)
```
(window size). WHY: a resized window, split-screen, and foldable all break device checks; constraints are always true.
Use the Material 3 window size classes as the breakpoint vocabulary. Compact
```
<600
```
, medium
```
600–840
```
, expanded
```
840–1200
```
, large
```
1200–1600
```
, extra-large
```
≥1600
```
(logical px width). WHY: these are STANDARD structural breakpoints (not design tokens); one shared enum keeps every screen's breakpoints identical.
Read the narrowest MediaQuery aspect:
sizeOf
/
paddingOf
/
viewInsetsOf
/
viewPaddingOf
, not
MediaQuery.of(context)
. WHY:
```
.of
```
subscribes the widget to EVERY MediaQuery change (keyboard, rotation, text scale); the aspect getters rebuild only when that one field changes — see
```
flutter-performance
```
.
Pick the navigation affordance by width, not by a per-screen guess.
```
NavigationBar
```
(compact) →
```
NavigationRail
```
(medium/expanded) →
```
NavigationDrawer
```
(large). Decide once in the shell. WHY: mixing affordances across screens disorients; one width→affordance map is consistent by construction. Coordinate with
```
navigation-and-routing
```
's
```
StatefulShellRoute
```
.
List-detail collapses to one pane on compact and splits on expanded. Compact: the list navigates to a detail route. Expanded: list and detail sit side-by-side; selection is shared state. WHY: two panes on a phone are unreadable; one pane on a desktop wastes 70% of the width.
Never lock orientation (
```
SystemChrome.setPreferredOrientations
```
to force portrait). WHY: it breaks tablets, foldables, and accessibility mounts. Let the size classes handle both orientations.
Constrain readable content with a max width; use
Flexible
/
Expanded
/
FractionallySizedBox
, not fixed pixel widths, for top-level regions. WHY: full-width body text on a wide screen is unreadable (~40–75 chars/line is legible); fixed region widths overflow or leave dead space.
Wrap edge content in
SafeArea
and respect display cutouts + keyboard insets. Read cutouts/system bars via
```
MediaQuery.paddingOf
```
/
```
viewPaddingOf
```
; the keyboard via
```
MediaQuery.viewInsetsOf
```
. WHY: notches, punch-holes, and the on-screen keyboard occlude content that ignores insets.
Never assume a fixed cell/row height. Large text scale can double a cell's height; let content size itself. WHY: a hardcoded
```
SizedBox(height: 48)
```
clips at 200% text scale — see
```
accessibility-as-code
```
and
```
widget-composition
```
.
Verify across sizes with a golden matrix, not one device. Snapshot each adaptive screen at compact/medium/expanded (+ largest text, LTR/RTL). WHY: adaptive bugs only appear at the breakpoint you did not open — see
```
widget-golden-and-a11y-testing
```
.

Size classes as one shared enum

Define the breakpoints once; every screen reads the same map.

dart

enum WindowSizeClass { compact, medium, expanded, large, extraLarge }

WindowSizeClass windowSizeClassFor(double width) => switch (width) {
      < 600 => WindowSizeClass.compact,
      < 840 => WindowSizeClass.medium,
      < 1200 => WindowSizeClass.expanded,
      < 1600 => WindowSizeClass.large,
      _ => WindowSizeClass.extraLarge,
    };

// In a widget: rebuilds only when the window SIZE changes.
final sizeClass = windowSizeClassFor(MediaQuery.sizeOf(context).width);

Prefer

LayoutBuilder

when the decision depends on the LOCAL box (a widget inside a split view, a card grid), and

MediaQuery.sizeOf

when it depends on the whole window (the top-level shell).

dart

// Local constraints drive a card grid's column count.
LayoutBuilder(
  builder: (context, constraints) {
    final columns = constraints.maxWidth ~/ 280; // min card width, structural
    return GridView.count(crossAxisCount: columns.clamp(1, 4), children: cards);
  },
);

Readable width and flexible regions

dart

// Center and cap body text to a legible measure; never full-bleed on desktop.
Center(
  child: ConstrainedBox(
    constraints: const BoxConstraints(maxWidth: 720), // structural readable cap
    child: article,
  ),
);

// Split a wide body proportionally, not with magic fixed widths.
Row(
  children: [
    Expanded(flex: 2, child: primaryPane),
    Expanded(flex: 3, child: secondaryPane),
  ],
);

Insets, cutouts, keyboard, foldables

dart

// Keyboard height: rebuilds only when the keyboard shows/hides.
final keyboard = MediaQuery.viewInsetsOf(context).bottom;

// Notch/system-bar padding without subscribing to text-scale/rotation changes.
final safeTop = MediaQuery.paddingOf(context).top;

// Foldable: a vertical fold/hinge spanning the full height => split around it.
final seam = MediaQuery.displayFeaturesOf(context)
    .where((f) =>
        (f.type == DisplayFeatureType.fold ||
            f.type == DisplayFeatureType.hinge) &&
        f.bounds.top == 0 && // starts at the top edge...
        f.bounds.width < f.bounds.height) // ...taller than wide => vertical
    .firstOrNull; // firstOrNull: import 'package:collection/collection.dart';

Wrap the outermost interactive region in

SafeArea

; opt specific edges out (

bottom: false

) when a

NavigationBar

or scrolling body should reach the edge.

Navigation affordance by width

dart

// One place decides the shell chrome; screens stay affordance-agnostic.
Widget shellFor(WindowSizeClass sc, {required Widget body, required int index}) {
  return switch (sc) {
    WindowSizeClass.compact =>
      Scaffold(body: body, bottomNavigationBar: _NavBar(index: index)),
    WindowSizeClass.medium || WindowSizeClass.expanded =>
      Scaffold(body: Row(children: [_Rail(index: index), Expanded(child: body)])),
    WindowSizeClass.large || WindowSizeClass.extraLarge =>
      Scaffold(body: Row(children: [_Drawer(index: index), Expanded(child: body)])),
  };
}

See

examples/adaptive_scaffold.dart

for the full shell and

examples/list_detail_pane.dart

for the two-pane pattern.

Anti-patterns

if (Platform.isIOS) ... else ...

to choose a layout. Branch on

MediaQuery.sizeOf(context).width

MediaQuery.of(context).size.width

— subscribes to every MediaQuery change. Use

MediaQuery.sizeOf(context)

SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp])

to dodge landscape layout. Support both.

Container(width: 375)

SizedBox(width: 320)

sizing a top-level pane. Use

Expanded

Flexible

FractionallySizedBox

ConstrainedBox

bool isTablet = MediaQuery.of(context).size.shortestSide > 600

flag threaded everywhere. Compute a

WindowSizeClass

from width at the shell.

Two panes shown on compact width, forcing horizontal scroll. Collapse to one pane and navigate.
Full-width paragraphs on desktop with no max-width. Cap the measure.
Assuming the keyboard is hidden — content jumps under it. Pad by
```
MediaQuery.viewInsetsOf(context).bottom
```
.

Definition of done

No
```
Platform.is*
```
/
```
kIsWeb
```
/
```
dart:io
```
used to select a layout (platform-specific plugins are fine).
Breakpoints come from the shared
```
WindowSizeClass
```
helper, not ad-hoc numbers scattered per screen.

MediaQuery is read via

sizeOf

paddingOf

viewInsetsOf

viewPaddingOf

, not

.of

Navigation affordance is chosen by width in ONE place (the shell), coordinated with
```
navigation-and-routing
```
.
List-detail screens collapse to one pane on compact and split on expanded, sharing selection state.
No fixed pixel widths on top-level regions; readable content is max-width capped.
Orientation is not locked; edge content uses
```
SafeArea
```
; keyboard insets are respected.
Golden matrix covers compact/medium/expanded (+ largest text, RTL).
```
scripts/check_adaptive.sh
```
passes.

Related skills

```
widget-composition
```
— structural layout primitives, computed sizing, edge-to-edge vs SafeArea, never-fixed cell heights.
```
navigation-and-routing
```
— the
```
StatefulShellRoute
```
this shell renders; width picks the chrome, routes pick the branch.
```
flutter-performance
```
— why
```
sizeOf
```
/
```
select
```
beat
```
.of
```
for rebuild scope.
```
accessibility-as-code
```
— large text scale interacts with every adaptive cell.
```
widget-golden-and-a11y-testing
```
— the device × text-scale × RTL golden matrix that proves adaptivity.
```
state-management-riverpod
```
— where shared list-detail selection lives.

References

Material 3 layout / window size classes: https://m3.material.io/foundations/layout/applying-layout/window-size-classes
Adaptive & responsive design (Flutter): https://docs.flutter.dev/ui/adaptive-responsive
```
MediaQuery
```
API (aspect getters): https://api.flutter.dev/flutter/widgets/MediaQuery-class.html
```
LayoutBuilder
```
: https://api.flutter.dev/flutter/widgets/LayoutBuilder-class.html
```
NavigationRail
```
: https://api.flutter.dev/flutter/material/NavigationRail-class.html
```
DisplayFeature
```
/ foldables: https://api.flutter.dev/flutter/dart-ui/DisplayFeature-class.html

adaptive-layout

NPX Install

Tags

SKILL.md Content

Adaptive Layout

Non-negotiable rules

Size classes as one shared enum

Readable width and flexible regions

Insets, cutouts, keyboard, foldables

Navigation affordance by width

Anti-patterns

Definition of done

Related skills

References