Does the widget...
├── Need to change after initial build?
│   ├── NO → StatelessWidget ✓
│   └── YES → Does the change come from...
│       ├── Parent rebuilding with new props? → StatelessWidget ✓
│       ├── Internal state (counter, toggle, animation)?
│       │   └── YES → StatefulWidget ✓
│       ├── AnimationController or TickerProvider?
│       │   └── YES → StatefulWidget with TickerProviderStateMixin ✓
│       └── Global/shared state (theme, auth, data)?
│           └── Use state management (Provider/Riverpod) ✓

class UserAvatar extends StatelessWidget {
  const UserAvatar({
    super.key,
    required this.imageUrl,
    this.radius = 24.0,
  });

  final String imageUrl;
  final double radius;

  @override
  Widget build(BuildContext context) {
    return CircleAvatar(
      radius: radius,
      backgroundImage: NetworkImage(imageUrl),
    );
  }
}

class ExpandableCard extends StatefulWidget {
  const ExpandableCard({
    super.key,
    required this.title,
    required this.content,
  });

  final String title;
  final Widget content;

  @override
  State<ExpandableCard> createState() => _ExpandableCardState();
}

class _ExpandableCardState extends State<ExpandableCard> {
  bool _isExpanded = false;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        GestureDetector(
          onTap: () => setState(() => _isExpanded = !_isExpanded),
          child: Text(widget.title),
        ),
        if (_isExpanded) widget.content,
      ],
    );
  }
}

// BAD: Helper method — rebuilds with parent, no independent lifecycle
class MyPage extends StatelessWidget {
  Widget _buildHeader(String title) {
    return Padding(
      padding: const EdgeInsets.all(16),
      child: Text(title, style: const TextStyle(fontSize: 24)),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [_buildHeader('Hello')]);
  }
}

// GOOD: Extracted widget — independent rebuild, can be const
class PageHeader extends StatelessWidget {
  const PageHeader({super.key, required this.title});
  final String title;

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(16),
      child: Text(title, style: const TextStyle(fontSize: 24)),
    );
  }
}

Do I need a key?
├── Static list (never reordered/filtered)? → No key needed
├── Dynamic list with unique domain IDs?
│   └── ValueKey(item.id) ✓
├── Dynamic list without unique IDs but with unique field combo?
│   └── ValueKey('${item.name}_${item.date}') ✓
├── Need to preserve state when widget moves in tree?
│   └── GlobalKey (sparingly) ✓
├── Need every instance to be unique?
│   └── UniqueKey() (forces rebuild, rarely needed)
└── Objects with proper == and hashCode?
    └── ObjectKey(item) ✓

// GOOD: ValueKey with stable ID
ListView.builder(
  itemCount: tasks.length,
  itemBuilder: (context, index) {
    final task = tasks[index];
    return TaskTile(
      key: ValueKey(task.id), // Stable across reorders
      task: task,
      onToggle: () => toggleTask(task.id),
    );
  },
);

// BAD: Using index as key — breaks when list reorders
key: ValueKey(index) // WRONG for reorderable lists

// Accessing State from outside the widget
final formKey = GlobalKey<FormState>();

Form(
  key: formKey,
  child: Column(children: [/* fields */]),
);

// Validate from parent
if (formKey.currentState?.validate() ?? false) {
  formKey.currentState!.save();
}

// GOOD: const constructor — widget never rebuilds
class AppDivider extends StatelessWidget {
  const AppDivider({super.key}); // const constructor

  @override
  Widget build(BuildContext context) {
    return const Divider(height: 1, thickness: 1); // const child too
  }
}

// Usage — const at call site
const AppDivider(), // Flutter caches this instance

// When you CAN'T use const
class UserChip extends StatelessWidget {
  const UserChip({super.key, required this.name}); // const constructor OK
  final String name;

  @override
  Widget build(BuildContext context) {
    return Chip(label: Text(name)); // Not const — name is runtime value
  }
}
// But call site can't be const because name varies:
UserChip(name: user.name) // No const prefix

class _MyWidgetState extends State<MyWidget> {
  Future<void> _submit() async {
    final navigator = Navigator.of(context); // Capture before await
    final messenger = ScaffoldMessenger.of(context);

    try {
      await api.submit(data);
      if (!mounted) return; // Check before using context
      navigator.pop();
    } catch (e) {
      if (!mounted) return;
      messenger.showSnackBar(SnackBar(content: Text('Error: $e')));
    }
  }
}

class AppConfig extends InheritedWidget {
  const AppConfig({
    super.key,
    required this.apiBaseUrl,
    required this.featureFlags,
    required super.child,
  });

  final String apiBaseUrl;
  final Map<String, bool> featureFlags;

  static AppConfig of(BuildContext context) {
    final result = context.dependOnInheritedWidgetOfExactType<AppConfig>();
    assert(result != null, 'No AppConfig found in context');
    return result!;
  }

  // Optional: static method that doesn't subscribe to changes
  static AppConfig? maybeOf(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<AppConfig>();
  }

  @override
  bool updateShouldNotify(AppConfig oldWidget) {
    return apiBaseUrl != oldWidget.apiBaseUrl ||
        featureFlags != oldWidget.featureFlags;
  }
}

// Usage
final config = AppConfig.of(context);
if (config.featureFlags['darkMode'] == true) { /* ... */ }

// Problem: Scaffold.of(context) fails because context is ABOVE the Scaffold
@override
Widget build(BuildContext context) {
  return Scaffold(
    body: ElevatedButton(
      onPressed: () {
        // BAD: context is above Scaffold, no ScaffoldMessenger found
        ScaffoldMessenger.of(context).showSnackBar(/*...*/);
      },
      child: const Text('Show Snackbar'),
    ),
  );
}

// Solution: Builder provides a context BELOW the Scaffold
@override
Widget build(BuildContext context) {
  return Scaffold(
    body: Builder(
      builder: (scaffoldContext) {
        return ElevatedButton(
          onPressed: () {
            // GOOD: scaffoldContext is below Scaffold
            ScaffoldMessenger.of(scaffoldContext).showSnackBar(/*...*/);
          },
          child: const Text('Show Snackbar'),
        );
      },
    ),
  );
}

class ResponsiveGrid extends StatelessWidget {
  const ResponsiveGrid({super.key, required this.children});
  final List<Widget> children;

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(
      builder: (context, constraints) {
        final columns = constraints.maxWidth > 900 ? 3
            : constraints.maxWidth > 600 ? 2
            : 1;
        return GridView.count(
          crossAxisCount: columns,
          children: children,
        );
      },
    );
  }
}

// BAD: setState in initState triggers unnecessary rebuild
@override
void initState() {
  super.initState();
  setState(() { _value = widget.initialValue; }); // WRONG
}

// GOOD: Initialize directly
@override
void initState() {
  super.initState();
  _value = widget.initialValue; // No setState needed
}

// BAD: Entire Column rebuilds when counter changes
class _MyState extends State<MyWidget> {
  int _counter = 0;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        const ExpensiveHeader(),       // Rebuilds unnecessarily
        Text('$_counter'),             // Only this needs to update
        const ExpensiveFooter(),       // Rebuilds unnecessarily
      ],
    );
  }
}

// GOOD: Extract the changing part into its own widget
class MyWidget extends StatelessWidget {
  const MyWidget({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        const ExpensiveHeader(),   // Never rebuilds
        const CounterText(),       // Only this rebuilds
        const ExpensiveFooter(),   // Never rebuilds
      ],
    );
  }
}

class CounterText extends StatefulWidget {
  const CounterText({super.key});

  @override
  State<CounterText> createState() => _CounterTextState();
}

class _CounterTextState extends State<CounterText> {
  int _counter = 0;

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () => setState(() => _counter++),
      child: Text('$_counter'),
    );
  }
}