Migra temas de XML a Material 3 en Compose

Si implementas Compose en una app existente, necesitará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 los temas XML.

Puedes usar la herramienta Material Theme Builder para migrar colores.

Cuando comiences la migración de XML a Compose, migra los temas a los temas de Material 3 Compose.

Glosario

Término Definición
MaterialTheme Es la función de componibilidad que proporciona temas (colores, tipografía y formas) a los componentes de la IU de Compose.
Shapes 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 y grosores) para un MaterialTheme.
ColorScheme 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 de View.

Limitaciones

Antes de migrar, ten en cuenta las siguientes limitaciones:

  • Esta guía se centra únicamente en la migración a Material 3. 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, lo que permite quitar los temas XML. En esta guía, se explica cómo migrar, pero no cómo quitar definitivamente los temas XML.

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

Identificar qué sistema de diseño se usa en el proyecto de vista XML Analizar 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 la aplicación de temas: esquemas de colores claros y oscuros, 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: El 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; nómbralos por su rol.

Ejemplos:

Nombre del color en 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 claro y oscuro de XML a sus equivalentes en Material 3 Compose.

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 Shapes para replicar tus definiciones de formas XML.

    2. Proporciona este objeto Shapes a tu MaterialTheme.

      Para obtener más detalles, 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 detalles, consulta Tipografía.

Rol de Compose Nombre de 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 los siguientes elementos:

  1. Widgets, componentes y 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/..." de forma directa y explícita en la vista XML
  2. Establecer 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 o modificadores a elementos componibles, con la nueva API de Styles experimental definida en AppTheme o creando variaciones de elementos componibles reutilizables y en capas con el estilo definido.

Proporciona funciones de componibilidad @Composable independientes con nombres que se correspondan con el estilo y el componente base para indicar la diferencia en el diseño 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 intercalado. En su lugar, sugiere crear un elemento componible 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 en una variable Modifier compartida.

Ejemplos comunes

XML Redactar
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) definido en Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.Material3.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.Material3.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 y strokeWidth border = BorderStroke(width, color)
android:textSize fontSize = X.sp en TextStyle

Paso 6: Valida la migración del tema

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

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