59 lines
2.3 KiB
Markdown
59 lines
2.3 KiB
Markdown
|
# 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.
|