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.
Como usar
Seção intitulada “Como usar”- Em ferramentas de código (Claude Code, Cursor e similares): baixe o arquivo e salve como
DESIGN.mdna 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 classesmds-*vêm do CSS).
O arquivo é gerado do CSS real e das diretrizes do MDS. Quando o sistema mudar, baixe de novo.
Conteúdo
Seção intitulada “Conteúdo”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.
- 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 commds_style_map_tokens. [token.hardcoded-color,token.hardcoded-spacing,token.hardcoded-radius,token.hardcoded-typography,token.unknown] - Use só classes que existem (Component Class Index da skill
mds-style). Não invente classe por analogia:.mds-toaste.mds-skeleton, por exemplo, não existem. - 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] - 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] - 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] - Botão só de ícone tem
aria-labele Tooltip. [button.icon-only-needs-name] - 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] - Toda tela cobre os cinco estados: carregando, vazio, erro, sucesso e com dados (seção 9.3).
- 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.
- 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] - Navegação com no máximo dois níveis; título da página = item de menu ativo (seção 9.7).
- 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
- Diga o problema e a ação principal da tela em uma frase (seção 9.1).
- 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. - 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.
- Desenhe os cinco estados (9.3), o feedback (9.4), as confirmações (9.5) e o formulário (9.6).
- Escreva os textos pela seção 8.
- Revise com o checklist 9.8 e rode
mds_style_audit(ounpm 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), eforeground-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 rebaixadobackground-main< carddimmed-default< hover/borda). Use o token de fundo da camada certa em vez de depender debox-shadowpara separar planos. - Não presuma que
-dark/-darkerescurecem: 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 omaindo 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 skillmds-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-flexe o resto do grid/flexbox) são utilitário de fundação, não conceito de spacing — catálogo exato na skillmds-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--roundede 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ãoprimarypor 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 emdanger; obrigatório pendente: destaque emwarning; válido: bordasecondary-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 2pxna 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.
Navegação (Topbar / Menu / Tabs)
- 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 deprimary) e borda/textoprimary-dark. - Abas (
nav-tabs): item ativo com peso bold e indicador emprimary; 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-labele 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-boxsobre 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-boxsobre 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”:
- Mensagem sobre um campo de formulário? → mensagem no próprio campo (
.mds-input--danger+.mds-input__helper). - Precisa de decisão antes de continuar (confirmar exclusão, escolher)? → Modal (
.mds-float-panel--modal). - O problema precisa continuar visível até ser resolvido (falha na emissão, manutenção atrasada)? → Alert (
.mds-alert--{neutral|info|warning|danger|success}). - Só confirma o resultado de uma ação, sem nada a fazer? → Toast.
- Explicação curta de ícone/sigla/dado? → Tooltip (
.mds-tooltip). - 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-toastnem<mds-toast>. A aproximação prevista é<mds-alert [fixed]="true" [dismissible]="true">(.mds-alertfixo 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):
- Título: a pergunta com ação + objeto, caixa de título, termina em “?” → Excluir Rota?
- 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.”
- 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.
PageHeader
- 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
h1ouh2do componenteText).
- 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.
- Atualizar dados: Botão de ícone (
- 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-toastnem<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.
Navegação
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.
Breadcrumb
- 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
tabelapara 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.
Dropdown / Menu flutuante
- 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 Lateral / Sidebar
- 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
personpara 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
>ouv) 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”.
Modal
- 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.