Skip to Content
Design

Cartões e níveis de superfície

Regras de utilização de cartões de conteúdo, shells de área de trabalho, sobreposições, sombras e fosco de fundo.

Componente em tempo realCamadas de cartão

Os cartões de conteúdo permanecem planos; a estrutura exterior comunica o agrupamento do espaço de trabalho.

Visão geral do projetoPronto para lançamento
Conteúdo12 páginas concluídas

Um cartão de conteúdo padrão não utiliza uma sombra externa.

VerificaçõesPronto para dispositivos móveis

A seleção e o estado são comunicados através da cor e da hierarquia da informação.

Materiais e normas de níveis dos cartões

Este documento descreve publicamente em que cenários a interface do Qokit utiliza sombras, transparência, gradientes e fosco de fundo. Aplica-se à plataforma, Builder, CMS, Dashboard, Studio e Admin. As páginas de marketing e os sites gerados podem ser mais expressivos, mas os efeitos devem pertencer ao tema atual e garantir a legibilidade do conteúdo.

Princípios fundamentais

Os efeitos visuais servem para expressar estrutura, não para decorar cada bloco:

  • O conteúdo distingue-se pela diferença de cor de fundo.
  • Os contentores expressam pertença através de transparência ou gradientes contidos.
  • As sobreposições expressam níveis através de sombras.
  • A interação expressa estados através de cor e anéis de foco.

Os cartões sólidos independentes e os campos de entrada partilham uma sombra primária ligeira; as listas, superfícies aninhadas e os grupos transparentes mantêm-se planos; apenas as sobreposições verdadeiras utilizam sombras evidentes.

Ordem de decisão

Antes de adicionar efeitos de material, determine o papel da superfície:

  1. É um cartão sólido independente ou um campo de entrada? Utilize a superfície primária partilhada ou a sombra de campo.
  2. É uma linha de lista, cartão aninhado, opção repetida ou grupo transparente? Mantenha-se plano.
  3. Organiza vários cartões de conteúdo internos numa área de trabalho? Utilize um Shell.
  4. Sobrepõe conteúdo da página ou aparece acima do plano atual? Utilize sombra de sobreposição.
  5. Está em estado de arrastamento, zoom ou flutuação temporária? Utilize sombra temporária.
  6. Serve apenas para expressar hover, seleção ou foco? Utilize o papel de hover partilhado, cor de fundo interativa e anel de foco.

A menos que o papel da superfície o exija, não combine simultaneamente sombra, transparência, gradiente e fosco.

Matriz de cenários

Papel da superfícieSombraTransparência ou gradienteFosco de fundo
Cartões de conteúdo sólidos independentes, cartões de métricasSombra primária ligeira partilhadaPermitida ligeira diferença de cor de fundoNenhum
Linhas de lista, cartões aninhados, grupos transparentes, opções repetidasNenhumaPermitida ligeira diferença de cor de fundoNenhum
Shell de agrupamento dentro da páginaNenhumaRecomendadoGeralmente não é necessário
Barra lateral ou Shell de área de trabalho permanenteLigeiraRecomendadoPermitido quando há conteúdo visível por trás
Dialog, Popover, Dropdown, menus de contextoSombra de sobreposição claraO fundo deve ser suficientemente sólido para garantir legibilidadePermitido
Pré-visualização de arrastamento, estado de zoom, pré-visualização flutuanteTemporariamente mais forteOpcionalGeralmente não é necessário
HoverManter ou reforçar ligeiramente a sombra primáriaPode alterar o fundoSem alteração
Estado selecionado ou ativoNenhumFundo de destaque ou gradiente contidoSem alteração
Campos de entrada, campos de pesquisaSombra de campo muito ligeiraUtilizar cor de superfície do controloGeralmente não é necessário
Ação primária independente, cápsula independente, invólucro de controlo segmentadoSombra de controlo muito ligeiraUtilizar cor de superfície do controloGeralmente não é necessário
Barra de ferramentas e controlos internos transparentesNenhumaUtilizar cor de superfície do controlo ou transparênciaGeralmente não é necessário
Cartões visuais de páginas de marketing ou sites geradosDeterminado pelo temaPermitidoUtilizar com contenção

Mapeamento de componentes

  • <Card> utiliza por predefinição layer="content": sombra primária ligeira partilhada, sem borda, raio de canto 20px predefinido; as variantes muted, aninhadas, de lista e transparentes mantêm-se planas.
  • <Card layer="shell">: dentro da página serve apenas para agrupar, utilizando superfície transparente ou com gradiente ligeiro e mantendo-se plano; o Shell de área de trabalho permanente recebe o seu próprio nível a partir do modo a que pertence.
  • <Card shape="pill">: utilizado para cartões compactos de uma linha, com raio de canto em forma de cápsula oval.
  • SidebarNavigation: Shell de área de trabalho independente, mantendo gradiente, transparência, fosco e sombra ligeira bem definidos.
  • O PromptPanel do Studio, quando utilizado como contentor de área de trabalho: utilizar --workspace-shell-shadow.
  • DialogPanel, menus pendentes, Popover, menus de contexto e navegador conceptual: utilizar sombra de sobreposição.
  • Canvas do Builder, pré-visualização de dispositivos, pré-visualização de sites gerados, pré-visualização de arrastamento e estado de zoom: como representam planos de pré-visualização independentes ou camadas de interação temporárias, podem manter sombras dedicadas.

Não crie cartões de conteúdo flutuantes em vários níveis. Se for realmente necessário um agrupamento externo, este deve ser um Shell plano. Exceto para sobreposições verdadeiras, deve existir no máximo uma sombra normal de conteúdo ou controlo na mesma cadeia de ancestrais do DOM.

Utilização de variáveis de design (Tokens)

Prefira tokens partilhados, 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 controlo: --qk-shadow-control / --qk-shadow-control-hover
  • Sombra de controlo de ação primária: --qk-shadow-control-accent / --qk-shadow-control-accent-hover
  • Fosco de cartão de conteúdo: --card-backdrop-filter: none
  • Superfície de Shell: --card-shell-surface
  • Fosco de Shell: --card-shell-backdrop-filter
  • Sombra de Shell de área de trabalho: --workspace-shell-shadow
  • Superfície de Dialog: --dialog-surface, fornece um gradiente de tema contido
  • Fosco de Dialog: --dialog-backdrop-filter
  • Sombra de sobreposição de Dialog: --dialog-shadow
  • Raio de canto de Dialog: reutilizar --card-radius
  • Foco de teclado: --focus-ring
  • Sombra de sobreposição: utilizar tokens existentes de Dialog, Dropdown, Menu ou sobreposição de nível de página

Os cartões de conteúdo normais e os painéis de área de trabalho não devem utilizar o token genérico mais forte --shadow.

As sombras globais seguem uma escala discreta de "deslocamento curto, baixa opacidade, incremento conforme o nível de colocação". Os Card, campos e controlos normais não devem aprofundar ou ampliar sombras partilhadas ao longo do roteamento; o Popover e o Dialog expressam o desprendimento da página através de maior deslocamento e alcance de desfocagem, em vez de sobrepor névoa cinzenta escura.

Regras de interação

Hover

  • Os cartões de conteúdo não devem subir para um nível superior a --qk-shadow-surface-hover.
  • Não elevar cartões de conteúdo através de translateY.
  • Utilizar alterações ligeiras de fundo ou feedback claro do controlo.
  • Não alterar a forma, evitando inconsistências de raio de canto ou recorte de sombra.

Seleção e ativação

  • Utilizar superfície de destaque, estado de ícone, estado semântico ou gradiente contido.
  • Não expressar o estado apenas através de sombra.

Foco de teclado

  • Utilizar a regra partilhada focus-visible ou --focus-ring.
  • A sombra normal de cartão não pode substituir a indicação de foco.
  • Deve ser claramente visível tanto nos temas claros como nos escuros.

Arrastamento e zoom

  • Só é permitida sombra mais forte quando a camada está a ser movida ou redimensionada.
  • A sombra temporária deve ser removida após o fim da interação.
  • Os contentores com overflow não podem recortar os efeitos de feedback da camada em movimento.

Transparência e fosco de fundo

A transparência expressa a relação de pertença entre a superfície externa e a área de trabalho. O fosco de fundo só faz sentido quando existe realmente conteúdo, cor ou imagem visível por trás da superfície.

  • Não utilize fosco em fundos de cor sólida: apenas aumenta o custo de renderização sem expressar níveis.
  • O texto, os ícones e os controlos devem ser sempre legíveis, independentemente do fundo por trás.
  • Quando o navegador não suporta fosco de fundo, deve existir um fundo de recurso opaco ou legível.
  • A intensidade de desfocagem deve ser contida em interfaces de trabalho densas.
  • Deve ser validado tanto em temas claros como escuros.

Exceções em que a sombra é permitida

  • Shell de barra lateral de área de trabalho
  • Dialog, Popover, Dropdown, menus e painéis modais
  • Navegador conceptual do Studio e sobreposições de confirmação
  • Canvas do Builder, molduras de dispositivos e planos de pré-visualização de sites gerados
  • Pré-visualização de arrastamento, feedback de zoom e ferramentas flutuantes temporárias
  • Botões de ação primária cujos tokens partilhados já definem sombra
  • Elementos visuais de páginas de marketing e sites gerados controlados pelo tema atual

Estas exceções não podem afetar cartões de conteúdo normais através de seletores amplos ou tokens partilhados.

Lista de verificação

  • Os cartões de conteúdo sólidos independentes e os campos de entrada utilizam apenas o papel de sombra primária ligeira partilhada.
  • As ações primárias independentes, cápsulas independentes e invólucros de controlos segmentados utilizam apenas a sombra de controlo muito ligeira partilhada.
  • Os agrupamentos de página, linhas de lista, cartões aninhados, grupos transparentes, Tabs/Pills repetidos, barras de ferramentas e itens internos de controlos compostos mantêm-se planos.
  • A pesquisa, filtragem, ordenação, visualização e ações primárias inline na barra de ferramentas mantêm-se planas; a sombra ligeira dos campos de entrada normais não deve transbordar 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 já com sombra, tanto o invólucro como o item selecionado mantêm-se planos; o clique do rato não mostra anel de foco de teclado.
  • Exceto para sobreposições verdadeiras, não se sobrepõem múltiplas sombras normais na mesma cadeia de ancestrais.
  • O hover não desloca verticalmente os cartões de conteúdo.
  • Os cartões de conteúdo aninhados foram removidos ou o invólucro externo foi explicitamente definido como Shell.
  • Apenas os Shells verdadeiros utilizam --workspace-shell-shadow.
  • Apenas as sobreposições verdadeiras e as camadas de interação temporárias utilizam sombras mais fortes.
  • Existe conteúdo visível por trás do fosco de fundo e há um fundo de recurso legível.
  • O focus-visible utiliza anel de foco.
  • Os temas claros e escuros mantêm contraste suficiente.
  • As superfícies com raio de canto não recortam o feedback de hover, foco, arrastamento ou sobreposição.
  • As larguras de desktop e móvel não introduzem novos overflows horizontais.
  • A verificação de npm run ui:check-card-surfaces --workspace @qokit-ai/web foi aprovada.

Nesta página