Flutter Apps skill for Codex

Done well means: flutter analyze is clean, widgets are small and mostly const, all colours and text styles come from the theme, native calls go through typed Pigeon APIs, and every screen has at least one widget test.

Inspect first

cat AGENTS.md 2>/dev/null
flutter --version                     # Flutter and Dart versions drive API availability
cat pubspec.yaml analysis_options.yaml
ls lib lib/* | head -50
flutter analyze

Note the state management package already in use (see $flutter-state-management) and follow it. flutter pub get needs network unless the pub cache is warm; ask before adding dependencies in a sandbox without network.

Project layout

Feature-first scales better than layer-first once there are more than a handful of screens:

lib/
  main.dart                 # bootstrap only: config, DI, runApp
  app/                      # MaterialApp.router, theme, router config
  core/                     # http client, storage, errors, shared widgets
  features/
    orders/
      data/                 # DTOs, repositories, API clients
      domain/               # models (immutable), business rules
      presentation/         # screens, widgets, controllers
test/                       # mirrors lib/

Keep main.dart tiny. Business logic never lives in widgets; widgets read state and dispatch intents.

Widgets

• Extract widgets into classes, not helper methods returning Widget. Classes get their own element, can be const, and rebuild independently.
• Mark constructors and instances const wherever possible; enable the prefer_const_constructors lints via flutter_lints or very_good_analysis.
• Pass the narrowest data a widget needs, not whole models or controllers.
• Read sizes with MediaQuery.sizeOf(context) / paddingOf(context) rather than MediaQuery.of(context), which rebuilds on any media change (keyboard, brightness).
• Lists: ListView.builder / SliverList.builder for anything longer than a screen, with itemExtent or prototypeItem when rows have fixed height.
• Give list items a ValueKey(item.id) when items can be reordered, inserted or removed.

Fixing the classic layout errors:

Error	Cause	Fix
RenderFlex overflowed by N pixels	Row/Column children wider than space	Wrap the flexible child in Expanded / Flexible; ellipsize text
Vertical viewport was given unbounded height	ListView inside Column	Wrap in Expanded, or use slivers in a CustomScrollView
BoxConstraints forces an infinite width	Unbounded parent (Row) with double.infinity child	Use Expanded, or give an explicit width
setState() called after dispose()	Async result after leaving screen	Check if (!mounted) return; before setState

Theming

final lightScheme = ColorScheme.fromSeed(seedColor: const Color(0xFF0B7A75));
final darkScheme = ColorScheme.fromSeed(
  seedColor: const Color(0xFF0B7A75), brightness: Brightness.dark);

@immutable
class BrandColors extends ThemeExtension<BrandColors> {
  const BrandColors({required this.success, required this.warning});
  final Color success;
  final Color warning;

  @override
  BrandColors copyWith({Color? success, Color? warning}) =>
      BrandColors(success: success ?? this.success, warning: warning ?? this.warning);

  @override
  BrandColors lerp(BrandColors? other, double t) => other == null
      ? this
      : BrandColors(
          success: Color.lerp(success, other.success, t)!,
          warning: Color.lerp(warning, other.warning, t)!);
}

ThemeData buildTheme(ColorScheme scheme) => ThemeData(
      colorScheme: scheme,
      textTheme: Typography.material2021().black.apply(fontFamily: 'Inter'),
      extensions: const [BrandColors(success: Color(0xFF1B873F), warning: Color(0xFFB25E00))],
    );

• Material 3 is the default; do not set useMaterial3: false in new code.
• In widgets: Theme.of(context).colorScheme.primary, Theme.of(context).extension<BrandColors>()!.success. Hard-coded Color(0x...) in a widget is a review comment.
• Color.withOpacity is deprecated; use color.withValues(alpha: 0.6).
• Support text scaling: never fix heights on containers holding text; test with MediaQuery.withClampedTextScaling or the accessibility text size set to largest.

Navigation

Use go_router for URL-based routing and deep links:

final router = GoRouter(
  initialLocation: '/orders',
  redirect: (context, state) {
    final signedIn = authNotifier.isSignedIn;
    final atLogin = state.matchedLocation == '/login';
    if (!signedIn && !atLogin) return '/login';
    if (signedIn && atLogin) return '/orders';
    return null;
  },
  refreshListenable: authNotifier,
  routes: [
    GoRoute(path: '/login', builder: (_, __) => const LoginScreen()),
    GoRoute(
      path: '/orders',
      builder: (_, __) => const OrdersScreen(),
      routes: [
        GoRoute(path: ':id',
            builder: (_, s) => OrderScreen(id: s.pathParameters['id']!)),
      ],
    ),
  ],
);

Use context.go to replace the location and context.push to stack on top. Use StatefulShellRoute.indexedStack for bottom navigation that keeps each tab’s stack.

Config and flavors

• Per-environment values: flutter run --dart-define-from-file=config/dev.json and read them with const String.fromEnvironment('API_URL'). These are compiled into the binary and are not secret.
• Different app IDs and icons per environment need flavors: Android productFlavors, iOS schemes and build configurations, then flutter run --flavor dev.

Platform channels with Pigeon

Hand-written MethodChannel string keys drift between Dart and native. Generate them:

// pigeons/device.dart
import 'package:pigeon/pigeon.dart';

@ConfigurePigeon(PigeonOptions(
  dartOut: 'lib/core/native/device_api.g.dart',
  kotlinOut: 'android/app/src/main/kotlin/com/acme/app/DeviceApi.g.kt',
  swiftOut: 'ios/Runner/DeviceApi.g.swift',
))
@HostApi()
abstract class DeviceApi {
  @async
  int batteryLevel();
}

dart run pigeon --input pigeons/device.dart

Implement the generated protocol/interface in AppDelegate.swift and MainActivity.kt, and register it with the engine’s binary messenger. Use EventChannel (or Pigeon event channel APIs) for streams such as sensor updates. Native code runs on the platform main thread by default; move slow work off it.

Gotchas

• Using BuildContext after an await: check if (!context.mounted) return; first.
• late fields that are never assigned crash at runtime, not compile time.
• FutureBuilder(future: fetch()) inside build refetches on every rebuild; create the future in state or a provider.
• Text fields losing focus on rebuild means a key or the controller is recreated in build. Own TextEditingController in state and dispose it.
• Images from the network need explicit cacheWidth/cacheHeight for thumbnails or they decode at full resolution.
• Impeller is the default renderer on iOS and modern Android; check rendering issues on device before assuming a Skia-only workaround is needed.

Verification

dart format --output=none --set-exit-if-changed .
flutter analyze
flutter test
flutter test --update-goldens   # only when a visual change is intended, then review diffs
flutter build apk --debug       # quick compile check; flutter build ios --no-codesign on macOS

Widget test skeleton:

testWidgets('shows empty state when there are no orders', (tester) async {
  await tester.pumpWidget(const MaterialApp(home: OrdersScreen(orders: [])));
  expect(find.text('No orders yet'), findsOneWidget);
});

Done when analyze, format and tests pass, the app builds for each touched platform, and changed screens were checked in light and dark mode at the largest text size.

Report template

**Flutter / Dart:** 3.x / 3.x, state: Riverpod
**Changed:** split OrdersScreen into OrdersList and OrderTile; BrandColors theme extension
**Native:** Pigeon DeviceApi (Swift + Kotlin) for battery level
**Checks:** analyze clean, 42 tests pass, goldens unchanged, built Android debug and iOS no-codesign