flutter-presentation-layer

Flutter Presentation Layer (Clean Architecture)

Purpose: Provide a concise, opinionated set of conventions and quick prompts for implementing the presentation layer (UI + state) in a Flutter Clean Architecture project.

Principles

• Each UI page lives in its own folder so all page-specific artifacts are colocated.
• Each Cubit has a single responsibility: one cubit per action/intent (fetch, post, delete, etc.).
• Widgets live as close as possible to where they're used. Only genuinely shared components go into a global widgets folder.
• Keep build() methods clean: extract widget-building functions into private class methods or small private widgets.
• All user-facing strings must come from the localization system (ARB, S, AppLocalizations, etc.).
• For CRUD-like flows, split by intent explicitly: one cubit to list items, one to add/create item, one to delete item, and one to remove item from a local collection/state (if this action differs from backend delete).

Folder layout (recommended)

Use a feature-first layout. Example for a user feature with a list page:

• lib/features/user/presentation/user_list/
  • user_list_page.dart # page entry (Widget)
  • cubit/
    • user_list/
      • user_list_cubit.dart # cubit with single responsibility (e.g., fetch list)
      • user_list_state.dart # states for the cubit
  • widgets/ # page-scoped widgets used only by this page
    • user_row.dart
    • user_loading.dart

Shared UI components (only for true reuse)

• lib/shared/widgets/ # cross-feature shared widgets (buttons, inputs, avatars)
• lib/core/localization/ # localization ARB files and generated accessors

Cubit conventions

• Name: <feature>_<page>_<action>_cubit.dart OR for simpler cases <page>_cubit.dart with clearly separated methods. The important rule is one cubit per action/intent.
• Each cubit should:
  • Represent a single asynchronous intent (fetch, create, delete, update).
  • Expose a minimal API: one method to trigger the action and one public state stream.
  • Map domain errors to UI-friendly states. Do not embed domain logic—call usecases.

Examples:

• user_list_cubit — only responsible for fetching the list of users.
• user_create_cubit — only responsible for sending a create-user request and reporting success/failure.
• item_list_cubit — only responsible for listing items.
• item_add_cubit — only responsible for adding a new item.
• item_delete_cubit — only responsible for deleting an item in the backend/source of truth.
• item_remove_cubit — only responsible for removing an item from current UI state/local cache when modeled as a distinct action.

Practical SRP split for Cubits

When the page supports multiple intents, avoid a “god cubit”. Prefer one cubit per intent:

• ListItemsCubit: loads and refreshes item collections.
• AddItemCubit: handles create/add submission flow.
• DeleteItemCubit: executes delete use case against remote/local source of truth.
• RemoveItemCubit: removes an element from an in-memory list/UI state when this is a separate intent from delete.

This separation keeps each cubit focused, easier to test, and aligned with the Single Responsibility Principle (SRP).

Widget placement and composition

• Keep small, page-private widgets under the page's widgets/ folder.
• Only move a widget to lib/shared/widgets/ when at least two pages use it and its contract is stable.
• Prefer small focused widgets instead of large build methods with many nested conditionals.

Clean build() pattern

Bad:

class UserListPage extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold(body: ButtonPrimary(onPressed: () { // handle click }, ...)) } }

Good:

class UserListPage extends StatefulWidget { ... }

class _UserListPageState extends State { void _onClick() { // handle click }

@override Widget build(BuildContext context) => Scaffold(body: ButtonPrimary(onPressed: _onClick, ...)); }