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.
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
Escuro
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.
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
| Token | Onde é usado |
|---|---|
--nui-background | Fundo da aplicação ou de um contêiner temático. |
--nui-surface | Fundo secundário para agrupar conteúdo. |
--nui-foreground | Cor padrão do texto. |
--nui-muted-foreground | Cor de texto secundário e descrições. |
--nui-muted | Realce discreto. Por padrão, usa o fundo suave do tom principal. |
--nui-border | Divisórias e bordas de superfícies. |
--nui-control-border | Borda padrão de campos e controles. |
--nui-control-border-hover | Borda de controles ao passar o ponteiro. |
--nui-disabled-background | Fundo de controles desabilitados. |
--nui-disabled-foreground | Texto e ícones de controles desabilitados. |
--nui-disabled-border | Borda 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.
| Token | Onde é usado |
|---|---|
--nui-{tom} | Fundo sólido da ação ou do estado. |
--nui-{tom}-hover | Fundo sólido ao passar o ponteiro. |
--nui-{tom}-soft | Fundo suave, como o de badges e avisos. |
--nui-{tom}-soft-hover | Fundo suave ao passar o ponteiro. |
--nui-{tom}-soft-active | Fundo suave pressionado ou selecionado. |
--nui-{tom}-border | Borda colorida, como a de um botão outline. |
--nui-{tom}-border-hover | Borda colorida ao passar o ponteiro. |
--nui-{tom}-text | Texto e ícones coloridos sobre fundos suaves ou neutros. |
--nui-{tom}-text-strong | Texto colorido com ênfase maior. |
--nui-{tom}-focus | Cor de foco associada ao tom. |
--nui-on-{tom} | Texto e ícones sobre o fundo sólido do tom. |
--nui-{tom}-1 … --nui-{tom}-12 | Escala de 12 degraus que alimenta os estados do tom. |
--nui-chart-1 … --nui-chart-5 | Cores 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
| Token | Onde é usado |
|---|---|
--nui-font-sans | Família padrão do texto e dos controles que herdam a fonte. |
--nui-font-mono | Famí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-tight | Espaçamento entre letras em títulos mais compactos. O padrão é −0,025em. |
Espaçamento e geometria
| Token | Onde é usado |
|---|---|
--nui-space-unit | Base 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-gap | Distância entre título e descrição em cabeçalhos compactos de Card, Dialog e outros componentes. |
--nui-resizable-handle-size | Espessura do separador arrastável de Resizable. |
--nui-toast-width / --nui-popover-width / --nui-hover-card-width | Larguras de referência de Toast, Popover e HoverCard. |
Foco, movimento e elevação
| Token | Onde é usado |
|---|---|
--nui-focus-ring / --nui-focus-width / --nui-focus-offset | Cor, espessura e distância do contorno de foco. |
--nui-motion-duration / --nui-motion-easing | Duração e curva padrão das transições, com 150ms e cubic-bezier(0.4, 0, 0.2, 1). |
--nui-elevated-border / --nui-elevated-shadow | Borda e sombra de superfícies elevadas, como Card. |
--nui-overlay-backdrop / --nui-overlay-shadow | Fundo atrás de janelas modais e sombra do painel. |
--nui-popover-shadow / --nui-tooltip-shadow / --nui-hover-card-shadow / --nui-toast-shadow | Sombras próprias de cada tipo de sobreposição. |
--nui-tooltip-background / --nui-tooltip-foreground | Fundo e texto de Tooltip. |
--nui-z-overlay / --nui-z-popover / --nui-z-hover-card / --nui-z-tooltip | Ordem de empilhamento das sobreposições. |
--nui-loading-track / --nui-progress-track | Fundo da trilha de indicadores de carregamento e progresso. |