# Flutter Mobile Development Constraints

This document defines **hard constraints** for Flutter mobile development. Treat all items as **non-negotiable** unless explicitly overridden.

## 1) Design Tokens (MUST)

- **MUST** use design tokens from `apps/lib/core/theme/design_tokens.dart`:
  - Colors: `AppColors.*`
  - Spacing: `AppSpacing.*`
  - Radius: `AppRadius.*`
- **MUST NOT** hardcode any visual values, including (but not limited to): colors, font sizes, spacing, padding/margins, widths/heights, radii, shadows, opacity, or “magic numbers”.
  - Examples that are **NOT allowed**: `Color(0xFF...)`, `SizedBox(height: 12)`, `EdgeInsets.all(16)`, `Radius.circular(8)`.

## 2) Component Reuse (MUST)

- **MUST** prefer existing components and established page patterns over creating new UI components.
- **MUST** use:
  - Buttons: `AppButton` from `apps/lib/shared/widgets/app_button.dart`
- **MUST NOT** introduce parallel UI systems (custom buttons, custom loading systems, custom input wrappers) unless explicitly required and approved.

## 3) Layout Mapping & Alignment (MUST)

- **MUST** explicitly set `crossAxisAlignment` for every `Row` / `Column` (do not rely on defaults).
- **MUST** preserve layout semantics from root to leaf:
  - alignment/justification intent must be explicitly represented in Flutter widgets.
- **MUST NOT** skip necessary container layers if doing so loses layout meaning or makes mapping non-traceable.

## 4) Centering & Visual Balance (MUST)

- **MUST** evaluate centering within `SafeArea` usable bounds (not full-screen bounds).
- **MUST NOT** rely on `Spacer` / proportional flex as the only centering mechanism for critical content.
- If persistent header/footer regions exist, **MUST** center primary content within the remaining usable region.
- **MUST** prioritize *visual centering* over purely geometric centering when they differ.

## 5) Quality Gate for Important Screens (MUST)

For important screens:

- **MUST** add widget tests to reduce layout regression risk:
  - Verify primary content stays centered relative to the usable viewport.
  - Include at least one constrained scenario (e.g., small height **or** large text scale).

## 6) UI Feedback System (MUST)

- All user-facing feedback **MUST** use the Toast system.
  - Transient notifications: `Toast.show(...)`
  - Persistent inline form errors: `AppBanner`
- **MUST NOT** create custom SnackBar/Dialog/Banner feedback components.
- **MUST NOT** use raw `ScaffoldMessenger` for feedback messaging.

## 7) Agent Chat (AG-UI Protocol) (MUST)

Agent chat functionality **MUST** follow the AG-UI protocol: `docs/knowledges/ag-ui-llms-full.txt`.

- **MUST** use Server-Sent Events (SSE) for streaming.
- **MUST** emit required lifecycle events:
  - `RUN_STARTED` is required for every run
  - End with exactly one of: `RUN_FINISHED` or `RUN_ERROR`
- **MUST** follow standard text streaming flow:
  - `TEXT_MESSAGE_START` → `TEXT_MESSAGE_CONTENT` (delta) → `TEXT_MESSAGE_END`
- **MUST** support the standard AG-UI event type set as defined in the spec.
- **MUST NOT** return non-streaming responses for agent chat.
- **MUST NOT** omit required lifecycle events.
- **MUST NOT** use non-AG-UI event formats (except where the spec explicitly allows).

## 8) Debugging Behavior (MUST)

- **MUST NOT** automatically start Flutter app debugging or running.
- After code changes, **MUST** instruct the user to run manually (user-controlled):
  - `flutter run --dart-define=MOCK_API=true -d emulator-5554`