Skip to Content
Conception

Cartes et niveaux de surface

Règles d'utilisation des cartes de contenu, des shells d'espace de travail, des calques flottants, des ombres et du floutage d'arrière-plan.

Composant en directCalques de carte

Les cartes de contenu restent plates ; la coque externe communique le regroupement de l'espace de travail.

Aperçu du projetPrêt à lancement
Contenu12 pages terminées

Une carte de contenu standard n'utilise pas d'ombre externe.

VérificationsPrêt mobile

La sélection et l'état sont communiqués par la couleur et la hiérarchie de l'information.

Matériaux de carte et normes de niveaux

Ce document décrit publiquement les scénarios dans lesquels l'interface Qokit utilise des ombres, de la transparence, des dégradés et du floutage d'arrière-plan. S'applique à la plateforme étendue, Builder, CMS, Dashboard, Studio et Admin. Les pages marketing et les sites générés peuvent être plus expressifs, mais les effets doivent appartenir au thème actuel et garantir la lisibilité du contenu.

Principes fondamentaux

Les effets visuels servent à exprimer la structure, pas à décorer chaque bloc :

  • Le contenu est différencié par les contrastes de couleur d'arrière-plan.
  • Les conteneurs expriment leur appartenance par la transparence ou des dégradés sobres.
  • Les calques flottants expriment les niveaux par des ombres.
  • Les interactions expriment les états par la couleur et les anneaux de focus.

Les cartes unies indépendantes et les champs de saisie partagent une ombre légère de premier niveau ; les listes, les surfaces imbriquées et les groupes transparents restent plats ; seules les véritables surfaces flottantes utilisent des ombres prononcées.

Ordre de décision

Avant d'ajouter un effet de matériau, déterminez d'abord le rôle de la surface :

  1. Est-ce une carte unie indépendante ou un champ de saisie ? Utilisez l'ombre partagée de premier niveau pour la surface ou le champ.
  2. Est-ce une ligne de liste, une carte imbriquée, une option répétée ou un groupe transparent ? Gardez-la plate.
  3. Organisez-vous plusieurs cartes de contenu internes en un espace de travail ? Utilisez un Shell.
  4. Recouvre-t-elle le contenu de la page ou apparaît-elle au-dessus du plan actuel ? Utilisez une ombre de calque flottant.
  5. Est-elle en état de glisser-déposer, de zoom ou de survol temporaire ? Utilisez une ombre temporaire.
  6. Est-ce uniquement pour exprimer le survol, la sélection ou le focus ? Utilisez le rôle de survol partagé, la couleur d'arrière-plan d'interaction et l'anneau de focus.

Ne superposez pas ombre, transparence, dégradé et floutage simultanément, sauf si le rôle de la surface l'exige vraiment.

Matrice des scénarios

Rôle de surfaceOmbreTransparence ou dégradéFloutage d'arrière-plan
Cartes de contenu unies indépendantes, cartes d'indicateursOmbre légère partagée de premier niveauLéger contraste de couleur d'arrière-plan autoriséAucun
Lignes de liste, cartes imbriquées, groupes transparents, options répétéesAucuneLéger contraste de couleur d'arrière-plan autoriséAucun
Shell de groupe dans la pageAucuneRecommandéGénéralement non nécessaire
Barre latérale ou Shell d'espace de travail permanentLégèreRecommandéAutorisé lorsque du contenu visible se trouve derrière
Dialog, Popover, Dropdown, menus contextuelsOmbre de calque flottant prononcéeL'arrière-plan doit être suffisamment opaque pour garantir la lisibilitéAutorisé
Aperçu de glisser-déposer, état de zoom, aperçu de survolTemporairement plus prononcéeOptionnelGénéralement non nécessaire
SurvolMaintenir ou renforcer légèrement l'ombre de premier niveauL'arrière-plan peut changerAucun changement
Sélection ou état actifAucuneArrière-plan de couleur d'accentuation ou dégradé sobreAucun changement
Champs de saisie, barres de rechercheOmbre de champ très légèreUtiliser la couleur de surface du contrôleGénéralement non nécessaire
Action principale indépendante, capsule indépendante, enveloppe de contrôle segmentéOmbre de contrôle très légèreUtiliser la couleur de surface du contrôleGénéralement non nécessaire
Barre d'outils et contrôles internes transparentsAucuneUtiliser la couleur de surface du contrôle ou la transparenceGénéralement non nécessaire
Pages marketing ou cartes visuelles de sites générésDéterminé par le thèmeAutoriséUtilisation sobre

Mappage des composants

  • <Card> utilise par défaut layer="content" : ombre légère partagée de premier niveau, pas de bordure, rayon par défaut 20px ; les variantes muted, imbriquées, listes et transparentes restent plates.
  • <Card layer="shell"> : dans la page, responsable uniquement du regroupement, utilise une surface transparente ou un dégradé léger et reste plat ; le Shell d'espace de travail permanent fournit son propre niveau selon le mode.
  • <Card shape="pill"> : pour les cartes compactes sur une seule ligne, avec un rayon de capsule ovale.
  • SidebarNavigation : Shell d'espace de travail indépendant, conserve un dégradé, une transparence, un floutage et une ombre légère prononcés.
  • Le PromptPanel de Studio en tant que conteneur d'espace de travail : utiliser --workspace-shell-shadow.
  • DialogPanel, menus déroulants, Popover, menus contextuels et explorateur conceptuel : utiliser l'ombre de calque flottant.
  • Canevas Builder, aperçu d'appareil, aperçu de site généré, aperçu de glisser-déposer et état de zoom : comme ils représentent un plan d'aperçu indépendant ou un calque d'interaction temporaire, une ombre dédiée peut être conservée.

Ne créez pas de cartes de contenu flottant en couches. Si un regroupement externe est vraiment nécessaire, il doit s'agir d'un Shell plat. À l'exception des véritables calques flottants, un maximum d'une ombre ordinaire de contenu ou de contrôle peut apparaître dans la même chaîne d'ancêtres DOM.

Utilisation des variables de design (Tokens)

Privilégiez les Tokens partagés, ne codez pas les effets en dur :

  • Ombre de carte de contenu : --card-shadow: var(--qk-shadow-surface)
  • Ombre de survol de carte de contenu : --card-shadow-hover: var(--qk-shadow-surface-hover)
  • Ombre de champ : --input-shadow: var(--qk-shadow-field)
  • Ombre de champ actif : --input-state-shadow: var(--qk-shadow-field-active)
  • Ombre de contrôle : --qk-shadow-control / --qk-shadow-control-hover
  • Ombre de contrôle d'action principale : --qk-shadow-control-accent / --qk-shadow-control-accent-hover
  • Floutage de carte de contenu : --card-backdrop-filter: none
  • Surface de Shell : --card-shell-surface
  • Floutage de Shell : --card-shell-backdrop-filter
  • Ombre de Shell d'espace de travail : --workspace-shell-shadow
  • Surface de Dialog : --dialog-surface, fournit un dégradé de thème sobre
  • Floutage de Dialog : --dialog-backdrop-filter
  • Ombre de calque flottant de Dialog : --dialog-shadow
  • Rayon de Dialog : réutilise --card-radius
  • Focus clavier : --focus-ring
  • Ombre de calque flottant : utiliser les Tokens de calque flottant existants de Dialog, Dropdown, Menu ou de niveau page

Les cartes de contenu ordinaires et les panneaux d'espace de travail ne doivent pas utiliser le Token générique plus prononcé --shadow.

Les ombres globales adoptent une échelle discrète de « déplacement court, faible opacité, incrément selon le niveau de dépôt ». Les Card, champs et contrôles ordinaires ne doivent pas approfondir ou agrandir les ombres partagées dans les routes ; les Popover et Dialog expriment leur détachement de la page par un déplacement et une plage de flou plus importants, plutôt qu'en superposant un brouillard gris foncé.

Règles d'interaction

Survol (Hover)

  • Les cartes de contenu ne doivent pas être élevées au-delà du niveau --qk-shadow-surface-hover.
  • Ne pas élever les cartes de contenu via translateY.
  • Utiliser un léger changement d'arrière-plan ou un retour de contrôle clair.
  • Ne pas changer la forme, éviter les rayons incohérents ou le découpage d'ombre.

Sélection et activation

  • Utiliser une surface de couleur d'accentuation, un état d'icône, un état sémantique ou un dégradé sobre.
  • Ne pas exprimer l'état uniquement par une ombre.

Focus clavier

  • Utiliser la règle focus-visible partagée ou --focus-ring.
  • L'ombre de carte générique ne peut pas remplacer l'indicateur de focus.
  • Doit être clairement visible dans les thèmes clair et sombre.

Glisser-déposer et zoom

  • Une ombre plus prononcée n'est autorisée que lorsque le calque est en cours de déplacement ou de redimensionnement.
  • L'ombre temporaire doit être supprimée à la fin de l'interaction.
  • Les conteneurs en débordement ne doivent pas découper les effets de retour du calque en mouvement.

Transparence et floutage d'arrière-plan

La transparence exprime la relation d'appartenance entre la surface externe et l'espace de travail. Le floutage d'arrière-plan n'a de sens que lorsque du contenu, des couleurs ou des images visibles se trouvent réellement derrière la surface.

  • N'utilisez pas de floutage sur un arrière-plan uni, cela augmente uniquement le coût de rendu sans exprimer de niveau.
  • Le texte, les icônes et les contrôles doivent rester clairement lisibles quel que soit l'arrière-plan derrière lequel ils passent.
  • Lorsque le navigateur ne prend pas en charge le floutage d'arrière-plan, un arrière-plan de secours opaque ou lisible doit être fourni.
  • L'intensité du flou doit être sobre dans les interfaces d'espace de travail denses.
  • Les thèmes clair et sombre doivent être validés simultanément.

Exceptions autorisées à conserver les ombres

  • Shell de barre latérale d'espace de travail
  • Dialog, Popover, Dropdown, menus et panneaux modaux
  • Explorateur conceptuel de Studio et calques flottants de confirmation
  • Canevas Builder, cadres d'appareil et plans d'aperçu de sites générés
  • Aperçus de glisser-déposer, retours de zoom et outils de survol temporaires
  • Boutons d'action principale dont l'ombre est définie par les Tokens de bouton partagés
  • Éléments visuels de pages marketing et de sites générés contrôlés par le thème actuel

Ces exceptions ne doivent pas affecter les cartes de contenu ordinaires via des sélecteurs larges ou des Tokens partagés.

Liste de vérification

  • Les cartes de contenu unies indépendantes et les champs de saisie utilisent uniquement le rôle d'ombre légère partagée de premier niveau.
  • Les actions principales indépendantes, les capsules indépendantes et les enveloppes de contrôles segmentés utilisent uniquement l'ombre de contrôle très légère partagée.
  • Les groupes de page, lignes de liste, cartes imbriquées, groupes transparents, onglets/pilles répétées, barres d'outils et éléments internes de contrôles composites restent plats.
  • La recherche, le filtrage, le tri, les vues et les actions principales en ligne dans la barre d'outils restent plats ; l'ombre légère des champs de saisie ordinaires ne doit pas déborder dans la barre d'outils, à l'exception de l'anneau de focus clavier.
  • Lorsque Segmented est situé à l'intérieur d'une carte, d'une boîte de dialogue ou d'une barre d'outils déjà ombrée, l'enveloppe et l'élément sélectionné restent tous deux plats ; le clic de souris n'affiche pas l'anneau de focus clavier.
  • À l'exception des véritables calques flottants, plusieurs ombres ordinaires ne sont pas superposées dans la même chaîne d'ancêtres.
  • Le survol ne déplace pas verticalement les cartes de contenu.
  • Les cartes de contenu imbriquées ont été supprimées, ou la couche externe a été explicitement définie comme Shell.
  • Seuls les véritables Shells utilisent --workspace-shell-shadow.
  • Seuls les véritables calques flottants et les calques d'interaction temporaires utilisent des ombres plus prononcées.
  • Du contenu visible existe derrière le floutage d'arrière-plan, et un arrière-plan de secours lisible est fourni.
  • focus-visible utilise un anneau de focus.
  • Un contraste suffisant est maintenu dans les thèmes clair et sombre.
  • Les surfaces à rayon ne découpent pas les retours de survol, de focus, de glisser-déposer ou de calque flottant.
  • Aucune nouvelle surcharge horizontale n'apparaît aux largeurs bureau et mobile.
  • Vérification npm run ui:check-card-surfaces --workspace @qokit-ai/web réussie.

Sur cette page