Materiais de Cartão e Hierarquia de Superfícies
Regras de uso para cartões de conteúdo, shells de área de trabalho, camadas flutuantes, sombras e desfoque de fundo.
Os cartões de conteúdo permanecem planos; a estrutura externa comunica o agrupamento do espaço de trabalho.
Um cartão de conteúdo padrão não utiliza sombra externa.
Seleção e status são comunicados por cor e hierarquia de informações.
Materiais de Cartão e Normas de Hierarquia
Este documento descreve publicamente em quais cenários a interface do Qokit utiliza sombras, transparência, gradientes e desfoque de fundo. Aplica-se à plataforma, Builder, CMS, Dashboard, Studio e Admin. Páginas de marketing e sites gerados podem ser mais expressivos, mas os efeitos devem pertencer ao tema atual e garantir a legibilidade do conteúdo.
Princípios Fundamentais
Efeitos visuais são usados para expressar estrutura, não para decorar cada bloco:
- O conteúdo é diferenciado pela diferença de cor de fundo.
- Os contêineres expressam pertencimento por meio de transparência ou gradientes contidos.
- Camadas flutuantes expressam hierarquia por meio de sombras.
- A interação expressa estado por meio de cor e anel de foco.
Cartões sólidos independentes e campos de entrada compartilham uma sombra leve de primeiro nível; listas, superfícies aninhadas e grupos transparentes permanecem planos; apenas camadas verdadeiramente flutuantes usam sombras evidentes.
Ordem de Decisão
Antes de adicionar efeitos de material, determine o papel da superfície:
- É um cartão sólido independente ou campo de entrada? Use a sombra compartilhada de primeiro nível de superfície ou campo.
- É uma linha de lista, cartão aninhado, opção repetida ou grupo transparente? Mantenha plano.
- Está organizando vários cartões de conteúdo interno em uma área de trabalho? Use um Shell.
- Está cobrindo o conteúdo da página ou aparecendo acima do plano atual? Use sombra de camada flutuante.
- Está em estado de arrastar, redimensionar ou flutuação temporária? Use sombra temporária.
- É apenas para expressar hover, seleção ou foco? Use o papel compartilhado de hover, cor de fundo de interação e anel de foco.
A menos que o papel da superfície realmente exija, não combine simultaneamente sombra, transparência, gradiente e desfoque.
Matriz de Cenários
| Papel da Superfície | Sombra | Transparência ou Gradiente | Desfoque de Fundo |
|---|---|---|---|
| Cartões de conteúdo sólido independente, cartões de métricas | Sombra leve compartilhada de primeiro nível | Diferença de cor de fundo leve permitida | Nenhum |
| Linhas de lista, cartões aninhados, grupos transparentes, opções repetidas | Nenhuma | Diferença de cor de fundo leve permitida | Nenhum |
| Shell de agrupamento dentro da página | Nenhuma | Recomendado | Geralmente não necessário |
| Sidebar ou Shell de área de trabalho persistente | Leve | Recomendado | Permitido quando há conteúdo visível atrás |
| Dialog, Popover, Dropdown, menu de contexto | Sombra flutuante clara | O fundo deve ser suficientemente sólido para garantir legibilidade | Permitido |
| Pré-visualização de arrastar, estado de zoom, pré-visualização flutuante | Temporariamente mais forte | Opcional | Geralmente não necessário |
| Hover | Manter ou reforçar levemente a sombra de primeiro nível | Pode alterar o fundo | Sem alteração |
| Estado selecionado ou ativo | Nenhum | Fundo de cor de destaque ou gradiente contido | Sem alteração |
| Campos de entrada, campos de busca | Sombra de campo extremamente leve | Usar cor de superfície do controle | Geralmente não necessário |
| Ação primária independente, cápsula independente, invólucro de controle segmentado | Sombra de controle extremamente leve | Usar cor de superfície do controle | Geralmente não necessário |
| Barra de ferramentas e controles internos transparentes | Nenhuma | Usar cor de superfície do controle ou transparente | Geralmente não necessário |
| Cartões visuais de página de marketing ou site gerado | Determinado pelo tema | Permitido | Uso contido |
Mapeamento de Componentes
<Card>usalayer="content"por padrão: sombra leve compartilhada de primeiro nível, sem borda, raio de borda padrão20px; variantes muted, aninhadas, de lista e transparentes permanecem planas.<Card layer="shell">: dentro da página, responsável apenas por agrupamento, usa superfície transparente ou com gradiente leve e permanece plano; o Shell de área de trabalho persistente recebe hierarquia do seu próprio modo.<Card shape="pill">: usado para cartões compactos de linha única, com raio de borda em forma de cápsula oval.SidebarNavigation: Shell de área de trabalho independente, mantém gradiente, transparência, desfoque e sombra leve definidos.- O
PromptPaneldo Studio, quando usado como contêiner de área de trabalho: usa--workspace-shell-shadow. DialogPanel, menus suspensos, Popover, menus de contexto e navegador conceitual: usam sombra flutuante.- Canvas do Builder, pré-visualização de dispositivo, pré-visualização de site gerado, pré-visualização de arrastar e estado de zoom: como representam planos de pré-visualização independentes ou camadas de interação temporária, podem manter sombras dedicadas.
Não crie cartões de conteúdo flutuantes em camadas. Se um agrupamento externo for realmente necessário, ele deve ser um Shell plano. Exceto para camadas flutuantes reais, no máximo uma sombra comum de conteúdo ou controle pode aparecer na mesma cadeia de ancestrais do DOM.
Uso de Variáveis de Design (Tokens)
Prefira usar Tokens compartilhados, não codifique efeitos diretamente:
- Sombra de cartão de conteúdo:
--card-shadow: var(--qk-shadow-surface) - Sombra de hover de cartão de conteúdo:
--card-shadow-hover: var(--qk-shadow-surface-hover) - Sombra de campo:
--input-shadow: var(--qk-shadow-field) - Sombra de campo ativo:
--input-state-shadow: var(--qk-shadow-field-active) - Sombra de controle:
--qk-shadow-control/--qk-shadow-control-hover - Sombra de controle de ação primária:
--qk-shadow-control-accent/--qk-shadow-control-accent-hover - Desfoque de cartão de conteúdo:
--card-backdrop-filter: none - Superfície de Shell:
--card-shell-surface - Desfoque de Shell:
--card-shell-backdrop-filter - Sombra de Shell de área de trabalho:
--workspace-shell-shadow - Superfície de Dialog:
--dialog-surface, fornece gradiente de tema contido - Desfoque de Dialog:
--dialog-backdrop-filter - Sombra flutuante de Dialog:
--dialog-shadow - Raio de borda de Dialog: reutiliza
--card-radius - Foco de teclado:
--focus-ring - Sombra flutuante: use Tokens flutuantes existentes de Dialog, Dropdown, Menu ou nível de página
Cartões de conteúdo comuns e painéis de área de trabalho não devem usar o Token genérico mais forte --shadow.
As sombras globais seguem uma escala discreta de "deslocamento curto, baixa opacidade, incremento por nível de elevação". Cartões, campos e controles comuns não devem aprofundar ou ampliar sombras compartilhadas durante a navegação; Popover e Dialog expressam desprendimento da página por meio de maior deslocamento e alcance de desfoque, não empilhando névoa cinza escura.
Regras de Interação
Hover
- Cartões de conteúdo não devem ser elevados acima do nível
--qk-shadow-surface-hover. - Não eleve cartões de conteúdo por meio de
translateY. - Use variação leve de fundo ou feedback claro de controle.
- Não altere a forma, evitando raios de borda inconsistentes ou recorte de sombra.
Seleção e Ativação
- Use superfície de cor de destaque, estado de ícone, estado semântico ou gradiente contido.
- Não expresse estado apenas por meio de sombra.
Foco de Teclado
- Use a regra compartilhada focus-visible ou
--focus-ring. - Sombras comuns de cartão não podem substituir a indicação de foco.
- Deve ser claramente visível nos temas claro e escuro.
Arrastar e Redimensionar
- Sombras mais fortes só são permitidas quando a camada está sendo movida ou redimensionada.
- A sombra temporária deve ser removida após o término da interação.
- Contêineres com overflow não podem recortar os efeitos de feedback da camada em movimento.
Transparência e Desfoque de Fundo
A transparência é usada para expressar a relação de pertencimento entre superfícies externas e áreas de trabalho. O desfoque de fundo só faz sentido quando há conteúdo, cor ou imagem realmente visível atrás da superfície.
- Não use desfoque em fundos de cor sólida, pois apenas aumenta o custo de renderização sem expressar hierarquia.
- Independentemente do fundo por trás, textos, ícones e controles devem ser claramente legíveis.
- Quando o navegador não suporta desfoque de fundo, deve haver um fundo de fallback opaco ou legível.
- A intensidade do desfoque deve ser contida em interfaces densas.
- Deve ser validado tanto no tema claro quanto no escuro.
Exceções que Podem Manter Sombra
- Shell de sidebar de área de trabalho
- Dialog, Popover, Dropdown, menus e painéis modais
- Navegador conceitual do Studio e camadas flutuantes de confirmação
- Canvas do Builder, moldura de dispositivo e planos de pré-visualização de site gerado
- Pré-visualização de arrastar, feedback de zoom e ferramentas flutuantes temporárias
- Botões de ação primária cujos Tokens compartilhados já definem sombra
- Elementos visuais de páginas de marketing e sites gerados controlados pelo tema atual
Essas exceções não podem afetar cartões de conteúdo comuns por meio de seletores amplos ou Tokens compartilhados.
Lista de Verificação de Revisão
- Cartões de conteúdo sólido independente e campos de entrada usam apenas o papel compartilhado de sombra leve de primeiro nível.
- Ação primária independente, cápsula independente e invólucro de controle segmentado usam apenas a sombra compartilhada extremamente leve de controle.
- Agrupamento de página, linhas de lista, cartões aninhados, grupos transparentes, Tabs/Pills repetidos, barras de ferramentas e itens internos de controles compostos permanecem planos.
- Busca, filtro, ordenação, visualização e ações primárias inline na barra de ferramentas permanecem planos; a sombra leve de campos de entrada comuns não pode vazar para a barra de ferramentas, exceto o anel de foco de teclado.
- Quando o Segmented está dentro de um cartão, diálogo ou barra de ferramentas com sombra existente, tanto o invólucro quanto o item selecionado permanecem planos; o clique do mouse não exibe o anel de foco de teclado.
- Exceto para camadas flutuantes reais, múltiplas sombras comuns não são empilhadas na mesma cadeia de ancestrais.
- O hover não move verticalmente os cartões de conteúdo.
- Cartões de conteúdo aninhados foram removidos ou o invólucro externo foi explicitamente definido como Shell.
- Apenas Shells verdadeiros usam
--workspace-shell-shadow. - Apenas camadas flutuantes reais e camadas de interação temporária usam sombras mais fortes.
- Há conteúdo visível atrás do desfoque de fundo e há um fundo de fallback legível.
- O focus-visible usa anel de foco.
- Os temas claro e escuro mantêm contraste suficiente.
- Superfícies com raio de borda não recortam feedback de hover, foco, arrastar ou camada flutuante.
- Larguras de desktop e mobile não apresentam novo overflow horizontal.
- Verificação de
npm run ui:check-card-surfaces --workspace @qokit-ai/webaprovada.