design-tokens

Design Tokens

The complete Material 3 design system foundation for Android. Every color, spacing value, elevation, and shape in a production app must come from this system. 22 rules covering all categories globally.

---

CRITICAL — Color System

Rule 1: Always Use Semantic Color Roles — Never Hardcode

// ✅ Every color references MaterialTheme
Text(color = MaterialTheme.colorScheme.onSurface)           // primary text
Text(color = MaterialTheme.colorScheme.onSurfaceVariant)    // secondary text
Box(Modifier.background(MaterialTheme.colorScheme.surfaceContainerLow))  // card bg
Icon(tint = MaterialTheme.colorScheme.onSurfaceVariant)     // secondary icon

// ❌ Hardcoded hex — breaks dark mode and dynamic color
Text(color = Color(0xFF212121))
Box(Modifier.background(Color.White))

The 6 color families — each has a surface + on-surface pair:

• primary / onPrimary — brand color, key interactive elements
• secondary / onSecondary — supporting brand color
• tertiary / onTertiary — accent, contrasting highlight
• error / onError — errors, destructive actions
• surface / onSurface — cards, sheets (use onSurfaceVariant for secondary text)
• background / onBackground — page background

Container variants — for filled backgrounds: primaryContainer/onPrimaryContainer, secondaryContainer/onSecondaryContainer

Surface containers — layered depth (lowest→low→default→high→highest)

Always pair correctly: content on primaryContainer uses onPrimaryContainer, never onSurface.

---

Rule 2: Theme Structure — Complete Theme.kt Required

// ✅ Complete theme with dynamic color + fallback
@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context)
            else dynamicLightColorScheme(context)
        }
        darkTheme -> DarkColorScheme   // your brand dark scheme
        else -> LightColorScheme       // your brand light scheme
    }
    MaterialTheme(colorScheme = colorScheme, typography = AppTypography,
        shapes = AppShapes, content = content)
}

// Theme files: Color.kt · Type.kt · Shape.kt · Theme.kt
// ❌ Defining theme inside a specific screen
// ❌ No dark color scheme defined — only light
// ❌ lightColorScheme() with no arguments — all M3 default purple, no brand