Superficies de tarjetas y niveles de elevación
Reglas de uso para tarjetas de contenido, shells de espacio de trabajo, capas flotantes, sombras y desenfoque de fondo.
Las tarjetas de contenido permanecen planas; la envolvente exterior comunica el agrupamiento del espacio de trabajo.
Una tarjeta de contenido estándar no utiliza una sombra externa.
La selección y el estado se comunican mediante color y jerarquía de información.
Materiales de tarjetas y normas de niveles
Este documento describe públicamente en qué escenarios la interfaz de Qokit utiliza sombras, transparencia, degradados y desenfoque de fondo. Aplica a la plataforma extendida, Builder, CMS, Dashboard, Studio y Admin. Las páginas de marketing y los sitios generados pueden ser más expresivos, pero los efectos deben pertenecer al tema actual y garantizar la legibilidad del contenido.
Principios fundamentales
Los efectos visuales se usan para expresar estructura, no para decorar cada bloque:
- El contenido se diferencia mediante contraste de color de fondo.
- Los contenedores expresan pertenencia mediante transparencia o degradados sobrios.
- Las capas flotantes expresan niveles mediante sombras.
- La interacción expresa estados mediante color y anillos de enfoque.
Las tarjetas sólidas independientes y los campos de entrada comparten una sombra ligera de primer nivel; las listas, superficies anidadas y agrupaciones transparentes se mantienen planas; solo las capas verdaderamente flotantes usan sombras pronunciadas.
Orden de decisión
Antes de añadir efectos de material, determina primero el rol de la superficie:
- ¿Es una tarjeta sólida independiente o un campo de entrada? Usa la sombra compartida de primer nivel de superficie o campo.
- ¿Es una fila de lista, tarjeta anidada, opción repetida o agrupación transparente? Mantenla plana.
- ¿Organiza varias tarjetas de contenido internas en un espacio de trabajo? Usa un Shell.
- ¿Cubre contenido de la página o aparece por encima del plano actual? Usa sombra de capa flotante.
- ¿Está en estado de arrastre, zoom o flotación temporal? Usa sombra temporal.
- ¿Solo expresa hover, selección o focus? Usa el rol compartido de hover, color de fondo de interacción y anillo de enfoque.
No combines simultáneamente sombra, transparencia, degradado y desenfoque a menos que el rol de la superficie lo requiera realmente.
Matriz de escenarios
| Rol de superficie | Sombra | Transparencia o degradado | Desenfoque de fondo |
|---|---|---|---|
| Tarjetas de contenido sólidas independientes, tarjetas de métricas | Sombra ligera compartida de primer nivel | Se permite ligera diferencia de color de fondo | Ninguno |
| Filas de lista, tarjetas anidadas, agrupaciones transparentes, opciones repetidas | Ninguna | Se permite ligera diferencia de color de fondo | Ninguno |
| Shell de agrupación dentro de página | Ninguna | Recomendado | Generalmente no necesario |
| Barra lateral o Shell de espacio de trabajo persistente | Ligera | Recomendado | Permitido cuando hay contenido visible detrás |
| Dialog, Popover, Dropdown, menús contextuales | Sombra de capa flotante clara | El fondo debe ser suficientemente opaco para garantizar legibilidad | Permitido |
| Vista previa de arrastre, estado de zoom, vista previa flotante | Temporalmente más fuerte | Opcional | Generalmente no necesario |
| Hover | Mantener o reforzar ligeramente la sombra de primer nivel | Puede cambiar el fondo | Sin cambios |
| Estado seleccionado o activo | Ninguna | Fondo de acento o degradado sobrio | Sin cambios |
| Campos de entrada, campos de búsqueda | Sombra de campo muy ligera | Usar color de superficie de control | Generalmente no necesario |
| Acción primaria independiente, cápsula independiente, carcasa de control segmentado | Sombra de control muy ligera | Usar color de superficie de control | Generalmente no necesario |
| Barra de herramientas y controles internos transparentes | Ninguna | Usar color de superficie de control o transparente | Generalmente no necesario |
| Tarjetas visuales de páginas de marketing o sitios generados | Determinado por el tema | Permitido | Uso sobrio |
Mapeo de componentes
<Card>usa por defectolayer="content": sombra ligera compartida de primer nivel, sin borde, radio de esquina predeterminado20px; las variantes muted, anidadas, de lista y transparentes se mantienen planas.<Card layer="shell">: dentro de la página solo se encarga de agrupar, usa superficie transparente o con degradado ligero y se mantiene plano; el Shell de espacio de trabajo persistente recibe su propio nivel según el modo.<Card shape="pill">: para tarjetas compactas de una sola línea, con radio de esquina de cápsula ovalada.SidebarNavigation: Shell de espacio de trabajo independiente, conserva degradado, transparencia, desenfoque y sombra ligera definidos.- El
PromptPanelde Studio como contenedor de espacio de trabajo: usa--workspace-shell-shadow. DialogPanel, menús desplegables, Popover, menús contextuales y explorador de conceptos: usan sombra de capa flotante.- Lienzo de Builder, vista previa de dispositivos, vista previa de sitios generados, vista previa de arrastre y estado de zoom: pueden conservar sombras dedicadas porque representan planos de vista previa independientes o capas de interacción temporal.
No crees tarjetas de contenido flotantes en múltiples niveles. Si realmente necesitas una agrupación externa, debe ser un Shell plano. Excepto para capas flotantes reales, solo puede aparecer una sombra ordinaria de contenido o control en la misma cadena de ancestros del DOM.
Uso de variables de diseño (Tokens)
Prioriza el uso de Tokens compartidos, no codifiques efectos directamente:
- Sombra de tarjeta de contenido:
--card-shadow: var(--qk-shadow-surface) - Sombra de tarjeta de contenido en hover:
--card-shadow-hover: var(--qk-shadow-surface-hover) - Sombra de campo:
--input-shadow: var(--qk-shadow-field) - Sombra de campo activo:
--input-state-shadow: var(--qk-shadow-field-active) - Sombra de control:
--qk-shadow-control/--qk-shadow-control-hover - Sombra de control de acción primaria:
--qk-shadow-control-accent/--qk-shadow-control-accent-hover - Desenfoque de tarjeta de contenido:
--card-backdrop-filter: none - Superficie de Shell:
--card-shell-surface - Desenfoque de Shell:
--card-shell-backdrop-filter - Sombra de Shell de espacio de trabajo:
--workspace-shell-shadow - Superficie de Dialog:
--dialog-surface, proporciona un degradado temático sobrio - Desenfoque de Dialog:
--dialog-backdrop-filter - Sombra flotante de Dialog:
--dialog-shadow - Radio de esquina de Dialog: reutiliza
--card-radius - Enfoque de teclado:
--focus-ring - Sombra flotante: usa Tokens existentes de Dialog, Dropdown, Menu o capa flotante de página
Las tarjetas de contenido ordinarias y los paneles de espacio de trabajo no deben usar el Token genérico más fuerte --shadow.
Las sombras globales siguen una escala silenciosa de "desplazamiento corto, baja opacidad, incremento según nivel de elevación". Las Card, campos y controles ordinarios no deben profundizar ni ampliar sombras compartidas en las rutas; Popover y Dialog expresan separación del página mediante mayor desplazamiento y rango de desenfoque, no superponiendo niebla gris oscura.
Reglas de interacción
Hover
- Las tarjetas de contenido no deben elevarse por encima del nivel
--qk-shadow-surface-hover. - No eleves tarjetas de contenido mediante
translateY. - Usa cambios ligeros de fondo o retroalimentación clara de control.
- No cambies la forma, evita radios de esquina inconsistentes o recorte de sombras.
Selección y activación
- Usa superficie de acento, estado de icono, estado semántico o degradado sobrio.
- No expreses estados solo mediante sombras.
Enfoque de teclado
- Usa la regla compartida focus-visible o
--focus-ring. - La sombra genérica de tarjeta no puede sustituir la indicación de enfoque.
- Debe ser claramente visible tanto en temas claros como oscuros.
Arrastre y zoom
- Solo se permite sombra más fuerte cuando la capa se está moviendo o redimensionando.
- La sombra temporal debe eliminarse al finalizar la interacción.
- Los contenedores con desbordamiento no deben recortar los efectos de retroalimentación de la capa en movimiento.
Transparencia y desenfoque de fondo
La transparencia se usa para expresar la relación de pertenencia entre superficies externas y espacios de trabajo. El desenfoque de fondo solo tiene sentido cuando realmente hay contenido, color o imagen visible detrás de la superficie.
- No uses desenfoque sobre fondos de color sólido; solo aumenta el coste de renderizado sin expresar niveles.
- El texto, los iconos y los controles deben ser claramente legibles sin importar el fondo que haya detrás.
- Cuando el navegador no soporta desenfoque de fondo, debe haber un fondo alternativo opaco o legible.
- La intensidad del desenfoque debe ser sobria en interfaces de trabajo densas.
- Debe validarse tanto en temas claros como oscuros.
Excepciones donde se permite conservar sombras
- Shell de barra lateral de espacio de trabajo
- Dialog, Popover, Dropdown, menús y paneles modales
- Explorador de conceptos de Studio y capas flotantes de confirmación
- Lienzo de Builder, marcos de dispositivos y planos de vista previa de sitios generados
- Vista previa de arrastre, retroalimentación de zoom y herramientas flotantes temporales
- Botones de acción primaria cuyo Token compartido ya define sombra
- Elementos visuales de páginas de marketing y sitios generados controlados por el tema actual
Estas excepciones no deben afectar a tarjetas de contenido ordinarias mediante selectores amplios o Tokens compartidos.
Lista de verificación
- Las tarjetas de contenido sólidas independientes y los campos de entrada solo usan el rol compartido de sombra ligera de primer nivel.
- Las acciones primarias independientes, cápsulas independientes y carcasas de control segmentado solo usan la sombra compartida muy ligera de control.
- Las agrupaciones de página, filas de lista, tarjetas anidadas, agrupaciones transparentes, pestañas/píldoras repetidas, barras de herramientas e ítems internos de controles compuestos se mantienen planos.
- La búsqueda, filtrado, ordenación, vistas y acciones primarias en línea dentro de barras de herramientas se mantienen planas; la sombra ligera de campos ordinarios no debe filtrarse a la barra de herramientas, excepto el anillo de enfoque de teclado.
- Cuando Segmented está dentro de una tarjeta, diálogo o barra de herramientas con sombra existente, tanto la carcasa como el ítem seleccionado se mantienen planos; el clic del ratón no muestra anillo de enfoque de teclado.
- Excepto para capas flotantes reales, no se superponen múltiples sombras ordinarias en la misma cadena de ancestros.
- El hover no desplaza verticalmente las tarjetas de contenido.
- Se han eliminado las tarjetas de contenido anidadas o se ha definido explícitamente la capa externa como Shell.
- Solo los Shells verdaderos usan
--workspace-shell-shadow. - Solo las capas flotantes reales y las capas de interacción temporal usan sombras más fuertes.
- Hay contenido visible detrás del desenfoque de fondo y existe un fondo alternativo legible.
- focus-visible usa anillo de enfoque.
- Se mantiene contraste suficiente tanto en temas claros como oscuros.
- Las superficies con radio de esquina no recortan retroalimentación de hover, focus, arrastre o capa flotante.
- No aparecen nuevos desbordamientos horizontales en anchos de escritorio y móvil.
- La verificación de
npm run ui:check-card-surfaces --workspace @qokit-ai/webha sido superada.