Temas e tokens

Entenda como a NewUI usa variáveis CSS para definir cores, medidas e tipografia.

O que são temas e tokens?

Tokens são variáveis CSS que guardam decisões de design, como a cor de uma ação, o raio de um botão ou a fonte do texto. Um tema define os valores desses tokens para uma interface inteira ou para uma seção.

Os nomes descrevem a função do valor. Um botão com tone="primary" usa os tokens da ação principal. Ao mudar a paleta, os componentes continuam com a mesma intenção e passam a usar as novas cores.

Referência de tokens

Claro, escuro e sistema

Use data-nui-theme="light", data-nui-theme="dark" ou data-nui-theme="system". Na raiz, o atributo vale para o documento. Em uma seção, vale para aquela seção e seus descendentes. Por padrão, a NewUI acompanha a preferência do sistema.

<html data-nui-theme="system">
  <body>
    <section data-nui-theme="dark">...</section>
  </body>
</html>

Aplique a identidade do seu produto

Use createTheme para escolher uma paleta e sobrescrever tokens. A função retorna um objeto de variáveis CSS. Aplique-o com style no contêiner para limitar o efeito àquele trecho.

A mesma paleta em dois modos

Claro

Em andamento

Escuro

Em andamento
import { Badge, Button } from "@egcs/newui";
import { createTheme } from "@egcs/newui/theme";

const theme = createTheme({
  "primary": "green",
  "tokens": {
    "radiusMd": "0.75rem"
  }
});

export default function ThemedSection() {
  return (
    <section style={theme}>
      <Button tone="primary">Continuar</Button>
      <Badge variant="soft" tone="primary">Em andamento</Badge>
    </section>
  );
}

A paleta preenche os papéis de cor em conjunto, incluindo fundo sólido, hover, bordas e texto. Para cores próprias, ajuste também os estados relacionados e verifique o contraste. A troca de cor principal sozinha afeta apenas os componentes e estados que leem esse token.

Defina tokens no CSS global

Coloque as sobrescritas em :root, depois de carregar os estilos da NewUI. Ao escolher uma fonte, carregue a família no projeto. O token informa qual fonte usar.

:root {
  --nui-radius-md: 0.75rem;
  --nui-space-unit: 0.25rem;
  --nui-font-sans: "Inter", system-ui, sans-serif;
}

Com o preset opcional do Tailwind, utilities como bg-surface e rounded-md leem os mesmos tokens. Os componentes já leem esses valores com o CSS compilado.

Experimente no editor de temas

Referência de tokens

Use os nomes com prefixo --nui- no CSS. Em createTheme({ tokens: … }), os nomes da API usam camelCase, como radiusMd e primarySoft. Os tokens de componentes, como as sombras de popover e as cores de séries de gráficos, podem ser ajustados diretamente no CSS.

Superfícies e texto

TokenOnde é usado
--nui-backgroundFundo da aplicação ou de um contêiner temático.
--nui-surfaceFundo secundário para agrupar conteúdo.
--nui-foregroundCor padrão do texto.
--nui-muted-foregroundCor de texto secundário e descrições.
--nui-mutedRealce discreto. Por padrão, usa o fundo suave do tom principal.
--nui-borderDivisórias e bordas de superfícies.
--nui-control-borderBorda padrão de campos e controles.
--nui-control-border-hoverBorda de controles ao passar o ponteiro.
--nui-disabled-backgroundFundo de controles desabilitados.
--nui-disabled-foregroundTexto e ícones de controles desabilitados.
--nui-disabled-borderBorda de controles desabilitados.

Cores semânticas

Na tabela, {tom} pode ser primary (ação principal), neutral (ação neutra), info (informação), success (sucesso), warning (atenção) ou danger (erro ou ação destrutiva). Por exemplo, --nui-danger-soft é o fundo suave do tom danger.

TokenOnde é usado
--nui-{tom}Fundo sólido da ação ou do estado.
--nui-{tom}-hoverFundo sólido ao passar o ponteiro.
--nui-{tom}-softFundo suave, como o de badges e avisos.
--nui-{tom}-soft-hoverFundo suave ao passar o ponteiro.
--nui-{tom}-soft-activeFundo suave pressionado ou selecionado.
--nui-{tom}-borderBorda colorida, como a de um botão outline.
--nui-{tom}-border-hoverBorda colorida ao passar o ponteiro.
--nui-{tom}-textTexto e ícones coloridos sobre fundos suaves ou neutros.
--nui-{tom}-text-strongTexto colorido com ênfase maior.
--nui-{tom}-focusCor de foco associada ao tom.
--nui-on-{tom}Texto e ícones sobre o fundo sólido do tom.
--nui-{tom}-1 … --nui-{tom}-12Escala de 12 degraus que alimenta os estados do tom.
--nui-chart-1 … --nui-chart-5Cores das séries dos gráficos, na ordem em que aparecem.

Os degraus de 1 a 12 vão de fundos sutis a texto de alto contraste. Use os tokens de estado para estilizar componentes. Eles já selecionam o degrau apropriado para a função e o modo.

Tipografia

TokenOnde é usado
--nui-font-sansFamília padrão do texto e dos controles que herdam a fonte.
--nui-font-monoFamília monoespaçada para código e outros trechos técnicos.
--nui-font-size-{xs, sm, base, lg, xl, 2xl, 3xl, 4xl, 5xl}Escala geral de texto, de 0,75rem a 3rem.
--nui-font-size-{display-sm, display-md}Títulos de destaque. Os valores padrão são 2rem e 2,5rem.
--nui-font-weight-{normal, medium, semibold}Pesos padrão de 400, 500 e 600.
--nui-leading-{tight, snug, normal, relaxed}Alturas de linha padrão de 1,25, 1,375, 1,5 e 1,625.
--nui-tracking-tightEspaçamento entre letras em títulos mais compactos. O padrão é −0,025em.

Espaçamento e geometria

TokenOnde é usado
--nui-space-unitBase de 0,25rem para espaçamento e medidas numéricas. Alterar o valor também afeta larguras e alturas que usam a escala.
--nui-radius-{xs, sm, md, lg, xl, 2xl, 3xl, 4xl}Raio dos cantos, de 0,125rem a 2rem. Button usa md e Card usa xl por padrão.
--nui-control-height-{xs, sm, md, lg}Altura dos controles por tamanho. Os padrões são 1,5rem, 2rem, 2,5rem e 3rem.
--nui-header-gapDistância entre título e descrição em cabeçalhos compactos de Card, Dialog e outros componentes.
--nui-resizable-handle-sizeEspessura do separador arrastável de Resizable.
--nui-toast-width / --nui-popover-width / --nui-hover-card-widthLarguras de referência de Toast, Popover e HoverCard.

Foco, movimento e elevação

TokenOnde é usado
--nui-focus-ring / --nui-focus-width / --nui-focus-offsetCor, espessura e distância do contorno de foco.
--nui-motion-duration / --nui-motion-easingDuração e curva padrão das transições, com 150ms e cubic-bezier(0.4, 0, 0.2, 1).
--nui-elevated-border / --nui-elevated-shadowBorda e sombra de superfícies elevadas, como Card.
--nui-overlay-backdrop / --nui-overlay-shadowFundo atrás de janelas modais e sombra do painel.
--nui-popover-shadow / --nui-tooltip-shadow / --nui-hover-card-shadow / --nui-toast-shadowSombras próprias de cada tipo de sobreposição.
--nui-tooltip-background / --nui-tooltip-foregroundFundo e texto de Tooltip.
--nui-z-overlay / --nui-z-popover / --nui-z-hover-card / --nui-z-tooltipOrdem de empilhamento das sobreposições.
--nui-loading-track / --nui-progress-trackFundo da trilha de indicadores de carregamento e progresso.