Descripción del proceso

Nuestro proceso de desarrollo asegura 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 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 fase evitan cambios costosos más adelante.

Entregables requeridos

Objetivo y alcance

DEBE definir:

• Objetivo del 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 tiempo o de recursos

Ejemplo:

Objetivo: Permitir a los usuarios explorar y filtrar sus parcelas de LAND de forma eficiente
Objetivo: Propietarios de LAND con 10+ parcelas
Éxito: El 80% de los usuarios puede encontrar una parcela específica en menos de 10 segundos
Restricciones: Debe funcionar en móvil; no se permiten cambios en el backend

Flujos de interacción

DEBE mapear los recorridos de usuario de extremo a extremo:

• Todos los casos de uso - Rutas de usuario primarias y secundarias

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

• Rutas alternativas - Diferentes formas de lograr los objetivos

• Ayudas visuales - Wireframes o diagramas de flujo cuando sean útiles

Ejemplo:

Flujo primario:
1. El usuario hace clic en "My Land"
2. El sistema carga parcelas
3. El usuario aplica un filtro
4. Los resultados se actualizan inmediatamente

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

Estados de la UI

DEBERÍA especificar todos los estados de los componentes:

• Inactivo - Estado por defecto

• Cargando - Recuperando o procesando datos

• Error - Operaciones fallidas

• Vacío - No hay datos disponibles

• Éxito - Operaciones exitosas

• Deshabilitado - Acciones no disponibles

DEBERÍA esbozar la recuperación de errores:

• ¿Qué ocurre cuando ocurre un error?

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

• ¿Qué información necesitan los usuarios?

Seguimiento de Analytics

DEBE ponerse de acuerdo sobre el seguimiento en esta etapa:

• Eventos - Qué acciones rastrear

• Propiedades - Qué datos capturar

• Propiedades de 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 Tab 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 dropdown de filtros
- Teclas de flecha: Navegar las opciones de filtro

Lector de pantalla:
- "Filter by: Owner address. Type to search or select from list"
- "3 parcels found matching your filters"

Legibilidad de accesibilidad

DEBERÍA asegurar:

• Contraste de color - Ratios mínimos WCAG AA

  • Texto normal: 4.5:1

  • Texto grande (18pt+): 3:1

  • Componentes de UI: 3:1

• Tamaño del texto - Legible en tamaños por defecto

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

Elementos interactivos de la UI

DEBERÍA definir estados para todos los elementos interactivos:

• Habilitado - Estado interactivo por defecto

• Deshabilitado - Estado no interactivo

• Hover - Mouse over (escritorio)

• Presionado/Activo - Durante la interacción

• Foco - Estado de foco por teclado

DEBERÍA especificar retroalimentación al usuario:

• Cambios visuales en la interacción

• Indicadores de carga

• Mensajes de éxito/error

• Retroalimentación háptica (móvil)

---

Diseño en Figma

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

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

Estándares requeridos

Usar la biblioteca de Figma de Decentraland

DEBE usar componentes MUI cuando exista un equivalente:

• Consultar primero la librería de componentes MUI

• Usar variantes y estilos de Decentraland

• No crear versiones personalizadas de componentes existentes

Si no existe un elemento de UI requerido:

1. Verificar si puede componerse a partir de componentes existentes

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

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

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

Colores

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

import { dclColors } from 'decentraland-ui2';

// Figma "Rarity / Unique" → Código
dclColors.rarity.unique

// Figma "Primary / Main" → Código
theme.palette.primary.main

// Figma "Text / Secondary" → Código
theme.palette.text.secondary

Fuente de la verdad: colors.ts

Tipografía

DEBE usar variantes definidas:

Variantes disponibles:

• h1, h2, h3, h4, h5, h6 - Encabezados

• subtitle1, subtitle2 - Subencabezados

• body1, body2 - Texto principal

• button - Texto de botones

• caption - Subtítulos

• overline - Texto overline

Referencias:

• Fuente tipográfica

• MUI Typography

• Material Design Type System

Ejemplo de mapeo:

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

Breakpoints

DEBE diseñar para estos puntos de quiebre:

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

Source: index.ts

Mejores prácticas:

• Diseñar mobile-first (comenzar en xs)

• Mostrar puntos de quiebre clave en marcos de Figma

• Documentar el comportamiento responsive

• Probar en los bordes de la ventana (767px, 768px, etc.)

Radio de borde y paletas

DEBE usar valores definidos por el tema:

• No introducir nuevos valores de radio de borde

• No crear nuevos roles de paleta

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

Valores del tema:

theme.shape.borderRadius // Radio por defecto
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 divisores

Esquemas de color

Si la pantalla soporta múltiples esquemas de color:

DEBE proporcionar:

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

• Vista previa en modo claro

• Vista previa en modo oscuro

• Documentación sobre el cambio de esquemas en Storybook

Ejemplo:

Esquemas soportados: Light, Dark
Predeterminado: Preferencia del sistema
Alternar: Menú de Settings → Appearance
Storybook: Usar el control "Theme" en la barra de herramientas

Selección de componentes

DEBERÍA reutilizar componentes preparados:

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

2. Consultar UI2 - ¿Existe una variante de Decentraland?

3. Componer si es posible - ¿Puedes combinar componentes existentes?

4. Personalizar como último recurso - Seguir Componentes personalizados process

---

Implementación dApp

Los desarrolladores implementan los diseños usando componentes UI2 y siguiendo nuestros Estándares de Styling & Theming .

Lista de verificación de implementación

• Comenzar con el componente UI2 si está disponible

• Usar componente MUI con el tema de Decentraland si no hay equivalente en UI2

• Seguir Estándares de Styling & Theming estándares

• Implementar todos los estados de la especificación UX

• Agregar seguimiento de analytics según lo especificado

• Probar en todos los puntos de quiebre

• Verificar navegación por teclado

• Comprobar contraste de color

• Probar con lector de pantalla

• Manejar estados de carga y error

• Agregar a Storybook si es un componente reutilizable

Flujo de implementación del componente

1. Buscar componente en UI2
   ↓
2. ¿Encontrado? → Usarlo
   ↓
3. ¿No encontrado? → Revisar MUI
   ↓
4. ¿Encontrado en MUI? → Usar con el tema de Decentraland
   ↓
5. ¿Necesita personalización? → Ver la guía de Componentes personalizados
   ↓
6. Implementar siguiendo los estándares de Styling
   ↓
7. Agregar a Storybook (si es reutilizable)

Puertas de calidad

Antes de marcar la implementación como completa:

1. Coincidencia visual - Coincide con Figma pixel-perfect en puntos de quiebre clave

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

3. Estados implementados - Todos los estados especificados por UX funcionan

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 puntos de quiebre

7. Rendimiento - Sin re-renderizados innecesarios

8. Tests - Las pruebas de componentes pasan

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

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

---

Mejores prácticas para la entrega

De UX a Diseño

• Documento de requisitos claro

• Flujos de usuario con anotaciones

• Diagramas de estados 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 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 diseñador y desarrollador

• Comentarios tempranos sobre restricciones técnicas

• Revisiones iterativas en hitos clave

• Revisión final antes de mergear

---

Siguientes pasos

• Aprende sobre Componentes personalizados para crear nuevos componentes

• Revisar Estándares de Styling & Theming para detalles de implementación

• Ver Guía de migración si se trabaja con componentes UI1