Squad Front

Appearance

UX e Design System ​

Este documento detalha os conceitos fundamentais de UX (User Experience) e como o nosso Design System utiliza tokens, slots e variantes para otimizar o desenvolvimento front-end. Ele serve como o guia definitivo para a integração entre Design e Engenharia.

1. O que é UX (User Experience)? ​

UX, ou Experiência do Usuário, é o conjunto de elementos e fatores relativos à interação do usuário com um produto, sistema ou serviço. O objetivo principal do UX é garantir que o usuário encontre valor no que você está fornecendo, tornando a jornada simples, intuitiva e eficiente.

No nosso contexto:

  • Utilidade: O sistema resolve o problema do usuário?
  • Usabilidade: É fácil de aprender e usar?
  • Desejabilidade: A interface é agradável e passa confiança?
  • Acessibilidade: Todos os usuários, independentemente de suas capacidades, conseguem usar o sistema?
  • Tratamento de Erros: O sistema é capaz de guiar o usuário em caso de falhas? Saiba mais sobre Erros de UX.
  • Estados de Loading: Como o sistema comunica que um processo está em andamento? Veja o guia de Loadings.

2. Design Tokens ​

Design Tokens são os "átomos" do nosso sistema de design. Eles são variáveis agnósticas de plataforma que armazenam atributos visuais, como cores, espaçamentos, tipografia e sombras.

Como funcionam? ​

Em vez de usar valores fixos (hexadecimais ou pixels), usamos nomes semânticos:

  • Ruim: color: #0052FF;
  • Bom: color: ${theme.colors.brand.primary};

Hierarquia de Tokens: ​

  1. Global Tokens: Valores brutos (ex: Blue-500: #0052FF). Raramente usados diretamente no código.
  2. Semantic Tokens: Descrevem a intenção (ex: Action-Primary: Global.Blue-500). Sempre use estes.
  3. Component Tokens: Específicos para um componente (ex: Button-Background: Semantic.Action-Primary).

3. Slot Components ​

Slot Components são componentes que possuem "buracos" (slots) onde outros componentes ou elementos podem ser injetados. É o conceito de composição sobre herança.

Benefícios: ​

  • Flexibilidade: Permite que um componente genérico (como um Card ou Modal) aceite conteúdos variados sem precisar de dezenas de props complexas.
  • Desacoplamento: O componente "pai" não precisa saber o que o "filho" faz; ele apenas reserva o espaço.
  • Reutilização: Um único componente de Layout pode ser usado em centenas de telas diferentes injetando conteúdos distintos nos slots de header, content e footer.

4. Variantes (Variants) e Propriedades ​

No design (Figma), as variantes permitem agrupar componentes similares com propriedades diferentes (ex: um botão que pode ser Pequeno, Médio ou Grande; Primário ou Secundário).

Impacto no Front-end: ​

As variantes do design mapeiam diretamente para as Props do componente no código:

  • Design: Botão [Type: Primary, Size: Large]
  • Código: <Button type="primary" size="large" />

5. Estados de Interação (Interactive States) ​

Seguindo o padrão do Material Design, utilizamos camadas de estado para indicar interatividade sem alterar a cor base do elemento.

  • Hover (8% de opacidade): Indica que um elemento é interativo (Desktop).
  • Pressed (12% de opacidade): Feedback tátil imediato ao clicar/tocar.
  • Disabled (38% de opacidade): Indica que a ação não está disponível.
  • Focus (Outline): Indispensável para navegação via teclado e acessibilidade.

6. Acessibilidade (a11y) ​

O sistema é construído para ser inclusivo por padrão. Desenvolvedores devem garantir:

  1. Área de Toque (Touch Targets): Mínimo de 44x44dp para qualquer elemento clicável. Use hitSlop no React Native se o elemento visual for menor.
  2. Contraste (WCAG AA): Texto normal deve ter contraste mínimo de 4.5:1 contra o fundo.
  3. Labels de Acessibilidade: Use sempre accessibilityLabel para descrever o que um botão ou ícone faz para leitores de tela.
  4. Não apenas cor: Nunca indique um erro ou estado apenas pela cor. Use ícones e textos explicativos. Veja exemplos de erros de tela.

7. Melhores Práticas de Desenvolvimento ​

Uso de Stacks ​

Evite margens manuais (margin-top, margin-left). Use componentes de layout baseados em pilhas:

  • Stack (Vertical/Horizontal): Gerencia o espaçamento uniforme entre elementos de forma automática.

Documentação Técnica ​

A IDE padrão para desenvolvimento é o WebStorm. Utilize as ferramentas integradas de inspeção e auto-complete para garantir o uso correto dos componentes e tokens do Design System.

8. Glossário de Layout ​

TermoDefinição
FoundationsCores, Tipografia, Sombras e Espaçamentos (o básico).
ComponentsElementos funcionais (Botão, Input, Card).
PatternsConjuntos de componentes que resolvem problemas comuns (ex: Formulário de Login).
ElevationProfundidade visual controlada por tokens (níveis 1 a 6).