Skip to Content
Ontwerp

Kaart- en oppervlaklagen

Gebruiksregels voor inhoudskaarten, werkruimte-shells, overlays, schaduwen en achtergrondvervaging.

Live-componentKaartlagen

Inhoudskaarten blijven plat; de buitenste structuur communiceert groepering in het werkruimte.

ProjectoverzichtLaunchbereidheid
Inhoud12 pagina’s voltooid

Een standaard inhoudskaart gebruikt geen buitenschaduw.

ControlesMobiel klaar

Selectie en status worden gecommuniceerd via kleur en informatierijkschap.

Kaartmaterialen en laagspecificaties

Dit document beschrijft openbaar wanneer de Qokit-werkomgeving schaduwen, transparantie, verlopen en achtergrondvervaging gebruikt. Van toepassing op platformuitbreidingen, Builder, CMS, Dashboard, Studio en Admin. Marketingpagina's en gegenereerde sites kunnen expressiever zijn, maar effecten moeten bij het huidige thema horen en de leesbaarheid van inhoud waarborgen.

Kernprincipes

Visuele effecten worden gebruikt om structuur uit te drukken, niet om elk blok te decoreren:

  • Inhoud wordt onderscheiden door achtergrondkleurverschillen.
  • Containers drukken toebehoren uit via transparantie of ingetogen verlopen.
  • Overlays drukken lagen uit via schaduwen.
  • Interactie drukt status uit via kleur en focusringen.

Onafhankelijke effen kaarten en invoervelden delen een lichte primaire schaduw; lijsten, geneste oppervlakken en transparante groepen blijven plat; alleen echte overlays gebruiken duidelijke schaduwen.

Bepalingsvolgorde

Bepaal voordat u materiaaleffecten toevoegt de rol van het oppervlak:

  1. Is het een onafhankelijke effen kaart of invoerveld? Gebruik de gedeelde primaire oppervlak- of veldschaduw.
  2. Is het een lijstrij, geneste kaart, herhaalde optie of transparante groep? Houd het plat.
  3. Organiseert het meerdere interne inhoudskaarten in een werkruimte? Gebruik een Shell.
  4. Bedekt het pagina-inhoud of verschijnt het boven het huidige vlak? Gebruik een overlay-schaduw.
  5. Is het in een sleep-, zoom- of tijdelijke zweefstatus? Gebruik een tijdelijke schaduw.
  6. Is het alleen om hover, selectie of focus uit te drukken? Gebruik de gedeelde hover-rol, interactie-achtergrondkleur en focusring.

Stapel geen schaduwen, transparantie, verlopen en vervaging tegelijkertijd tenzij de rol van het oppervlak dit echt vereist.

Scenariomatrix

OppervlakrolSchaduwTransparantie of verloopAchtergrondvervaging
Onafhankelijke effen inhoudskaarten, metriekkaartenGedeelde lichte primaire schaduwLichte achtergrondkleurverschillen toegestaanGeen
Lijstrijen, geneste kaarten, transparante groepen, herhaalde optiesGeenLichte achtergrondkleurverschillen toegestaanGeen
Pagina-interne groeps-ShellGeenAanbevolenMeestal niet nodig
Zijbalk of permanente werkruimte-ShellLichtAanbevolenToegestaan wanneer er zichtbare inhoud achter staat
Dialog, Popover, Dropdown, contextmenuDuidelijke overlay-schaduwAchtergrond moet voldoende effen zijn voor leesbaarheidToegestaan
Sleepvoorbeelden, zoomstatus, zweefvoorbeeldenTijdelijk sterkerOptioneelMeestal niet nodig
HoverBehoud of lichte versterking van primaire schaduwAchtergrond kan veranderenVerandert niet
Selectie- of actieve statusGeenAccentkleur-achtergrond of ingetogen verloopVerandert niet
Invoervelden, zoekveldenZeer lichte veldschaduwGebruik controle-oppervlakkleurMeestal niet nodig
Onafhankelijke primaire acties, onafhankelijke capsules, segmentbesturingsbehuizingenZeer lichte controleschaduwGebruik controle-oppervlakkleurMeestal niet nodig
Werkbalken en transparante interne besturingselementenGeenGebruik controle-oppervlakkleur of transparantMeestal niet nodig
Marketingpagina's of gegenereerde site visuele kaartenBepaald door themaToegestaanIngetogen gebruik

Componenttoewijzing

  • <Card> gebruikt standaard layer="content": gedeelde lichte primaire schaduw, geen rand, standaard 20px hoekradius; gedempte, geneste, lijst- en transparante varianten blijven plat.
  • <Card layer="shell">: binnen pagina's alleen verantwoordelijk voor groepering, gebruikt transparante of lichte verloopoppervlakken en blijft plat; permanente werkruimte-Shells krijgen hun laag van het bijbehorende patroon.
  • <Card shape="pill">: voor compacte enkele rij kaarten, hoekradius is een ovaal capsulevorm.
  • SidebarNavigation: onafhankelijke werkruimte-Shell, behoudt duidelijke verlopen, transparantie, vervaging en lichte schaduwen.
  • De PromptPanel van Studio als werkruimtecontainer: gebruikt --workspace-shell-shadow.
  • DialogPanel, dropdownmenu's, Popover, contextmenu's en conceptverkenner: gebruiken overlay-schaduwen.
  • Builder-canvas, apparaatvoorbeelden, gegenereerde site-voorbeelden, sleepvoorbeelden en zoomstatus: kunnen speciale schaduwen behouden omdat ze een onafhankelijk voorbeeldvlak of tijdelijke interactorlaag vertegenwoordigen.

Maak geen lagen van zwevende inhoudskaarten. Als een externe groepering echt nodig is, moet het een platte Shell zijn. Behalve bij echte overlays mag maximaal één gewone inhouds- of controleschaduw voorkomen in dezelfde DOM-voorouderketen.

Ontwerpvariabelen (Token) gebruik

Geef voorrang aan gedeelde Tokens, codeer effecten niet hard:

  • Inhoudskaart-schaduw: --card-shadow: var(--qk-shadow-surface)
  • Inhoudskaart hover-schaduw: --card-shadow-hover: var(--qk-shadow-surface-hover)
  • Veldschaduw: --input-shadow: var(--qk-shadow-field)
  • Veldactieve schaduw: --input-state-shadow: var(--qk-shadow-field-active)
  • Controleschaduw: --qk-shadow-control / --qk-shadow-control-hover
  • Primaire actie-controleschaduw: --qk-shadow-control-accent / --qk-shadow-control-accent-hover
  • Inhoudskaart-vervaging: --card-backdrop-filter: none
  • Shell-oppervlak: --card-shell-surface
  • Shell-vervaging: --card-shell-backdrop-filter
  • Werkruimte-Shell-schaduw: --workspace-shell-shadow
  • Dialog-oppervlak: --dialog-surface, biedt een ingetogen thema-verloop
  • Dialog-vervaging: --dialog-backdrop-filter
  • Dialog overlay-schaduw: --dialog-shadow
  • Dialog hoekradius: hergebruik --card-radius
  • Toetsenbordfocus: --focus-ring
  • Overlay-schaduw: gebruik bestaande Dialog, Dropdown, Menu of pagina-niveau overlay-Tokens

Gewone inhoudskaarten en werkruimtepanelen mogen niet de sterkere algemene --shadow Token gebruiken.

Globale schaduwen gebruiken een stille schaal van 'korte verschuiving, lage transparantie, toenemend op basis van plaatsingslaag'. Gewone Kaarten, velden en besturingselementen mogen gedeelde schaduwen niet verdiepen of vergroten in routes; Popover en Dialog drukken loskoppeling van de pagina uit via grotere verschuiving en vervagingsbereik, niet door donkere grijze mist te stapelen.

Interactieregels

Hover

  • Inhoudskaarten mogen niet hoger stijgen dan de --qk-shadow-surface-hover-laag.
  • Verhoog inhoudskaarten niet via translateY.
  • Gebruik lichte achtergrondveranderingen of duidelijke controlefeedback.
  • Verander de vorm niet, vermijd inconsistente hoekradii of schaduwafsnijding.

Selectie en activatie

  • Gebruik accentkleur-oppervlakken, pictogramstatus, semantische status of ingetogen verlopen.
  • Druk status niet alleen uit via schaduwen.

Toetsenbordfocus

  • Gebruik de gedeelde focus-visible regel of --focus-ring.
  • Algemene kaartschaduwen kunnen focustips niet vervangen.
  • Moet duidelijk zichtbaar zijn in zowel lichte als donkere thema's.

Slepen en zoomen

  • Alleen wanneer een laag beweegt of van grootte verandert, is een sterkere schaduw toegestaan.
  • Tijdelijke schaduwen moeten worden verwijderd na het einde van de interactie.
  • Overloopcontainers mogen de feedbackeffecten van bewegende lagen niet afsnijden.

Transparantie en achtergrondvervaging

Transparantie wordt gebruikt om de relatie tussen externe oppervlakken en werkruimten uit te drukken. Achtergrondvervaging is alleen zinvol wanneer er daadwerkelijk zichtbare inhoud, kleuren of afbeeldingen achter het oppervlak zijn.

  • Gebruik geen vervaging op effen achtergronden; het verhoogt alleen de renderkosten zonder lagen uit te drukken.
  • Tekst, pictogrammen en besturingselementen moeten duidelijk leesbaar zijn, ongeacht welke achtergrond erachter ligt.
  • Wanneer de browser achtergrondvervaging niet ondersteunt, moet er een ondoorzichtige of leesbare terugvalachtergrond zijn.
  • De vervagingsintensiteit moet ingetogen zijn in dichte werkomgevingen.
  • Moet worden gevalideerd in zowel lichte als donkere thema's.

Uitzonderingen waarbij schaduwen behouden mogen blijven

  • Werkruimte zijbalk-Shell
  • Dialog, Popover, Dropdown, menu's en modale panelen
  • Studio conceptverkenner en bevestigingsoverlay
  • Builder-canvas, apparaatframes en gegenereerde site-voorbeeldvlakken
  • Sleepvoorbeelden, zoomfeedback en tijdelijke zweefgereedschappen
  • Primaire actieknoppen waarbij de gedeelde knop-Token al een schaduw definieert
  • Marketingpagina's en gegenereerde site visuele elementen die door het huidige thema worden beheerst

Deze uitzonderingen mogen gewone inhoudskaarten niet beïnvloeden via brede selectors of gedeelde Tokens.

Reviewchecklist

  • Onafhankelijke effen inhoudskaarten en invoervelden gebruiken alleen de gedeelde lichte primaire schaduwrol.
  • Onafhankelijke primaire acties, onafhankelijke capsules en segmentbesturingsbehuizingen gebruiken alleen de gedeelde zeer lichte controleschaduw.
  • Paginagroepering, lijstrijen, geneste kaarten, transparante groepen, herhaalde Tab/Pill, werkbalken en interne items van samengestelde besturingselementen blijven plat.
  • Zoeken, filteren, sorteren, weergave en inline primaire acties in werkbalken blijven plat; lichte schaduwen van gewone invoervelden mogen niet lekken naar de werkbalk, behalve de toetsenbordfocusring.
  • Wanneer Segmented zich binnen een kaart, dialoog of werkbalk met al een schaduw bevindt, blijven zowel de behuizing als het geselecteerde item plat; muisklik toont geen toetsenbordfocusring.
  • Behalve bij echte overlays worden meerdere gewone schaduwen niet gestapeld in dezelfde voorouderketen.
  • Hover laat inhoudskaarten niet verticaal bewegen.
  • Geneste inhoudskaarten zijn verwijderd, of de buitenste laag is expliciet gedefinieerd als Shell.
  • Alleen echte Shells gebruiken --workspace-shell-shadow.
  • Alleen echte overlays en tijdelijke interactorlagen gebruiken sterkere schaduwen.
  • Er is zichtbare inhoud achter de achtergrondvervaging, en er is een leesbare terugvalachtergrond.
  • focus-visible gebruikt een focusring.
  • Voldoende contrast wordt behouden in zowel lichte als donkere thema's.
  • Oppervlakken met hoekradii snijden geen hover-, focus-, sleep- of overlayfeedback af.
  • Desktop- en mobiele breedtes veroorzaken geen nieuwe horizontale overloop.
  • npm run ui:check-card-surfaces --workspace @qokit-ai/web-controle geslaagd.

Op deze pagina