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.
Les cartes de contenu restent plates ; la coque externe communique le regroupement de l'espace de travail.
Une carte de contenu standard n'utilise pas d'ombre externe.
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 :
- 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.
- Est-ce une ligne de liste, une carte imbriquée, une option répétée ou un groupe transparent ? Gardez-la plate.
- Organisez-vous plusieurs cartes de contenu internes en un espace de travail ? Utilisez un Shell.
- Recouvre-t-elle le contenu de la page ou apparaît-elle au-dessus du plan actuel ? Utilisez une ombre de calque flottant.
- Est-elle en état de glisser-déposer, de zoom ou de survol temporaire ? Utilisez une ombre temporaire.
- 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 surface | Ombre | Transparence ou dégradé | Floutage d'arrière-plan |
|---|---|---|---|
| Cartes de contenu unies indépendantes, cartes d'indicateurs | Ombre légère partagée de premier niveau | Léger contraste de couleur d'arrière-plan autorisé | Aucun |
| Lignes de liste, cartes imbriquées, groupes transparents, options répétées | Aucune | Léger contraste de couleur d'arrière-plan autorisé | Aucun |
| Shell de groupe dans la page | Aucune | Recommandé | Généralement non nécessaire |
| Barre latérale ou Shell d'espace de travail permanent | Légère | Recommandé | Autorisé lorsque du contenu visible se trouve derrière |
| Dialog, Popover, Dropdown, menus contextuels | Ombre de calque flottant prononcée | L'arrière-plan doit être suffisamment opaque pour garantir la lisibilité | Autorisé |
| Aperçu de glisser-déposer, état de zoom, aperçu de survol | Temporairement plus prononcée | Optionnel | Généralement non nécessaire |
| Survol | Maintenir ou renforcer légèrement l'ombre de premier niveau | L'arrière-plan peut changer | Aucun changement |
| Sélection ou état actif | Aucune | Arrière-plan de couleur d'accentuation ou dégradé sobre | Aucun changement |
| Champs de saisie, barres de recherche | Ombre de champ très légère | Utiliser la couleur de surface du contrôle | Gé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ère | Utiliser la couleur de surface du contrôle | Généralement non nécessaire |
| Barre d'outils et contrôles internes transparents | Aucune | Utiliser la couleur de surface du contrôle ou la transparence | Généralement non nécessaire |
| Pages marketing ou cartes visuelles de sites générés | Déterminé par le thème | Autorisé | Utilisation sobre |
Mappage des composants
<Card>utilise par défautlayer="content": ombre légère partagée de premier niveau, pas de bordure, rayon par défaut20px; 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
PromptPanelde 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/webréussie.