Component Guidelines

Widget composition and UI reuse conventions for apps/lib/**.

Practical Conventions

Prefer shared widgets before creating new feature-local widgets.
Use semantic theme slots (Theme.of(context).colorScheme.*) and project tokens (AppSpacing, AppRadius).
Keep feature screens focused on composition; move reusable sections into shared/widgets/**.
Use project-consistent feedback components (Toast / AppBanner / AppLoadingIndicator).

Shared base components:
- apps/lib/shared/widgets/app_button.dart
- apps/lib/shared/widgets/banner/app_banner.dart
- apps/lib/shared/widgets/app_loading_indicator.dart
Feature screen composition using shared widgets/tokens:
- apps/lib/features/auth/presentation/screens/login_screen.dart
- apps/lib/features/settings/presentation/widgets/settings_page_scaffold.dart
- apps/lib/features/home/presentation/widgets/home_composer_stack.dart
Design system sources:
- apps/lib/core/theme/design_tokens.dart
- apps/lib/core/theme/app_theme.dart

Color usage
- Use colorScheme for semantic colors.
- Use Theme.extension<AppColorPalette>() only for brand palette/event/avatar domains.
Spacing & radius
- Use AppSpacing.* / AppRadius.* tokens as defaults.
Page actions & confirmations
- Reuse shared action/confirmation surfaces where available (for consistent interaction style).

Duplicating near-identical controls per feature instead of extending shared widgets.
- Existing shared baseline in apps/lib/shared/widgets/** should be checked first.
Hardcoding user-facing feedback patterns outside project primitives.
- Existing patterns: AppBanner in login_screen.dart, AppLoadingIndicator in shared/widgets/app_loading_indicator.dart.
Bypassing theme semantics by introducing ad-hoc Colors.* in feature widgets.
- Current style source of truth is apps/lib/core/theme/app_theme.dart + design_tokens.dart.

There is no automated lint rule in this repo that forbids all hardcoded color constants in feature widgets; consistency relies on code review and AGENTS guidance.
Some older UI files may still contain local one-off style values where token extraction is incomplete.