Enforcing Compose Material3 Architecture
Before writing any Composable, check for violations:
KOTLIN// ❌ REJECTED - hardcoded literals, no state hoisting, shadow for depth @Composable fun UserCard() { Card(elevation = CardDefaults.cardElevation(defaultElevation = 4.dp)) { Text("Title", fontSize = 16.sp, color = Color(0xFF1A1A1A)) } } // ✅ CORRECT - tokens, tonal hierarchy, stateless, modifier on root @Composable fun UserCard( title: String, modifier: Modifier = Modifier, ) { Card( modifier = modifier, colors = CardDefaults.cardColors( containerColor = MaterialTheme.colorScheme.surfaceContainer, ), ) { Text( text = title, style = MaterialTheme.typography.titleMedium, color = MaterialTheme.colorScheme.onSurface, modifier = Modifier.padding(MaterialTheme.spacing.medium), ) } }
Progress checklist for every screen/component delivered:
- No hardcoded
.dp/.sp/Color(0x...)outside:core:designsystem - Spacing uses
MaterialTheme.spacing.*scale only - Typography uses
MaterialTheme.typography.*roles only - Tonal hierarchy applied correctly by nesting level (no
shadowElevationhacks) - Text color hierarchy respected (
onSurfacevsonSurfaceVariant) - Composable is stateless,
modifier: Modifier = Modifieris first optional param, applied only to root node - Screen split into
XxxRoute/XxxScreen/ atomic sub-components (≤60 lines each) -
@PreviewLightDark+@PreviewFontScaleadded, wrapped inAppTheme - Previews cover: loading (skeleton/shimmer), empty state, long text truncation
Step 1: Audit for literals
Grep the file for \d+\.dp, \d+\.sp, Color(0x. Any match outside :core:designsystem is a violation — replace with the nearest token in MaterialTheme.spacing or MaterialTheme.typography.
Step 2: Assign tonal level
Determine nesting depth and map to surface token:
| Level | Use case | Token |
|---|---|---|
| 0 | Base screen | colorScheme.surface |
| 1 | Sections/lists | colorScheme.surfaceContainerLow |
| 2 | Interactive cards | colorScheme.surfaceContainer |
| 3 | Modals/floating | colorScheme.surfaceContainerHigh |
Never jump levels arbitrarily (e.g., a card inside a card should go Level 1 → Level 2, not Level 0 → Level 3).
Step 3: Structure the screen
KOTLIN@Composable fun XxxRoute( viewModel: XxxViewModel = hiltViewModel(), onNavigateBack: () -> Unit, ) { val uiState by viewModel.uiState.collectAsStateWithLifecycle() XxxScreen( uiState = uiState, onAction = viewModel::onAction, onNavigateBack = onNavigateBack, ) } @Composable fun XxxScreen( uiState: XxxUiState, onAction: (XxxAction) -> Unit, onNavigateBack: () -> Unit, modifier: Modifier = Modifier, ) { // layout delegating to atomic sub-components }
Step 4: Add previews
KOTLIN@PreviewLightDark @PreviewFontScale @Composable private fun XxxScreenPreview( @PreviewParameter(XxxUiStateProvider::class) uiState: XxxUiState, ) { AppTheme { XxxScreen(uiState = uiState, onAction = {}, onNavigateBack = {}) } }
Provide a PreviewParameterProvider yielding at least: loading, empty, success-with-long-text states.
Example 1: Input:
KOTLINText("Settings", fontSize = 20.sp, modifier = Modifier.padding(16.dp))
Output:
KOTLINText( text = "Settings", style = MaterialTheme.typography.headlineSmall, color = MaterialTheme.colorScheme.onSurface, modifier = Modifier.padding(MaterialTheme.spacing.medium), )
Example 2:
Input: A ProductCard composable with internal remember { mutableStateOf(false) } for "expanded" state, used directly by multiple screens.
Output: Hoist state — ProductCard(expanded: Boolean, onExpandToggle: () -> Unit, modifier: Modifier = Modifier). Caller (XxxScreen) owns the state via rememberSaveable or ViewModel, depending on whether it must survive process death.
Example 3:
Input: A nested card-in-card layout both using surfaceContainerHigh.
Output: Outer card → surfaceContainer (Level 2), inner card → surfaceContainerHigh (Level 3). Flag as violation if both share the same token — visually flat, no hierarchy.
- When a new spacing/typography need arises that doesn't fit existing tokens, flag it — propose adding to
:core:designsystem, don't inline a one-off value. - Prefer semantic color roles (
onSurfaceVariantfor metadata) over manipulating alpha ononSurfacemanually. - Keep divider/border thickness fixed at
1.dpusingoutlineVariant; never useoutline(reserved for stronger emphasis, e.g., input field errors). - Sub-components should take primitive/data-class params, not raw
ViewModelor navigation callbacks beyond what they emit. - Long text fields always pair
maxLineswithoverflow = TextOverflow.Ellipsis.
- Using
shadowElevation/tonalElevationas a shortcut instead of explicit surface container tokens — rejected even if visually similar. - Applying
modifierparam to an inner node "for convenience" instead of the root — breaks caller's layout expectations (padding, size constraints). - Collapsing
Route/Screeninto one Composable "to save a file" — breaks testability and preview isolation. - Previews that only show the happy path — always include loading/empty/overflow states.
- Reusing
onSurfacefor secondary/meta text out of laziness — breaks visual hierarchy contract.