> 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-para-colaboradores/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 flui por três etapas distintas, com entregáveis e responsabilidades claros em cada passo. ## Etapas do fluxo de trabalho ```mermaid flowchart LR UX[Descoberta de UX] --> Figma[Design no Figma] --> dApp[Implementação da dApp] style UX fill:#e3f2fd style Figma fill:#fff3e0 style dApp fill:#e8f5e9 ``` Cada etapa se baseia na anterior, garantindo alinhamento do conceito ao código. *** ## Descoberta de UX A etapa de UX estabelece a base para tudo o que vem a seguir. Requisitos claros nesta etapa evitam mudanças custosas depois. ### Entregáveis obrigatórios #### Objetivo e Escopo **DEVE** defina: * **Objetivo de negócio** - Qual problema estamos resolvendo? * **Usuário-alvo** - Para quem é isso? * **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 parcels de LAND de forma eficiente Alvo: Proprietários de LAND com 10+ parcels Sucesso: 80% dos usuários conseguem encontrar um parcel específico em menos de 10 segundos Restrições: Deve funcionar em mobile; não são permitidas alterações no backend ``` #### Fluxos de interação **DEVE** mapear jornadas do usuário de ponta a ponta: * **Todos os casos de uso** - Caminhos primários e secundários do usuário * **Casos-limite** - Estados vazios, usuários de primeira vez, erros * **Caminhos alternativos** - Diferentes formas de alcançar os objetivos * **Recursos visuais** - Wireframes ou diagramas de fluxo quando útil **Exemplo**: ``` Fluxo principal: 1. O usuário clica em "Meu LAND" 2. O sistema carrega os parcels 3. O usuário aplica o filtro 4. Os resultados são atualizados imediatamente Casos-limite: - O usuário não tem parcels → Exibir estado vazio com CTA - O filtro não retorna resultados → Exibir mensagem "sem resultados" - O carregamento leva >2s → Exibir skeleton loaders ``` #### Estados da UI **DEVE** especificar todos os estados dos componentes: * **Inativo** - Estado padrão * **Carregando** - Busca ou processamento de dados * **Erro** - Operações com falha * **Vazio** - Sem dados disponíveis * **Sucesso** - Operações bem-sucedidas * **Desativado** - Ações indisponíveis **DEVE** descrever a recuperação de erros: * O que acontece quando ocorre um erro? * Como os usuários podem tentar novamente ou resolvê-lo? * Que informações os usuários precisam? #### Rastreamento de Analytics **DEVE** alinhar o rastreamento nesta etapa: * **Eventos** - Quais ações rastrear * **Propriedades** - Quais dados capturar * **Propriedades do usuário** - Atributos relevantes do usuário * **Objetivos de conversão** - Principais métricas 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** descreva: * **Fluxos de teclado** - Ordem de tabulação e atalhos * **Ordem de foco** - Progressão lógica do foco * **Rótulos para leitor de tela** - 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 o filtro selecionado - Escape: Fechar o dropdown de filtros - Teclas de seta: Navegar pelas opções de filtro Leitor de tela: - "Filtrar por: Endereço do proprietário. Digite para pesquisar ou selecione na lista" - "3 parcels encontrados que correspondem aos seus filtros" ``` #### Legibilidade de Acessibilidade **DEVE** garanta: * **Contraste de cores** - Relações mínimas WCAG AA * Texto normal: 4.5:1 * Texto grande (18pt+): 3:1 * Componentes da UI: 3:1 * **Dimensionamento do texto** - Legível nos tamanhos padrão * **Alvos interativos** - Alvos de toque mínimos de 44×44px #### Elementos interativos da UI **DEVE** defina estados para todos os elementos interativos: * **Ativado** - Estado interativo padrão * **Desativado** - Estado não interativo * **Hover** - Passar o mouse (desktop) * **Pressed/Active** - Durante a interação * **Foco** - Estado de foco do teclado **DEVE** especificar o feedback do usuário: * Mudanças visuais na interação * Indicadores de carregamento * Mensagens de sucesso/erro * Feedback háptico (mobile) *** ## Design no Figma Os designers DEVEM começar a partir da nossa [biblioteca Figma](https://www.figma.com/design/tsyaDSedcsVZ8iM9N0McT2/DCL-UI2)que espelha os componentes Material UI e usa o tema Decentraland definido no UI2. {% hint style="warning" %} Cores, tamanhos ou estilos especiais NÃO DEVEM ser usados. Exceções podem existir, mas DEVEM ser justificadas na spec e aprovadas durante a revisão. {% endhint %} ### Padrões obrigatórios #### Use a biblioteca Figma da Decentraland **DEVE** use componentes MUI quando existir um equivalente: * Verifique primeiro a biblioteca de componentes MUI * Use variantes e estilos da Decentraland * Não crie versões personalizadas de componentes existentes **Se um elemento de UI necessário não existir:** 1. Verifique se ele pode ser composto a partir de componentes existentes 2. Se não, proponha um componente personalizado (veja [Componentes personalizados](/contributor/contributor-pt/guias-para-colaboradores/padroes-de-web-ui/custom-components.md)) 3. Documente a justificativa na spec 4. Obtenha aprovação durante a revisão de design #### Cores **DEVE** corresponda os estilos de cor do Figma aos nomes de tema do 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** use variantes definidas: Variantes disponíveis: * `h1`, `h2`, `h3`, `h4`, `h5`, `h6` - Títulos * `subtitle1`, `subtitle2` - Subtítulos * `body1`, `body2` - Texto do corpo * `button` - Texto do botão * `caption` - Legendas * `overline` - Texto overline **Referências**: * [Fonte da tipografia](https://github.com/decentraland/ui2/blob/master/src/theme/typography.ts) * [MUI Typography](https://mui.com/material-ui/react-typography/) * [Sistema de tipografia do Material Design](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: | Nome | Largura | Dispositivo típico | | ---- | ------- | ------------------ | | `xs` | 768px | Mobile | | `sm` | 991px | Tablet | | `md` | 1024px | Desktop pequeno | | `lg` | 1280px | Desktop | | `xl` | 1500px | Desktop grande | **Source**: [index.ts](https://github.com/decentraland/ui2/blob/master/src/theme/index.ts) **Boas práticas**: * Projete mobile-first (comece em `xs`) * Mostre os breakpoints principais nos frames do Figma * Documente o comportamento responsivo * Teste nas bordas da viewport (767px, 768px, etc.) #### Border Radius e Paletas **DEVE** use valores definidos pelo tema: * Não introduza novos valores de border radius * Não crie novos papéis de palette * Exceções exigem justificativa na spec 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 do texto theme.palette.background // Cores de fundo theme.palette.divider // Cores do divisor ``` #### Esquemas de cores **Se a tela suportar vários esquemas de cores:** **DEVE** forneça: * Qual esquema se aplica (veja [colorSchemes.ts](https://github.com/decentraland/ui2/blob/master/src/theme/colorSchemes.ts)) * Pré-visualização do modo claro * Pré-visualização do modo escuro * Documentação sobre a troca de esquemas no Storybook **Exemplo**: ``` Esquemas suportados: Claro, Escuro Padrão: preferência do sistema Alternar: menu Configurações → Aparência Storybook: use o controle "Theme" na barra de ferramentas ``` ### Seleção de componentes **DEVE** reutilize componentes preparados: 1. **Verifique o MUI primeiro** - O MUI tem este componente? 2. **Verifique o UI2** - Existe uma variante da Decentraland? 3. **Componha se possível** - Você pode combinar componentes existentes? 4. **Personalizado como último recurso** - Siga [Componentes personalizados](/contributor/contributor-pt/guias-para-colaboradores/padroes-de-web-ui/custom-components.md) processar *** ## Implementação da dApp Os desenvolvedores implementam os designs usando componentes UI2 e seguindo nossas [Estilo e tematização](/contributor/contributor-pt/guias-para-colaboradores/padroes-de-web-ui/styling-and-theming.md) padrões. ### Lista de verificação de implementação * [ ] Comece com o componente UI2 se estiver disponível * [ ] Use um componente MUI com o tema Decentraland se não houver equivalente no UI2 * [ ] Siga [Estilo e tematização](/contributor/contributor-pt/guias-para-colaboradores/padroes-de-web-ui/styling-and-theming.md) padrões * [ ] Implemente todos os estados definidos na spec de UX * [ ] Adicione o rastreamento de Analytics conforme especificado * [ ] Teste em todos os breakpoints * [ ] Verifique a navegação por teclado * [ ] Verifique o contraste de cores * [ ] Teste com leitor de tela * [ ] Lide com estados de carregamento e erro * [ ] Adicione ao Storybook se for um componente reutilizável ### Fluxo de implementação de componentes ``` 1. Verifique o UI2 para o componente ↓ 2. Encontrou? → Use-o ↓ 3. Não encontrou? → Verifique o MUI ↓ 4. Encontrou no MUI? → Use com o tema Decentraland ↓ 5. Precisa de personalização? → Consulte o guia de Componentes Personalizados ↓ 6. Implemente seguindo os padrões de estilo ↓ 7. Adicione ao Storybook (se reutilizável) ``` ### Critérios de qualidade Antes de marcar a implementação como concluída: 1. **Correspondência visual** - Corresponde pixel-perfect ao Figma nos breakpoints principais 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** - Os eventos são disparados conforme especificado 6. **Responsivo** - Funciona em todos os breakpoints 7. **Desempenho** - Sem re-renderizações desnecessárias 8. **Testes** - Os testes do componente passam 9. **Storybook** - Stories adicionadas (se reutilizável) 10. **Revisão de código** - Aprovado pelos mantenedores *** ## Boas práticas de handoff ### De UX para Design * Documento de requisitos claro * Fluxos do 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 o modo dev ativado * Especificações dos componentes * Notas sobre comportamento responsivo * Mapeamento de tokens de cor e tipografia * Anotações de acessibilidade * Link para os 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 de fazer merge *** ## Próximos passos * Saiba mais sobre [Componentes personalizados](/contributor/contributor-pt/guias-para-colaboradores/padroes-de-web-ui/custom-components.md) para criar novos Components * Rever [Estilo e tematização](/contributor/contributor-pt/guias-para-colaboradores/padroes-de-web-ui/styling-and-theming.md) para detalhes de implementação * Veja [Guia de migração](/contributor/contributor-pt/guias-para-colaboradores/padroes-de-web-ui/migration.md) se estiver a trabalhar com Components 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-pt/guias-para-colaboradores/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 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.