AI Skill Report Card

Enforcing Compose Material3 Architecture

A90·Nov 11, 2026·Source: Web
15 / 15

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), ) } }
Recommendation▾
Add one more example showing a full rejected-vs-corrected screen-level structure (Route/Screen split) rather than just component-level snippets, since that's a key workflow claim.
15 / 15

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 shadowElevation hacks)
  • Text color hierarchy respected (onSurface vs onSurfaceVariant)
  • Composable is stateless, modifier: Modifier = Modifier is first optional param, applied only to root node
  • Screen split into XxxRoute / XxxScreen / atomic sub-components (≤60 lines each)
  • @PreviewLightDark + @PreviewFontScale added, wrapped in AppTheme
  • 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:

LevelUse caseToken
0Base screencolorScheme.surface
1Sections/listscolorScheme.surfaceContainerLow
2Interactive cardscolorScheme.surfaceContainer
3Modals/floatingcolorScheme.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.

Recommendation▾
Consider adding a brief note on how to handle ambiguous cases where no existing token fits, beyond 'flag it' — e.g., escalation path or temporary naming convention.
17 / 20

Example 1: Input:

KOTLIN
Text("Settings", fontSize = 20.sp, modifier = Modifier.padding(16.dp))

Output:

KOTLIN
Text( 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.

Recommendation▾
The tonal hierarchy table is strong; a similarly concise table for typography role selection (headline vs title vs body usage) would round out completeness.
  • 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 (onSurfaceVariant for metadata) over manipulating alpha on onSurface manually.
  • Keep divider/border thickness fixed at 1.dp using outlineVariant; never use outline (reserved for stronger emphasis, e.g., input field errors).
  • Sub-components should take primitive/data-class params, not raw ViewModel or navigation callbacks beyond what they emit.
  • Long text fields always pair maxLines with overflow = TextOverflow.Ellipsis.
  • Using shadowElevation/tonalElevation as a shortcut instead of explicit surface container tokens — rejected even if visually similar.
  • Applying modifier param to an inner node "for convenience" instead of the root — breaks caller's layout expectations (padding, size constraints).
  • Collapsing Route/Screen into 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 onSurface for secondary/meta text out of laziness — breaks visual hierarchy contract.
0
Grade AAI Skill Framework
Scorecard
Criteria Breakdown
Quick Start
15/15
Workflow
15/15
Examples
17/20
Completeness
19/20
Format
14/15
Conciseness
14/15