Skip to Content
Projektowanie

Karty i warstwy powierzchni

Zasady stosowania cieni, przezroczystości, gradientów i matowego tła w kartach treści, powłokach obszaru roboczego, warstwach unoszących się, cieniach i matowym tle.

Komponent w trybie czasu rzeczywistegoWarstwy karty

Karty zawartości pozostają płaskie; zewnętrzna powłoka przekazuje grupowanie obszaru roboczego.

Przegląd projektuGotowość do uruchomienia
Zawartość12 stron ukończonych

Standardowa karta zawartości nie używa zewnętrznej cienie.

SprawdzanieGotowe do mobilnych

Wybór i stan są przekazywane poprzez kolor i hierarchię informacji.

Specyfikacja materiałów i warstw kart

Niniejszy dokument opisuje, w jakich scenariuszach interfejs Qokit wykorzystuje cienie, przezroczystość, gradienty i matowe tło. Dotyczy to platformy rozszerzeń, Buildera, CMS, Dashboard, Studio i Admina. Strony marketingowe i generowane witryny mogą być bardziej ekspresyjne, ale efekty muszą należeć do bieżącego motywu i zapewniać czytelność treści.

Podstawowe zasady

Efekty wizualne służą do wyrażania struktury, a nie do dekorowania każdego bloku:

  • Treści są rozróżniane przez różnicę kolorów tła.
  • Kontenery wyrażają przynależność poprzez przezroczystość lub powściągliwe gradienty.
  • Warstwy unoszące się wyrażają hierarchię za pomocą cieni.
  • Interakcje wyrażają stan za pomocą koloru i pierścienia fokusu.

Niezależne, nieprzezroczyste karty i pola wejściowe współdzielą pierwszy poziom lekkiego cienia; listy, zagnieżdżone powierzchnie i przezroczyste grupy pozostają płaskie; wyraźne cienie są stosowane tylko w przypadku prawdziwych warstw unoszących się.

Kolejność decyzyjna

Przed dodaniem efektu materiału należy najpierw określić rolę powierzchni:

  1. Czy jest to niezależna, nieprzezroczysta karta treści lub pole wejściowe? Użyj współdzielonej powierzchni pierwszego poziomu lub cienia pola.
  2. Czy jest to wiersz listy, zagnieżdżona karta, powtarzalna opcja lub przezroczysta grupa? Pozostaw płaską.
  3. Czy organizujesz wiele wewnętrznych kart treści w jeden obszar roboczy? Użyj powłoki (Shell).
  4. Czy nakrywa zawartość strony lub pojawia się powyżej bieżącej płaszczyzny? Użyj cienia warstwy unoszącej się.
  5. Czy jest w stanie przeciągania, powiększania lub tymczasowego unoszenia się? Użyj tymczasowego cienia.
  6. Czy służy jedynie do wyrażenia hover, zaznaczenia lub fokusu? Użyj współdzielonej roli hover, koloru tła interakcji i pierścienia fokusu.

Nie nakładaj jednocześnie cieni, przezroczystości, gradientów i matowego tła, chyba że rola powierzchni tego rzeczywiście wymaga.

Macierz scenariuszy

Rola powierzchniCieńPrzezroczystość lub gradientMatowe tło
Niezależna, nieprzezroczysta karta treści, karta wskaźnikówWspółdzielony lekki cień pierwszego poziomuDozwolona lekka różnica kolorów tłaBrak
Wiersz listy, zagnieżdżona karta, przezroczysta grupa, powtarzalna opcjaBrakDozwolona lekka różnica kolorów tłaBrak
Powłoka grupująca wewnątrz stronyBrakZalecaneZazwyczaj niepotrzebne
Pasek boczny lub stała powłoka obszaru roboczegoLekkiZalecaneDozwolone, gdy za powłoką widoczna jest zawartość
Dialog, Popover, Dropdown, menu kontekstoweWyraźny cień warstwy unoszącej sięTło musi być wystarczająco nieprzezroczyste, aby zapewnić czytelnośćDozwolone
Podgląd przeciągania, stan powiększenia, podgląd unoszenia sięTymczasowy, silniejszyOpcjonalneZazwyczaj niepotrzebne
HoverZachowaj lub lekko wzmocnij cień pierwszego poziomuMoże zmienić tłoBez zmian
Stan zaznaczenia lub aktywacjiBrakTło koloru akcentu lub powściągliwy gradientBez zmian
Pole wejściowe, pole wyszukiwaniaBardzo lekki cień polaUżyj koloru powierzchni kontrolkiZazwyczaj niepotrzebne
Niezależna akcja główna, niezależna kapsuła, obudowa kontrolki segmentowejBardzo lekki cień kontrolkiUżyj koloru powierzchni kontrolkiZazwyczaj niepotrzebne
Pasek narzędzi i przezroczyste kontrolki wewnętrzneBrakUżyj koloru powierzchni kontrolki lub przezroczystościZazwyczaj niepotrzebne
Karty wizualne stron marketingowych lub generowanych witrynOkreślone przez motywDozwoloneUżywaj powściągliwie

Mapowanie komponentów

  • <Card> domyślnie używa layer="content": współdzielony lekki cień pierwszego poziomu, brak obramowania, domyślny promień narożnika 20px; warianty muted, zagnieżdżone, listy i przezroczyste pozostają płaskie.
  • <Card layer="shell">: wewnątrz strony odpowiada jedynie za grupowanie, używa przezroczystej lub lekko gradientowej powierzchni i pozostaje płaska; stała powłoka obszaru roboczego otrzymuje warstwę od odpowiedniego trybu.
  • <Card shape="pill">: służy do kompaktowych kart jednoliniowych, z zaokrągleniami w kształcie eliptycznej kapsuły.
  • SidebarNavigation: niezależna powłoka obszaru roboczego, zachowuje wyraźne gradienty, przezroczystość, matowe tło i lekki cień.
  • PromptPanel w Studio jako kontener obszaru roboczego: używa --workspace-shell-shadow.
  • DialogPanel, menu rozwijane, Popover, menu kontekstowe i przeglądarka koncepcji: używają cienia warstwy unoszącej się.
  • Płótno Buildera, podgląd urządzeń, podgląd generowanej witryny, podgląd przeciągania i stan powiększenia: ponieważ reprezentują niezależne płaszczyzny podglądu lub tymczasowe warstwy interakcji, mogą zachować dedykowane cienie.

Nie twórz wielowarstwowo unoszących się kart treści. Jeśli zewnętrzne grupowanie jest rzeczywiście potrzebne, musi to być płaska powłoka. Z wyjątkiem prawdziwych warstw unoszących się, w tym samym łańcuchu przodków DOM może występować co najwyżej jeden zwykły cień treści lub kontrolki.

Użycie zmiennych projektowych (Tokenów)

Preferuj współdzielone tokeny, nie koduj efektów na sztywno:

  • Cień karty treści: --card-shadow: var(--qk-shadow-surface)
  • Cień hover karty treści: --card-shadow-hover: var(--qk-shadow-surface-hover)
  • Cień pola: --input-shadow: var(--qk-shadow-field)
  • Cień aktywnego pola: --input-state-shadow: var(--qk-shadow-field-active)
  • Cień kontrolki: --qk-shadow-control / --qk-shadow-control-hover
  • Cień kontrolki akcji głównej: --qk-shadow-control-accent / --qk-shadow-control-accent-hover
  • Matowe tło karty treści: --card-backdrop-filter: none
  • Powierzchnia powłoki: --card-shell-surface
  • Matowe tło powłoki: --card-shell-backdrop-filter
  • Cień powłoki obszaru roboczego: --workspace-shell-shadow
  • Powierzchnia Dialog: --dialog-surface, zapewnia powściągliwy gradient motywu
  • Matowe tło Dialog: --dialog-backdrop-filter
  • Cień warstwy unoszącej się Dialog: --dialog-shadow
  • Promień narożnika Dialog: ponownie wykorzystuje --card-radius
  • Fokus klawiatury: --focus-ring
  • Cień warstwy unoszącej się: użyj istniejących tokenów Dialog, Dropdown, Menu lub warstwy unoszącej się na poziomie strony

Zwykłe karty treści i panele obszaru roboczego nie mogą używać silnego, ogólnego tokena --shadow.

Globalne cienie stosują spokojną skalę „krótkie przesunięcie, niska przezroczystość, rosnąca wraz z poziomem umieszczenia”. Zwykłe karty, pola i kontrolki nie mogą pogłębiać ani powiększać współdzielonych cieni w trasie; Popover i Dialog wyrażają oderwanie od strony poprzez większe przesunięcie i zakres rozmycia, a nie nakładanie ciemnej szarej mgły.

Zasady interakcji

Hover

  • Karty treści nie mogą być podnoszone powyżej poziomu --qk-shadow-surface-hover.
  • Nie podnoś kart treści za pomocą translateY.
  • Użyj lekkiej zmiany tła lub wyraźnego feedbacku kontrolki.
  • Nie zmieniaj kształtu, aby uniknąć niespójnych zaokrągleń lub przycinania cieni.

Zaznaczenie i aktywacja

  • Użyj powierzchni koloru akcentu, stanu ikony, stanu semantycznego lub powściągliwego gradientu.
  • Nie wyrażaj stanu wyłącznie za pomocą cienia.

Fokus klawiatury

  • Użyj współdzielonej reguły focus-visible lub --focus-ring.
  • Ogólny cień karty nie może zastępować wskazówki fokusu.
  • Musi być wyraźnie widoczny zarówno w jasnym, jak i ciemnym motywie.

Przeciąganie i powiększanie

  • Silniejszy cień jest dozwolony tylko wtedy, gdy warstwa jest rzeczywiście przesuwana lub zmieniany jest jej rozmiar.
  • Tymczasowy cień musi zostać usunięty po zakończeniu interakcji.
  • Przepełnione kontenery nie mogą przycinać efektów feedbacku przesuwanej warstwy.

Przezroczystość i matowe tło

Przezroczystość służy do wyrażania przynależności zewnętrznej powierzchni do obszaru roboczego. Matowe tło ma sens tylko wtedy, gdy za powierzchnią rzeczywiście widoczna jest zawartość, kolor lub obraz.

  • Nie używaj matowego tła na jednolitym kolorze — zwiększa jedynie koszt renderowania i nie wyraża warstwy.
  • Tekst, ikony i kontrolki muszą być wyraźnie czytelne niezależnie od tła przechodzącego za nimi.
  • Gdy przeglądarka nie obsługuje matowego tła, musi istnieć nieprzezroczyste lub czytelne tło zastępcze.
  • Intensywność rozmycia w gęstych interfejsach roboczych musi być powściągliwa.
  • Należy zweryfikować zarówno jasny, jak i ciemny motyw.

Wyjątki, w których dozwolone jest zachowanie cieni

  • Powłoka paska bocznego obszaru roboczego
  • Dialog, Popover, Dropdown, menu i panele modalne
  • Przeglądarka koncepcji Studio i warstwy potwierdzenia
  • Płótno Buildera, ramki urządzeń i płaszczyzny podglądu generowanej witryny
  • Podgląd przeciągania, feedback powiększania i tymczasowe unoszące się narzędzia
  • Przyciski akcji głównej, dla których współdzielony token przycisku definiuje już cień
  • Elementy wizualne stron marketingowych i generowanych witryn kontrolowane przez bieżący motyw

Te wyjątki nie mogą wpływać na zwykłe karty treści za pomocą szerokich selektorów lub współdzielonych tokenów.

Lista kontrolna

  • Niezależne, nieprzezroczyste karty treści i pola wejściowe używają wyłącznie współdzielonej roli lekkiego cienia pierwszego poziomu.
  • Niezależne akcje główne, niezależne kapsuły i obudowy kontrolek segmentowych używają wyłącznie współdzielonego bardzo lekkiego cienia kontrolki.
  • Grupowanie na stronie, wiersze listy, zagnieżdżone karty, przezroczyste grupy, powtarzalne zakładki/pigułki, paski narzędzi i elementy wewnętrzne kontrolek złożonych pozostają płaskie.
  • Wyszukiwanie, filtrowanie, sortowanie, widoki i wbudowane akcje główne na pasku narzędzi pozostają płaskie; lekki cień zwykłych pól wejściowych nie może przenikać do paska narzędzi, z wyjątkiem pierścienia fokusu klawiatury.
  • Gdy Segmented znajduje się wewnątrz karty, okna dialogowego lub paska narzędzi z już istniejącym cieniem, zarówno obudowa, jak i zaznaczony element pozostają płaskie; kliknięcie myszą nie wyświetla pierścienia fokusu klawiatury.
  • Z wyjątkiem prawdziwych warstw unoszących się, w tym samym łańcuchu przodków nie nakładaj wielu zwykłych cieni.
  • Hover nie powoduje pionowego przesunięcia kart treści.
  • Usunięto zagnieżdżone karty treści lub wyraźnie zdefiniowano warstwę zewnętrzną jako powłokę.
  • Tylko prawdziwe powłoki używają --workspace-shell-shadow.
  • Tylko prawdziwe warstwy unoszące się i tymczasowe warstwy interakcji używają silniejszych cieni.
  • Za matowym tłem widoczna jest zawartość i istnieje czytelne tło zastępcze.
  • focus-visible używa pierścienia fokusu.
  • Zarówno jasny, jak i ciemny motyw zachowuje wystarczający kontrast.
  • Powierzchnie z zaokrąglonymi narożnikami nie przycinają feedbacku hover, fokusu, przeciągania ani warstwy unoszącej się.
  • Na szerokościach desktopowych i mobilnych nie pojawiają się nowe poziome przepełnienia.
  • npm run ui:check-card-surfaces --workspace @qokit-ai/web — sprawdzenie zakończone powodzeniem.

Na tej stronie