flutter-core:flutter-ui-widgets

What this skill does

# Flutter UI Widgets

Master Flutter's powerful widget-based UI system to build beautiful, responsive, and platform-adaptive interfaces. This skill covers everything from basic layout widgets to advanced Material Design 3 components and iOS-style Cupertino widgets.

## Purpose

Flutter's UI is built entirely from widgets—composable building blocks that describe what the view should look like given their current configuration and state. Everything in Flutter is a widget, from structural elements like buttons and menus to layout models like padding and alignment. This fundamental design philosophy enables unprecedented flexibility and reusability.

The widget system operates on a composition model where complex UIs emerge from combining simple, single-purpose widgets. Rather than inheriting behavior through deep class hierarchies, Flutter favors shallow, broad hierarchies that maximize possible combinations. This approach leads to code that is concise, performant, and easier to reason about.

Flutter ships with two comprehensive design systems: Material Design for cross-platform consistency and Cupertino for iOS-native aesthetics. Material Design 3, enabled by default since Flutter 3.16, provides dynamic color support, enhanced accessibility, and an expressive component library. Cupertino widgets implement Apple's Human Interface Guidelines with high-fidelity iOS and macOS styling. You can use either system exclusively or mix them within the same app for truly adaptive experiences.

## Core Concepts

### 1. Widget Composition

Flutter's architecture is built on composition, not inheritance. Complex widgets are created by combining simpler widgets, each doing one thing well. The framework's shallow class hierarchy maximizes flexibility—instead of subclassing to modify behavior, you compose new widgets from existing ones.

**Example:**
```dart
// Composition: Build complex UI from simple widgets
Widget build(BuildContext context) {
  return Container(
    padding: const EdgeInsets.all(16),
    decoration: BoxDecoration(
      color: Colors.blue,
      borderRadius: BorderRadius.circular(8),
    ),
    child: Row(
      children: [
        const Icon(Icons.star),
        const SizedBox(width: 8),
        const Text('Featured'),
      ],
    ),
  );
}
```

### 2. Stateless vs Stateful Widgets

Widgets come in two flavors: `StatelessWidget` for immutable UI and `StatefulWidget` for dynamic, interactive components. Stateless widgets are ideal for static content, while stateful widgets maintain mutable state that can trigger rebuilds when changed via `setState()`.

**Example:**
```dart
// Stateless: UI doesn't change
class WelcomeMessage extends StatelessWidget {
  const WelcomeMessage({super.key});

  @override
  Widget build(BuildContext context) {
    return const Text('Welcome to Flutter!');
  }
}

// Stateful: UI responds to interaction
class Counter extends StatefulWidget {
  const Counter({super.key});

  @override
  State<Counter> createState() => _CounterState();
}

class _CounterState extends State<Counter> {
  int _count = 0;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Count: $_count'),
        ElevatedButton(
          onPressed: () => setState(() => _count++),
          child: const Text('Increment'),
        ),
      ],
    );
  }
}
```

### 3. Layout Constraints

Flutter's layout system is constraint-based. Parent widgets pass constraints (minimum and maximum width/height) down to their children. Children then decide their size within those constraints, and the parent positions them accordingly. Understanding this "constraints go down, sizes go up, parent sets position" model is crucial for effective layout design.

### 4. Material Design 3

Material 3 is Flutter's default design language, providing a comprehensive set of components, theming capabilities, and design tokens. It emphasizes dynamic color, personal expression, and accessibility. Key widgets include `Scaffold`, `AppBar`, `Card`, `FloatingActionButton`, and navigation components like `NavigationBar` and `NavigationDrawer`.

### 5. Cupertino Widgets

For iOS-native experiences, Cupertino widgets implement Apple's design language with pixel-perfect fidelity. Use `CupertinoApp`, `CupertinoPageScaffold`, `CupertinoButton`, and other iOS-styled components when targeting Apple platforms or when you need that specific aesthetic.

### 6. Responsive Layouts

Build responsive UIs using `Row`, `Column`, `Expanded`, `Flexible`, and `MediaQuery`. `Expanded` makes children fill available space proportionally, while `Flexible` allows wrapping. Use `MediaQuery` to adapt layouts based on screen size, orientation, and platform.

### 7. Widget Lifecycle

Stateful widgets have a well-defined lifecycle: `initState()` for initialization, `build()` for rendering, `setState()` for triggering rebuilds, and `dispose()` for cleanup. Understanding this lifecycle is essential for managing resources, subscriptions, and animations properly.

### 8. Custom Widgets

Create reusable custom widgets to maintain consistency, reduce duplication, and encapsulate complexity. Extract common UI patterns into dedicated widget classes that can be configured through constructor parameters. This promotes a clean architecture and makes your codebase more maintainable.

## Quick Reference

### Basic Layout
```dart
import 'package:flutter/material.dart';

// Column: Vertical layout
Column(
  mainAxisAlignment: MainAxisAlignment.center,
  crossAxisAlignment: CrossAxisAlignment.start,
  children: [
    const Text('Item 1'),
    const Text('Item 2'),
    const Text('Item 3'),
  ],
)

// Row: Horizontal layout
Row(
  mainAxisAlignment: MainAxisAlignment.spaceEvenly,
  children: [
    const Icon(Icons.home),
    const Icon(Icons.search),
    const Icon(Icons.settings),
  ],
)

// Stack: Overlapping widgets
Stack(
  alignment: Alignment.center,
  children: [
    Container(width: 200, height: 200, color: Colors.blue),
    const Text('Centered', style: TextStyle(color: Colors.white)),
  ],
)
```

### Responsive Sizing
```dart
// Expanded: Fill available space proportionally
Row(
  children: [
    Expanded(
      flex: 1,
      child: Container(color: Colors.red),
    ),
    Expanded(
      flex: 2,
      child: Container(color: Colors.blue),
    ),
  ],
)

// Flexible: Flexible sizing with wrapping
Row(
  children: [
    Flexible(
      child: Text('This text will wrap if needed'),
    ),
  ],
)
```

### Material Design 3
```dart
import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
        useMaterial3: true,
      ),
      home: Scaffold(
        appBar: AppBar(title: const Text('Material 3')),
        body: Center(
          child: FilledButton(
            onPressed: () {},
            child: const Text('Filled Button'),
          ),
        ),
        floatingActionButton: FloatingActionButton(
          onPressed: () {},
          child: const Icon(Icons.add),
        ),
      ),
    );
  }
}
```

### Cupertino (iOS Style)
```dart
import 'package:flutter/cupertino.dart';

class MyIOSApp extends StatelessWidget {
  const MyIOSApp({super.key});

  @override
  Widget build(BuildContext context) {
    return CupertinoApp(
      theme: const CupertinoThemeData(
        primaryColor: CupertinoColors.systemBlue,
      ),
      home: CupertinoPageScaffold(
        navigationBar: const CupertinoNavigationBar(
          middle: Text('iOS Style'),
        ),
        child: Center(
          child: CupertinoButton.filled(
            onPressed: () {},
            child: const Text('iOS Button'),
          ),
        ),
      ),
    );
  }
}
```

### Stateful Widget Template
```dart
class MyWidget extends StatefulWidget {
  const M