# UI1 to UI2 Migration Guide This guide covers the process of migrating components from UI1 (`decentraland-ui`) to UI2 (`decentraland-ui2`). ## When to Migrate Migrations can start for three valid reasons: ### 1. Technical Improvement You want to migrate a component for: * Better theming support * Improved TypeScript types * Consistency with other UI2 components * Performance optimization * Accessibility improvements ### 2. Updating a Component * A UI1 component needs to be updated * There is no UI2 equivalent yet * **Requirement**: Create it in UI2 first, then use it ### 3. Project Needs * The component will be used in a new or existing project * There is time available to migrate it properly * Project resources allow for thorough migration > [!WARNING] > **Do not** migrate components "just because." Each migration should have a clear business or technical justification. --- ## Migration Process ### Step 1: Planning Before starting the migration: 1. **Identify dependencies** * What other components does it use? * What projects currently use it? * Are there any breaking changes planned? 2. **Review current usage** * How many projects use this component? * What props are most commonly used? * Are there any known issues? 3. **Define scope** * Will this be a 1:1 migration? * Are there planned improvements? * What's the timeline? ### Step 2: Create UI2 Component Follow the [Custom Components](/docs/contributor/contributor-guides/web-ui-standards/custom-components/) guide for UI2 candidate components. **Requirements:** * Use object syntax for styled-components * Use only theme values (no arbitrary values) * Add comprehensive Storybook stories * Write complete tests * Document all props and behaviors **Example structure:** ``` ui2/src/components/Button/ ├── Button.tsx ├── Button.styles.ts ├── Button.stories.tsx ├── Button.test.tsx ├── types.ts ├── index.ts └── README.md ``` ### Step 3: Maintain Compatibility The UI2 component **MUST** expose the same props and behaviors as the UI1 version. #### Same Props ```tsx // UI1 Button interface ButtonProps { primary?: boolean; size?: 'small' | 'medium' | 'large'; onClick?: () => void; disabled?: boolean; children: React.ReactNode; } // UI2 Button - MUST support same props interface ButtonProps { primary?: boolean; size?: 'small' | 'medium' | 'large'; onClick?: () => void; disabled?: boolean; children: React.ReactNode; // Can add new optional props variant?: 'text' | 'outlined' | 'contained'; } ``` #### Backward Compatible Changes If you need to change or add props: 1. **First**, add the new props to UI1 as optional 2. **Then**, migrate UI1 consumers to use the new props 3. **Finally**, create the UI2 component with the new API ```tsx // Step 1: Add optional prop to UI1 interface ButtonProps { primary?: boolean; // New optional prop variant?: 'primary' | 'secondary'; } // Step 2: Update UI1 implementation export function Button({ primary, variant = primary ? 'primary' : 'secondary' }: ButtonProps) { // Use variant instead of primary internally } // Step 3: Create UI2 with new API interface ButtonProps { // variant is now the primary prop variant?: 'primary' | 'secondary'; // Keep primary for compatibility, mark as deprecated /** @deprecated Use variant instead */ primary?: boolean; } ``` ### Step 4: Deprecate UI1 Component Add a deprecation notice to the UI1 component: ```tsx /** * @deprecated This component has been migrated to UI2. * Import from 'decentraland-ui2' instead: * * ```tsx * import { Button } from 'decentraland-ui2'; * ``` * * See migration guide: https://docs.decentraland.org/contributor-guides/web-ui-standards/migration */ export function Button(props: ButtonProps) { // ... existing implementation } ``` ### Step 5: Gradual Adoption Don't force immediate migration. Allow gradual adoption: 1. **Publish** UI2 component 2. **Document** migration path 3. **Update** new projects to use UI2 4. **Migrate** existing projects opportunistically 5. **Plan** eventual UI1 removal (with notice) --- ## Migration Examples ### Example 1: Simple Component Migrating a basic `Card` component: #### UI1 Version ```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}
); } ``` #### UI2 Version ```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} ); } ``` ### Example 2: Component with Variants Migrating a `Button` with variants: #### UI1 Version ```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