# Component Guidelines

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

---

## Practical Conventions

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

---

## Real File Path Examples

- 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`

---

## UI Contract Rules

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

---

## Anti-patterns (with evidence)

- 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`.

---

## Uncertainties / Gaps

- 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.