Do's & Don'ts

Faça:

Use sempre os tokens --mds-* (cor, espaçamento, raio, sombra) — nunca hex, px ou rgba “cru” no meio do código.
Prefixe todo componente novo com mds- e siga BEM (mds-bloco__elemento--modificador); mantenha fundação/utilitário sem prefixo.
Limite a interface a um objetivo por tela e um botão primary por contexto (formulário/modal/página).
Use d-flex + gap--* para o interior dos componentes; grid de 12 colunas só na estrutura macro da página.
Mantenha o texto direto e escaneável: rótulo curto, sem frases completas em botões/campos, revelando detalhe só quando o usuário pede (progressive disclosure).
Reaproveite os 5 níveis de elevação e a escala de raio conforme a tabela gerada — não invente um 6º nível ou um raio intermediário.
Ao gerar para um cliente/tenant específico, preserve [data-primary="..."] em vez de fixar a cor primária.

Não faça:

Não crie fundo cinza genérico de IA (#f5f5f5, #e0e0e0 soltos) — use background-light/main/dark conforme a profundidade real do elemento.
Não use border-radius fixo “por costume” — cada família de componente tem seu raio real (ver tabela de Shapes & Borders gerada); misturar raios entre famílias quebra a identidade.
Não use sombras arbitrárias (box-shadow: 0 2px 4px rgba(0,0,0,.1)) — sempre a cor-base do token de sombra e um dos 5 níveis nomeados.
Não use as classes tipográficas legadas sem prefixo em telas novas — são compatibilidade, não o padrão atual (ver aviso na tabela de tipografia).
Não empilhe mais de um CTA de destaque igual na mesma tela — dilui a hierarquia e contraria o princípio de Objetividade.
Não escreva rótulo/placeholder como frase (“Digite aqui o nome do motorista…”) — o MDS pede UX writing direto e no infinitivo/substantivo curto (“Nome do motorista”).
Não sobreponha texto escuro fixo em qualquer fundo colorido — use sempre o par --mds-colors-<papel>-main + --mds-colors-<papel>-on-main, que garante legibilidade nos dois temas.

Este arquivo é regenerado por npm run design:build (ver package.json). O gerador falha (em vez de gerar algo errado) se um valor que ele espera encontrar no SCSS mudou de lugar — rode npm run design:build de novo para ver a mensagem de erro com o arquivo/linha exatos.