> 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-pt/guias-do-contribuidor/padroes-de-web-ui/process-overview.md). # Visão Geral do Processo Nosso processo de desenvolvimento garante que o que é projetado é o que é construído. O trabalho passa por três estágios distintos com entregáveis claros e responsabilidades em cada etapa. ## Estágios do Fluxo de Trabalho {% @mermaid/diagram content="flowchart LR UX\[UX Discovery] --> Figma\[Figma Design] --> dApp\[dApp Implementation] ``` style UX fill:#e3f2fd style Figma fill:#fff3e0 style dApp fill:#e8f5e9" %} ``` Cada estágio se baseia no anterior, garantindo alinhamento do conceito ao código. *** ## Descoberta de UX O estágio de UX estabelece a base para tudo o que segue. Requisitos claros neste estágio evitam mudanças custosas posteriormente. ### Entregáveis Obrigatórios #### Objetivo e Escopo **DEVE** definir: * **Objetivo de negócio** - Qual problema estamos resolvendo? * **Usuário alvo** - Para quem é isto? * **Métricas de sucesso** - Como medimos o sucesso? * **Restrições** - Limitações técnicas, de cronograma ou de recursos **Exemplo**: ``` Objetivo: Permitir que os usuários naveguem e filtrem seus lotes de LAND de forma eficiente Alvo: Proprietários de LAND com 10+ parcelas Sucesso: 80% dos usuários conseguem encontrar um parcel específico em menos de 10 segundos Restrições: Deve funcionar em mobile; sem alterações de backend permitidas ``` #### Fluxos de Interação **DEVE** mapear jornadas de usuário de ponta a ponta: * **Todos os casos de uso** - Caminhos de usuário primários e secundários * **Casos limites** - Estados vazios, usuários de primeira vez, erros * **Caminhos alternativos** - Diferentes maneiras de alcançar objetivos * **Auxílios visuais** - Wireframes ou diagramas de fluxo quando úteis **Exemplo**: ``` Fluxo Primário: 1. Usuário clica em "My Land" 2. Sistema carrega parcels 3. Usuário aplica filtro 4. Resultados atualizam imediatamente Casos Limite: - Usuário não tem parcels → Mostrar estado vazio com CTA - Filtro não retorna resultados → Mostrar mensagem de "sem resultados" - Carregamento leva >2s → Mostrar skeleton loaders ``` #### Estados de UI **DEVE** especificar todos os estados dos componentes: * **Ocioso** - Estado padrão * **Carregando** - Buscando ou processando dados * **Erro** - Operações falhadas * **Vazio** - Nenhum dado disponível * **Sucesso** - Operações bem-sucedidas * **Desabilitado** - Ações indisponíveis **DEVE** esboçar recuperação de erro: * O que acontece quando um erro ocorre? * Como os usuários podem tentar novamente ou resolver? * Que informações os usuários precisam? #### Rastreamento de Analytics **DEVE** concordar sobre o rastreamento neste estágio: * **Eventos** - Quais ações rastrear * **Propriedades** - Quais dados capturar * **Propriedades do usuário** - Atributos relevantes do usuário * **Metas de conversão** - Métricas-chave de sucesso **Exemplo**: ``` Eventos: - parcel_filter_applied { filter_type, filter_value } - parcel_selected { parcel_id, source } - parcel_transfer_initiated { parcel_id } Propriedades: - user_parcel_count - filter_used (boolean) - time_to_result (ms) ``` ### Entregáveis Recomendados #### Intenção de Acessibilidade **DEVE** descrever: * **Fluxos de teclado** - Ordem de Tab e atalhos * **Ordem de foco** - Progressão lógica do foco * **Rótulos para screen reader** - Rótulos e descrições ARIA * **Conteúdo alternativo** - Texto para imagens, ícones, gráficos **Exemplo**: ``` Navegação por teclado: - Tab: Navegar pelos filtros - Enter: Aplicar filtro selecionado - Escape: Fechar dropdown de filtro - Teclas de seta: Navegar opções de filtro Leitor de tela: - "Filter by: Owner address. Type to search or select from list" - "3 parcels found matching your filters" ``` #### Legibilidade de Acessibilidade **DEVE** garantir: * **Contraste de cor** - Razões mínimas WCAG AA * Texto normal: 4.5:1 * Texto grande (18pt+): 3:1 * Componentes de UI: 3:1 * **Tamanho do texto** - Legível em tamanhos padrão * **Alvos interativos** - Alvos de toque mínimos de 44×44px #### Elementos Interativos de UI **DEVE** definir estados para todos os elementos interativos: * **Habilitado** - Estado interativo padrão * **Desabilitado** - Estado não interativo * **Hover** - Mouse over (desktop) * **Pressionado/Ativo** - Durante a interação * **Foco** - Estado de foco por teclado **DEVE** especificar feedback ao usuário: * Mudanças visuais na interação * Indicadores de carregamento * Mensagens de sucesso/erro * Feedback háptico (mobile) *** ## Design no Figma Designers DEVEM começar a partir da nossa [Figma library](https://www.figma.com/design/tsyaDSedcsVZ8iM9N0McT2/DCL-UI2), que espelha componentes do Material UI e usa o tema Decentraland definido em UI2. {% hint style="warning" %} Cores, tamanhos ou estilos especiais NÃO DEVEM ser usados. Exceções podem existir, mas DEVEM ser justificadas na especificação e aprovadas durante a revisão. {% endhint %} ### Padrões Obrigatórios #### Usar Decentraland Figma Library **DEVE** usar componentes MUI quando existir um equivalente: * Verificar a biblioteca de componentes MUI primeiro * Usar variantes e estilos Decentraland * Não criar versões customizadas de componentes existentes **Se um elemento de UI necessário não existir:** 1. Verificar se pode ser composto a partir de componentes existentes 2. Se não, propor um componente customizado (ver [Componentes Personalizados](/contributor/contributor-pt/guias-do-contribuidor/padroes-de-web-ui/custom-components.md)) 3. Documentar o racional na especificação 4. Obter aprovação durante a revisão de design #### Cores **DEVE** corresponder estilos de cor do Figma aos nomes do tema UI2: ```tsx import { dclColors } from 'decentraland-ui2'; // Figma "Rarity / Unique" → Code dclColors.rarity.unique // Figma "Primary / Main" → Code theme.palette.primary.main // Figma "Text / Secondary" → Code theme.palette.text.secondary ``` **Fonte da verdade**: [colors.ts](https://github.com/decentraland/ui2/blob/master/src/theme/colors.ts) #### Tipografia **DEVE** usar variantes definidas: Variantes disponíveis: * `h1`, `h2`, `h3`, `h4`, `h5`, `h6` - Títulos * `subtitle1`, `subtitle2` - Subtítulos * `body1`, `body2` - Texto do corpo * `button` - Texto de botão * `caption` - Legendas * `overline` - Texto overline **Referências**: * [Fonte de tipografia](https://github.com/decentraland/ui2/blob/master/src/theme/typography.ts) * [MUI Typography](https://mui.com/material-ui/react-typography/) * [Material Design Type System](https://m2.material.io/design/typography/the-type-system.html#type-scale) **Exemplo de mapeamento**: ``` Figma "H1" → Figma "Body 1" → Figma "Caption" → ``` #### Breakpoints **DEVE** projetar para estes breakpoints: | Name | Largura | Dispositivo típico | | ---- | ------- | ------------------ | | `xs` | 768px | Mobile | | `sm` | 991px | Tablet | | `md` | 1024px | Small Desktop | | `lg` | 1280px | Desktop | | `xl` | 1500px | Large Desktop | **Source**: [index.ts](https://github.com/decentraland/ui2/blob/master/src/theme/index.ts) **Boas práticas**: * Design mobile-first (começar em `xs`) * Mostrar breakpoints chave em frames do Figma * Documentar comportamento responsivo * Testar nas bordas da viewport (767px, 768px, etc.) #### Raio de borda e Paletas **DEVE** usar valores definidos pelo tema: * Não introduzir novos valores de border radius * Não criar novos papéis de paleta * Exceções requerem justificativa na especificação e aprovação **Valores do tema**: ```tsx theme.shape.borderRadius // Raio padrão theme.palette.primary // Cores primárias theme.palette.secondary // Cores secundárias theme.palette.error // Cores de erro theme.palette.text // Cores de texto theme.palette.background // Cores de fundo theme.palette.divider // Cores de divisor ``` #### Esquemas de Cor **Se a tela suportar múltiplos esquemas de cor:** **DEVE** fornecer: * Qual esquema se aplica (ver [colorSchemes.ts](https://github.com/decentraland/ui2/blob/master/src/theme/colorSchemes.ts)) * Pré-visualização em modo claro * Pré-visualização em modo escuro * Documentação sobre alternância de esquemas no Storybook **Exemplo**: ``` Esquemas suportados: Light, Dark Padrão: Preferência do sistema Alternar: Menu de configurações → Appearance Storybook: Usar controle "Theme" na barra de ferramentas ``` ### Seleção de Componentes **DEVE** reutilizar componentes preparados: 1. **Verificar MUI primeiro** - O MUI tem este componente? 2. **Verificar UI2** - Existe uma variante Decentraland? 3. **Compor se possível** - É possível combinar componentes existentes? 4. **Customizar como último recurso** - Seguir [Componentes Personalizados](/contributor/contributor-pt/guias-do-contribuidor/padroes-de-web-ui/custom-components.md) process *** ## Implementação de dApp Desenvolvedores implementam designs usando componentes UI2 e seguindo nosso [Styling & Theming](/contributor/contributor-pt/guias-do-contribuidor/padroes-de-web-ui/styling-and-theming.md) padrões. ### Checklist de Implementação * [ ] Começar com componente UI2 se disponível * [ ] Usar componente MUI com tema Decentraland se não houver equivalente UI2 * [ ] Seguir [Styling & Theming](/contributor/contributor-pt/guias-do-contribuidor/padroes-de-web-ui/styling-and-theming.md) padrões * [ ] Implementar todos os estados da especificação de UX * [ ] Adicionar rastreamento de analytics conforme especificado * [ ] Testar em todos os breakpoints * [ ] Verificar navegação por teclado * [ ] Checar contraste de cor * [ ] Testar com leitor de tela * [ ] Tratar estados de carregamento e erro * [ ] Adicionar ao Storybook se for um componente reutilizável ### Fluxo de Implementação de Componentes ``` 1. Verificar UI2 para o componente ↓ 2. Encontrado? → Usar ↓ 3. Não encontrado? → Verificar MUI ↓ 4. Encontrado no MUI? → Usar com tema Decentraland ↓ 5. Precisa de customização? → Ver guia de Componentes Customizados ↓ 6. Implementar seguindo padrões de Styling ↓ 7. Adicionar ao Storybook (se reutilizável) ``` ### Portões de Qualidade Antes de marcar a implementação como completa: 1. **Correspondência visual** - Coincide com Figma pixel-perfect nos breakpoints chave 2. **Conformidade com o tema** - Todos os valores do tema UI2 3. **Estados implementados** - Todos os estados especificados em UX funcionam 4. **Acessibilidade** - Navegação por teclado, estados de foco, rótulos ARIA 5. **Analytics** - Eventos disparam conforme especificado 6. **Responsivo** - Funciona em todos os breakpoints 7. **Desempenho** - Sem re-renders desnecessários 8. **Testes** - Testes de componente passam 9. **Storybook** - Stories adicionadas (se reutilizável) 10. **Revisão de código** - Aprovado pelos mantenedores *** ## Melhores Práticas de Handoff ### De UX para Design * Documento de requisitos claro * Fluxos de usuário com anotações * Diagramas de estado para interações complexas * Especificações de eventos de analytics ### De Design para Desenvolvimento * Arquivo Figma com modo dev habilitado * Especificações de componentes * Notas de comportamento responsivo * Mapeamento de tokens de cor e tipografia * Anotações de acessibilidade * Link para requisitos de UX ### Durante a Implementação * Check-ins regulares entre designer e desenvolvedor * Feedback antecipado sobre restrições técnicas * Revisões iterativas em marcos chave * Revisão final antes do merge *** ## Próximos Passos * Aprenda sobre [Componentes Personalizados](/contributor/contributor-pt/guias-do-contribuidor/padroes-de-web-ui/custom-components.md) para criar novos componentes * Rever [Styling & Theming](/contributor/contributor-pt/guias-do-contribuidor/padroes-de-web-ui/styling-and-theming.md) para detalhes de implementação * Veja [Guia de Migração](/contributor/contributor-pt/guias-do-contribuidor/padroes-de-web-ui/migration.md) se estiver trabalhando com 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/contributor/contributor-pt/guias-do-contribuidor/padroes-de-web-ui/process-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.