MUI (Material UI)

Para aplicações React com MUI, o pacote @mobiis/mds-style traz createMdsTheme, um tema gerado dos mesmos tokens do CSS do MDS. Os componentes do MUI ficam com a mesma forma, cores e estados (hover, pressionado, foco, desabilitado e erro) dos componentes do mds-styles.css.

Instalação

Requer @mui/material e react. O tema foi validado no MUI 7.3.

npm i @mobiis/mds-style

import { ThemeProvider, CssBaseline } from '@mui/material';
import { createMdsTheme } from '@mobiis/mds-style/mui';

const theme = createMdsTheme({ mode: 'light' });

export function App() {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      {/* … */}
    </ThemeProvider>
  );
}

Fonte

O tema usa a Manrope (--mds-font-family), que precisa ser carregada uma vez na aplicação. Duas formas:

• importe @mobiis/mds-style/css/mds-tokens.css, que traz o @font-face e os tokens --mds-* para o CSS próprio da aplicação;
• declare o @font-face apontando para @mobiis/mds-style/fonts/Manrope-VariableFont_wght.ttf.

Tema e cor primária

Opção	Equivale a	Valores
mode	data-theme	light (padrão), dark, dark-blue
brand	data-primary	brand-mobiis, blue, teal, aqua, green, yellow, orange, red, pink. Sem valor = brand-mobiis.

const theme = useMemo(() => createMdsTheme({ mode: preferencias.tema, brand: tenant.cor }), [preferencias.tema, tenant.cor]);

Para trocar o tema ou a cor primária, crie outro tema e passe ao ThemeProvider. Ajustes próprios vão como argumentos extras e são mesclados por cima:

createMdsTheme({ mode: 'dark' }, { components: { MuiButton: { defaultProps: { size: 'small' } } } });

O que segue o MDS

Componente	Segue	Comportamento
Button	.mds-btn	small, medium e large = 32, 48 e 56px (e xsmall = 24px). Negrito, sem caixa alta, degrau de 1px. contained, outlined e text com os tokens --mds-buttons-*. Pressionado = escala 0,98 + sombra interna; foco = contorno de 2px; desabilitado cinza
IconButton	botão só-ícone	32, 48 e 56px, raio do MDS, hover na cor de item
TextField, OutlinedInput, Select	.mds-input	48px (small = 32px), borda de 2px, raio 8px. Hover com borda primary; foco com borda e halo de 4px a 30%; erro, desabilitado e texto de ajuda do MDS
Checkbox, Radio	.mds-checkbox, .mds-radio	caixa de 24px com raio de 6px e círculo de 20px; marcados em primary
Switch	.mds-checkbox--switch	40×24px; ligado em primary
Chip	.mds-badge	raio de 4px, 12px negrito, mesmas cores do badge (.mds-badge--success…); variant="solid" = badge sólido
Alert	.mds-alert	fundo e texto --mds-highlight-*, borda e ícone na cor do papel; filled = sólido
Tabs, Tab	nav-tabs	sem caixa alta; aba ativa em negrito; indicador primary
Table	.mds-table	linha de 48px, padding de 8px, cabeçalho dimmed-3
Tooltip	.mds-tooltip	fundo dimmed-7, 14px, raio de 6px
Dialog, Menu, Popover, Card, Paper	elevações do MDS	raio de 8px, sombras elevation-1…5, backdrop background-transparency
MenuItem, ListItemButton	item do MDS	hover e selecionado com --mds-item-*
AppBar, Toolbar	top-bar	64px, fundo de superfície, borda inferior
Avatar	.mds-avatar	quadrado com raio de 8px por padrão (variant="circular" para círculo)

Outros ajustes:

• Ripple: fica desligado. O MDS não tem ripple: o retorno de toque é a escala e a sombra interna.
• Botão padrão: <Button> sem props é o control sólido (.mds-btn--control), o botão neutro do MDS, como o mdsButton do Angular e o tema do PrimeFaces. A ação principal leva color="primary": no máximo um por tela, formulário ou diálogo. Para ações secundárias de suporte (Exportar, Imprimir), use variant="outlined" color="primary". Para ações de baixa prioridade, use variant="text".
• Tipografia:

Variante MUI	Estilo MDS
h1 … h4	headline-h1 … headline-h4
h5	title-lg
h6, subtitle1	title-md
subtitle2	title-sm
body1, body2	body-md, body-sm
caption	body-xs

• Medidas:
  • theme.spacing(1) = 8px (sm), então 0.5, 2, 3 e 4 = xs, md, lg e xl;
  • shape.borderRadius = 8px;
  • breakpoints do grid MDS: 576, 768, 992 e 1200px.

<Stack direction="row" spacing={1}>
  <Button>Cancelar</Button>
  <Button color="primary">Salvar</Button>
</Stack>
<TextField label="Placa do veículo" error helperText="Placa inválida. Use o formato ABC1D23." />
<Chip label="Em trânsito" color="success" />
<Chip label="Atrasada" color="error" variant="solid" />

Tokens no código

theme.mds.tokens['colors-primary-main'];   // valor resolvido para o tema e a cor primária
theme.palette.primary.lighter;             // os 5 tons: lighter, light, main, dark, darker

import { getMdsTokens } from '@mobiis/mds-style/mui';
getMdsTokens({ mode: 'dark' })['control-default-border'];

O TypeScript conhece as extensões:

• color="control" no Button e no IconButton;
• size="xsmall" no Button;
• variant="solid" no Chip;
• theme.mds e os nomes de token e de cor primária, com autocompletar.

Como o tema é feito

O MUI faz conta com as cores da paleta (alpha(), contraste do texto), por isso precisa de valores, e não de var(--mds-*).

• Geração dos tokens: npm run mui:build (scripts/mui/build-mui.js) compila src/scss/mds-tokens.scss e resolve a cascata real dos tokens (especificidade, ordem e var()) para cada tema e cor primária. O resultado vai para themes/mui/tokens.js no repositório (mui/tokens.js no pacote).
• O tema: themes/mui/index.js monta a paleta e os styleOverrides dos componentes a partir desses tokens e das medidas do SCSS.

npm run mui:verify falha se themes/mui/tokens.js estiver desatualizado. Quando os tokens mudam, rode npm run tokens e depois npm run mui:build.

Validação

• Os 15.360 valores gerados (512 tokens × 3 temas × 10 estados de cor primária) bateram com o que o Chrome calcula carregando mds-tokens.css.
• Botões (8 combinações de variante, cor e tamanho), campo (normal, erro e desabilitado), checkbox e tabela foram comparados com os componentes reais do mds-styles.css. O estilo computado deu idêntico em repouso, hover, pressionado e foco.

Limitações conhecidas

• Migração de apps que já usam MUI: no MUI, <Button> sem color é primary. Com o tema, ele vira o control, que é cinza. Revise as telas para marcar a ação principal com color="primary".
• Troca em tempo de execução: trocar tema ou cor primária exige criar outro tema. No CSS do MDS e no Tailwind, a troca é pelos atributos do <html>.
• Rótulo dos campos: sobe para a borda, como no MUI, e não flutua dentro do campo como no .mds-input.
• Versões do MUI: a comparação exata foi feita no MUI 7.3.