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.
Os cartões de conteúdo permanecem planos; a estrutura exterior comunica o agrupamento do espaço de trabalho.
Um cartão de conteúdo padrão não utiliza uma sombra externa.
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:
- É um cartão sólido independente ou um campo de entrada? Utilize a superfície primária partilhada ou a sombra de campo.
- É uma linha de lista, cartão aninhado, opção repetida ou grupo transparente? Mantenha-se plano.
- Organiza vários cartões de conteúdo internos numa área de trabalho? Utilize um Shell.
- Sobrepõe conteúdo da página ou aparece acima do plano atual? Utilize sombra de sobreposição.
- Está em estado de arrastamento, zoom ou flutuação temporária? Utilize sombra temporária.
- 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ície | Sombra | Transparência ou gradiente | Fosco de fundo |
|---|---|---|---|
| Cartões de conteúdo sólidos independentes, cartões de métricas | Sombra primária ligeira partilhada | Permitida ligeira diferença de cor de fundo | Nenhum |
| Linhas de lista, cartões aninhados, grupos transparentes, opções repetidas | Nenhuma | Permitida ligeira diferença de cor de fundo | Nenhum |
| Shell de agrupamento dentro da página | Nenhuma | Recomendado | Geralmente não é necessário |
| Barra lateral ou Shell de área de trabalho permanente | Ligeira | Recomendado | Permitido quando há conteúdo visível por trás |
| Dialog, Popover, Dropdown, menus de contexto | Sombra de sobreposição clara | O fundo deve ser suficientemente sólido para garantir legibilidade | Permitido |
| Pré-visualização de arrastamento, estado de zoom, pré-visualização flutuante | Temporariamente mais forte | Opcional | Geralmente não é necessário |
| Hover | Manter ou reforçar ligeiramente a sombra primária | Pode alterar o fundo | Sem alteração |
| Estado selecionado ou ativo | Nenhum | Fundo de destaque ou gradiente contido | Sem alteração |
| Campos de entrada, campos de pesquisa | Sombra de campo muito ligeira | Utilizar cor de superfície do controlo | Geralmente não é necessário |
| Ação primária independente, cápsula independente, invólucro de controlo segmentado | Sombra de controlo muito ligeira | Utilizar cor de superfície do controlo | Geralmente não é necessário |
| Barra de ferramentas e controlos internos transparentes | Nenhuma | Utilizar cor de superfície do controlo ou transparência | Geralmente não é necessário |
| Cartões visuais de páginas de marketing ou sites gerados | Determinado pelo tema | Permitido | Utilizar com contenção |
Mapeamento de componentes
<Card>utiliza por predefiniçãolayer="content": sombra primária ligeira partilhada, sem borda, raio de canto20pxpredefinido; 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
PromptPaneldo 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/webfoi aprovada.