Resumen del proceso

Nuestro proceso de desarrollo garantiza que lo que se diseña es lo que se construye. El trabajo fluye a través de tres etapas distintas con entregables y responsabilidades claras en cada paso.

Etapas del flujo de trabajo

Cada etapa se basa en la anterior, asegurando la alineación desde el concepto hasta el código.

---

Descubrimiento UX

La etapa de UX establece la base para todo lo que sigue. Requisitos claros en esta etapa evitan cambios costosos más adelante.

Entregables requeridos

Objetivo y alcance

DEBE definir:

• Objetivo de negocio - ¿Qué problema estamos resolviendo?

• Usuario objetivo - ¿Para quién es esto?

• Métricas de éxito - ¿Cómo medimos el éxito?

• Restricciones - Limitaciones técnicas, de cronograma o de recursos

Ejemplo:

Objetivo: Permitir que los usuarios exploren y filtren sus parcelas de LAND de forma eficiente
Público objetivo: Propietarios de LAND con más de 10 parcelas
Éxito: El 80% de los usuarios puede encontrar una parcela específica en menos de 10 segundos
Restricciones: Debe funcionar en mobile; no se permiten cambios en el backend

Flujos de interacción

DEBE mapear recorridos de usuario de extremo a extremo:

• Todos los casos de uso - Rutas principales y secundarias del usuario

• Casos límite - Estados vacíos, usuarios primerizos, errores

• Rutas alternativas - Diferentes maneras de lograr objetivos

• Ayudas visuales - Wireframes o diagramas de flujo cuando sea útil

Ejemplo:

Flujo principal:
1. El usuario hace clic en "My Land"
2. El sistema carga las parcelas
3. El usuario aplica el filtro
4. Los resultados se actualizan de inmediato

Casos límite:
- El usuario no tiene parcelas → Mostrar un estado vacío con CTA
- El filtro no devuelve resultados → Mostrar el mensaje "sin resultados"
- La carga tarda >2 s → Mostrar skeleton loaders

Estados de UI

DEBERÍA especificar todos los estados del componente:

• Inactivo - Estado predeterminado

• Cargando - Obtención o procesamiento de datos

• Error - Operaciones fallidas

• Vacío - No hay datos disponibles

• Éxito - Operaciones exitosas

• Deshabilitado - Acciones no disponibles

DEBERÍA describir la recuperación de errores:

• ¿Qué sucede cuando ocurre un error?

• ¿Cómo pueden los usuarios reintentar o resolverlo?

• ¿Qué información necesitan los usuarios?

Seguimiento de analytics

DEBE acordar el seguimiento en esta etapa:

• Eventos - Qué acciones rastrear

• Propiedades - Qué datos capturar

• Propiedades del usuario - Atributos relevantes del usuario

• Objetivos de conversión - Métricas clave de éxito

Ejemplo:

Eventos:
- parcel_filter_applied { filter_type, filter_value }
- parcel_selected { parcel_id, source }
- parcel_transfer_initiated { parcel_id }

Propiedades:
- user_parcel_count
- filter_used (boolean)
- time_to_result (ms)

Entregables recomendados

Intención de accesibilidad

DEBERÍA describir:

• Flujos de teclado - Orden de tabulación y atajos

• Orden de foco - Progresión lógica del foco

• Etiquetas para lectores de pantalla - Etiquetas y descripciones ARIA

• Contenido alternativo - Texto para imágenes, iconos, gráficos

Ejemplo:

Navegación por teclado:
- Tab: Navegar por los filtros
- Enter: Aplicar el filtro seleccionado
- Escape: Cerrar el desplegable de filtros
- Teclas de flecha: Navegar por las opciones del filtro

Lector de pantalla:
- "Filter by: dirección del propietario. Escribe para buscar o selecciona de la lista"
- "Se encontraron 3 parcelas que coinciden con tus filtros"

Legibilidad de accesibilidad

DEBERÍA asegurar:

• Contraste de color - Ratios mínimos WCAG AA

  • Texto normal: 4.5:1

  • Texto grande (18 pt o más): 3:1

  • Componentes de UI: 3:1

• Tamaño del texto - Legible en tamaños predeterminados

• Objetivos interactivos - Objetivos táctiles mínimos de 44×44 px

Elementos interactivos de UI

DEBERÍA definir estados para todos los elementos interactivos:

• Habilitado - Estado interactivo predeterminado

• Deshabilitado - Estado no interactivo

• Hover - Al pasar el mouse (desktop)

• Presionado/Activo - Durante la interacción

• Foco - Estado de foco del teclado

DEBERÍA especificar retroalimentación del usuario:

• Cambios visuales en la interacción

• Indicadores de carga

• Mensajes de éxito/error

• Retroalimentación háptica (mobile)

---

Diseño en Figma

Los diseñadores DEBEN partir de nuestra biblioteca de Figma, que replica los componentes de Material UI y usa el tema de Decentraland definido en UI2.

No se DEBEN usar colores, tamaños o estilos especiales. Puede haber excepciones, pero DEBEN justificarse en la especificación y aprobarse durante la revisión.

Estándares requeridos

Usa la biblioteca de Figma de Decentraland

DEBE usa componentes de MUI cuando exista un equivalente:

• Primero revisa la biblioteca de componentes de MUI

• Usa variantes y estilos de Decentraland

• No crees versiones personalizadas de componentes existentes

Si no existe un elemento de UI requerido:

1. Comprueba si puede componerse a partir de componentes existentes

2. Si no, propone un componente personalizado (ver Componentes personalizados)

3. Documenta la justificación en la especificación

4. Obtén aprobación durante la revisión de diseño

Colores

DEBE asocia los estilos de color de Figma con los nombres del tema UI2:

import { dclColors } from 'decentraland-ui2';

// Figma "Rareza / Único" → Código
dclColors.rarity.unique

// Figma "Primario / Principal" → Código
theme.palette.primary.main

// Figma "Texto / Secundario" → Código
theme.palette.text.secondary

Fuente de verdad: colors.ts

Tipografía

DEBE usa las variantes definidas:

Variantes disponibles:

• h1, h2, h3, h4, h5, h6 - Títulos

• subtitle1, subtitle2 - Subtítulos

• body1, body2 - Texto del cuerpo

• button - Texto del botón

• caption - Leyendas

• overline - Texto superior

Referencias:

• Fuente de tipografía

• Typography de MUI

• Sistema tipográfico de Material Design

Ejemplo de mapeo:

Figma "H1" → <Typography variant="h1">
Figma "Body 1" → <Typography variant="body1">
Figma "Caption" → <Typography variant="caption">

Puntos de corte

DEBE diseña para estos breakpoints:

Nombre	Ancho	Dispositivo típico
xs	768 px	Móvil
sm	991 px	Tablet
md	1024 px	Escritorio pequeño
lg	1280 px	Escritorio
xl	1500 px	Escritorio grande

Source: index.ts

Buenas prácticas:

• Diseña mobile-first (comienza en xs)

• Muestra los breakpoints clave en los frames de Figma

• Documenta el comportamiento responsive

• Prueba en los bordes del viewport (767 px, 768 px, etc.)

Border Radius y paletas

DEBE usa valores definidos por el tema:

• No introduzcas nuevos valores de border radius

• No crees nuevos roles de paleta

• Las excepciones requieren justificación en la especificación y aprobación

Valores del tema:

theme.shape.borderRadius // Radio predeterminado
theme.palette.primary    // Colores primarios
theme.palette.secondary  // Colores secundarios
theme.palette.error      // Colores de error
theme.palette.text       // Colores de texto
theme.palette.background // Colores de fondo
theme.palette.divider    // Colores de separador

Esquemas de color

Si la pantalla admite múltiples esquemas de color:

DEBE proporciona:

• Qué esquema se aplica (ver colorSchemes.ts)

• Vista previa del modo claro

• Vista previa del modo oscuro

• Documentación sobre el cambio de esquemas en Storybook

Ejemplo:

Esquemas compatibles: Claro, Oscuro
Predeterminado: Preferencia del sistema
Alternar: menú de configuración → Apariencia
Storybook: usa el control "Theme" en la barra de herramientas

Selección de componentes

DEBERÍA reutiliza componentes preparados:

1. Revisa MUI primero - ¿MUI tiene este componente?

2. Revisa UI2 - ¿Hay una variante de Decentraland?

3. Compón si es posible - ¿Puedes combinar componentes existentes?

4. Personalizado como último recurso - Sigue Componentes personalizados procesar

---

Implementación dApp

Los desarrolladores implementan los diseños usando componentes UI2 y siguiendo nuestras estilo y tematización estándares.

Lista de verificación de implementación

• Comienza con un componente UI2 si está disponible

• Usa un componente de MUI con el tema de Decentraland si no existe un equivalente en UI2

• Sigue estilo y tematización estándares

• Implementa todos los estados de la especificación de UX

• Añade el seguimiento de analytics según lo especificado

• Prueba en todos los breakpoints

• Verifica la navegación por teclado

• Comprueba el contraste de color

• Prueba con lector de pantalla

• Gestiona los estados de carga y error

• Añádelo a Storybook si es un componente reutilizable

Flujo de implementación de componentes

1. Comprueba si el componente está en UI2
   ↓
2. ¿Lo encontraste? → Úsalo
   ↓
3. ¿No lo encontraste? → Revisa MUI
   ↓
4. ¿Lo encontraste en MUI? → Úsalo con el tema de Decentraland
   ↓
5. ¿Necesitas personalización? → Consulta la guía de Custom Components
   ↓
6. Implementa siguiendo los estándares de Styling
   ↓
7. Añádelo a Storybook (si es reutilizable)

Puertas de calidad

Antes de marcar la implementación como completa:

1. Coincidencia visual - Coincide píxel a píxel con Figma en los breakpoints clave

2. Cumplimiento del tema - Todos los valores provienen del tema UI2

3. Estados implementados - Funcionan todos los estados especificados en UX

4. Accesibilidad - Navegación por teclado, estados de foco, etiquetas ARIA

5. Analytics - Los eventos se disparan según lo especificado

6. Responsive - Funciona en todos los breakpoints

7. Rendimiento - Sin re-renderizados innecesarios

8. Pruebas - Las pruebas del componente pasan

9. Storybook - Stories añadidas (si es reutilizable)

10. Revisión de código - Aprobado por los mantenedores

---

Mejores prácticas de handoff

De UX a diseño

• Documento de requisitos claro

• Flujos de usuario con anotaciones

• Diagramas de estado para interacciones complejas

• Especificaciones de eventos de analytics

De diseño a desarrollo

• Archivo de Figma con el modo dev habilitado

• Especificaciones de componentes

• Notas sobre el comportamiento responsive

• Mapeo de tokens de color y tipografía

• Anotaciones de accesibilidad

• Enlace a los requisitos de UX

Durante la implementación

• Revisiones periódicas entre el diseñador y el desarrollador

• Retroalimentación temprana sobre restricciones técnicas

• Revisiones iterativas en hitos clave

• Revisión final antes de hacer merge

---

Próximos pasos

• Aprende sobre Componentes personalizados para crear nuevos componentes

• Revisar estilo y tematización para detalles de implementación

• Ver Guía de migración si estás trabajando con componentes UI1