gabuldev/flutter-skills

You are implementing or auditing accessibility (a11y) for a Flutter app.

## Context

Accessibility pressure differs by surface, and it changes what you prioritise:

- **Customer-facing web** — the highest bar. Screen-reader semantics are off by
  default on Flutter web (see section 5), the audience is unknown, and in many
  jurisdictions this is a legal requirement, not a nicety.
- **Internal/admin web** — keyboard navigation and contrast matter most; staff
  use these all day.
- **Mobile** — platform screen readers (TalkBack/VoiceOver) mostly work if you
  give widgets labels and keep tap targets large enough.

You are implementing caching for a Flutter feature. The patterns below assume Dio for HTTP, a secure-storage wrapper for sensitive data, `flutter_bloc` for state, and Clean Architecture (domain/data/presentation) - adapt the names to your stack, the shapes carry over.

## Caching Strategy Selection

| Strategy | When to Use | Package/Impl |
|---|---|---|
| `shared_preferences` | Non-sensitive key-value: UI prefs, filters, TTL timestamps, feature flags | `shared_preferences` |
| Secure storage | Auth tokens, credentials, sensitive user data. Wrap it in a `Storage` service with a `StorageKeys` enum rather than passing raw strings | `flutter_secure_storage` |
| In-memory cache | Short-lived GET responses, session-scoped data, computed values | Dio interceptor or Map in repository |
| `cached_network_image` | Product photos, logos, any remote image in list or detail screens | `cached_network_image` |
| Local DB (drift/sqflite) | Offline-first with complex queries (orders, history, large local datasets) | `drift` or `sqflite` |

**Rule of thumb**: SecureStorage for secrets, shared_preferences for preferences, in-memory for API responses, local DB for offline-first features.

You are working with Clean Architecture in a Flutter project.

## Layer Responsibilities

```
┌─────────────────────────────────────────┐
│  PRESENTATION                           │
│  Modules, Screens, Controllers (Cubits) │
│  Only knows: Domain entities + Usecases │
├─────────────────────────────────────────┤
│  DOMAIN (pure Dart, no Flutter)         │
│  Entities, Repository interfaces,       │
│  Usecases                               │
│  Depends on: nothing                    │

You are implementing concurrency for a Flutter feature. Choose the pattern based on the skill argument, if one was given, or on the context of the operation.

## Decision Framework

Pick the right tool for the workload:

| Workload | Pattern | Examples |
|---|---|---|
| I/O (network, storage) | `async/await` | Dio API calls, SharedPreferences, Hive reads |
| CPU < 16 ms | `async/await` | Small list transforms, formatting |
| One-time heavy CPU | `Isolate.run()` | PDF receipt generation, large JSON parsing |
| Continuous background | `Isolate.spawn()` with ports | Payment status polling, data sync |

**Rule of thumb**: if it does NOT block the main isolate for more than one frame (~16 ms), use `async/await`. Otherwise, offload to an isolate.

You are writing or reviewing Dart for craft — the layer below architecture.
Where a project convention exists, it wins; this is what to do when there isn't
one, and what the analyzer will not tell you.

Related in this repo: **flutter-clean-arch** for layering, **flutter-testing**
for what to test, **flutter-concurrency** for isolates and streams,
**flutter-accessibility** for semantics, **flutter-theming** for colour and type.

Some topics below have a **canonical skill from the Dart team**
([dart-lang/skills](https://github.com/dart-lang/skills)) that goes deeper than
this file should. Where one exists it is named inline — install it and defer to
it. What stays here is the opinion: which convention this codebase picked, and
the traps the analyzer won't flag.

You are working on a Flutter design system package - a `design_system/` package at the monorepo root, depended on by every app.

## When argument is "setup" or empty

Scaffold the complete design system package structure:

### Package Structure
```
design_system/
├── pubspec.yaml
└── lib/
    ├── design_system.dart              ← Barrel export file
    └── src/
        ├── tokens/

You are configuring dependency injection for a Flutter feature using `flutter_injections`.

## DI Architecture Overview

```
FlutterInjectionsWidget (root, in AppWidget)
  └── CoreInjections.core()        ← global singletons (Dio, repos, session)
       ├── auth()
       ├── services()
       ├── eventBus()
       └── ...

FlutterModule (per-module, lazy)
  └── HomeModule.injections        ← scoped to module lifetime

You are implementing a form for a Flutter feature.

## Three Patterns by Use Case

Choose based on the skill argument, if one was given, or on the context of the feature:

- `simple` — basic form with minimal validation (settings toggle, quick input)
- `validated` — full validation, field-level errors, submit-to-Cubit flow (login, product creation)
- `multi-step` — form split across tabs or stepper (store config, onboarding)

---

## Form Architecture

You are working with a Melos-based Flutter monorepo.

## Monorepo Layout

```
<project_root>/
├── melos.yaml              <- Melos workspace config
├── pubspec.yaml            <- Workspace root (required for Melos 4+)
├── Makefile                <- Developer commands (setup, dev, build, test)
├── core/                   <- Shared domain + data layer
│   ├── pubspec.yaml
│   └── lib/
│       ├── domain/
│       ├── data/

You are creating a complete feature module for a scalable Flutter project - Cubit for state, `flutter_injections` for DI, one folder per feature under `lib/modules/`.

## Input
- Module name: from the request, or from the skill argument (e.g., "payment", "order", "profile").
  **If no name was given, ask before creating any file** — it drives every directory,
  file and class name below, and renaming afterwards touches all of them.
- If a second argument is given, it's the package path (e.g., "../my_app/lib")
- If no path given, use the current package's `lib/` directory

## Module Structure to Create

Create ALL the following files for module `<module_name>`:

```

You are running or building a Flutter app. The core idea of this skill: **a bare
`flutter run` is almost never the right command in a real project.** Flavors,
`--dart-define`s and the Flutter version all have to line up, and remembering
them by hand is where the lost afternoons come from.

## Put a task runner in front of `flutter`

Make the repo's `Makefile` (or melos script, or `just` file) the source of truth
for how each app is launched, and run *that*. It is the only way the flags stay
consistent between your machine, a teammate's, and CI.

A shape that works for a multi-app monorepo:

```bash

You are implementing state management for a Flutter feature using Cubit + RxDart.

## Three Patterns by Use Case

Choose based on the skill argument, if one was given, or on the context of the feature:

- `simple` — basic async operations (load data, submit form)
- `stream` — real-time data via RxDart BehaviorSubject
- `event-bus` — cross-module communication via Broker

---

## Pattern 1: Simple Cubit (default)

You are setting up, or fixing, the pipeline that takes a Flutter app from a git
tag to TestFlight and Google Play. The design in one line: **push a `v*` tag,
two independent workflows build, sign and upload each platform; nothing else
triggers a store build.**

Two ready workflows sit next to this file, written in full from a production app.
Copy them to `.github/workflows/`, then set the `env:` block at the top of each:

- [`templates/android-play.yml`](templates/android-play.yml): ubuntu, signs an
  App Bundle, uploads it to Play
- [`templates/ios-testflight.yml`](templates/ios-testflight.yml): macOS, archives
  and signs an IPA, uploads it to TestFlight

The rest of this skill is the reasoning behind them and the traps each line

You are implementing tests for a Flutter feature.

## Test Pyramid

```
┌─────────────────────┐
│   E2E (Maestro)     │  Few — critical user flows only
│   Real device/emu   │
├─────────────────────┤
│   Widget Tests      │  Medium — one per screen/widget
│   WidgetTester      │
├─────────────────────┤
│   Unit Tests        │  Many — usecases, repos, models,
│   Pure Dart          │  controllers, extensions

You are working on theming for a Flutter app. The patterns below assume a shared `design_system/` package holding cross-app tokens (`DSColors`, `DSSpacing`, `DSRadius`, `DSTypography`), with each app free to keep its own `lib/theme/` for app-specific overrides.

Always prefer importing a token from the design system over duplicating the value in an app.

---

## Workflow: create

Scaffold a complete theme for the target app, taken
from the request or the skill argument. **If it is not clear which app, ask before writing
anything:** each one has its own theme directory and overwriting the wrong app is silent.

### Theme Directory Structure

You are working on a Flutter **web** build. Everything here is a lesson that
cost real hours — each one looks like an application bug and is not.

## Browser QA only counts in a visible tab

Flutter web drives its **entire** frame pipeline from `requestAnimationFrame`,
and Chrome throttles rAF to near zero in a tab that is not the active one. In a
background tab the app still runs — events are processed, network calls fire —
but it barely paints. So route transitions appear frozen for tens of seconds,
and click coordinates read off a screenshot land nowhere, because the painted
frame no longer matches the real hit-test layout.

That looks exactly like two bugs that do not exist: a slow splash screen and
broken Tab traversal.