Migra temas de XML a Material 3 en Compose

Si implementas Compose en una app existente, deberás migrar tus temas XML de Material para usar MaterialTheme en los componentes de Compose. Eso significa que el tema de tu app tendrá dos fuentes de confianza: un tema basado en View y otro basado en Compose. Si decides realizar cambios en tu estilo, deberás hacerlos en varios lugares. Una vez que tu app se haya migrado por completo a Compose, quita el tema XML.

Puedes usar la herramienta Material Theme Builder para migrar colores.

Cuando comiences la migración de XML a Compose, migra el tema al tema de Compose de Material 3.

Glosario

Término Definición
MaterialTheme Es la función de componibilidad que proporciona temas (colores, tipografía, formas) a los componentes de la IU de Compose.
Shape Es un objeto de Compose que se usa para definir formas de componentes personalizados para un MaterialTheme.
Typography Es un objeto de Compose que se usa para definir estilos de texto personalizados (familias de fuentes, tamaños, pesos) para un MaterialTheme.
Color Es un objeto de Compose que se usa para definir esquemas de colores personalizados para MaterialTheme.
Tema XML Es el sistema de temas de Android definido en archivos XML que usa el sistema View.

Limitaciones

Antes de la migración, ten en cuenta las siguientes limitaciones:

  • Esta guía se enfoca en la migración a Material 3 únicamente. Para migrar desde sistemas de diseño alternativos, consulta Material 2 o Sistemas de diseño personalizado en Compose.
  • El objetivo final es una migración completa a Compose, que permite quitar el tema XML. En esta guía, se explica cómo migrar, pero no cómo quitar finalmente el tema XML.

Paso 1: Evalúa el sistema de diseño

Identifica qué sistema de diseño se usa en el proyecto de vista XML. Analiza la ruta de migración y los pasos necesarios para migrar el sistema de diseño existente a Material 3 en Compose.

Paso 2: Identifica los archivos fuente del tema

En XML, escribes ?attr/colorPrimary. En Compose, accedes a los valores del tema con MaterialTheme.*:

Identifica y ubica todos los recursos y archivos XML necesarios para el tema: esquemas de colores claros y oscuros y calificadores, temas, formas, dimensiones, tipografía, estilos y otros archivos relevantes.

Los recursos, como las cadenas, se pueden reutilizar tal como están y no es necesario migrarlos.

Paso 3: Migra los colores

Principio clave: XML usa colores hexadecimales con nombre. Material 3 usa roles semánticos (p.ej., primary, onPrimary, surface). Deja de nombrar los colores por su valor hexadecimal y nómbralos por su rol.

Ejemplos:

Nombre del color XML Rol de Material 3
colorPrimary primary
colorPrimaryDark / colorPrimaryVariant primaryContainer o secondary
colorAccent secondary o tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

Migra los esquemas de colores oscuros y claros de XML a sus equivalentes en Compose de Material 3.

Paso 4: Migra las formas y la tipografía personalizadas

  • Si tu app usa formas personalizadas, haz lo siguiente:

    1. En tu código de Compose, define un objeto Shape para replicar tus definiciones de formas XML.

    2. Proporciona este objeto Shape a tu MaterialTheme.

      Para obtener más información, consulta formas.

  • Si tu app usa tipografía personalizada, haz lo siguiente:

    1. En tu código de Compose, define un objeto Typography para replicar tus estilos de texto XML y definiciones de fuentes.

    2. Proporciona este objeto Typography a tu MaterialTheme.

      Para obtener más información, consulta tipografía.

Rol de Compose Nombre XML
displayLarge TextAppearance.Material3.DisplayLarge
displayMedium TextAppearance.Material3.DisplayMedium
displaySmall TextAppearance.Material3.DisplaySmall
headlineLarge TextAppearance.Material3.HeadlineLarge
headlineMedium TextAppearance.Material3.HeadlineMedium
headlineSmall TextAppearance.Material3.HeadlineSmall
titleLarge TextAppearance.Material3.TitleLarge
titleMedium TextAppearance.Material3.TitleMedium
titleSmall TextAppearance.Material3.TitleSmall
bodyLarge TextAppearance.Material3.BodyLarge
bodyMedium TextAppearance.Material3.BodyMedium
bodySmall TextAppearance.Material3.BodySmall
labelLarge TextAppearance.Material3.LabelLarge
labelMedium TextAppearance.Material3.LabelMedium
labelSmall TextAppearance.Material3.LabelSmall

Paso 5: Migra los estilos (styles.xml)

El sistema de estilos XML (styles.xml) define los estilos y la apariencia de lo siguiente: 1. Widgets, componentes, temas para ventanas y diálogos 2. Tipografía 3. Temas y superposiciones 4. Formas

Las vistas y los componentes XML combinan varios atributos para crear un estilo. Establecen sus estilos desde styles.xml de dos maneras diferentes: 1. Configurar "style="@style/..." directamente y de forma explícita en la vista XML 2. Configurar el estilo de forma indirecta e implícita para un componente como parte de un tema más grande (theme.xml)

Los estilos no tienen un equivalente directo en Compose. En su lugar, se pasan como parámetros a los elementos de componibilidad, se definen en AppTheme o se crean variaciones de componibilidad reutilizables y en capas con el estilo definido.

Proporciona funciones @Composable independientes con nombres según el estilo y el componente base para indicar la diferencia en el estilo y los casos de uso de esos componentes.

  • Patrón: Si un elemento XML usa un estilo personalizado (p.ej., style="@style/MyPrimaryButton"), no intentes replicar el estilo en línea. En su lugar, sugiere crear un elemento de componibilidad específico.
  • Ejemplo:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Compose: MyPrimaryButton(onClick = { ... })
  • Grupos de atributos comunes: Si un estilo establece modificadores comunes (como padding + height), extráelos en una propiedad de extensión legible o una variable Modifier compartida.

Ejemplos comunes

XML Redactar
Theme.MaterialComponents.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) definido en Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.MaterialComponents.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.MaterialComponents.CardView Card(shape=..., elevation=..., colors=...)
Widget.*.TextInputLayout.OutlinedBox OutlinedTextField(colors = OutlinedTextFieldDefaults.colors(...))
Widget.*.Chip.Filter FilterChip(colors = FilterChipDefaults.filterChipColors(...))
Widget.*.Toolbar.Primary TopAppBar(colors = TopAppBarDefaults.topAppBarColors(...))
Widget.*.FloatingActionButton FloatingActionButton(containerColor = ...)
backgroundTint containerColor en ComponentDefaults.ComponentColors()
android:textColor contentColor en ComponentDefaults.ComponentColors()
cornerRadius shape = RoundedCornerShape(X.dp)
android:elevation elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding contentPadding = PaddingValues(...) o Modifier.padding()
android:minHeight Modifier.heightIn(min = X.dp)
strokeColor + strokeWidth border = BorderStroke(width, color)
android:textSize fontSize = X.sp en TextStyle

Paso 6: Valida la migración del tema

Siempre usa los valores del tema existente del tema XML original como fuente de confianza para el nuevo tema de Material en Compose. Nunca inventes valores de tema nuevos durante la migración para mantener la coherencia de la marca y evitar regresiones visuales.

Verifica que todos los valores del tema de Compose nuevos coincidan con los valores XML existentes. No codifiques ningún valor migrado.