> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/migration.md). # Guía de migración Esta guía cubre el proceso de migrar componentes de UI1 (`decentraland-ui`) a UI2 (`decentraland-ui2`). ## Cuándo migrar Las migraciones pueden comenzar por tres razones válidas: ### 1. Mejora técnica Quieres migrar un componente por: * Mejor compatibilidad con temas * Tipos de TypeScript mejorados * Coherencia con otros componentes de UI2 * Optimización del rendimiento * Mejoras de accesibilidad ### 2. Actualización de un componente * Un componente de UI1 necesita ser actualizado * Todavía no existe un equivalente en UI2 * **Requisito**: Créalo primero en UI2 y luego úsalo ### 3. Necesidades del proyecto * El componente se utilizará en un proyecto nuevo o existente * Hay tiempo disponible para migrarlo correctamente * Los recursos del proyecto permiten una migración exhaustiva {% hint style="warning" %} **No** migres componentes "solo porque sí". Cada migración debe tener una justificación empresarial o técnica clara. {% endhint %} *** ## Proceso de migración ### Paso 1: Planificación Antes de comenzar la migración: 1. **Identifica dependencias** * ¿Qué otros componentes utiliza? * ¿Qué proyectos lo usan actualmente? * ¿Hay algún breaking change planificado? 2. **Revisa el uso actual** * ¿Cuántos proyectos usan este componente? * ¿Qué props se usan con más frecuencia? * ¿Hay problemas conocidos? 3. **Define el alcance** * ¿Será una migración 1:1? * ¿Hay mejoras planificadas? * ¿Cuál es el cronograma? ### Paso 2: Crear el componente de UI2 Sigue la [Componentes personalizados](/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/custom-components.md) guía para componentes candidatos de UI2. **Requisitos:** * Usa sintaxis de objeto para styled-components * Usa solo valores del tema (sin valores arbitrarios) * Añade historias completas de Storybook * Escribe pruebas completas * Documenta todas las props y comportamientos **Estructura de ejemplo:** ``` ui2/src/components/Button/ ├── Button.tsx ├── Button.styles.ts ├── Button.stories.tsx ├── Button.test.tsx ├── types.ts ├── index.ts └── README.md ``` ### Paso 3: Mantener la compatibilidad El componente de UI2 **DEBE** debe exponer las mismas props y comportamientos que la versión de UI1. #### Mismas props ```tsx // Button de UI1 interface ButtonProps { primary?: boolean; size?: 'small' | 'medium' | 'large'; onClick?: () => void; disabled?: boolean; children: React.ReactNode; } // Button de UI2 - DEBE admitir las mismas props interface ButtonProps { primary?: boolean; size?: 'small' | 'medium' | 'large'; onClick?: () => void; disabled?: boolean; children: React.ReactNode; // Se pueden añadir nuevas props opcionales variant?: 'text' | 'outlined' | 'contained'; } ``` #### Cambios compatibles con versiones anteriores Si necesitas cambiar o añadir props: 1. **Primero**, añade las nuevas props a UI1 como opcionales 2. **Después**, migra a los consumidores de UI1 para que usen las nuevas props 3. **Por último**, crea el componente de UI2 con la nueva API ```tsx // Paso 1: Añadir prop opcional a UI1 interface ButtonProps { primary?: boolean; // Nueva prop opcional variant?: 'primary' | 'secondary'; } // Paso 2: Actualizar la implementación de UI1 export function Button({ primary, variant = primary ? 'primary' : 'secondary' }: ButtonProps) { // Usa variant en lugar de primary internamente } // Paso 3: Crear UI2 con la nueva API interface ButtonProps { // variant ahora es la prop principal variant?: 'primary' | 'secondary'; // Mantén primary por compatibilidad, márcala como obsoleta /** @deprecated Usa variant en su lugar */ primary?: boolean; } ``` ### Paso 4: Marcar como obsoleto el componente de UI1 Añade un aviso de deprecación al componente de UI1: ````tsx /** * @deprecated Este componente se ha migrado a UI2. * Importa desde 'decentraland-ui2' en su lugar: * * ```tsx * import { Button } from 'decentraland-ui2'; * ``` * * Consulta la guía de migración: https://docs.decentraland.org/contributor-guides/web-ui-standards/migration */ export function Button(props: ButtonProps) { // ... implementación existente } ```` ### Paso 5: Adopción gradual No fuerces una migración inmediata. Permite una adopción gradual: 1. **Publica** componente de UI2 2. **Documenta** ruta de migración 3. **Actualiza** los nuevos proyectos para que usen UI2 4. **Migra** los proyectos existentes de forma oportunista 5. **Planifica** la eventual eliminación de UI1 (con aviso) *** ## Ejemplos de migración ### Ejemplo 1: Componente simple Migración de un `Card` componente: #### Versión de UI1 ```tsx // decentraland-ui/src/components/Card/Card.tsx import React from 'react'; import './Card.css'; export interface CardProps { className?: string; children: React.ReactNode; } export function Card({ className, children }: CardProps) { return (
{children}
); } ``` #### Versión de UI2 ```tsx // decentraland-ui2/src/components/Card/Card.tsx import { styled } from '@mui/material/styles'; export interface CardProps { className?: string; children: React.ReactNode; } const StyledCard = styled('div')(({ theme }) => ({ backgroundColor: theme.palette.background.paper, borderRadius: theme.shape.borderRadius, padding: theme.spacing(2), boxShadow: theme.shadows[1], [theme.breakpoints.down('sm')]: { padding: theme.spacing(1), }, })); export function Card({ className, children }: CardProps) { return ( {children} ); } ``` ### Ejemplo 2: Componente con variantes Migración de un `Button` con variantes: #### Versión de UI1 ```tsx // UI1 import './Button.css'; interface ButtonProps { primary?: boolean; secondary?: boolean; size?: 'small' | 'medium' | 'large'; } export function Button({ primary, secondary, size = 'medium', ...props }: ButtonProps) { const classes = [ 'dcl-button', primary && 'primary', secondary && 'secondary', `size-${size}`, ].filter(Boolean).join(' '); return