Pular para o conteúdo

DESIGN.md

O DESIGN.md reúne, em um único arquivo de texto, as decisões visuais e de interface do MDS: cores, tipografia, espaçamento, elevação, formas, componentes-chave, estilo de escrita e as diretrizes de comportamento (estados, feedback, ações destrutivas, formulários e navegação). É o contexto que uma IA precisa para gerar telas que parecem e se comportam como o produto.

  • Em ferramentas de código (Claude Code, Cursor e similares): baixe o arquivo e salve como DESIGN.md na raiz do projeto, para o agente ler antes de gerar ou alterar interface.
  • Em geradores de interface (Google AI Studio, Lovable, v0 e similares): cole o conteúdo nas instruções do projeto ou anexe o arquivo como conhecimento.
  • Para classes CSS exatas, combine com o pacote @mobiis/mds-style (o DESIGN.md descreve as decisões; as classes mds-* vêm do CSS).

O arquivo é gerado do CSS real e das diretrizes do MDS. Quando o sistema mudar, baixe de novo.

1. Overview

O Mobiis Design System (MDS) é a linguagem visual do ecossistema de logística integrada da Mobiis (TMS, YMS, WMS, roteirização, rastreamento de frota e a assistente MIA). O público é operacional e técnico — operadores logísticos, motoristas, gerentes de pátio, diretores de supply chain — e a interface precisa sustentar alta densidade de dados em tempo real sem parecer poluída.

Diretriz central: simplificar e revelar informação progressivamente. Mostre apenas o que é pertinente para a ação do momento; deixe o sistema fazer o trabalho pesado e o usuário no controle. Cada tela tem um objetivo principal (Lei de Hick: mais opções visíveis = mais tempo de decisão).

Regras essenciais (leia primeiro)

Valem para qualquer tela, em qualquer tecnologia. Entre colchetes, a regra que a auditoria (mds_style_audit) aplica.

  1. Toda cor, espaçamento, raio, sombra e fonte vem de um token var(--mds-*); nunca hex, px ou rgba soltos. Valor vindo do Figma ou de CSS antigo: converta com mds_style_map_tokens. [token.hardcoded-color, token.hardcoded-spacing, token.hardcoded-radius, token.hardcoded-typography, token.unknown]
  2. Use só classes que existem (Component Class Index da skill mds-style). Não invente classe por analogia: .mds-toast e .mds-skeleton, por exemplo, não existem.
  3. Use o componente do MDS em vez de elemento nativo ou estrutura feita à mão (botão, campo, select, data, tabela, modal, alerta, abas, loader, estado vazio). [structure.native-button, structure.native-text-input, structure.native-select, structure.native-table, structure.handmade-overlay, structure.handmade-alert]
  4. Uma tela, um objetivo: no máximo um botão primary por tela, formulário ou diálogo. Cancelar/Voltar/Fechar nunca é o primary. [button.max-primary-per-scope, button.dismiss-not-primary]
  5. Ação destrutiva usa a variante danger, rótulo explícito (verbo + objeto) e confirmação proporcional ao custo de desfazer (seção 9.5). [button.destructive-needs-danger, button.danger-explicit-label]
  6. Botão só de ícone tem aria-label e Tooltip. [button.icon-only-needs-name]
  7. Campo sempre com rótulo visível acima; placeholder não substitui rótulo. Validação ao sair do campo, mensagem “o que está errado + como corrigir” (seção 9.6). [input.label-required]
  8. Toda tela cobre os cinco estados: carregando, vazio, erro, sucesso e com dados (seção 9.3).
  9. Escolha o feedback pela árvore da seção 9.4 (campo → Modal → Alert → Toast → Tooltip → EmptyState). Cor nunca é o único sinal; vermelho só para erro.
  10. Texto: voz neutra do sistema (sem “você”, “Ops”, exclamação); botão, título, menu e coluna em Caixa de Título; rótulo, mensagem e placeholder em Caixa de Sentença; reticências com o caractere … (seção 8). [copy.neutral-tone, copy.no-filler, copy.title-case, copy.sentence-case, copy.ellipsis-char]
  11. Navegação com no máximo dois níveis; título da página = item de menu ativo (seção 9.7).
  12. Nunca fixe a cor primária nem o tema: preserve [data-primary] e [data-theme] no elemento raiz (seção 2).

Como gerar uma tela com este documento

  1. Diga o problema e a ação principal da tela em uma frase (seção 9.1).
  2. Escolha os componentes pelo índice da seção 10 e pela tabela “Preciso… → Use” da seção 9.7; confira as classes no Component Class Index da skill mds-style.
  3. Monte o layout com o grid e a escala de espaçamento (seção 4); cores, raio e elevação pelos papéis das seções 2, 5 e 6.
  4. Desenhe os cinco estados (9.3), o feedback (9.4), as confirmações (9.5) e o formulário (9.6).
  5. Escreva os textos pela seção 8.
  6. Revise com o checklist 9.8 e rode mds_style_audit (ou npm run audit -- <arquivo>) até não sobrar erro nem aviso.

Se duas seções conflitarem, a precedência é: seções 2 a 7 (lidas do código) › seção 9 (diretrizes de interface) › seção 10 (comportamento por componente, vindo do Notion).

Princípios

Princípios formais do MDS (fonte: docs/principios-de-design.md):

  • Questionamos — O trabalho deve ter um propósito - procuramos abordar problemas reais e urgentes que as pessoas estão enfrentando. Questionamos até entender claramente o núcleo do problema antes de gastar um pouco de tempo no desenvolvimento de soluções. Questionamos afim de não perder tempo resolvendo os problemas errados.
  • Clareza — Para uma interface ser eficaz e eficiente, o usuário deve ser capaz de reconhecer a sua utilidade e entender como ela pode ajudá-lo, prever o que vai acontecer durante o uso, e conseguir interagir com sucesso. Não há motivos para mistérios nas interfaces. Clareza inspira confiança e cativa o uso.
  • Objetividade — O tempo que leva para fazer uma decisão aumenta com o número de opções apresentadas. (Lei de Hick)
  • Consistência — Padronização de componentes, comportamentos e funcionalidades. Comportamento igual para itens semelhantes. “Se parece um botão, deve se comportar como um botão”.

Identidade técnica: BEM estrito com prefixo mds- em todo componente (.mds-btn, .mds-card__header, .mds-btn--primary), enquanto fundações e utilitários (grid, spacing, texto) usam nomes “limpos” no padrão Bootstrap/Tailwind (.container, .gap--md, .text-muted) para reduzir a curva de aprendizado. Tudo — com ou sem prefixo — resolve para os mesmos design tokens (CSS Custom Properties --mds-*), então a consistência visual é garantida mesmo nas classes sem prefixo.

Multi-marca: O sistema suporta múltiplos tenants/produtos trocando só a cor primária via [data-primary="..."] no elemento raiz. O padrão (sem atributo) é brand-mobiis. Um agente que gerar UI para um cliente específico deve preservar essa variável, nunca fixar a cor em hexadecimal.


2. Colors

Todas as cores são CSS Custom Properties (--mds-colors-*), nunca hex fixo no HTML/CSS de consumo. Cada papel semântico tem 5 tons (lighter, light, main, dark, darker) + seu par de contraste — nomenclatura alinhada ao Figma (--mds-colors-<papel>-<tom> para o fundo, --mds-colors-<papel>-on-<tom> para o texto/ícone legível sobre ele, ex.: --mds-colors-primary-main + --mds-colors-primary-on-main).

Papéis semânticos (tema claro)

Papel Token base lighter light main dark darker Quando usar
Primary --mds-colors-primary-* #ecf3ff #a0c4fd #408afa #3068bb #20457d Ação principal, marca, item ativo/selecionado, foco de interação
Secondary --mds-colors-secondary-* #e9ebf3 #939ac5 #27348b #1d2768 #141a46 Marca institucional, badges/destaques secundários, campo válido (borda)
Danger --mds-colors-danger-* #fcebe6 #f29980 #e53200 #ac2600 #731900 Erro, exclusão, bloqueio, ação irreversível
Warning --mds-colors-warning-* #fef9e6 #f8e280 #f0c400 #b49300 #786200 Atenção, campo obrigatório, dado pendente de revisão
Info --mds-colors-info-* #e6f3fb #80c3ed #0087db #0065a4 #00446e Mensagem neutra, dica, estado informativo sem urgência
Success --mds-colors-success-* #e6f9e6 #80e381 #00c703 #009502 #006402 Confirmação, conclusão, dado validado

on-<tom> é a cor de texto/ícone garantida legível sobre aquele fundo — sempre use o par (--mds-colors-<papel>-main + --mds-colors-<papel>-on-main), nunca aplique texto escuro fixo sobre um fundo de token.

Os fundos de todas as famílias de cor batem com o Figma Design System 2.0. Histórico das conferências e das correções: docs/historico-cores-e-temas.md (material de manutenção).

Background / Surface / Text (neutros)

Escala base: --mds-colors-gray-0 #fefefe … --mds-colors-gray-50 #fafbfc … --mds-colors-gray-100 #f3f4f6 … --mds-colors-gray-200 #e8eaee … --mds-colors-gray-300 #dcdfe5 … --mds-colors-gray-400 #d0d4dc … --mds-colors-gray-500 #9c9fa5 … --mds-colors-gray-600 #686a6e … --mds-colors-gray-700 #343537 … --mds-colors-gray-800 #151516 … --mds-colors-gray-900 #060607.

Uso Token Valor Regra
Surface / Card --mds-dimmed-default #fefefe Fundo padrão de card, modal, painel — “branco” do sistema
Background (página) --mds-colors-background-light #fafbfc Fundo da aplicação por trás dos cards
Background (elemento) --mds-colors-background-main #f3f4f6 Fundo de blocos secundários (ex.: .mds-box)
Background (rebaixado) --mds-colors-background-dark #e8eaee Hover neutro, divisores de área, estado “dimmed”
Border --mds-colors-border-main #e8eaee Toda borda 1px de card, input, tabela
Text — corpo (padrão) --mds-colors-foreground-main #686a6e Texto de parágrafo, valor de dado, corpo em geral
Text — ênfase/secundário --mds-colors-foreground-dark #343537 Título, rótulo em destaque, texto que precisa de mais peso que o corpo
Text — muted/apoio --mds-colors-foreground-light #9c9fa5 Placeholder, texto de ajuda, timestamp, metadado de baixa prioridade

Note a inversão de intuição: foreground-dark é o texto de MAIOR ênfase (mais escuro = mais peso), e foreground-light é o texto de MENOR ênfase (mais claro = apoio). Siga essa semântica, não o nome literal.

Destructive

Não existe token destructive isolado — Danger cobre esse papel (botão de exclusão = variant="danger" / .mds-btn--danger, --mds-colors-border-error = #e53200).

Overlay / Shadow

  • --mds-colors-background-shadow: rgba(22, 22, 23, 0.15) — base de toda sombra do sistema.
  • --mds-colors-background-transparency: rgba(52, 53, 55, 0.6) — backdrop de modal/drawer.

Multi-marca ([data-primary="..."])

Tenant Cor main
brand-mobiis #408afa
blue #0087db
teal #00dbdb
aqua #00f0b8
green #00c703
yellow #f0c400
orange #f07800
red #e53200
pink #ff0073

Tema escuro

[data-theme="dark"] e :root aplicam-se ao mesmo elemento — uma prop não redeclarada em [data-theme="dark"] cai para o valor de :root (cascata normal do CSS); a maioria dos papéis redeclara os 5 tons com valores próprios para dark. Ex.: primary-main é #408afa no claro e #3068bb no escuro. Neutros do tema escuro: fundo #121c2b, texto de corpo #d1d8e2. Um agente de IA nunca deve ler valor de cor fixo: sempre referenciar o token, para funcionar nos dois temas automaticamente.

  • Três temas, todos sobre os mesmos tokens: claro (padrão), [data-theme="dark"] e [data-theme="dark-blue"] (neutros azul-marinho). Qualquer tema combina com [data-primary="..."].
  • No escuro a sombra quase não aparece: a hierarquia vem da luminosidade da superfície (página background-light < bloco rebaixado background-main < card dimmed-default < hover/borda). Use o token de fundo da camada certa em vez de depender de box-shadow para separar planos.
  • Não presuma que -dark/-darker escurecem: no tema escuro esses tons clareiam. Não monte hover ou ênfase próprios com esses tons; use os estados que o componente já tem ou os tokens semânticos (foreground-*, border-*, ui-interactive-*).
  • Contraste já está resolvido nos pares de token (texto de corpo, apoio, erro, link, borda de campo) nos três temas. Texto colorido usa --mds-colors-foreground-{primary|secondary|error|warning|info|success}, não o main do papel (note: o de perigo é foreground-error).

3. Typography

Fonte: "Manrope", system-ui, -apple-system, "Segoe UI", "Roboto", "Helvetica Neue", "Arial", "Noto Sans", "Liberation Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji". Token: --mds-font-family.

Pesos: --mds-font-weight-light 300 · --mds-font-weight-normal 400 · --mds-font-weight-semibold 600 · --mds-font-weight-bold 700 (peso padrão de botões: semibold).

Escala de tamanho (--mds-font-size-*)

Token px
xs 12
sm 14
md 16
lg 20
xl 24
xxl 32
xxxl 40
hg 48
xhg 56
xxhg 64

Hierarquia semântica (classes atuais, prefixo mds-)

Classe Tamanho Peso Line-height
.mds-headline--h1 64px 700 125%
.mds-headline--h2 48px 700 125%
.mds-headline--h3 32px 700 125%
.mds-headline 24px 700 125%
.mds-headline--h4 24px 700 125%
.mds-title--lg 20px 700 125%
.mds-title 16px 700 125%
.mds-title--md 16px 700 125%
.mds-title--sm 14px 700 125%
.mds-body--lg 20px 400 150%
.mds-body 16px 400 150%
.mds-body--md 16px 400 150%
.mds-body--sm 14px 400 150%
.mds-body--xs 12px 400 150%

Classes legadas (sem prefixo, @deprecated): .display2, .display, .title, .subtitle, .body, .small, .caption, .helper-text. Não use em código novo; troque pela classe mds- de mesmo papel na tabela acima.

Também existem diretivas Angular equivalentes às classes atuais: mdsHeadline="h1|h2|h3|h4", mdsTitle="lg|md|sm", mdsParagraph="lg|md|sm|xs".

Classes utilitárias de alinhamento/transformação de texto (.text-left, .text-uppercase…) não são conceito de tipografia — são utilitário de fundação. Lista exata na skill mds-style (agent-skills/SKILL.md), seção “Utility Classes Cheat Sheet”.


4. Layout & Spacing

Base: grid inspirado em Bootstrap (.container, .container-fluid, .row, .col-[n], breakpoints xs/sm/md/lg/xl/xxl), sem prefixo mds- (é fundação, não componente).

Densidade: média-alta — o produto prioriza mostrar mais dado por tela (tabelas, kanbans, cards compactos) mantendo respiro suficiente para uso prolongado.

Escala de espaçamento (--mds-spacing-*)

Token px
xs 4
sm 8
md 16
lg 24
xl 32
xxl 40
xxxl 48

md (16px) é o padrão quando nenhum tamanho é especificado.

As classes utilitárias que aplicam esta escala (.padding-{pos}--{tam}, .margin-{pos}--{tam}, .gap--{tam}, .d-flex e o resto do grid/flexbox) são utilitário de fundação, não conceito de spacing — catálogo exato na skill mds-style (agent-skills/SKILL.md), seção “Utility Classes Cheat Sheet”.


5. Elevation & Depth

Sombra em 5 níveis, todas usando a mesma cor-base, variando só o espalhamento — cresce junto com a escala de espaçamento. Escolha o nível pelo papel do elemento na hierarquia da página, não pela aparência:

Nível Classe box-shadow Uso
5 .mds-elevation--5 (ou .elevation--5) 0 16px 24px rgba(22, 22, 23, 0.15) Elementos sobrepostos à página: toolbar
4 .mds-elevation--4 (ou .elevation--4) 0 8px 16px rgba(22, 22, 23, 0.15) Elementos de níveis sobrepostos ao conteúdo pai: modal, diálogos
3 .mds-elevation--3 (ou .elevation--3) 0 4px 8px rgba(22, 22, 23, 0.15) Elementos sobrepostos ao conteúdo: popover, dropdown, tooltips
2 .mds-elevation--2 (ou .elevation--2) 0 2px 4px rgba(22, 22, 23, 0.15) Cards clicáveis
1 .mds-elevation--1 (ou .elevation--1) 0 1px 1px rgba(22, 22, 23, 0.15) Botões
Sem elevação — none Raiz e corpo do documento, planos de fundo e qualquer elemento que não seja elevado

No SCSS, aplique com @include elevation.apply(n) (mixins/_elevation.scss) ou @extend %elevation--n (foundations/_elevation.scss).

Blur (glassmorphism pontual — não é padrão de fundo): --mds-blur-xs 8px · --mds-blur-sm 16px · --mds-blur-md 32px · --mds-blur-lg 48px · --mds-blur-xl 64px, via .blur--{tam} (backdrop-filter).

Divisores: linha 1px sólida na cor de borda (não sombra) — usada em vez de elevação para separar seções de mesma superfície.

Motion: transições de estado (hover/active/expand) usam 0.2s com easing cubic-bezier(0.645, 0.045, 0.355, 1) — perceptível mas rápido, sem “bounce”.


6. Shapes & Borders

Cantos padronizados em escala própria (não ligada à escala de spacing, apesar de nomes iguais):

Token px
xxs 4
xs 6
sm 8
md 16
lg 24
xl 32
xxl 40
xxxl 48

Raio por família de componente

O componente já aplica o próprio raio; use esta tabela só ao compor algo novo que precise combinar com ele.

Elemento Raio
Botão (md, padrão) 8px (--mds-radius-sm)
Input / Select (padrão) 8px (--mds-radius-sm)
Card 8px (--mds-radius-sm)
Modal (mds-float-panel--modal) 8px (--mds-radius-sm)
Drawer / tela cheia (--fullscreen) 0px (sem raio — encosta na borda da viewport)
Avatar (padrão) 8px, quadrado arredondado (não é círculo por padrão)
Avatar .mds-avatar--rounded 100% (círculo completo)
Checkbox 6px (--mds-radius-xs)
Switch/Toggle 40px (--mds-radius-xxl, pill)

A maioria dos componentes de formulário/superfície (botão, input, select, card, modal, checkbox) usa o mesmo raio pequeno (--mds-radius-sm, 8px, ou --mds-radius-xs, 6px, no checkbox) — não há um raio “de input” desproporcionalmente maior; só avatar --rounded e switch/toggle chegam a formas totalmente arredondadas.

Borda: 1px sólida como padrão (--mds-colors-border-main ou --mds-control-default-border); campo em foco/erro sobe para 2–3px com a cor semântica. Nunca use outline do navegador puro — o MDS estiliza o próprio anel de foco.


7. Key Components

Medidas e estados visuais das famílias principais, lidos do SCSS. Para que serve e como se comporta cada um dos 46 componentes: seção 10.

Botões (.mds-btn)

Tamanho Altura Raio Fonte do botão
xxs 12px --mds-radius-xxs — (sem botão nesse tamanho)
xs 24px --mds-radius-xs 12px
sm 32px --mds-radius-sm 12px
md 48px --mds-radius-sm 14px
lg 56px --mds-radius-sm 16px
  • Peso de texto sempre semibold (600), independente do tamanho.
  • Variantes de cor: control/default (neutro, cinza), primary, secondary, danger, warning, success, info, transparent/link (sem fundo, ação de baixa prioridade). Regra de produto: no máximo 1 botão primary por tela/formulário/diálogo.
  • Modificadores: outline (contorno, sem fundo sólido), rounded (pill), loading (loader substitui o conteúdo, botão inerte), disabled.
  • Botão só-ícone precisa de aria-label/tooltip — nunca um botão mudo visualmente.

Inputs / Campos de formulário

  • Raio padrão igual ao de botões e cards (8px) — não é mais arredondado que o resto do sistema.
  • Estado padrão: fundo branco (surface), borda 1px na cor de borda padrão.
  • Foco/ativo: borda sobe para a cor primary; erro: borda + sombra em danger; obrigatório pendente: destaque em warning; válido: borda secondary-dark.
  • Rótulo acima do campo (não usa placeholder como rótulo); texto de ajuda abaixo, cor muted.

Cards

  • Fundo surface, raio 8px, elevação 1 em repouso, sobe ao hover/seleção.
  • Cabeçalho (.mds-card__header) arredonda só o topo; o rodapé (.mds-card__footer) segue o mesmo raio do card.
  • Notificação/atualização: badge sólido no canto; seleção em lote: checkbox + anel de destaque (box-shadow: 0 0 0 2px na cor do estado).

Modais e Drawers (mds-float-panel)

  • Modal (--modal): raio 8px, elevação alta, backdrop escuro translúcido. Diálogo central, para interrupção/confirmação/detalhe que exige foco total.
  • Drawer (--drawer): painel lateral sem raio (encosta na borda), para fluxos de formulário que devem manter contexto da tela por trás.
  • Tela cheia (--fullscreen): raio zerado explicitamente.
  • Ações sempre no rodapé, fixas; título curto; fechamento por “×” ou clique no backdrop.
  • Topbar: altura fixa 64px. Menu lateral: 256px expandido, 64px compacto (só ícones), altura de item 64px.
  • Item ativo com fundo item-active-background (tom claro de primary) e borda/texto primary-dark.
  • Abas (nav-tabs): item ativo com peso bold e indicador em primary; nunca mais de 2 níveis de profundidade em menus/dropdowns.

Ícones

  • Sistema Lucide (SVG), consumido por alias semântico em português no Angular (ex.: icon="excluir") — nunca pelo nome literal do ícone Lucide.
  • Tamanhos alinhados à escala de fonte (sm/md/lg/xl), herdam a cor do texto/ícone do contexto (currentColor).

8. Voice & Writing

O texto da interface é lido em movimento (pátio, doca, celular do motorista), por quem quer saber o que aconteceu com a carga e o que fazer agora. Todo texto gerado para o MDS segue as regras abaixo — inclusive rótulos, placeholders, mensagens e dados de exemplo em protótipos.

Princípios

Princípio Regra
Direto A informação mais importante vem primeiro.
Preciso Diga qual carga, placa ou documento e quanto; nada de “ocorreu um erro”.
Neutro Voz do sistema: sem “você”, “eu” ou “nós”; sem “Ops”; sem exclamação.
Familiar Vocabulário do operador (Carga, Viagem, Manifesto, Pátio, Doca), não o do banco de dados.
Consistente Um conceito, um nome, em todas as telas.

Estrutura da mensagem

Mensagem de feedback = o que aconteceu (com o objeto específico) + o que fazer (se houver). Ex.: “CPF inválido. Insira apenas números.” — nunca “Você digitou o CPF errado.” nem “Ocorreu um erro.”

Capitalização

Elemento Estilo Exemplo
Botão Título Confirmar Entrega
Título de página/modal/drawer/EmptyState Título Excluir Rota?
Item de menu e aba, cabeçalho de coluna de tabela Título Agendamento de Docas · Data de Entrega
Rótulo de campo, placeholder Sentença Nome do motorista
Toast, Alert, erro, Tooltip, texto de carregamento Sentença Falha na conexão.
Descrição e texto de ajuda, status/badge Sentença Em trânsito

Caixa de título: cada palavra significativa em maiúscula; artigos, preposições e conjunções (a, o, de, da, em, para, por, com, e, ou…) em minúscula (Ir para o Dashboard). Caixa de sentença: só a primeira palavra e nomes próprios; siglas mantêm a grafia (NF-e, CPF). Nunca digite texto em CAIXA ALTA — se o design pedir maiúsculas, é estilo (CSS). (a validar: A regra por classe gramatical adapta ao português a regra “AP” (palavras com mais de 3 letras) hoje descrita nas Diretrizes.)

Regras de rótulo, pontuação e vocabulário

  • Botão: verbo no infinitivo + objeto, 1–2 palavras (Salvar, Emitir Nota, Despachar Carga); sem repetir o contexto da seção (seção “Motoristas” → Adicionar). Em confirmação, o botão repete a ação (Excluir Rota), nunca “Sim”/“OK”; a saída é Cancelar.
  • Reticências (…) no botão/item que abre outra janela ou pede mais dados antes de concluir (Configurar Filtros…); nunca em placeholder, tooltip ou item de submenu. Use o caractere único …, não três pontos.
  • Ponto final em mensagens e descrições (Toast, Alert, erro, EmptyState); sem ponto em rótulo, botão, título, placeholder, status e tooltip de uma frase. Pergunta sempre termina com “?”.
  • Status descreve onde a coisa está (particípio/expressão curta: Despachada, Em trânsito, Aguardando doca); ação descreve o que vai acontecer (infinitivo); processo em andamento é gerúndio + reticências (Gerando relatório…).
  • Verbo padrão por ação: Salvar, Excluir (definitivo), Cancelar (interrompe e mantém histórico), Pesquisar, Confirmar/Registrar/Concluir, Despachar, Emitir (documento fiscal). Não alterne com sinônimos (Deletar, Apagar, Buscar, Submeter).
  • Siglas: as de todo operador (NF-e, CT-e, MDF-e, CPF, CNPJ, CEP, ETA) valem sem explicação; as demais vêm por extenso ou em Tooltip (ICMS → “Imposto sobre circulação de mercadorias”). Termo em inglês só se for nome de produto ou uso corrente do setor.
  • Link descreve o destino (“Ver detalhes da carga”), nunca “Clique aqui”. Botão só-ícone sempre com aria-label e Tooltip.
  • Plural e gênero corretos, sem “(s)”: “1 carga”, “12 cargas”, “Nenhuma carga”. Cada frase é uma string inteira — nunca montada por concatenação.

Formatos (pt-BR)

Tipo Formato Exemplo
Data dd/mm/aaaa 25/09/2026
Hora 24 h 14:30
Moeda R$, ponto no milhar, vírgula nos centavos R$ 1.250,90
Peso, volume, distância Número, espaço, unidade 1.250 kg · 32,5 m³ · 142 km
Duração Unidade abreviada, sem ponto 45 min · 2 h 10 min
Placa Com hífen (antiga); sem hífen (Mercosul) ABC-1234 · ABC1D23
CEP / CPF Com máscara 00.000-000 · 000.000.000-00

Evite → Prefira

Evite Prefira
Sua carga foi despachada com sucesso agora. Carga despachada.
Tem certeza que quer apagar? Título “Excluir Rota?” + botões Cancelar · Excluir Rota
Ops, nada por aqui! Nenhuma Viagem Encontrada. Não há viagens para o filtro selecionado.
Por favor, aguarde enquanto carregamos… Carregando viagens…
Não foi possível agendar. Doca 3 indisponível às 14h. Escolha outro horário.
Digite aqui o nome do motorista… Nome do motorista

Ainda em aberto (a validar com Produto)

  • Termos oficiais do domínio (Carga, Viagem, Doca, Check-in/Check-out…) e o verbo Remover (tirar um item de uma lista ou vínculo sem apagá-lo) ainda precisam ser fechados com Produto e Operações.
  • Mostrar o fuso horário explicitamente em telas que operem em mais de um fuso.

9. Interface Guidelines

Estas diretrizes são direcionamento, não livro de regras: desviar é permitido, desviar sem saber por quê não. Quando duas regras conflitarem, desempate nesta ordem — Clareza › Consistência › Objetividade (e antes de tudo, confirme que o problema é o certo). Se nenhum padrão serve, procure um componente existente no MDS antes de inventar; nunca crie estilo local “quase igual” ao do sistema.

Regras de comportamento e composição de tela (o “como a interface deve se comportar”), complementares às seções visuais 2–7 e ao estilo de escrita da seção 8. Fonte: seção Guidelines do docs-site. Itens marcados (proposta) ainda não foram validados com Produto — aplique, mas não trate como regra fechada.

9.1 Princípios aplicados a uma tela

Princípio Como aplicar Teste
Questionamos Parta do problema da pessoa (“quem quer fazer o quê e o que impede”), não da tela pedida. Consigo dizer qual problema isto resolve sem citar tela ou componente?
Clareza Toda tela responde: onde estou (título, breadcrumb, item ativo), o que posso fazer (uma ação principal em destaque), o que vai acontecer (rótulo que diz o resultado, estado sempre visível). Hierarquia por tamanho, contraste e espaço — “se tudo grita, nada é ouvido”. Em 5 segundos a pessoa diz para que serve a tela e qual é o próximo passo?
Objetividade Uma tela, um objetivo, um CTA primary. Mostre só o que serve à ação do momento; o resto fica atrás de um clique (Collapse, Drawer, Modal). Preencha o que o sistema já sabe. A ação principal cabe em uma frase sem “e”?
Consistência Mesma coisa, mesma aparência (tokens, nunca valor avulso); mesmo gesto, mesmo resultado (se Excluir confirma numa tela, confirma em todas); um conceito, um nome. Antes de criar, procure no MDS. Quem domina uma tela adivinha como funciona outra?

9.2 Filosofia — quando as regras acabam

  • O sistema carrega a complexidade, não a pessoa (Lei de Tesler): calcule, valide, preencha, sugira. Não peça digitação do que o sistema já sabe (usuário logado, carga selecionada, data de hoje).
  • Projete para o “usuário bêbado” — distraído, com pressa, de luva, no celular no pátio sob o sol, interrompido: alvos de toque generosos, contexto sempre visível, caminho de volta, dados preservados se a pessoa for interrompida, prevenção de erro em vez de só mensagem de erro. (proposta como checklist de revisão)
  • A pessoa no controle: preencha automaticamente mas deixe editar; toda ação que altera dado pode ser desfeita ou avisa claramente que não pode; nunca tome decisão irreversível pela pessoa.
  • Design não é decoração: sem enfeite que não ajude a tarefa (ilustração no lugar de dado, animação sem função, gradiente que compete com a informação). Cor, espaço e tipografia servem à hierarquia. Beleza é consequência de clareza.

9.3 Estados da interface

Nenhuma tela está pronta enquanto os cinco estados não estiverem desenhados e implementados — o estado “com dados” é só um deles.

Estado Pergunta que responde Componente
Carregando O sistema está trabalhando? .mds-loader, .mds-loader-box, .mds-progress--bar/--circle
Vazio Por que não há nada aqui e o que faço? .mds-empty-state
Erro O que falhou e como resolvo? .mds-alert--danger ou EmptyState com ação “Tentar novamente”
Sucesso Deu certo? Toast (ver lacuna abaixo), .mds-btn--success, tela de conclusão
Com dados Estado principal O componente da tela

Carregando

  • Nunca deixe o usuário olhando tela parada sem saber se travou. Escopo: global (página inteira → loader centralizado), da área (.mds-loader-box sobre o painel/tabela; o resto segue utilizável), inline (botão .mds-btn--loading).
  • Diga o que carrega, em caixa de sentença e sem pronome: “Gerando relatório…”, “Carregando viagens…” — nunca “Por favor, aguarde enquanto carregamos…”.
  • Desabilite a ação em andamento (evita despacho duplo). Prefira barra de progresso a spinner quando o sistema sabe quanto falta.
  • Skeleton não existe (nem em CSS nem no Angular): use .mds-loader-box sobre a área. Não invente .mds-skeleton.

Vazio

  • Estrutura fixa de cima para baixo: ícone/ilustração ligado ao contexto → título (caixa de título) → descrição (por quê/como resolver, caixa de sentença) → ação. Título e descrição são obrigatórios; ilustração sozinha não explica nada; nunca “Ops, nada por aqui”.
  • Três vazios diferentes: primeiro uso (ação = criar: “Subir Arquivo”), sem resultado do filtro (ação = Limpar Filtros, não criar), tudo em ordem (“Nenhum Alerta Pendente” + “Ir para o Dashboard”).

Erro

  • Três escalas: campo (no campo, abaixo dele), ação (Alert no contexto, ou Toast se não exigir correção), tela (estado de erro ocupando a área, com “Tentar novamente” — proposta).
  • Fórmula: o que aconteceu + como resolver, sem culpa — “CPF inválido. Insira apenas números.”, nunca “Você digitou o CPF errado.” / “Ocorreu um erro.”
  • Preserve tudo que o usuário digitou. Mantenha o erro visível até ser resolvido. Erro de campo aparece ao sair do campo, não a cada tecla.

Sucesso

  • Proporcional ao impacto: ação pequena → Toast “Alterações salvas.”; conclusão de fluxo (despachar, registrar entrega) → botão Success + estado de conclusão; ação em massa → resumo completo “12 cargas despachadas. 2 com falha.”

9.4 Feedback ao usuário

Regra de ouro: o peso do feedback é proporcional ao impacto — quanto mais a pessoa precisa agir, mais ele interrompe e permanece visível. Um erro que some sozinho em 4 s pode ser uma carga não despachada que ninguém viu.

Escolha o componente respondendo na ordem e parando no primeiro “sim”:

  1. Mensagem sobre um campo de formulário? → mensagem no próprio campo (.mds-input--danger + .mds-input__helper).
  2. Precisa de decisão antes de continuar (confirmar exclusão, escolher)? → Modal (.mds-float-panel--modal).
  3. O problema precisa continuar visível até ser resolvido (falha na emissão, manutenção atrasada)? → Alert (.mds-alert--{neutral|info|warning|danger|success}).
  4. Só confirma o resultado de uma ação, sem nada a fazer? → Toast.
  5. Explicação curta de ícone/sigla/dado? → Tooltip (.mds-tooltip).
  6. Não há dados? → EmptyState.
Tipo (Alert) Cor Quando usar
Erro Danger (vermelho) Bloqueia a operação — falha na emissão de nota
Aviso Warning (amarelo) Requer cautela, não bloqueia — veículo com manutenção atrasada
Sucesso Success (verde) Confirma conclusão — rota otimizada
Informação Info (azul) Contexto útil, sem urgência — nova versão do manifesto disponível
Neutro sem cor semântica Aviso genérico, sem peso semântico
  • A cor nunca é o único sinal: acompanhe sempre com texto e, quando couber, ícone (parte dos operadores não distingue vermelho de verde; o sol no pátio apaga contraste sutil). Vermelho é reservado para erro — para destacar “importante”, use aviso.
  • Alert: fica no contexto do problema (topo da área afetada, não num canto distante); dispensável só quando ignorar não tem consequência; um por área (vários problemas → uma lista dentro de um Alert). Botão de ação que leva a tela de resolução usa reticências (“Configurar impressora…”).
  • Toast: no máximo uma frase curta, sem ação crítica, sem tirar o foco; nunca o único registro de erro que exige correção. (proposta) sucesso/info somem sozinhos, erro permanece até ser dispensado; um por vez, o resto em fila.
  • Modal: só para interromper (confirmação crítica, decisão, detalhe que pede foco total); sempre com saída clara (Cancelar e ×); nunca abra modal sobre modal — fluxo longo usa Drawer. (proposta) foco preso dentro, Esc fecha, foco volta ao elemento de origem.
  • Tooltip: descreve ícone sem texto visível; nunca repete o rótulo visível; nunca carrega informação essencial ou ação (não aparece em toque); sem ponto final.
  • Lacuna conhecida — Toast: existe só no Figma; não há .mds-toast nem <mds-toast>. A aproximação prevista é <mds-alert [fixed]="true" [dismissible]="true"> (.mds-alert fixo e dispensável). Não invente a classe; sinalize no ticket que a tela usa a aproximação.

9.5 Ações destrutivas e confirmação

Regra de ouro: o atrito da confirmação é proporcional ao custo de desfazer. Reversível → sem confirmar. Irreversível → confirmação explícita dizendo o que será perdido. Confirmar tudo faz o operador clicar “OK” sem ler.

Nível de atrito Quando O que fazer
1. Reversível, baixo impacto Recuperável fácil, afeta só o próprio usuário Executa direto + Toast. (proposta) oferecer “Desfazer” por alguns segundos
2. Destrutivo e limitado Apaga/cancela um item; perda grande mas isolada (excluir rota, cancelar agendamento) Modal de confirmação
3. Irreversível, em massa ou com impacto em outros Não recupera, ou afeta muitos itens/pessoas Modal com a consequência explícita; (proposta) nos casos graves, exigir digitar o nome/número do item

Anatomia da modal de confirmação (sempre estas partes):

  1. Título: a pergunta com ação + objeto, caixa de título, termina em “?” → Excluir Rota?
  2. Corpo: o que será perdido, com números e nomes, e se dá para desfazer; cite impacto em outras pessoas quando houver → “A rota RT-2041 e seus 12 pontos de parada serão removidos. Essa ação não pode ser desfeita.”
  3. Saída: Cancelar, estilo secundário. Confirmação: repete a ação, .mds-btn--danger → Excluir Rota. Nunca “Sim”/“Não”/“OK”; sem reticências no botão de confirmação.
  • Fechar (×, Esc, clique no backdrop) equivale a Cancelar — nunca confirma. Uma decisão por modal. Sem tom de ameaça, caixa alta ou exclamação: a seriedade vem do conteúdo. (proposta) foco inicial em Cancelar, para Enter sem pensar não destruir nada.
  • Vocabulário: Excluir = apaga de forma definitiva; Cancelar = interrompe algo em andamento/criado e mantém histórico; Remover = tira da lista/vínculo sem apagar o item (verbo ainda a validar com Produto). Não misture os três.
  • Prefira alternativas a excluir quando há histórico/auditoria/obrigação fiscal: motorista com viagens → Inativar Motorista (proposta); carga que já andou → Cancelar Carga; documento fiscal emitido → não oferecer exclusão, emitir o cancelamento/correção previsto em lei.
  • Posição na tela: a ação destrutiva nunca é o primary da tela; usa Danger e peso visual menor que a principal. Em menu de ações: no fim, separada por divisor, em cor de perigo; frequentes (Editar, Duplicar) no topo. Em linha de tabela: uma ação → botão de ícone com Tooltip; duas ou mais → menu Mais opções com a destrutiva no fim. Afaste de ações de uso constante (toque/luva). O item de menu que abre a confirmação leva reticências (“Excluir Registro…”).
  • Em massa: selecionar não executa (ação em botão separado); a confirmação diz a quantidade (“Excluir 12 cargas?”); diga antes quais itens não podem ser afetados e por quê; depois mostre o resultado completo (“10 cargas excluídas. 2 mantidas.”) — nunca só “Concluído”.
  • Prevenir em vez de confirmar: ação inválida fica desabilitada com Tooltip explicando o motivo (“Carga em trânsito. Cancele a viagem para excluir.”); bloqueie por dependência e explique; respeite permissões (sem permissão, não aparece ou desabilita com motivo); mostre o impacto antes do clique.
  • Depois: sucesso → Toast “Rota excluída.” e o item some da lista imediatamente, usuário continua onde estava (volta à lista, não a uma tela vazia); falha → Alert no contexto, item continua na lista; parcial → resumo do que foi e do que falhou, com motivo.

9.6 Formulários e validação

Regra de ouro: só peça o que é necessário para concluir a tarefa agora; o resto pode ser preenchido depois. Antes de desenhar cada campo: o sistema já sabe? precisa agora? dá para escolher em vez de digitar?

  • Uma coluna por padrão; duas só para campos curtos e relacionados (CEP + número; data + hora). Rótulo sempre acima e visível — placeholder nunca substitui rótulo. Texto de apoio abaixo, curto, esmaecido; explica formato ou consequência, não repete o rótulo.
  • Ordem da tarefa, não do banco de dados. Agrupe campos relacionados sob cabeçalho de seção (SectionHeader: “Dados do motorista”, “Veículo”). Revelação progressiva: campos dependentes só aparecem depois da escolha (ConfigToggle, opção “Outro”). (proposta) acima de ~10 campos, use seções/etapas com indicação do que falta.
  • Obrigatório: realce amarelo (warning) + asterisco no rótulo + aria-required="true" (.mds-input--required); vermelho é só erro. Explique o asterisco no topo se houver mais de um. (proposta) se quase tudo é obrigatório, marque os opcionais com “(opcional)” e retire o amarelo.

Qual controle usar

Necessidade Controle Regra
Texto, número, dado com máscara (CPF, CNPJ, CEP, placa, moeda) Input Use a máscara pronta do tipo, nunca máscara customizada
Uma opção entre 2 a 5 Radio Sempre com uma opção pré-selecionada e título de grupo
Uma ou mais entre muitas Select com busca Múltipla mostra tags dentro do campo (só via Angular)
Marcar itens de uma lista Checkbox Cada caixa independente; só vale após confirmar
Ligar/desligar com efeito imediato Switch Sem botão de confirmar. Se só vale após “Salvar” → Checkbox
Ligar/desligar um bloco de campos ConfigToggle Campos dependentes aparecem logo abaixo
Data ou período DatePicker dd/mm/aaaa, com atalhos (Hoje, Últimos 7 dias)
Arquivo Uploader Mostre formatos e tamanho aceitos antes do envio (só via Angular)
Cadastrar item que falta num Select MicroForm (.mds-microform) Máx. 5 campos; o que foi digitado na busca entra no campo principal; ao confirmar, o item já fica selecionado
  • Input/Select/DatePicker: substantivo curto, caixa de sentença. Checkbox: positivo e diz o que acontece ao marcar (“Incluir seguro de carga”, não “Não deixar sem seguro”). Switch: rótulo estático, nunca alterna entre “Ativado/Desativado”, sem pergunta (“Rastreador GPS”). ConfigToggle: título em caixa de título + descrição em sentença. Placeholder de Select convida sem reticências (“Selecione o estado”).

Prevenção

  • Prefira prevenir: máscaras para dados formatados; restrinja o que não faz sentido (datas retroativas em agendamento futuro; campo dependente desabilitado até a origem ser preenchida); valores padrão inteligentes; placeholder com formato quando a máscara não deixa claro (ABC-1234, 00.000-000); busca no Select em listas longas. Nunca bloqueie a digitação por regra de validação — o campo não “engole” o que a pessoa digita.

Quando validar

Momento Regra
Enquanto digita Não mostra erro (exceção: requisito que se cumpre em tempo real, como força de senha)
Ao sair do campo Valida e mostra o erro daquele campo
Ao enviar Valida tudo; (proposta) foco no primeiro campo com erro e resumo se houver mais de um
Depois de corrigir O erro some assim que o valor fica válido
  • Mensagem = o que está errado + como corrigir, no próprio campo, abaixo dele, em vermelho, sem culpa. Nunca “inválido” sozinho: “Informe a placa do veículo.”, “CPF inválido. Insira apenas números.”, “Mínimo de 8 caracteres.”, “Já existe um motorista com este CPF.”, “O peso máximo por carga é 32.000 kg.”.
  • Erro do servidor: de um campo → no campo, com foco nele; do envio como um todo (falha de conexão) → Alert no topo do formulário (“Falha ao salvar a carga CG-1042. Verifique a conexão e tente novamente.”). Nos dois casos mantenha os dados e devolva o botão ao estado normal para nova tentativa.

Ações do formulário

  • Um único botão primary com o verbo da tarefa (Salvar, Emitir Nota, Agendar Doca); Cancelar ao lado em estilo secundário, nunca mais chamativo que o de salvar. Botões fixos no rodapé do Drawer/Modal. Enquanto envia: botão em carregamento (“Salvando…”) e inerte (sem envio duplo).
  • Não desabilite o enviar só porque o formulário está inválido sem explicar (proposta: deixe clicar e mostre os erros). (proposta) Com alterações não salvas, confirme antes de sair: Descartar alterações? → Continuar Editando · Descartar.
Situação Onde colocar Por quê
Cadastro/edição completa Drawer (.mds-float-panel--drawer) Mantém tabela/mapa visível ao fundo, preservando o contexto
Poucos campos e uma decisão Modal (.mds-float-panel--modal) Foco total; a pessoa volta logo
Item que falta em um Select MicroForm Cadastra sem sair do fluxo
Configuração de recurso ConfigToggle na própria tela Campos só aparecem quando o recurso é ligado

Estados de campo

Estado Como se apresenta
Padrão Borda neutra, fundo surface; placeholder só exemplifica formato, sem reticências
Foco Borda realçada em primary; rótulo ganha destaque
Obrigatório Realce amarelo + asterisco + aria-required (.mds-input--required)
Preenchido Borda de maior peso visual (.mds-input--active) — confirma que o dado foi assimilado
Desabilitado Opacidade reduzida, cursor de bloqueio; rótulo legível; (proposta) explique o motivo em tooltip/apoio
Somente leitura Fundo e texto esmaecidos, valor visível
Erro Borda e mensagem em vermelho (.mds-input--danger), mensagem específica

Acessibilidade

  • Rótulo associado ao campo (clicar no texto foca; em Radio/Checkbox, marca). Erro nunca só por cor (texto + ícone/borda). Ordem de tabulação = ordem visual. Alvo de toque confortável para luva/tablet. (proposta) mensagem de erro ligada ao campo com aria-describedby.

9.7 Navegação e hierarquia

Regra de ouro: cada tipo de navegação tem um lugar e um componente; não misture (páginas de módulos diferentes no mesmo submenu, ação no lugar de destino, produto dentro do menu do módulo). A pessoa sempre sabe onde está, o que pode fazer e como chegar a outro lugar.

Hierarquia, do mais amplo ao detalhe: Produto (AppLauncher) → Contexto/unidade (.mds-menu-business) → Módulo (menu nível 1) → Página (menu nível 2) → Aba → Seção (SectionHeader).

Preciso… Use
Trocar de produto (TMS, Roteirizador, Torre de Controle) AppLauncher na topbar (produtos não licenciados separados)
Trocar de unidade/empresa Alternador de contexto .mds-menu-business (muda dados, permissões, módulos)
Outro módulo Menu lateral, nível 1 (.mds-menu + .mds-menu-item)
Outra página do módulo Menu lateral, nível 2 (.mds-menu__group, item --sm)
Outro conteúdo da mesma página Tabs (.mds-nav-tabs); subpágina tem rota própria
2–3 visões exclusivas simples, sem rota .mds-control-group
Subir um nível Breadcrumb (.mds-breadcrumbs)
Executar algo Botão ou Dropdown — ação não é destino
Dividir a página em blocos SectionHeader (só Angular, header[mdsSectionHeader])
Escolher período DateNavigator (disponibilidade) ou DatePicker (dado)
  • Máximo de dois níveis no menu (módulo › página) e no Dropdown (menu › submenu). Se sente falta de um terceiro, o problema é a estrutura da informação: reagrupe, use Tabs ou outro módulo. Nunca aninhe mais.
  • Menu lateral: nível 1 = módulo, com ícone e maior peso; nível 2 = só páginas daquele módulo, menores e recuados. Rótulos em caixa de título, curtos (“Dashboard”, não “Ver o Dashboard de indicadores”). Item ativo sempre destacado (fundo claro de primary, .mds-menu-item--active); módulo com página ativa abre sozinho. Navegação utilitária (Automação, Preferências, Integrações, Cadastros gerais) ancorada na base, separada dos módulos operacionais.
  • Três modos do menu: expandido (256 px, ícone + rótulo), compacto (64 px, só ícones com Tooltip em cada um), flutuante (mobile/telas reduzidas, sobrepõe o conteúdo, .mds-menu--floating).
  • Topbar (.mds-top-bar, 64 px, fixa e visível em todas as telas): marca + nome do produto ativo à esquerda; pesquisa global (cargas, veículos, motoristas); utilitários (notificações, ajuda, seletor de produtos, perfil) — (proposta) em ordem fixa, do mais ao menos frequente. Botão só-ícone sempre com Tooltip. Um único lugar para trocar a unidade (o perfil pode mostrá-la, não trocá-la).
  • Breadcrumb só em páginas com 3+ níveis (em estrutura plana, não use). Último item = página atual, sem link; anteriores são links; nomes curtos; a partir de 4 itens colapsa o meio em “…” (caractere único).
  • PageHeader (.mds-page-title + .mds-page-options): um título por página, caixa de título, igual ao item de menu; ação principal (primary, verbo) junto ao título — um único destaque por tela; utilitários à direita (atualizar ↻, filtros/configurações, Mais opções ⋮) só ícone com Tooltip; busca rápida com placeholder “Pesquisar por código” (Pesquisar, nunca “Buscar”).
  • Tabs: só conteúdos do mesmo nível (nunca trocar módulo/produto); rótulos substantivos em caixa de título, sem ponto; a mais importante à esquerda; exatamente uma ativa; ícone em todas ou em nenhuma; modo compacto só-ícone exige Tooltip (aba sem ícone precisa manter o rótulo).
  • SectionHeader: título em caixa de título, descrição opcional em sentença; tamanho reflete a profundidade (seção mestra > subseção); se uma seção tem descrição, todas têm. Dropdown: item pai curto e categórico, seta para submenu sem reticências; frequentes no topo, destrutivas no fim separadas por divisor em danger; item que abre confirmação/janela leva reticências.
  • Localização e estado: item de menu ativo, aba ativa e último item do breadcrumb dizem a mesma coisa. (proposta) URL é o estado (módulo/página/aba na URL; link compartilhável; voltar do navegador funciona). Item sem permissão não aparece (ou aparece desabilitado com o motivo). Ao carregar a próxima página, menu e cabeçalho ficam no lugar; só a área de conteúdo carrega.
  • Nome de destino é substantivo, nome de ação é verbo (“Agendamentos” leva a uma lista; “Novo Agendamento” faz algo) — não misture no mesmo menu. Título da página = item de menu = (versão curta no) breadcrumb.

Hierarquia visual na página

  • Uma ação principal por tela, junto ao título; as demais secundárias ou em Mais opções. Ordem de leitura = importância (mais crítico primeiro, à esquerda e no topo). Um título, muitos subtítulos — não pule níveis. Peso visual proporcional à importância (módulo > página; seção mestra > subseção).
  • Ícones ajudam, não substituem texto na navegação principal; ícone sozinho só em modo compacto, sempre com Tooltip.

9.8 Checklist de revisão (auto-verificação antes de entregar)

  • Sei dizer o problema real que a tela resolve, sua ação principal em uma frase e há no máximo um botão primary?
  • Os cinco estados (carregando, vazio, erro, sucesso, com dados) estão contemplados? O carregamento diz o quê; o vazio tem título + descrição + ação?
  • Escolhi o componente de feedback pela árvore de decisão (campo → Modal → Alert → Toast → Tooltip → EmptyState)? Erro que exige ação não depende só de Toast? Nada depende só de cor?
  • Ação destrutiva: atrito proporcional, confirmação com título-pergunta + botão que repete a ação (Danger) + Cancelar, nunca “Sim/OK”?
  • Formulário: uma coluna, rótulo visível acima, máscara/tipo certo, validação ao sair do campo, mensagem “o que + como corrigir”, dados preservados em erro, envio com botão inerte em carregamento?
  • Navegação: no máximo dois níveis, título = item de menu, item ativo/aba/breadcrumb concordam, botão só-ícone com Tooltip, substantivo para destino e verbo para ação?
  • Usei só componentes, tokens e classes existentes (nada de .mds-toast/.mds-skeleton/estilo local “quase igual”)? Se abri exceção, sei justificar?

10. Component Behavior

Para que serve e como se comporta cada um dos 46 componentes do MDS, extraído das páginas de componentes do docs-site (vindas do Notion), sem exemplos de escrita (seção 8), anotações internas nem API de desenvolvedor. A classe CSS exata de cada um está no Component Class Index da skill mds-style. Em conflito com as seções 2 a 9, valem as seções 2 a 9.

Índice: qual componente usar

Componente Grupo Para que serve
Button Entradas Botões iniciam ações instantâneas ou permitem que o usuário faça escolhas em diálogos.
Checkbox Entradas O Checkbox permite que o usuário selecione um ou mais itens de uma lista, ou alterne entre dois estados mutuamente exclusivos (ativado/desativado) para uma única opção independente.
ColorPicker Entradas O ColorPicker permite ao usuário selecionar uma cor a partir de uma paleta pré-estabelecida.
ConfigToggle Entradas O ConfigToggle é um componente de controle utilizado para habilitar ou desabilitar funcionalidades ou blocos de configuração.
DatePicker Entradas O DatePicker permite ao usuário selecionar uma data específica ou um intervalo de datas através de uma interface de calendário.
Input Entradas O Input permite que o usuário insira e edite textos, números ou dados específicos em um formulário.
MicroForm Entradas O MicroForm é um formulário simplificado embutido em um componente de seleção (Select/Autocomplete).
Radio Button Entradas O Radio Button permite que o usuário selecione apenas uma opção de um conjunto de escolhas mutuamente exclusivas.
Select / Autocomplete Entradas O Select permite ao usuário escolher uma ou mais opções de uma lista predefinida.
Toggle/Switch Entradas O Switch é um controle binário utilizado para alternar entre dois estados opostos (ligado/desligado).
Uploader / AnexoUpload Entradas O AnexoUpload permite que o usuário envie um ou mais arquivos para o sistema.
AnexoItem Exibição de dados O AnexoItem é utilizado para exibir e gerenciar arquivos anexados ao sistema.
Avatar Exibição de dados O Avatar é uma representação visual de um usuário ou entidade.
Badge Exibição de dados O Badge é um pequeno indicador visual utilizado para exibir contagens, notificações ou estados de status associados a um elemento específico da interface.
BoardPipe Exibição de dados O BoardPipe é a unidade estrutural do Kanban que agrupa cartões (cards) por etapas de um processo.
ControlGroup Exibição de dados O ControlGroup agrupa uma série de elementos de entrada e ação relacionados em uma única linha contínua.
DynamicCard Exibição de dados O DynamicCard é um contêiner modular projetado para exibir registros de forma estruturada.
LegendBar Exibição de dados A LegendBar é uma barra de utilidade fixada no rodapé da interface que fornece o significado de ícones, cores e símbolos utilizados na tela atual.
LegendItem Exibição de dados O LegendItem é o componente atômico projetado exclusivamente para compor a LegendBar.
PageHeader Exibição de dados O PageHeader é o cabeçalho padronizado que se posiciona no topo das páginas de módulos e seções.
Popover Exibição de dados O Popover é um painel flutuante que exibe conteúdos informativos ou interativos relacionados a um elemento específico.
ScoreMeter Exibição de dados O ScoreMeter é um indicador de medidor de pontuação (CSAT/Satisfação) que exibe visualmente um valor dentro de uma escala de 0 a 100.
SectionItem Exibição de dados O SectionItem é um componente utilizado para exibir pares de informações estruturadas (rótulo e valor).
Table Exibição de dados A Table organiza conjuntos de dados em linhas e colunas, facilitando a visualização, comparação e análise de informações estruturadas.
Totalizer Exibição de dados O Totalizer é um componente de visualização de dados utilizado para exibir métricas e indicadores de desempenho de forma destacada.
Alert Feedback O Alert destaca informações essenciais ou mudanças de estado no sistema.
EmptyState Feedback O EmptyState é utilizado para preencher telas ou seções onde não existem dados para exibição no momento.
Loading Feedback O Loading é um indicador visual que comunica o processamento de uma tarefa ou o carregamento de conteúdos em andamento.
PasswordStrength Feedback O PasswordStrength monitora e exibe o nível de segurança da senha digitada pelo usuário em tempo real.
Toast/Notification Feedback O Toast fornece feedback breve sobre uma operação do sistema em uma pequena janela sobreposta.
Tooltip Feedback O Tooltip é uma pequena etiqueta flutuante que aparece ao passar o mouse ou focar em um elemento.
AppLauncher Navegação O AppLauncher é um seletor de produtos que permite a alternância rápida entre os diferentes sistemas do ecossistema Mobiis.
Breadcrumb Navegação O Breadcrumb exibe o caminho hierárquico da página atual em relação à estrutura do sistema.
CardItem Navegação O CardItem é um componente interativo utilizado para listar opções de ação, links ou modos de visualização.
DateNavigator Navegação O DateNavigator é um seletor de datas horizontal que permite a navegação e visualização de disponibilidade por períodos (semanal ou mensal).
Dropdown / Menu flutuante Navegação Um menu suspenso exibe uma lista de ações ou opções em um painel temporário.
Menu Lateral / Sidebar Navegação o Menu/Sidebar é o eixo principal de navegação do sistema, organizando módulos e funcionalidades em uma estrutura hierárquica.
MenuItem Navegação O MenuItem é o elemento base para a construção de menus contextuais (Dropdowns) e da Navegação Global do sistema.
SectionHeader Navegação O SectionHeader é um cabeçalho utilizado para identificar e separar seções de conteúdo em uma página.
TabNav / Tabs Navegação O componente Tabs organiza conteúdos relacionados em grupos distintos, permitindo a alternância entre eles sem sair da página atual.
Topbar Navegação A Topbar é a barra de utilitários superior que fornece contexto global e ferramentas de navegação persistentes.
Box Superfícies O Box é um contêiner básico utilizado para agrupar elementos relacionados, criando blocos lógicos de informação.
Collapse Superfícies O Collapse oculta ou revela conteúdos secundários em áreas expansíveis.
Drawer Superfícies O Drawer é um painel deslizante que emerge da lateral da tela para fluxos de entrada de dados ou navegação.
Modal Superfícies A Modal é uma janela centralizada que interrompe o fluxo do usuário para exigir uma ação ou fornecer informações detalhadas.
Toolbar Superfícies O Toolbar é uma barra de ferramentas persistente que aparece para indicar que a interface entrou em um modo de operação específico (ex: edição, personalização ou seleção em massa).

Entradas

Button

Variante Uso Recomendado Regra de UX Writing
Control/Default Opções ou ações neutras. Use verbos diretos: Editar, Visualizar.
Primary Ação principal da página ou formulário (máx. 1 por tela). Foque no objetivo: Salvar, Continuar.
Primary Outline Ações secundárias importantes, mas não essenciais. Use para ações de suporte: Exportar, Imprimir.
Danger Ações destrutivas ou irreversíveis. Seja explícito: Excluir Registro, Cancelar Carga.
Success Conclusão de fluxos positivos e finais. Use para fechamento: Registrar Entrega.
Text/Transparent Ações de baixa prioridade ou botões de ícone. Rótulos curtos ou apenas ícones com tooltip.
  • O rótulo deve ter preferencialmente uma ou duas palavras.
  • Use verbos no infinitivo que descrevam a ação.
  • Caixa de Título: Todos os botões devem seguir a regra de capitalização de título.
  • Uso de Reticências (…): Se o botão abrir uma nova janela ou exigir mais entradas antes de concluir a ação, use reticências.
  • Evite Repetição: Se o título da seção é “Motoristas”, o botão não precisa dizer “Adicionar Motorista”, apenas Adicionar.

Checkbox

  • Independência: Cada caixa de seleção opera de forma independente; selecionar uma opção não deve desmarcar outra na mesma lista.
  • Rótulos Claros: O texto associado deve ser positivo e descrever claramente o que acontece quando marcado.
  • Use Caixa de Sentença para os rótulos. Apenas a primeira letra e nomes próprios em maiúsculas.
  • Agrupamento: Se houver uma lista longa, use um Checkbox “Mestre” no topo para permitir “Selecionar todos”.
  • Feedback Imediato: A alteração do estado deve ser visualmente clara, mas a aplicação da ação (como excluir itens selecionados) geralmente requer um botão de confirmação separado.

ColorPicker

  • Gatilho de Seleção: O componente deve exibir a cor atualmente selecionada no botão de ativação.
  • Paleta de Cores (Swatches): As cores devem ser organizadas de forma lógica (por matriz ou tonalidade) em um painel flutuante (Popover).
  • Feedback de Seleção: A cor escolhida deve ser destacada visualmente no painel (ex: ícone de check sobre o quadro da cor) para confirmar a ação.
  • Acessibilidade: Garanta que as cores oferecidas na paleta possuam contraste suficiente quando utilizadas como fundo para textos ou ícones.
  • Se o campo possuir um rótulo, seja conciso.

ConfigToggle

  • Estado Binário: Utilize um Switch (alternador) posicionado à direita para indicar o estado Ativado/Desativado.
  • Título de Controle: Deve descrever claramente a ação ou recurso. Use Caixa de Título.
  • Descrição de Apoio: Explique o que acontece ao ativar a opção. Use Caixa de Sentença.
  • Expansão Condicional: Ao ativar o toggle, os campos relacionados (Selects, ColorPickers, etc.) devem aparecer imediatamente abaixo, preferencialmente com uma animação suave de transição.
  • Pré-visualização (Preview): Sempre que a configuração resultar em uma mudança visual (como um ícone colorido), ofereça um elemento de “Pré-visualização” para feedback imediato.

DatePicker

  • Formatos de Data: Utilize o formato padrão regional (DD/MM/AAAA). O campo deve ser preenchido automaticamente ao selecionar no calendário.
  • Seleção de Período (Range): Para relatórios ou filtros de viagem, utilize a variação que permite selecionar “Data Inicial” e “Data Final” em um único fluxo.
  • Datas Relativas: Sempre que possível, ofereça atalhos para períodos comuns (ex: Hoje, Ontem, Últimos 7 dias). Isso acelera a operação em dashboards.
  • Rótulos (Labels): Devem ser claros sobre qual data está sendo solicitada. Use Caixa de Sentença.
  • Restrições: Desabilite datas que não fazem sentido para o contexto (ex: impedir a seleção de datas retroativas para um agendamento futuro).

Input

  • Rótulos Claros (Labels): Use nomes curtos e diretos em Caixa de Sentença acima do campo. Nunca substitua o rótulo pelo texto de marcação (placeholder).
  • Texto de Marcação (Placeholder): Use apenas para exemplificar o formato esperado. Não utilize reticências (…) no final, conforme as diretrizes do sistema.
  • Mensagens de Erro: Devem ser específicas e indicar como corrigir o problema. Evite tons de culpa.
  • Máscaras de Campo: Utilize máscaras visuais para dados formatados (datas, telefones, documentos) para reduzir erros de digitação.
  • Estados de Foco: O campo deve indicar visualmente quando está ativo para recepção de dados.

MicroForm

  • Gatilho de Ação: Exiba a opção de cadastro no final da lista de resultados do Select quando a busca não encontrar o item desejado.
  • Limitação de Campos: Limite rigoroso de até 5 campos. Devem ser incluídos apenas parâmetros estritamente necessários para viabilizar o fluxo atual.
  • Cabeçalho de Contexto: O valor digitado pelo operador no campo de busca deve ser herdado automaticamente pelo campo de identificação principal do MicroForm (ex.: Razão Social).
  • Feedback de Ajuda: Use textos curtos para informar que dados complementares podem ser editados posteriormente nas configurações.
  • Seleção Automática: Ao acionar o botão de confirmação, o MicroForm fecha-se imediatamente e o registo recém-criado assume o estado selecionado no campo de origem.
  • Ações Claras: Utilize Cancelar e Adicionar (ou Salvar) para fechar o fluxo.

Radio Button

  • Exclusividade: Selecionar uma nova opção desmarca automaticamente a anterior.
  • Seleção Padrão: Sempre apresente um dos botões pré-selecionado por padrão para evitar estados inválidos ou indecisão do usuário.
  • Agrupamento: As opções devem estar logicamente relacionadas sob um título de grupo claro.
  • Os rótulos devem ser curtos e positivos. Use Caixa de Sentença.
  • Listas Curtas: Utilize Radio Buttons para conjuntos de 2 a 5 opções. Se houver mais, considere um Dropdown para reduzir a carga visual.
  • Interatividade: O clique deve ser permitido tanto no círculo quanto no texto do rótulo para facilitar o uso em dispositivos móveis ou tablets de armazém.

Select / Autocomplete

  • Busca Integrada: O campo deve filtrar as opções em tempo real conforme o usuário digita.
  • Texto de Marcação (Placeholder): Indique que o campo é interativo. Não use reticências.
  • Feedback de Busca: Se a digitação não encontrar resultados, exiba a mensagem: Nenhum resultado encontrado.
  • Rótulos (Labels): Devem ser curtos e descritivos. Use Caixa de Sentença.
  • Seleção Múltipla: Se o componente permitir escolher mais de um item, utilize tags (chips) dentro do campo para indicar o que já foi selecionado.

Toggle/Switch

  • Efeito Imediato: Use apenas quando a alteração não exigir um botão de confirmação posterior.
  • Rótulos Diretos: O rótulo deve descrever o que o Switch faz quando está “ligado”. Use Caixa de Sentença.
  • Não use rótulos que mudam conforme o estado (ex: não troque “Ativado” por “Desativado”). O rótulo deve ser estático e o componente indica o estado.
  • Neutralidade: Evite perguntas.

Uploader / AnexoUpload

  • Área de Drop: Deve ser visualmente distinta (borda tracejada) para indicar que é uma zona interativa. Use a instrução: Arraste os arquivos aqui.
  • Ação Manual (Botão): O botão deve ser claro e direto. Use Caixa de Título.
  • Informação de Suporte: Use textos curtos em Caixa de Sentença para conectar as ações.
  • Formatos Suportados: Exiba claramente as extensões permitidas no rodapé do componente para evitar frustração do usuário ao tentar subir arquivos inválidos.
  • Múltiplos Arquivos: Se o componente permitir mais de um arquivo, a interface deve sinalizar que a seleção múltipla está ativa.

Exibição de dados

Avatar

  • Identificação Visual: Priorize o uso de fotos reais para usuários diretos. Caso a imagem não esteja disponível, utilize as iniciais do nome (máximo de duas letras).
  • Consistência: Utilize o formato circular como padrão para usuários humanos e formatos alternativos (como quadrados arredondados) se precisar diferenciar entidades, como transportadoras ou filiais.
  • Indicadores de Estado: O Avatar pode ser acompanhado de um pequeno selo (badge) para indicar disponibilidade ou status (ex: Online, Em Viagem, Indisponível).
  • Acessibilidade: Sempre forneça um texto alternativo (alt text) com o nome da pessoa representada para leitores de tela.

No CSS, o avatar padrão é quadrado arredondado (seção 6); para pessoa, use .mds-avatar--rounded (círculo).

Badge

  • Simplicidade no Conteúdo: Use apenas números ou palavras curtíssimas (ex: “Novo”, “Lido”).
  • Se o número for maior que 99, use o padrão “99+” para evitar que o componente cresça demais e quebre o layout.
  • Hierarquia Visual: Posicione o Badge geralmente no canto superior direito do elemento pai (como um ícone de notificações ou uma aba de “Cargas”).
  • Se o Badge estiver sobre um ícone de “Caminhão”, não escreva “Caminhão: 5”. Use apenas “5”. O contexto visual já explica ao que o número se refere.

BoardPipe

  • Título (Obrigatório): Identifica o status da etapa. Use Caixa de Título.
  • Descrição (Opcional): Texto curto em Caixa de Sentença que explica a função ou critério daquela coluna.
  • Ícone de Apoio: Posicionado ao lado do título para reforçar o reconhecimento visual (ex: ícone de relógio para “Atrasados”).
  • Personalização de Cor: O usuário pode definir uma cor de destaque para o topo do Pipe.
    • Dica UX: Garanta que a cor escolhida mantenha o contraste necessário com o texto (branco ou preto) para legibilidade.

ControlGroup

  • Unidade Visual: Os elementos dentro do grupo devem compartilhar bordas internas (removendo o arredondamento de cantos que se tocam) para parecerem uma única peça.
  • Componentes Suportados: Pode combinar Buttons, Inputs, Selects e demais inputs.
  • Ordem Lógica: Posicione a entrada de dados principal à esquerda e a ação ou seletor de apoio à direita.
  • Consistência de Altura: Todos os componentes dentro de um ControlGroup devem ter exatamente a mesma altura para não quebrar a linha visual.
  • Como o espaço é reduzido, evite rótulos longos nos botões agrupados.

DynamicCard

  • Tags de Apoio (Cabeçalho): Localizadas no topo, servem para categorização rápida (ex: Tipo de frete, Origem do cadastro). Use etiquetas curtas.
  • Identificação Principal (Título): O dado mestre do card (ex: Código Identificador). Deve estar em Caixa de Título, negrito e maior destaque visual.
  • Informações Primárias: Dados essenciais que nunca mudam de posição, garantindo a ancoragem visual (ex: Rota/Origem-Destino).
  • Informações Secundárias de Apoio: Campos dinâmicos mapeados conforme a necessidade da etapa. Podem ser ocultados para reduzir a densidade visual.
  • Mensagens de Alerta: Espaço reservado para notificações críticas de sistema que exigem atenção imediata.
  • Totalizadores e Ações (Rodapé): Agrupa indicadores numéricos (anexos, mensagens), o usuário responsável e o menu de opções (Popover).

LegendBar

  • Estados de Visibilidade:
    • Minimizada: Exibe apenas um gatilho (ícone de ajuda ou texto “Legenda”). Expande-se ao passar o mouse (hover) ou ao ser clicada.
    • Fixada: Permanece aberta no rodapé, empurrando o conteúdo da página para cima (ou sobrepondo-se com transparência, conforme o layout).
  • Organização dos Itens: As legendas devem ser agrupadas por categoria. Cada item deve combinar o elemento visual (cor/ícone) seguido pelo seu significado.
  • Escrita (UX Writing): Use Caixa de Sentença para as descrições das legendas. Seja extremamente breve.
  • Posicionamento: Sempre na base inferior da tela (bottom), alinhada à direita ou centralizada, dependendo da densidade de informações do rodapé.

LegendItem

  • texto de Uso: O LegendItem não deve ser utilizado de forma isolada na interface; ele deve sempre estar contido dentro de uma LegendBar para garantir o alinhamento e o comportamento de exibição (fixo ou minimizado).
  • Identidade Visual: O elemento gráfico do item (círculo, ícone ou tag) deve ser uma réplica exata do que o usuário vê nos cards, tabelas ou mapas para evitar confusão.
  • Escrita (UX Writing):
    • Use Caixa de Sentença.
    • Mantenha o texto extremamente curto (preferencialmente até 3 palavras).
    • Não utilize ponto final, facilitando a leitura em linha dentro da barra.
  • Título da Página (Identificação):
    • Deve indicar de forma clara o nome da tela ou do módulo.
    • Use Caixa de Título com fonte de maior destaque visual (ex: classe h1 ou h2 do componente Text).
  • Ação Principal (CTA Primário):
    • Posicionada logo ao lado do título (à esquerda) para ser encontrada rapidamente.
    • Deve ser um botão de alto destaque (cor primária) acompanhado de ícone intuitivo (ex: + para criação).
    • Use Caixa de Título e verbos de ação diretos no infinitivo.
  • Ações Secundárias e Utilitários (Direita):
    • Atualizar dados: Botão de ícone (refresh) para recarregar a visualização sem recarregar a página.
    • Configurações/Filtros Avançados: Botão de ícone (tune / sliders) para abrir opções de personalização da tela ou da tabela.
    • Mais Opções (Overflow): Menu de três pontos (more_vert) para ações secundárias menos frequentes.
  • Busca e Filtro Rápidos:
    • Campo de Busca (Input): Utilizado para busca rápida por texto. O texto de placeholder deve ser em Caixa de Sentença e instruir o parâmetro de busca sem reticências desnecessárias.
    • Botão de Filtro: Destaque de cor (como o amarelo da imagem) para aplicar ou abrir a gaveta de filtros ativos.

Navegação e hierarquia da página (título = item de menu, uma ação principal junto ao título): seção 9.7.

Popover

  • Conteúdo Rico: Utilize para exibir resumos, mini-formulários ou grupos de ações que exigem mais contexto do que um Tooltip permite.
  • Foco Contextual: O Popover deve estar visualmente ancorado ao elemento que o originou (geralmente através de uma “seta” ou proximidade imediata).
  • Interatividade: Pode conter botões de ação. Use Caixa de Título para os botões dentro do painel.
  • Não use textos longos. Se a informação for extensa, forneça um link para a página completa.
  • Fechamento: Deve possuir um comportamento claro de saída (clicar fora ou um botão de fechar, se necessário).

ScoreMeter

  • Crítico (Vermelho): Desempenho muito abaixo do esperado.
  • Ruim (Laranja): Necessita de melhorias imediatas.
  • Regular (Amarelo): Atende aos requisitos mínimos, mas com ressalvas.
  • Bom (Verde Claro): Desempenho satisfatório e dentro da meta.
  • Excelente (Verde Escuro): Supera as expectativas de qualidade.
  • Indicador de Valor (Pin): O marcador numérico deve flutuar abaixo da barra, apontando exatamente para a posição do valor na escala.
  • Cores Semânticas: A cor do rótulo, do ícone e do marcador deve ser idêntica à cor da faixa onde o valor se encontra.
  • Ícones de Sentimento: Utilize ícones de expressão (emojis ou faces lineares) para reforçar a classificação qualitativa.
  • Os rótulos das faixas devem ser palavras únicas ou expressões curtíssimas.

SectionItem

  • Rótulo (Label): Identifica o que é a informação. Deve ser curto e usar Caixa de Sentença.
  • Valor (Value): É o dado propriamente dito. Deve ter maior peso visual (ex: negrito ou cor mais escura) que o rótulo para facilitar a leitura.
  • Ícone de Apoio: Utilize ícones para categorizar visualmente o tipo de informação (ex: ícone de calendário para datas, ícone de cifrão para valores monetários).
  • Alinhamento: Em listas verticais, mantenha o alinhamento à esquerda. Em cartões de resumo, pode-se utilizar o layout lado a lado (rótulo à esquerda, valor à direita).
  • Não use frases completas nos rótulos.

Table

  • Cabeçalhos de Coluna: Devem ser extremamente curtos e usar Caixa de Título.
  • Alinhamento:
    • Textos: Alinhados à esquerda.
    • Números/Valores: Alinhados à direita (facilita a comparação de grandezas).
  • Estados Vazios: Se a tabela não possuir dados, use um Estado Vazio com uma mensagem clara e neutra.
  • Densidade: Utilize textos concisos para evitar o truncamento com reticências (…), que deve ser usado apenas em casos extremos de falta de espaço.
  • Ações em Linha: Botões dentro da tabela (como “Editar” ou “Excluir”) devem preferencialmente usar ícones com Tooltips para economizar espaço horizontal.
    • Ação Única: Se houver apenas uma ação possível (ex: apenas “Visualizar”), utilize um botão de ícone direto na linha com um Tooltip.
    • Múltiplas Ações: Quando houver duas ou mais ações, agrupe-as em um Dropdown acionado por um botão de “Mais Opções”.
    • Hierarquia no Menu:
      • Coloque as ações mais frequentes no topo (ex: Editar, Duplicar).
      • Ações destrutivas (ex: Excluir, Cancelar) devem ficar ao final da lista e, se possível, separadas por um divisor e destacadas com a cor de perigo (danger).
    • Rótulos dos Itens: Use Caixa de Título e verbos de ação curtos.
    • Uso de Reticências (…): Aplique a regra de reticências para itens que abrem modais ou diálogos de confirmação antes de concluir a tarefa.

Feedback

Alert

  • O texto deve ser curto. Se a mensagem for de erro, descreva o problema e, se possível, a solução.
  • Tom de Voz: Mantenha a neutralidade. Evite “Você” ou “Eu”.
  • Uso de Reticências: Se o alerta levar o usuário a uma nova tela de configuração para resolver o problema, o botão de ação deve usar reticências.
  • Hierarquia Visual: Use títulos em negrito dentro do alerta para destacar o tipo de mensagem (Erro, Aviso ou Sucesso) quando houver um texto descritivo longo abaixo.

EmptyState

  • Ilustração ou Ícone: Utilize um elemento visual centralizado que remeta ao contexto (ex: um ícone de “caixa” para falta de mercadoria).
  • Título (O que está acontecendo): Identifique o estado atual de forma direta. Use Caixa de Título.
  • Descrição (Por que e como resolver): Explique o contexto e dê uma sugestão. Use Caixa de Sentença.
  • Botão de Ação (Call to Action): Se possível, ofereça um caminho para criar o dado. Use Caixa de Título.
  • Evite mensagens de erro genéricas como “Ops, nada por aqui”. Seja técnico e útil.

Loading

  • Contextualização: Sempre que possível, informe o que está sendo carregado em vez de usar apenas um termo genérico.
  • Utilize Caixa de Sentença e evite o uso de pronomes ou artigos.
  • Uso de Reticências (…): Utilize reticências apenas se o carregamento for um processo demorado que indica uma espera ativa. No caso de spinners (ícones giratórios) pequenos em botões, a reticência é opcional.
  • Localização: * Global: Para carregamento de páginas inteiras.
    • Inline: Para ações específicas, como clicar em um botão de “Salvar”.
    • Skeleton: Para antecipar a estrutura de tabelas ou painéis de dados.

PasswordStrength

  • Barra de Progresso (Segmentada): A barra deve mudar de cor conforme a força aumenta.
    • Vermelho: Muito fraca / Fraca.
    • Amarelo/Laranja: Média.
    • Verde: Forte / Muito forte.
  • Checklist de Requisitos: Os critérios (números, letras, etc.) devem ser riscados ou receber um ícone de “concluído” (check) imediatamente após serem satisfeitos.
  • Feedback de Texto: Exiba o rótulo do nível de força atual (ex: Muito fraca) ao lado da barra para facilitar a interpretação. Use Caixa de Sentença.
  • Instrução de Meta: Deixe claro qual o nível mínimo exigido para que a senha seja aceita pelo sistema (ex: Mínimo: Média).

Toast/Notification

  • O usuário tem poucos segundos para ler. Use no máximo uma frase curta.
  • Tom de Voz: Neutro e focado no objeto da ação. Use Caixa de Sentença.
  • Sem Interação Obrigatória: Não coloque ações críticas dentro de um Toast (como “Excluir”). Para isso, use o componente Alert.
  • Remova artigos e pronomes.
  • Ícones de Apoio: Utilize ícones universais (check para sucesso, “x” para erro) para acelerar a compreensão visual.

Não existe .mds-toast nem <mds-toast>: use a aproximação descrita na seção 9.4 (Alert fixo e dispensável).

Tooltip

  • Use o menor número de palavras possível. Evite artigos e preenchimentos.
  • Pontuação Final: Não utilize ponto final para frases únicas e curtas. Use pontuação apenas se o Tooltip contiver duas ou mais frases (o que deve ser evitado).
  • Sem Reticências: Não use reticências em textos de Tooltip; ele deve ser uma informação completa por si só.
  • Se o botão já possui um rótulo de texto, não use um Tooltip que repita o mesmo texto.
  • Acessibilidade: Tooltips são essenciais para descrever ícones que não possuem texto visível ao lado.

AppLauncher

  • Identidade da Marca (Header): Exibe o logotipo Mobiis para reforçar que todos os itens pertencem ao mesmo ecossistema.
  • Nome do Produto (Título): Identificador principal do módulo (geralmente uma sigla técnica ou nome comercial). Use Caixa de Título.
  • Descrição do Produto: Frase curta que resume a proposta de valor do módulo. Use Caixa de Sentença.
  • Elementos Visuais: Cada item deve conter um ícone distintivo em um contêiner (box) colorido ou neutro para facilitar o reconhecimento visual imediato.
  • Indicador de Navegação: Seta lateral (chevron_right) indicando que o item é clicável e levará a uma nova URL ou contexto.
  • Hierarquia Visual: O último item da trilha (a página atual) deve estar em negrito ou em uma cor diferente para indicar onde o usuário está.
  • Use nomes curtos para as páginas. Se o título de uma página for “Gerenciamento de Inventário de Produtos Perecíveis”, no Breadcrumb use apenas “Inventário”.
  • Interatividade: Todos os itens, exceto o último, devem ser links clicáveis.
  • Uso de Reticências: Se o caminho for muito longo e comprometer o layout, oculte os níveis intermediários usando reticências (…) entre o primeiro e o último item.
  • Separadores: Use símbolos neutros (como / ou >) para separar os níveis.

CardItem

  • Ícone de Contexto (Esquerda): Ajuda no reconhecimento visual da categoria da ação (ex: ícone de tabela para Visão Tabela).
  • Rótulo (Label): O nome da ação ou opção. Use Caixa de Título e negrito.
  • Descrição (Description): Texto curto que detalha o que acontecerá ao clicar. Use Caixa de Sentença.
  • Indicador de Navegação (Chevron): Seta à direita (proximo) que reforça a natureza de “link” do componente.
  • Interatividade: Todo o corpo do card deve possuir um estado de hover (mudança leve de cor ou elevação) para confirmar que é clicável.

DateNavigator

  • Alternância de Visão: O componente deve permitir a expansão (através da seta inferior) para alternar entre a visão de Semana (foco em agendamento imediato) e Mês (planejamento a longo prazo).
  • Indicação de Disponibilidade: Utilize estilos visuais distintos (como azul para dias com vagas e cinza para dias sem vagas/indisponíveis).
  • Navegação Temporal: As setas laterais devem permitir o avanço ou retrocesso dos períodos (semana a semana ou mês a mês).
  • Formatação de Datas: No cabeçalho, utilize o intervalo de datas de forma concisa.
  • Os rótulos dos dias da semana devem ser abreviados com três letras em Caixa Alta (DOM, SEG, TER) para otimizar o espaço e garantir o alinhamento.
  • Navegação Multinível: Use uma seta para a direita (ícone) para indicar que um item abre um submenu.
  • Sem Reticências em Submenus: Não utilize reticências (…) para itens que apenas abrem um submenu. A seta visual já comunica que há mais opções.
  • Nomes de Categorias: O item pai deve ser curto e categórico.
  • Limitação de Níveis: Evite ultrapassar dois níveis de profundidade (Menu > Submenu) para não dificultar a navegação e a leitura rápida.
  • Mantenha a Caixa de Título em todos os níveis para consistência.
  • Menu Estático (Expandido): Fixado à esquerda, exibe ícones e rótulos. Ideal para resoluções maiores, permitindo navegação rápida entre módulos.
  • Menu Estático (Compacto): Exibe apenas ícones para otimizar a área de trabalho. Utilize Tooltips em cada ícone para garantir a clareza.
  • Menu Flutuante: Utilizado em dispositivos móveis ou telas reduzidas. Sobrepõe o conteúdo e inclui um cabeçalho com a logo e o botão de fechamento.
Elemento Sugestão UX Writing (Conciso) Justificativa
Seletor de Contexto Unidade de Negócio Define o escopo operacional e as permissões de dados.
Módulos (Nível 1) Menu Principal Estrutura de navegação entre as grandes áreas do sistema.
Seções (Submenu) Navegação Local Organiza as páginas internas de um módulo de forma hierárquica.
Rodapé do Menu Informações do Sistema Exibe a versão do software e créditos de desenvolvimento.

Níveis, item ativo, navegação utilitária e os três modos do menu: seção 9.7.

SectionHeader

  • Hierarquia (Variações de Tamanho): Utilize as variações de escala para refletir a profundidade da arquitetura de informação. Seções mestras usam títulos maiores; subseções, títulos menores.
  • Títulos Diretos: Identifique o assunto da seção com brevidade. Use Caixa de Título.
  • Descrições de Apoio: Utilize a descrição para detalhar a finalidade daquela seção ou dar instruções curtas. Use Caixa de Sentença.
  • Elementos Visuais: O uso de ícones ou avatares deve reforçar o tema da seção (ex: ícone de person para dados pessoais).
  • Consistência: Se usar descrição em um SectionHeader de um grupo, tente manter o padrão nos demais da mesma página para evitar desequilíbrio visual.

TabNav / Tabs

  • Rótulos Concisos: Use apenas substantivos ou verbos curtos. Use Caixa de Título.
  • Estado Ativo: Apenas um Tab Item pode estar ativo por vez. Ele deve ter um destaque visual (cor ou borda inferior) e o texto em negrito.
  • Ordem Lógica: Coloque as informações mais críticas na primeira aba (à esquerda).
  • Sem Pontuação: Nunca utilize ponto final nos rótulos das abas.
  • Ícones de Apoio: Utilize ícones que possuam semântica direta com o conteúdo da aba. O ícone deve ser posicionado à esquerda do rótulo.
  • Modo Compacto (Responsivo): Em telas menores, o rótulo de texto pode ser ocultado, mantendo apenas o ícone.
  • Uso de Tooltip: Sempre que o rótulo de texto for ocultado no modo compacto, o uso de Tooltip no ícone torna-se obrigatório para descrever a função da aba.
  • Consistência: Não misture abas com ícones e abas sem ícones no mesmo conjunto. Se uma aba possui ícone, todas as outras do mesmo grupo devem possuir.

Topbar

  • Marca e Nome do Produto: Identifica a plataforma e o módulo atual (ex: Torre de Controle). Use Caixa de Título.
  • Busca Global: Barra de pesquisa para localização rápida de registros (cargas, veículos, motoristas) em todo o sistema.
  • Acesso Rápido: Agrupa utilitários que devem estar acessíveis de qualquer tela, como notificações e configurações.
  • Central de Ajuda: Concentra recursos de suporte e documentação para o usuário.
  • Seletor de Produtos: Permite a alternância rápida entre diferentes sistemas do ecossistema Mobiis.
  • Perfil e Empresa: Exibe o usuário logado e a unidade/empresa ativa.

Superfícies

Box

  • Títulos de Seção: Utilize títulos curtos e diretos no topo do Box para identificar o grupo de dados. Use Caixa de Título.
  • Agrupamento Lógico: Coloque dentro do Box apenas elementos que pertençam ao mesmo contexto. Não misture ações globais com dados específicos de um item.
  • Espaçamento (Padding): Mantenha um respiro interno consistente para que os textos e campos de entrada não toquem as bordas, garantindo a legibilidade.
  • O título do Box deve ser autossuficiente.

Collapse

  • Comportamento Exclusivo (Accordion): Utilize este modo quando o usuário deve processar informações de forma sequencial ou quando o espaço vertical é crítico.
  • Foco na Tarefa: Ao expandir uma nova seção no modo Accordion, o sistema deve garantir que o conteúdo revelado esteja visível, ajustando a rolagem se necessário.
  • Indicação de Estado: Use ícones claros (como > ou v) em Caixa de Título para os cabeçalhos.
  • O cabeçalho deve ser autossuficiente. Se o usuário precisar saber o que há dentro antes de abrir, use um resumo curto.

Drawer

  • Uso: Formulários de cadastro, edição de itens e menus globais.
  • Título: Use Caixa de Título no topo do painel para identificar a ação (ex: Novo Motorista).
  • Ações: Os botões de ação (Salvar, Cancelar) devem ficar fixos no rodapé do Drawer.
  • Saída: Deve permitir o fechamento ao clicar fora (backdrop) ou em um ícone de “X”.
  • Uso: Visualização de detalhes de carga, alertas críticos, diálogos de confirmação ou mensagens de erro.
  • Título: Deve ser curto e direto. Se for uma pergunta, use pontuação final.
  • Uso de Reticências (…): Se o botão que abre a modal for, por exemplo, “Configurar…”, a modal deve ter o título “Configurações”.
  • Hierarquia: Coloque a informação mais importante no início do texto.

Quando usar Modal, Drawer ou Alert e a anatomia da confirmação: seções 9.4 e 9.5.

Toolbar

  • Posicionamento: Geralmente fixado no topo ou rodapé da tela para garantir visibilidade constante enquanto o modo estiver ativo.
  • Título do Modo: Identifique claramente o que está sendo executado. Use Caixa de Título.
  • Instrução Contextual: Texto curto que orienta o usuário sobre como interagir com os elementos da tela naquele modo. Use Caixa de Sentença.
  • Ações de Conclusão: O botão principal deve ter um destaque semântico (geralmente verde para sucesso/conclusão). Use Caixa de Título.
  • Saída e Cancelamento: Deve sempre oferecer um botão de fechar (X) ou “Cancelar” para retornar ao estado normal do sistema.

Gerado por npm run design:build; não edite à mão.