Background
Tokens de background — fundos de página, cards, modais e overlays.
Derivam da escala Neutral. Regras gerais no hub de Tokens.
Hierarquia de elevação
As superfícies formam uma escada — do mais plano (ao fundo) ao mais elevado (mais perto de quem usa). Suba um degrau só quando o conteúdo precisa se separar do que está atrás; não pule degraus.
--ui-bg— base da página, o fundo de tudo.--ui-bg-muted— apoio sutil sobre a base (sidebar, fundo de seção).--ui-bg-elevated— conteúdo que "sobe" da base (card, modal, popover, dropdown).--ui-bg-accented— realce pontual sobre uma superfície (hover de linha, item ativo).--ui-bg-inverted— alto contraste, fora da escada (tooltip, badge sólido).
A elevação vem do token de superfície + borda + sombra combinados — nunca de opacidade.
Boas Práticas
Quando usar
Fundo principal da página com `--ui-bg`.
Cards e blocos com `--ui-bg-elevated` ou `--ui-bg-muted`.
Destaque estrutural com `--ui-bg-accented`.
Overlays e scrims com tokens alpha (`--ui-bg-90`, `--ui-bg-inverted-80`).
Quando não usar
Fundos avulsos (`#fff`, `gray-100`) fora dos tokens.
Alpha improvisada quando o token alpha já existe.
Background invertido sem par com texto invertido.
Tokens
Tokens
| Token | Light | Dark |
|---|---|---|
| --ui-bg | White | neutral-900 |
| --ui-bg-muted | neutral-50 | neutral-800 |
| --ui-bg-elevated | neutral-100 | neutral-800 |
| --ui-bg-accented | neutral-200 | neutral-700 |
| --ui-bg-inverted | neutral-900 | White |
Alpha
| Token | Light | Dark |
|---|---|---|
| --ui-bg-90 | FFFFFF 90% | FFFFFF 90% |
| --ui-bg-75 | FFFFFF 75% | FFFFFF 75% |
| --ui-bg-10 | FFFFFF 10% | FFFFFF 10% |
| --ui-bg-elevated-75 | alpha/100-75 | alpha/800-75 |
| --ui-bg-elevated-50 | alpha/100-50 | alpha/800-50 |
| --ui-bg-accented-75 | alpha/200-75 | alpha/700-75 |
| --ui-bg-accented-50 | alpha/200-50 | alpha/700-50 |
| --ui-bg-inverted-90 | alpha/900-90 | FFFFFF 90% |
| --ui-bg-inverted-80 | alpha/900-80 | FFFFFF 80% |
| --ui-bg-inverted-20 | alpha/900-10 | FFFFFF 20% |
Guia de decisão
| Contexto | Token recomendado |
|---|---|
| Fundo principal da página | --ui-bg |
| Sidebar, área de apoio, fundo de seção sutil | --ui-bg-muted |
| Card, painel, modal, popover | --ui-bg-elevated |
| Hover de linha ou item, chip/badge ativo | --ui-bg-accented |
| Tooltip, banner de alto contraste | --ui-bg-inverted |
| Overlay com transparência | --ui-bg-75 ou --ui-bg-90 conforme opacidade desejada |
Pareamentos recomendados
Combinações validadas de background + borda + texto. Evite montar pares fora dessas combinações sem testar contraste.
| Contexto | Background | Borda | Texto |
|---|---|---|---|
| Página base | --ui-bg | --ui-border-muted | --ui-text |
| Card / painel / modal | --ui-bg-elevated | --ui-border | --ui-text |
| Sidebar / área de apoio | --ui-bg-muted | --ui-border-muted | --ui-text-muted |
| Hover de linha / item interativo | --ui-bg-accented | — | --ui-text |
| Tooltip / background invertido | --ui-bg-inverted | — | --ui-text-inverted |
Os pares são válidos em claro e escuro — cada token resolve automaticamente para a primitiva correta em cada modo. Consulte as páginas de cada família para ver os valores resolvidos.
Onde aparece
Alterações nesses tokens afetam diretamente os componentes abaixo — use como referência de impacto antes de propor ajustes.
| Token | Componentes |
|---|---|
--ui-bg | UCard (solid), UModal (fundo do conteúdo), base do layout |
--ui-bg-muted | UAlert (variant sutil), UInput (desabilitado), UTabs (barra de abas) |
--ui-bg-elevated | UCard, UModal (overlay), UPopover, UDropdownMenu, LoginForm |
--ui-bg-accented | UTable (zebra / linha expandida), hover global de item interativo |
--ui-bg-inverted | Tooltip, UBadge (solid neutro) |