home / skills / hoangnguyen0403 / agent-skills-standard / android-design-system

android-design-system skill

This skill enforces Material Design 3 tokens in Jetpack Compose apps using MaterialTheme for consistent theming and typography.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill android-design-system

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.7 KB

---
name: Android Design System (Jetpack Compose)
description: Enforce Material Design 3 and design token usage in Jetpack Compose apps.
metadata:
  labels: [android, compose, dls, material-design, design-tokens]
  triggers:
    files: ['**/*Screen.kt', '**/ui/theme/**', '**/compose/**']
    keywords: [MaterialTheme, Color, Typography, Modifier, Composable]
---

# Android Design System (Jetpack Compose)

## **Priority: P2 (OPTIONAL)**

Enforce Material Design 3 tokens in Jetpack Compose. Use `MaterialTheme` for consistency.

## Token Structure

```kotlin
// ui/theme/Color.kt
val Primary = Color(0xFF2196F3)
val Secondary = Color(0xFF9C27B0)
val Background = Color(0xFFFFFFFF)

// ui/theme/Theme.kt
private val LightColorScheme = lightColorScheme(
    primary = Primary,
    secondary = Secondary,
    background = Background
)

// ui/theme/Type.kt
val Typography = Typography(
    headlineLarge = TextStyle(fontSize = 32.sp, fontWeight = FontWeight.Bold),
    bodyMedium = TextStyle(fontSize = 16.sp, fontWeight = FontWeight.Normal)
)
```

## Usage

```kotlin
// ❌ FORBIDDEN
Box(modifier = Modifier.background(Color(0xFF2196F3)))
Text("Title", fontSize = 32.sp, color = Color.Black)

// ✅ ENFORCED
Box(modifier = Modifier.background(MaterialTheme.colorScheme.primary))
Text("Title", style = MaterialTheme.typography.headlineLarge)
Spacer(modifier = Modifier.height(16.dp)) // Use dp units
```

## Anti-Patterns

- **No Hardcoded Colors**: Use `Color(0xFF...)` → Error. Use `MaterialTheme.colorScheme.*`.
- **No Inline Typography**: Define `fontSize = 32.sp` → Error. Use `MaterialTheme.typography.*`.
- **No Magic Spacing**: Use `padding = 16.dp` inline → Acceptable, but consider tokens.

## Related Topics

mobile-ux-core | android/compose

Overview

This skill enforces Material Design 3 and design token usage in Jetpack Compose applications. It guides developers to centralize colors, typography, and spacing into a theme using MaterialTheme and design tokens. The goal is consistent UI, easier theming, and fewer visual regressions across the app.

How this skill works

The skill inspects Compose code to detect hardcoded Color, inline TextStyle, and ad-hoc spacing values. It flags violations and recommends replacing literals with MaterialTheme.colorScheme, MaterialTheme.typography, and tokenized dp values. It also provides concrete examples showing forbidden patterns and the enforced alternatives.

When to use it

When building or auditing Jetpack Compose UI components
When migrating an app to Material Design 3 or a centralized theme
When enforcing a design system across teams or feature modules
During code review to catch inline styles and color literals
When preparing theming for light/dark modes and dynamic color support

Best practices

Define a single theme module with color, typography, and shape tokens
Always reference colors via MaterialTheme.colorScheme.* instead of Color(0xFF...)
Reference text styles through MaterialTheme.typography.* rather than inline font sizes
Use dp and tokenized spacing values from a spacing token set instead of magic numbers
Keep tokens expressive and reusable (e.g., spacingSmall, spacingMedium, headlineLarge)

Example use cases

Replace Box(modifier = Modifier.background(Color(0xFF2196F3))) with Modifier.background(MaterialTheme.colorScheme.primary)
Swap inline Text("Title", fontSize = 32.sp) for Text("Title", style = MaterialTheme.typography.headlineLarge)
Create a central ui/theme package with Color.kt, Theme.kt, and Type.kt for consistent tokens
Run the skill during CI to fail builds when hardcoded colors or inline typography are detected
Use the skill to enforce consistent spacing units and prepare the app for dynamic color theming

FAQ

What happens if I need a one-off color?

Prefer adding a token to the theme; reserve true one-offs for rare cases and document them. Adding tokens keeps the system predictable and easier to maintain.

Are magic dp values forbidden?

Magic dp values are allowed but discouraged for repeated values. Prefer spacing tokens for consistency; occasional inline dp for unique layouts is acceptable.