Kaart- en oppervlaklagen
Gebruiksregels voor inhoudskaarten, werkruimte-shells, overlays, schaduwen en achtergrondvervaging.
Inhoudskaarten blijven plat; de buitenste structuur communiceert groepering in het werkruimte.
Een standaard inhoudskaart gebruikt geen buitenschaduw.
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:
- Is het een onafhankelijke effen kaart of invoerveld? Gebruik de gedeelde primaire oppervlak- of veldschaduw.
- Is het een lijstrij, geneste kaart, herhaalde optie of transparante groep? Houd het plat.
- Organiseert het meerdere interne inhoudskaarten in een werkruimte? Gebruik een Shell.
- Bedekt het pagina-inhoud of verschijnt het boven het huidige vlak? Gebruik een overlay-schaduw.
- Is het in een sleep-, zoom- of tijdelijke zweefstatus? Gebruik een tijdelijke schaduw.
- 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
| Oppervlakrol | Schaduw | Transparantie of verloop | Achtergrondvervaging |
|---|---|---|---|
| Onafhankelijke effen inhoudskaarten, metriekkaarten | Gedeelde lichte primaire schaduw | Lichte achtergrondkleurverschillen toegestaan | Geen |
| Lijstrijen, geneste kaarten, transparante groepen, herhaalde opties | Geen | Lichte achtergrondkleurverschillen toegestaan | Geen |
| Pagina-interne groeps-Shell | Geen | Aanbevolen | Meestal niet nodig |
| Zijbalk of permanente werkruimte-Shell | Licht | Aanbevolen | Toegestaan wanneer er zichtbare inhoud achter staat |
| Dialog, Popover, Dropdown, contextmenu | Duidelijke overlay-schaduw | Achtergrond moet voldoende effen zijn voor leesbaarheid | Toegestaan |
| Sleepvoorbeelden, zoomstatus, zweefvoorbeelden | Tijdelijk sterker | Optioneel | Meestal niet nodig |
| Hover | Behoud of lichte versterking van primaire schaduw | Achtergrond kan veranderen | Verandert niet |
| Selectie- of actieve status | Geen | Accentkleur-achtergrond of ingetogen verloop | Verandert niet |
| Invoervelden, zoekvelden | Zeer lichte veldschaduw | Gebruik controle-oppervlakkleur | Meestal niet nodig |
| Onafhankelijke primaire acties, onafhankelijke capsules, segmentbesturingsbehuizingen | Zeer lichte controleschaduw | Gebruik controle-oppervlakkleur | Meestal niet nodig |
| Werkbalken en transparante interne besturingselementen | Geen | Gebruik controle-oppervlakkleur of transparant | Meestal niet nodig |
| Marketingpagina's of gegenereerde site visuele kaarten | Bepaald door thema | Toegestaan | Ingetogen gebruik |
Componenttoewijzing
<Card>gebruikt standaardlayer="content": gedeelde lichte primaire schaduw, geen rand, standaard20pxhoekradius; 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
PromptPanelvan 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.