feature-screen

Flutter Template Feature Screen

Use this skill when adding a new screen or route to this repository.

Read First

• AGENTS.md
• docs/PROJECT_OVERVIEW.md
• docs/PROJECT_GUIDELINES.md
• lib/app/navigation/app_router.dart

Default Output

Create work inside lib/features/<feature>/.

Prefer this shape when the screen owns state:

lib/features/<feature>/
  <feature>_page.dart
  <feature>_page_content.dart
  <feature>_state.dart
  <feature>_event.dart

For simple static screens, *_state.dart and *_event.dart may be unnecessary.

Workflow

1. Inspect nearby features with a similar level of complexity.
2. Create the new feature folder under lib/features/.
3. Add the route widget with @RoutePage().
4. Put larger widget trees into *_page_content.dart.
5. If the screen has async state, create a freezed state plus @riverpod notifier in *_state.dart.
6. If the screen needs one-off navigation, snackbar, or dialog effects, create a freezed event union in *_event.dart and listen in the page widget.
7. Register the route in lib/app/navigation/app_router.dart.
8. Use shared widgets and extensions before adding new abstractions.
9. If data is needed, add DTOs, entities, and use cases in the shared locations instead of doing IO in widgets.
10. Check narrow and wide layout behavior for the page content. Use LayoutBuilder for parent constraint-driven layouts, wrap flexible Row content in Expanded/Flexible, and avoid fixed dimensions that can overflow localized text.
11. Run make gen, then fvm flutter analyze, then relevant tests.

Conventions To Keep

• Keep *_page.dart thin.
• Prefer CustomAppBar, shared components, and shared compositions.
• Use context.colorScheme, context.textTheme, and context.locale.
• Use DTOs in lib/common/data/dto/ and entities in lib/common/data/entity/.
• Put IO-oriented behavior in lib/common/usecase/.
• Use AsyncValueExtension.mapState or mapContentState for async UI.
• Do not hand-edit generated files.