Surface

A Surface é a base de qualquer bloco que precisa de fundo: ela aplica o fundo do degrau escolhido e avisa os campos filhos qual variante usar. Card, Widget e Sheet se apoiam nela. Use Surface direto para um bloco avulso; use Widget quando houver cabeçalho, conteúdo e rodapé.

import { Surface } from "@rastreio-x/ui";

Padrão

O raio e o preenchimento vêm das suas classes, com os tokens do Tailwind.

Variantes

Quatro degraus: default, secondary, tertiary e transparent (sem fundo, para colocar sobre fundos próprios).

Com formulário

Campos dentro de uma Surface pedem variant="secondary", para não somar duas camadas de fundo.

Aninhada

Cada nível sobe um degrau: o item destacado fica em secondary dentro do default.

Anatomia

A Surface é uma peça só: um div com a classe do degrau e o contexto de variante para os filhos.

Propriedades

Animações

A Surface não anima. Trocar de tema é a única mudança, e acontece pelos tokens.

Acessibilidade

• É um div sem papel: ela não anuncia nada ao leitor de tela. Adicione título (h2 ou h3) ou role="region" com aria-label quando o bloco for uma seção.
• O contraste do texto precisa passar de 4,5:1 sobre cada degrau (use text-foreground e text-muted do tema).
• Bordas só quando o fundo não bastar: o tema usa superfícies sem borda fina.

Boas práticas

• Use classes de token (rounded-2xl, p-4), nunca valores soltos.
• Em seções com cabeçalho e rodapé, troque por Widget.
• Em blocos clicáveis, use ItemCard.

Relacionados

• Widget para blocos com cabeçalho e rodapé.
• Card para cartões de conteúdo.
• ItemCard para linhas-cartão.