# 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](https://docs.decentraland.org/contributor/contributor-pt/guias-para-contribuidores/web-ui-standards/custom-components))
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" → <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](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](https://docs.decentraland.org/contributor/contributor-pt/guias-para-contribuidores/web-ui-standards/custom-components) process

***

## Implementação de dApp

Desenvolvedores implementam designs usando componentes UI2 e seguindo nosso [Styling & Theming](https://docs.decentraland.org/contributor/contributor-pt/guias-para-contribuidores/web-ui-standards/styling-and-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](https://docs.decentraland.org/contributor/contributor-pt/guias-para-contribuidores/web-ui-standards/styling-and-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](https://docs.decentraland.org/contributor/contributor-pt/guias-para-contribuidores/web-ui-standards/custom-components) para criar novos componentes
* Rever [Styling & Theming](https://docs.decentraland.org/contributor/contributor-pt/guias-para-contribuidores/web-ui-standards/styling-and-theming) para detalhes de implementação
* Veja [Guia de Migração](https://docs.decentraland.org/contributor/contributor-pt/guias-para-contribuidores/web-ui-standards/migration) se estiver trabalhando com componentes UI1