Diretrizes de Design da Plataforma Android — Material Design 3
1. Material You & Tematização [CRÍTICO]
1.1 Cor Dinâmica
Ative a cor dinâmica derivada do papel de parede do usuário. A cor dinâmica é o padrão no Android 12+ e deve ser a estratégia principal de tematização.
// Compose: Tema de cor dinâmica
@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()
else -> lightColorScheme()
}
MaterialTheme(
colorScheme = colorScheme,
typography = AppTypography,
content = content
)
}
<!-- XML: Cor dinâmica em themes.xml -->
<style name="Theme.App" parent="Theme.Material3.DayNight.NoActionBar">
<item name="dynamicColorThemeOverlay">@style/ThemeOverlay.Material3.DynamicColors.DayNight</item>
</style>
Regras:
- R1.1: Sempre forneça um esquema de cores estático de fallback para dispositivos anteriores ao Android 12.
- R1.2: Nunca codifique valores hexadecimais de cores em componentes. Sempre referencie papéis de cores do tema.
- R1.3: Teste com pelo menos 3 papéis de parede diferentes para verificar a harmonia das cores dinâmicas.
1.2 Papéis de Cores
O Material 3 define um conjunto estruturado de papéis de cores. Use-os semanticamente, não esteticamente.
| Papel | Uso | On-Papel |
|---|---|---|
primary | Ações principais, estados ativos, FAB | onPrimary |
primaryContainer | Elementos primários menos proeminentes | onPrimaryContainer |
secondary | UI de suporte, chips de filtro | onSecondary |
secondaryContainer | Indicador ativo da barra de navegação | onSecondaryContainer |
tertiary | Acento, contraste, complementar | onTertiary |
tertiaryContainer | Campos de entrada, acentos menos proeminentes | onTertiaryContainer |
surface | Fundos, cartões, folhas | onSurface |
surfaceVariant | Elementos decorativos, divisores | onSurfaceVariant |
error | Estados de erro, ações destrutivas | onError |
errorContainer | Fundos de erro | onErrorContainer |
outline | Bordas, divisores | — |
outlineVariant | Bordas sutis | — |
inverseSurface | Fundo do Snackbar | inverseOnSurface |
// Correto: papéis de cores semânticas
Text(
text = "Mensagem de erro",
color = MaterialTheme.colorScheme.error
)
Surface(color = MaterialTheme.colorScheme.errorContainer) {
Text(text = "Detalhe do erro", color = MaterialTheme.colorScheme.onErrorContainer)
}
// ERRADO: cores codificadas
Text(text = "Erro", color = Color(0xFFB00020)) // Anti-padrão
Regras:
- R1.4: Cada elemento de primeiro plano deve usar o papel de cor
oncorrespondente ao seu fundo (ex.: textoonPrimaryno fundoprimary). - R1.5: Use
surfacee suas variantes para fundos. Nunca useprimaryousecondarycomo grandes áreas de fundo. - R1.6: Use
tertiarycom moderação, apenas para acento e contraste complementar.
1.3 Temas Claro e Escuro
Suporte ambos os temas claro e escuro. Respeite a configuração do sistema por padrão.
// Compose: Detectar tema do sistema
val darkTheme = isSystemInDarkTheme()
Regras:
- R1.7: Sempre suporte ambos os temas claro e escuro. Nunca lance apenas o claro.
- R1.8: Superfícies do tema escuro usam mapeamento tonal baseado em elevação, não preto puro (#000000). Use os papéis de cor
surfaceque lidam com isso automaticamente. - R1.9: Forneça uma substituição manual de tema nas configurações do app (Sistema / Claro / Escuro).
1.4 Sementes de Cores Personalizadas
Quando a marca exigir cores personalizadas, forneça uma cor semente e gere paletas tonais usando o Material Theme Builder.
// Esquema de cores personalizado com semente da marca
private val BrandLightColorScheme = lightColorScheme(
primary = Color(0xFF1B6D2F),
onPrimary = Color(0xFFFFFFFF),
primaryContainer = Color(0xFFA4F6A8),
onPrimaryContainer = Color(0xFF002107),
// ... gere a paleta completa a partir da semente
)
Regras:
- R1.10: Gere paletas tonais a partir de cores semente usando o Material Theme Builder. Nunca escolha tons individuais manualmente.
- R1.11: Ao usar cores personalizadas, ainda suporte a cor dinâmica como padrão e use as cores personalizadas como fallback.
2. Navegação [CRÍTICO]
2.1 Barra de Navegação (Inferior)
O padrão de navegação principal para telefones com 3-5 destinos de nível superior.
// Compose: Barra de Navegação
NavigationBar {
items.forEachIndexed { index, item ->
NavigationBarItem(
icon = {
Icon(
imageVector = if (selectedItem == index) item.filledIcon else item.outlinedIcon,
contentDescription = item.label
)
},
label = { Text(item.label) },
selected = selectedItem == index,
onClick = { selectedItem = index }
)
}
}
Regras:
- R2.1: Use a Barra de Navegação para 3-5 destinos de nível superior em telas compactas. Nunca use para menos de 3 ou mais de 5.
- R2.2: Sempre mostre rótulos nos itens da barra de navegação. Barras de navegação apenas com ícones não são permitidas.
- R2.3: Use ícones preenchidos para o estado selecionado e ícones contornados para estados não selecionados.
- R2.4: O indicador ativo usa a cor
secondaryContainer. Não substitua isso.
2.2 Trilho de Navegação
Para telas médias e expandidas (tablets, dobráveis, desktop).
// Compose: Trilho de Navegação para telas maiores
NavigationRail(
header = {
FloatingActionButton(
onClick = { /* ação principal */ },
containerColor = MaterialTheme.colorScheme.tertiaryContainer
) {
Icon(Icons.Default.Add, contentDescription = "Criar")
}
}
) {
items.forEachIndexed { index, item ->
NavigationRailItem(
icon = { Icon(item.icon, contentDescription = item.label) },
label = { Text(item.label) },
selected = selectedItem == index,
onClick = { selectedItem = index }
)
}
}
Regras:
- R2.5: Use o Trilho de Navegação em tamanhos de janela médios (600-839dp) e expandidos (840dp+). Combine-o com a Barra de Navegação no compacto.
- R2.6: Opcionalmente, inclua um FAB no cabeçalho do trilho para a ação principal.
- R2.7: Rótulos são opcionais no trilho, mas recomendados para clareza.
2.3 Gaveta de Navegação
Para 5+ destinos ou hierarquias de navegação complexas, tipicamente em telas expandidas.
// Compose: Gaveta de Navegação Permanente para telas grandes
PermanentNavigationDrawer(
drawerContent = {
PermanentDrawerSheet {
Text("Nome do App", modifier = Modifier.padding(16.dp),
style = MaterialTheme.typography.titleMedium)
HorizontalDivider()
items.forEach { item ->
NavigationDrawerItem(
label = { Text(item.label) },
selected = item == selectedItem,
onClick = { selectedItem = item },
icon = { Icon(item.icon, contentDescription = null) }
)
}
}
}
) {
Scaffold { /* conteúdo da página */ }
}
Regras:
- R2.8: Use a gaveta modal em telas compactas, gaveta permanente em telas expandidas.
- R2.9: Agrupe itens da gaveta em seções com divisores e cabeçalhos de seção.
2.4 Gestão de Volta Preditiva
Android 13+ suporta volta preditiva com uma animação de pré-visualização.
// Compose: Volta preditiva com BackHandler (androidx.activity.compose)
BackHandler(enabled = true) {
// Chamado quando a volta é confirmada; navegue de volta no seu controlador de navegação
navController.popBackStack()
}
// Compose: Animação de progresso da volta preditiva usando o modificador predictiveBackHandler
// (androidx.activity:activity-compose 1.8+)
Modifier.predictiveBackHandler(enabled = true) { progress ->
// progress é um Flow<BackEventCompat> com x, y, swipeEdge, progress (0.0–1.0)
progress.collect { backEvent ->
animationState = backEvent.progress
}
}
<!-- AndroidManifest.xml: optar pela volta preditiva -->
<application android:enableOnBackInvokedCallback="true">
Regras:
- R2.10: Opte pela volta preditiva no manifesto. Em apps Compose, use
BackHandler(deandroidx.activity.compose) para interceptar eventos de volta. Em apps baseados em View, implementeOnBackInvokedCallback(API 33+) ouOnBackPressedCallback(AndroidX) em vez de substituironBackPressed(). - R2.11: O gesto de volta do sistema navega para trás na pilha de navegação. O botão Acima (seta da barra de ferramentas) navega para cima na hierarquia do app. Eles podem diferir.
- R2.12: Nunca intercepte a volta do sistema para mostrar diálogos "tem certeza?", a menos que haja entrada de usuário não salva.
- R2.13: Não suprima a animação de pré-visualização de volta fornecida pelo sistema. Se você implementar transições de entrada/saída personalizadas, interpole-as usando
BackEventCompat.progress(0.0–1.0) e respeiteBackEventCompat.swipeEdge(EDGE_LEFT/EDGE_RIGHT) para que a tela de saída seja reduzida e deslocada em direção à borda de início, correspondendo à animação do sistema. - R2.14: Prefira reconhecimento em vez de recall. Mantenha os destinos rotulados, o estado selecionado visível e o contexto da pilha de retorno preservado para que os usuários não tenham que reconstruir onde estão após cada etapa de navegação.
// Compose: conduzir uma animação personalizada a partir do progresso da volta preditiva
Modifier.predictiveBackHandler(enabled = true) { progress ->
progress.collect { backEvent ->
// backEvent.progress: 0.0 (início do gesto) → 1.0 (confirmado)
// backEvent.swipeEdge: BackEventCompat.EDGE_LEFT ou EDGE_RIGHT
exitScale = 1f - (backEvent.progress * 0.1f)
exitOffsetX = if (backEvent.swipeEdge == BackEventCompat.EDGE_LEFT) -backEvent.progress * 32.dp.toPx() else backEvent.progress * 32.dp.toPx()
}
}
2.5 Seleção do Componente de Navegação
| Tamanho da Tela | 3-5 Destinos | 5+ Destinos |
|---|---|---|
| Compacto (< 600dp) | Barra de Navegação | Gaveta Modal + Barra de Navegação |
| Médio (600-839dp) | Trilho de Navegação | Gaveta Modal + Trilho de Navegação |
| Expandido (840dp+) | Trilho de Navegação | Gaveta Permanente |
3. Layout & Responsividade [ALTA]
3.1 Classes de Tamanho de Janela
Use classes de tamanho de janela para layouts adaptativos, não pontos de interrupção de pixel brutos.
// Compose: Classes de tamanho de janela
val windowSizeClass = calculateWindowSizeClass(this)
when (windowSizeClass.widthSizeClass) {
WindowWidthSizeClass.Compact -> CompactLayout()
WindowWidthSizeClass.Medium -> MediumLayout()
WindowWidthSizeClass.Expanded -> ExpandedLayout()
}
| Classe | Largura | Dispositivo Típico | Colunas |
|---|---|---|---|
| Compacto | < 600dp | Telefone retrato | 4 |
| Médio | 600-839dp | Tablet retrato, dobrável | 8 |
| Expandido | 840dp+ | Tablet paisagem, desktop | 12 |
Regras:
- R3.1: Sempre use
WindowSizeClassdematerial3-window-size-classpara decisões de layout responsivo. - R3.2: Nunca use pontos de interrupção de pixel fixos. As categorias de dispositivos são fluidas.
- R3.3: Suporte todas as três classes de tamanho de largura. No mínimo, compacto e expandido.
3.2 Grade Material
Aplique margens e medianiz canônicas da grade Material.
| Classe de Tamanho | Margens | Medianiz | Colunas |
|---|---|---|---|
| Compacto | 16dp | 8dp | 4 |
| Médio | 24dp | 16dp | 8 |
| Expandido | 24dp | 24dp | 12 |
Regras:
- R3.4: O conteúdo não deve ocupar toda a largura em telas expandidas. Use uma largura máxima de conteúdo de ~840dp ou layout de lista-detalhe.
- R3.5: Aplique margens horizontais consistentes correspondendo à especificação da grade.
3.3 Exibição Borda a Borda
Android 15+ exige borda a borda. Todos os apps devem desenhar atrás das barras do sistema.
// Compose: Configuração borda a borda
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
enableEdgeToEdge()
super.onCreate(savedInstanceState)
setContent {
Scaffold(
modifier = Modifier.fillMaxSize(),
// Scaffold lida com insets para barras superior/inferior automaticamente
) { innerPadding ->
Content(modifier = Modifier.padding(innerPadding))
}
}
}
}
Regras:
- R3.6: Chame
enableEdgeToEdge()antes desetContent. Desenhe atrás da barra de status e da barra de navegação. - R3.7: Use
WindowInsetspara preencher o conteúdo longe das barras do sistema.Scaffoldlida com isso para o conteúdo da barra superior e inferior automaticamente. - R3.8: O conteúdo rolável deve rolar atrás das barras do sistema transparentes com preenchimento de insets apropriado no topo e na base da lista.
3.4 Suporte a Dispositivos Dobráveis
// Compose: Detectar postura de dobra
val foldingFeatures = WindowInfoTracker.getOrCreate(context)
.windowLayoutInfo(context)
.collectAsState(initial = WindowLayoutInfo(emptyList()))
Regras:
- R3.9: Detecte a posição da dobradiça/dobra e evite colocar conteúdo crítico através da dobra.
- R3.10: Use
ListDetailPaneScaffoldouSupportingPaneScaffoldda biblioteca adaptativa Material3 para layouts cientes de dobra.
4. Tipografia [ALTA]
4.1 Escala de Tipo Material
| Papel | Tamanho Padrão | Peso Padrão | Uso |
|---|---|---|---|
| displayLarge | 57sp | 400 | Texto herói, integração |
| displayMedium | 45sp | 400 | Texto de recurso grande |
| displaySmall | 36sp | 400 | Exibição proeminente |
| headlineLarge | 32sp | 400 | Títulos de tela |
| headlineMedium | 28sp | 400 | Cabeçalhos de seção |
| headlineSmall | 24sp | 400 | Títulos de cartão |
| titleLarge | 22sp | 400 | Título da barra de aplicativo superior |
| titleMedium | 16sp | 500 | Abas, navegação |
| titleSmall | 14sp | 500 | Subtítulos |
| bodyLarge | 16sp | 400 | Texto do corpo principal |
| bodyMedium | 14sp | 400 | Texto do corpo secundário |
| bodySmall | 12sp | 400 | Legendas |
| labelLarge | 14sp | 500 | Botões, rótulos proeminentes |
| labelMedium | 12sp | 500 | Chips, metadados |
| labelSmall | 11sp | 500 | Rótulos de componentes pequenos |
Regras:
- R4.1: Defina
Typographypersonalizada uma vez no tema do seu app. Personalize com base na face de fonte da sua marca.
// Exemplo de tipografia personalizada
val AppTypography = Typography(
displayLarge = TextStyle(fontFamily = FontFamily.Default, fontWeight = FontWeight.Normal),
headlineLarge = TextStyle(fontFamily = FontFamily.Default, fontWeight = FontWeight.Bold),
bodyLarge = TextStyle(fontFamily = FontFamily.Default, fontWeight = FontWeight.Normal),
labelLarge = TextStyle(fontFamily = FontFamily.Default, fontWeight = FontWeight.Medium)
)
- R4.2: Use
lineHeightda tipografia (o Material 3 define automaticamente lineHeight como 1.0×, 1.25× ou 1.5× dependendo do papel). - R4.3: Não use fontes diferentes para tamanhos diferentes da mesma face de fonte. Escolha uma face e varie o peso.
5. Ícones [ALTA]
5.1 Ícones de Material
Use ícones preenchidos e contornados consistentemente.
| Uso | Estado | Forma do Ícone |
|---|---|---|
| Barra de navegação, itens de gaveta | Selecionado | Preenchido |
| Barra de navegação, itens de gaveta | Não selecionado | Contornado |
| Ações em AppBars | Qualquer | Contornado |
| Ações FAB | Qualquer | Preenchido |
Regras:
- R5.1: Use ícones de Material Design do pacote
material-icons-coreou extensões. Use ícones SVG (vector drawable) para ícones personalizados. - R5.2: Ícones decorativos (sem ação) devem ser marcados como
contentDescription = nullpara acessibilidade. - R5.3: Sempre forneça
contentDescriptionpara ícones interativos.
6. Superfícies & Elevação [MÉDIA]
6.1 Efeitos de Elevação e Sombra
Os componentes do Material 3 usam sombras para indicar elevação. Use Card, ElevatedButton, Surface em vez de sombras manuais.
// Compose: Níveis de elevação do Material 3
Surface(
tonalElevation = 3.dp, // Elevação para o nível 3
shadowElevation = 1.dp
) {
Text("Conteúdo")
}
Regras:
- R6.1: Use
SurfacecomtonalElevationem vez deelevationdiretamente. As cores de superfície mudam com a elevação no modo escuro. - R6.2: Ajuste a elevação com base nos níveis de elevação do Material 3: 0 (plano), 1 (card/botão), 2 (gaveta/folha), 3 (caixa de diálogo/Snackbar), 4 (FAB), 5 (barra de aplicativo).
7. Animações [MÉDIA]
7.1 Animações Preditivas de Volta
Veja a Seção 2.4 acima.
7.2 Animação de Tema
// Compose: Animação suave de tema
AnimatedContent(
targetState = currentTheme,
transitionSpec = {
if (targetState == Theme.Dark) {
fadeIn() with fadeOut()
} else {
fadeIn() with fadeOut()
}
}
) { theme ->
WhenTheme(theme)
}
Regras:
- R7.1: Use
animateFloatAsStateouAnimatedVisibilitypara animar alterações em elementos de UI. - R7.2: Animações padrão de componentes são fornecidas pelo Material 3. Não as substitua, a menos que seja necessário para a marca.
- R7.3: Use
FadeThroughpara transições entre ícones.
8. Acessibilidade [ALTA]
8.1 Meta de Toque
Todos os alvos de toque devem ter pelo menos 48dp × 48dp.
// Compose: Tamanho mínimo de toque
Modifier.minimumInteractiveComponentSize() // 48dp
Regras:
- R8.1: Garanta que todos os elementos interativos cumpram a meta de toque de 48dp.
- R8.2: Use
Modifier.minimumInteractiveComponentSizepara componentes que não atingem o tamanho mínimo. - R8.3: Forneça espaço suficiente entre alvos de toque adjacentes (8dp+).
8.2 Contraste de Cores
**Regras:**
- R8.4: Garanta que as taxas de contraste de cores cumpram os padrões WCAG AA (4.5:1 para texto normal, 3:1 para texto grande).
- R8.5: Teste com o verificador de contraste do Android Studio. Verifique tanto os modos claro quanto escuro.
8.3 Navegação por Leitor de Tela
// Compose: Acessibilidade
Icon(
painter = painterResource(id = R.drawable.ic_edit),
contentDescription = "Editar perfil" // texto descritivo para TalkBack
)
Regras:
- R8.6: Todos os ícones interativos devem ter
contentDescription. - R8.7: Imagens decorativas devem ter
contentDescription = null. - R8.8: Use
SemanticsModifier(ex.:semantics { role = Role.Button }) para mapear elementos de UI para funções de acessibilidade apropriadas.