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.
Karty zawartości pozostają płaskie; zewnętrzna powłoka przekazuje grupowanie obszaru roboczego.
Standardowa karta zawartości nie używa zewnętrznej cienie.
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:
- Czy jest to niezależna, nieprzezroczysta karta treści lub pole wejściowe? Użyj współdzielonej powierzchni pierwszego poziomu lub cienia pola.
- Czy jest to wiersz listy, zagnieżdżona karta, powtarzalna opcja lub przezroczysta grupa? Pozostaw płaską.
- Czy organizujesz wiele wewnętrznych kart treści w jeden obszar roboczy? Użyj powłoki (Shell).
- Czy nakrywa zawartość strony lub pojawia się powyżej bieżącej płaszczyzny? Użyj cienia warstwy unoszącej się.
- Czy jest w stanie przeciągania, powiększania lub tymczasowego unoszenia się? Użyj tymczasowego cienia.
- 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 powierzchni | Cień | Przezroczystość lub gradient | Matowe tło |
|---|---|---|---|
| Niezależna, nieprzezroczysta karta treści, karta wskaźników | Współdzielony lekki cień pierwszego poziomu | Dozwolona lekka różnica kolorów tła | Brak |
| Wiersz listy, zagnieżdżona karta, przezroczysta grupa, powtarzalna opcja | Brak | Dozwolona lekka różnica kolorów tła | Brak |
| Powłoka grupująca wewnątrz strony | Brak | Zalecane | Zazwyczaj niepotrzebne |
| Pasek boczny lub stała powłoka obszaru roboczego | Lekki | Zalecane | Dozwolone, gdy za powłoką widoczna jest zawartość |
| Dialog, Popover, Dropdown, menu kontekstowe | Wyraź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, silniejszy | Opcjonalne | Zazwyczaj niepotrzebne |
| Hover | Zachowaj lub lekko wzmocnij cień pierwszego poziomu | Może zmienić tło | Bez zmian |
| Stan zaznaczenia lub aktywacji | Brak | Tło koloru akcentu lub powściągliwy gradient | Bez zmian |
| Pole wejściowe, pole wyszukiwania | Bardzo lekki cień pola | Użyj koloru powierzchni kontrolki | Zazwyczaj niepotrzebne |
| Niezależna akcja główna, niezależna kapsuła, obudowa kontrolki segmentowej | Bardzo lekki cień kontrolki | Użyj koloru powierzchni kontrolki | Zazwyczaj niepotrzebne |
| Pasek narzędzi i przezroczyste kontrolki wewnętrzne | Brak | Użyj koloru powierzchni kontrolki lub przezroczystości | Zazwyczaj niepotrzebne |
| Karty wizualne stron marketingowych lub generowanych witryn | Określone przez motyw | Dozwolone | Używaj powściągliwie |
Mapowanie komponentów
<Card>domyślnie używalayer="content": współdzielony lekki cień pierwszego poziomu, brak obramowania, domyślny promień narożnika20px; 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ń.PromptPanelw 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.