material-ui

# Material UI ## Purpose Make the app's Android UI feel like a native Material 3 business app: calm, tactile, clear, scannable, accessible, expressive, and current. Use official Compose Material 3 components first, your app's theme tokens second, and custom drawing only when no native component or Material Symbol fits. ## First Moves 1. Inspect nearby screens/components before designing; match the app's existing navigation, sheets, cards, lists, forms, loading states, and haptics. 2. For detailed implementation rules, read [references/implementation-contract.md](references/implementation-contract.md). 3. For component choices and official links, read [references/component-catalog.md](references/component-catalog.md). 4. For app-owned reusable component patterns, read [references/app-components.md](references/app-components.md). 5. For icons, read [references/material-symbols.md](references/material-symbols.md). 6. For review/polish work, read [references/audit-checklist.md](references/audit-checklist.md). ## Design Posture - Treat the app as an operational business tool, not a marketing app. Favor dense but breathable layouts, fast scanning, obvious actions, and stable navigation. - Apply Material 3 Expressive selectively: stronger hierarchy, warmer shape/surface relationships, modern motion, and tactile feedback. Do not make every element oversized, bouncy, colorful, or decorative. - Prefer native M3 controls over custom compositions: buttons, chips, segmented buttons, cards, dialogs, sheets, top bars, bottom navigation, progress indicators, text fields, switches, radio buttons, checkboxes, and date/time pickers. - Use the app's semantic meaning consistently: sale/success uses secondary semantics, expense/error uses error semantics, due/warning uses tertiary semantics. - Keep every UI change accessible, localized, dark-theme-safe, and resource-backed. - Make feedback immediate and local. When a user starts work that takes time, render the resulting row/card/selection as soon as it is safe, show progress inside that surface, and update it in place when the work completes. ## Implementation Rules - Import UI components from `androidx.compose.material3`. Do not introduce `androidx.compose.material.*` in new UI. - Use `MaterialTheme.colorScheme`, `MaterialTheme.typography`, `MaterialTheme.shapes`, and helpers from `core/design` such as `AppSemanticColors`, `cardContainer`, `raisedCardContainer`, and `sheetContainer`. - Build app-owned components in the spirit of shadcn: local, readable, composable wrappers around native M3 primitives, not a black-box library and not wrappers for every component. - Avoid hardcoded feature-screen colors, type sizes, font families, and shape constants unless the value is intrinsic content or explicitly documented. - Use local Material Symbols Rounded XML drawables rendered with Material 3 `Icon(painter = painterResource(...))`. - Put user-visible text in string resources and preserve Arabic/Urdu expansion. - Use `contentDescription = null` for decorative icons and meaningful descriptions for icon-only actions. - Keep loading, disabled, empty, error, offline, and dirty-dismiss states as first-class UI states. - Treat expected business validation as user feedback, not infrastructure failure. Use M3 snackbars or sheet-level errors for user-correctable issues such as balance limits, required values, unavailable choices, or invalid amounts; do not route these into offline queue / sync-attention states unless the work genuinely needs retry or review. - Prefer optimistic previews for uploads and imports: show a pending card with a `CircularProgressIndicator`, use the local URI as the preview when available, disable save while required upload ids are still pending, and replace the pending item with the uploaded item in place. ## Verification Run at least: ```bash cd apps/android ./gradlew :app:compileDebugKotlin ``` For meaningful UI work, also run or inspect the relevant screen on device/emulator when practical. If `:app:lintDebug` fails only on known unrelated translation debt, report that clearly.