Skip to content

sickn33/agentic-awesome-skills / plugins/aasb-aas-mobile-app-builder/skills/flutter-expert

flutter-expert

Verified

Master Flutter development with Dart 3, advanced widgets, and multi-platform deployment.

FileKindSize
SKILL.mdskill md10.2 KB
resources/implementation-playbook.mdmarkdown6.4 KB

resources/implementation-playbook.md

View on GitHub
# Flutter Implementation Playbook

Concrete, copy-adaptable patterns for the `flutter-expert` skill. Every snippet
targets **Flutter 3.x + Dart 3.x** with null safety. Use these as starting
points, then adapt to the project's architecture and constraints.

---

## 1. Recommended Project Structure (feature-first + clean layers)

```
lib/
  main.dart
  core/                 # cross-cutting: theme, router, errors, DI
    errors/failure.dart
    network/dio_client.dart
  features/
    products/
      data/             # models, DTOs, repositories impl
      domain/           # entities, repository contracts, use cases
      presentation/     # widgets, screens, providers/controllers
```

**Rule of thumb:** `presentation` may import `domain`; `data` implements
`domain` contracts; `domain` imports nothing from Flutter. This keeps business
logic testable without a widget tree.

---

## 2. State Management with Riverpod 2.x (recommended default)

Riverpod gives compile-time safety and easy testing. Prefer code-generation
(`riverpod_generator`) for new projects.

```dart
// products_controller.dart
import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'products_controller.g.dart';

@riverpod
class ProductsController extends _$ProductsController {
  @override
  Future<List<Product>> build() async {
    // The return value is exposed as AsyncValue<List<Product>>.
    return ref.watch(productRepositoryProvider).fetchAll();
  }

  Future<void> refresh() async {
    state = const AsyncLoading();
    state = await AsyncValue.guard(
      () => ref.read(productRepositoryProvider).fetchAll(),
    );
  }
}
```

Consume it with explicit loading/error/data states — never assume data is
ready:

```dart
class ProductsScreen extends ConsumerWidget {
  const ProductsScreen({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final productsAsync = ref.watch(productsControllerProvider);

    return productsAsync.when(
      loading: () => const Center(child: CircularProgressIndicator()),
      error: (err, _) => ErrorView(message: err.toString()),
      data: (products) => ListView.builder(
        itemCount: products.length,
        itemBuilder: (_, i) => ProductTile(product: products[i]),
      ),
    );
  }
}
```

---

## 3. Repository + Dio with error mapping

Keep network failures out of the UI. Map them to a typed `Failure` in the data
layer.

```dart
sealed class Failure {
  const Failure(this.message);
  final String message;

  // Override toString so UI code that renders err.toString() shows the
  // mapped message instead of "Instance of 'NetworkFailure'".
  @override
  String toString() => message;
}

class NetworkFailure extends Failure {
  const NetworkFailure(super.message);
}

class ProductRepository {
  ProductRepository(this._dio);
  final Dio _dio;

  Future<List<Product>> fetchAll() async {
    try {
      final res = await _dio.get('/products');
      return (res.data as List)
          .map((json) => Product.fromJson(json as Map<String, dynamic>))
          .toList();
    } on DioException catch (e) {
      // Log sanitized diagnostic details privately; do not expose URLs/headers/tokens.
      throw const NetworkFailure('Unable to load products. Please try again.');
    }
  }
}
```

---

## 4. Performance: rebuilds, const, and keys

- Mark widgets `const` whenever their inputs are compile-time constants — this
  can let Flutter reuse unchanged widget instances; inherited dependencies and other invalidations can still rebuild them.
- Split large `build` methods into smaller widgets so only the changing subtree
  rebuilds.
- Use `ListView.builder` / slivers for long or infinite lists (never map a huge
  list into a `Column`).
- Give list items stable `Key`s when their order can change.

```dart
// Good: const permits reuse when configuration/dependencies remain unchanged.
const _Header(title: 'Products');

// Bad: rebuilding a giant Column holds every child in memory.
Column(children: products.map(ProductTile.new).toList());
```

Profile with **Flutter DevTools → Performance** and enable the "Rebuild
counts" overlay to find widgets rebuilding more than expected.

---

## 5. Widget & golden testing

```dart
void main() {
  testWidgets('shows product name', (tester) async {
    await tester.pumpWidget(
      const MaterialApp(home: ProductTile(product: Product(name: 'Seeds'))),
    );

    expect(find.text('Seeds'), findsOneWidget);
  });

  testWidgets('golden matches baseline', (tester) async {
    await tester.pumpWidget(
      const MaterialApp(home: ProductTile(product: Product(name: 'Seeds'))),
    );

    await expectLater(
      find.byType(ProductTile),
      matchesGoldenFile('goldens/product_tile.png'),
    );
  });
}
```

Create/update goldens only after visually reviewing the intended rendering; inspect diffs before accepting new baselines. Pin fonts/platform/device pixel ratio in CI so failures indicate actual visual changes.

---

## 6. Async & isolates for CPU-bound work

Never block the UI isolate with heavy work (parsing large JSON, image
processing). Offload with `compute`:

```dart
Future<List<Product>> parseProducts(String rawJson) {
  return compute(_decode, rawJson); // native: separate isolate; web: current event loop
}

List<Product> _decode(String rawJson) =>
    (jsonDecode(rawJson) as List)
        .map((e) => Product.fromJson(e as Map<String, dynamic>))
        .toList();
```

---

## 7. Common pitfalls

- **Problem:** `setState` called after `dispose` → `mounted` exception.
  **Solution:** guard with `if (!mounted) return;` after any `await`.
- **Problem:** Rebuilding the whole screen on every keystroke.
  **Solution:** isolate the changing widget or use a `select` on the provider.
- **Problem:** Memory leaks from uncancelled `StreamSubscription` / controllers.
  **Solution:** cancel/dispose in `dispose()`; with Riverpod use `ref.onDispose`.
- **Problem:** Blocking the UI thread with synchronous file/JSON work.
  **Solution:** move it to an isolate via `compute` (section 6).

---

## 8. Pre-ship checklist

- [ ] `flutter analyze` is clean (no warnings)
- [ ] `flutter test` passes, including golden tests
- [ ] Widgets use `const` where possible; long lists use builders/slivers
- [ ] All loading/error/empty states are handled in the UI
- [ ] Controllers, streams, and subscriptions are disposed
- [ ] Tested on a real device for both iOS and Android
- [ ] Accessibility: semantic labels on interactive widgets, adequate contrast
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall