> 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/process-overview.md). # 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 ```mermaid flowchart LR UX[Descubrimiento UX] --> Figma[Diseño en Figma] --> dApp[Implementación dApp] estilo UX fill:#e3f2fd estilo Figma fill:#fff3e0 estilo dApp fill:#e8f5e9 ``` 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](https://www.figma.com/design/tsyaDSedcsVZ8iM9N0McT2/DCL-UI2), que replica los componentes de Material UI y usa el tema de Decentraland definido en UI2. {% hint style="warning" %} 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. {% endhint %} ### 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](/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/custom-components.md)) 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: ```tsx 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](https://github.com/decentraland/ui2/blob/master/src/theme/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](https://github.com/decentraland/ui2/blob/master/src/theme/typography.ts) * [Typography de MUI](https://mui.com/material-ui/react-typography/) * [Sistema tipográfico de Material Design](https://m2.material.io/design/typography/the-type-system.html#type-scale) **Ejemplo de mapeo**: ``` Figma "H1" → Figma "Body 1" → Figma "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](https://github.com/decentraland/ui2/blob/master/src/theme/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**: ```tsx 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](https://github.com/decentraland/ui2/blob/master/src/theme/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](/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/custom-components.md) procesar *** ## Implementación dApp Los desarrolladores implementan los diseños usando componentes UI2 y siguiendo nuestras [estilo y tematización](/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/styling-and-theming.md) 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](/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/styling-and-theming.md) 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](/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/custom-components.md) para crear nuevos componentes * Revisar [estilo y tematización](/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/styling-and-theming.md) para detalles de implementación * Ver [Guía de migración](/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/migration.md) si estás trabajando con componentes UI1 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.decentraland.org/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/process-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.