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

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, que espelha componentes do Material UI e usa o tema Decentraland definido em UI2.

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.

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)

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:

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

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

• MUI Typography

• Material Design Type System

Exemplo de mapeamento:

Figma "H1" → <Typography variant="h1">
Figma "Body 1" → <Typography variant="body1">
Figma "Caption" → <Typography variant="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

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:

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)

• 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 process

---

Implementação de dApp

Desenvolvedores implementam designs usando componentes UI2 e seguindo nosso Styling & Theming 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 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 para criar novos componentes

• Rever Styling & Theming para detalhes de implementação

• Veja Guia de Migração se estiver trabalhando com componentes UI1