Skip to Content
Design

Karten- und Oberflächenebenen

Regeln für die Verwendung von Inhaltskarten, Workspace-Shells, Overlays, Schatten und Hintergrundunschärfe.

Live-KomponenteKarten-Ebenen

Inhaltskarten bleiben flach; die äußere Struktur kommuniziert die Gruppierung im Arbeitsbereich.

ProjektübersichtLaunch-Bereitschaft
Inhalt12 Seiten abgeschlossen

Eine Standard-Inhaltskarte verwendet keinen äußeren Schatten.

ÜberprüfungenMobile-fähig

Auswahl und Status werden über Farbe und Informationshierarchie kommuniziert.

Kartenmaterialien und Ebenenrichtlinien

Dieses Dokument beschreibt öffentlich, in welchen Szenarien die Qokit-Benutzeroberfläche Schatten, Transparenz, Verläufe und Hintergrundunschärfe einsetzt. Gilt für Plattform-Erweiterungen, Builder, CMS, Dashboard, Studio und Admin. Marketingseiten und generierte Websites dürfen ausdrucksstärker gestaltet werden, aber die Effekte müssen dem aktuellen Theme zugeordnet sein und die Lesbarkeit des Inhalts gewährleisten.

Grundprinzipien

Visuelle Effekte dienen der Darstellung von Struktur, nicht der Dekoration jedes einzelnen Bereichs:

  • Inhalte werden durch Hintergrundfarbunterschiede abgegrenzt.
  • Container drücken Zugehörigkeit durch Transparenz oder zurückhaltende Verläufe aus.
  • Overlays drücken Ebenen durch Schatten aus.
  • Interaktionen drücken Zustände durch Farben und Fokus-Ringe aus.

Eigenständige Volltonkarten und Eingabefelder verwenden einen gemeinsamen, leichten Primärschatten; Listen, verschachtelte Oberflächen und transparente Gruppen bleiben flach; nur echte Overlays verwenden deutliche Schatten.

Entscheidungsreihenfolge

Bevor Sie Materialeffekte hinzufügen, bestimmen Sie zunächst die Rolle der Oberfläche:

  1. Ist es eine eigenständige Volltonkarte oder ein Eingabefeld? Verwenden Sie den gemeinsamen Primärschatten für Oberflächen oder Felder.
  2. Ist es eine Listenzeile, eine verschachtelte Karte, eine wiederholte Option oder eine transparente Gruppe? Flach halten.
  3. Werden mehrere innere Inhaltskarten zu einem Workspace zusammengefasst? Verwenden Sie eine Shell.
  4. Überdeckt es Seiteninhalte oder erscheint es über der aktuellen Ebene? Verwenden Sie einen Overlay-Schatten.
  5. Befindet es sich im Zustand des Ziehens, der Skalierung oder des vorübergehenden Schwebens? Verwenden Sie einen temporären Schatten.
  6. Dient es nur der Darstellung von Hover, Auswahl oder Fokus? Verwenden Sie die gemeinsame Hover-Rolle, interaktive Hintergrundfarben und Fokus-Ringe.

Überlagern Sie nicht gleichzeitig Schatten, Transparenz, Verläufe und Unschärfe, es sei denn, die Rollen der Oberfläche erfordern dies ausdrücklich.

Szenario-Matrix

OberflächenrolleSchattenTransparenz oder VerlaufHintergrundunschärfe
Eigenständige Vollton-Inhaltskarten, Metrik-KartenGemeinsamer, leichter PrimärschattenLeichte Hintergrundfarbunterschiede erlaubtKeine
Listenzeilen, verschachtelte Karten, transparente Gruppen, wiederholte OptionenKeineLeichte Hintergrundfarbunterschiede erlaubtKeine
Seiteninterne Gruppen-ShellKeineEmpfohlenIn der Regel nicht erforderlich
Seitenleiste oder permanenter Workspace-ShellLeichtEmpfohlenErlaubt, wenn sichtbare Inhalte dahinter liegen
Dialog, Popover, Dropdown, KontextmenüDeutlicher Overlay-SchattenHintergrund muss ausreichend deckend sein, um Lesbarkeit zu gewährleistenErlaubt
Zieh-Vorschau, Skalierungszustand, Schwebe-VorschauTemporär stärkerOptionalIn der Regel nicht erforderlich
HoverPrimärschatten beibehalten oder leicht verstärkenHintergrund darf geändert werdenKeine Änderung
Auswahl- oder AktivierungszustandKeineAkzentfarbener Hintergrund oder zurückhaltender VerlaufKeine Änderung
Eingabefelder, SuchfelderSehr leichter FeldschattenSteuerungsoberflächenfarbe verwendenIn der Regel nicht erforderlich
Eigenständige Hauptaktionen, eigenständige Kapseln, Segmentsteuerungs-GehäuseSehr leichter SteuerungsschattenSteuerungsoberflächenfarbe verwendenIn der Regel nicht erforderlich
Werkzeugleisten und transparente innere SteuerungenKeineSteuerungsoberflächenfarbe oder transparent verwendenIn der Regel nicht erforderlich
Marketingseiten oder visuelle Karten generierter WebsitesDurch Theme bestimmtErlaubtZurückhaltend einsetzen

Komponentenzuordnung

  • <Card> verwendet standardmäßig layer="content": gemeinsamer, leichter Primärschatten, kein Rahmen, standardmäßig 20px Eckenradius; gedämpfte, verschachtelte, Listen- und transparente Varianten bleiben flach.
  • <Card layer="shell">: Innerhalb von Seiten nur für Gruppierung zuständig, verwendet transparente oder leicht verlaufende Oberflächen und bleibt flach; permanente Workspace-Shells erhalten ihre Ebene separat vom jeweiligen Modus.
  • <Card shape="pill">: Für kompakte einzeilige Karten, Eckenradius in elliptischer Kapsel-Form.
  • SidebarNavigation: Eigenständiger Workspace-Shell, behält deutliche Verläufe, Transparenz, Unschärfe und leichte Schatten.
  • PromptPanel von Studio als Workspace-Container: Verwendet --workspace-shell-shadow.
  • DialogPanel, Dropdown-Menüs, Popover, Kontextmenüs und Konzept-Browser: Verwenden Overlay-Schatten.
  • Builder-Canvas, Gerätevorschau, Vorschau generierter Websites, Zieh-Vorschau und Skalierungszustand: Können dedizierte Schatten beibehalten, da sie eigenständige Vorschau-Ebenen oder temporäre Interaktionsebenen darstellen.

Erstellen Sie keine stapelweise schwebenden Inhaltskarten. Wenn eine äußere Gruppierung wirklich erforderlich ist, muss sie eine flache Shell sein. Mit Ausnahme echter Overlays darf in derselben DOM-Vorfahren-Kette höchstens ein gewöhnlicher Inhalts- oder Steuerungsschatten vorkommen.

Verwendung von Design-Variablen (Tokens)

Bevorzugen Sie gemeinsame Tokens, vermeiden Sie hartcodierte Effekte:

  • Inhaltskarten-Schatten: --card-shadow: var(--qk-shadow-surface)
  • Inhaltskarten-Hover-Schatten: --card-shadow-hover: var(--qk-shadow-surface-hover)
  • Feldschatten: --input-shadow: var(--qk-shadow-field)
  • Feld-Aktiv-Schatten: --input-state-shadow: var(--qk-shadow-field-active)
  • Steuerungsschatten: --qk-shadow-control / --qk-shadow-control-hover
  • Hauptaktions-Steuerungsschatten: --qk-shadow-control-accent / --qk-shadow-control-accent-hover
  • Inhaltskarten-Unschärfe: --card-backdrop-filter: none
  • Shell-Oberfläche: --card-shell-surface
  • Shell-Unschärfe: --card-shell-backdrop-filter
  • Workspace-Shell-Schatten: --workspace-shell-shadow
  • Dialog-Oberfläche: --dialog-surface, bietet einen zurückhaltenden Theme-Verlauf
  • Dialog-Unschärfe: --dialog-backdrop-filter
  • Dialog-Overlay-Schatten: --dialog-shadow
  • Dialog-Eckenradius: Verwendet --card-radius erneut
  • Tastaturfokus: --focus-ring
  • Overlay-Schatten: Verwenden Sie vorhandene Dialog-, Dropdown-, Menü- oder seitenweite Overlay-Tokens

Gewöhnliche Inhaltskarten und Workspace-Panels dürfen nicht den stärkeren allgemeinen --shadow Token verwenden.

Globale Schatten verwenden eine ruhige Skala mit „kurzer Verschiebung, niedriger Deckkraft, zunehmend nach Ablageebene". Gewöhnliche Cards, Felder und Steuerungen dürfen auf Routen keine gemeinsamen Schatten vertiefen oder vergrößern; Popover und Dialog drücken die Ablösung von der Seite durch größere Verschiebung und Unschärfebereich aus, nicht durch Überlagerung dunkler grauer Nebelschichten.

Interaktionsregeln

Hover

  • Inhaltskarten dürfen nicht über die Ebene von --qk-shadow-surface-hover angehoben werden.
  • Inhaltskarten nicht durch translateY anheben.
  • Leichte Hintergrundänderungen oder klare Steuerungs-Feedbacks verwenden.
  • Die Form nicht ändern, um inkonsistente Eckenradien oder Schattenabschnitte zu vermeiden.

Auswahl und Aktivierung

  • Akzentfarbene Oberflächen, Symbolzustände, semantische Zustände oder zurückhaltende Verläufe verwenden.
  • Zustände nicht ausschließlich durch Schatten ausdrücken.

Tastaturfokus

  • Gemeinsame focus-visible-Regeln oder --focus-ring verwenden.
  • Allgemeine Kartenschatten können Fokus-Hinweise nicht ersetzen.
  • Muss sowohl in hellen als auch in dunklen Themes klar sichtbar sein.

Ziehen und Skalieren

  • Stärkere Schatten nur erlaubt, wenn sich die Ebene gerade bewegt oder ihre Größe ändert.
  • Temporäre Schatten müssen nach Ende der Interaktion entfernt werden.
  • Überlaufende Container dürfen die Feedback-Effekte bewegter Ebenen nicht abschneiden.

Transparenz und Hintergrundunschärfe

Transparenz drückt die Zugehörigkeit äußerer Oberflächen zum Workspace aus. Hintergrundunschärfe ist nur sinnvoll, wenn sich hinter der Oberfläche tatsächlich sichtbare Inhalte, Farben oder Bilder befinden.

  • Verwenden Sie keine Unschärfe auf einfarbigen Hintergründen; sie erhöht nur die Renderkosten, ohne Ebenen auszudrücken.
  • Text, Symbole und Steuerungen müssen unabhängig vom dahinterliegenden Hintergrund klar lesbar sein.
  • Wenn der Browser keine Hintergrundunschärfe unterstützt, muss ein undurchsichtiger oder lesbarer Fallback-Hintergrund vorhanden sein.
  • Die Unschärfeintensität in dichten Benutzeroberflächen muss zurückhaltend sein.
  • Muss sowohl in hellen als auch in dunklen Themes validiert werden.

Ausnahmen, bei denen Schatten beibehalten werden dürfen

  • Workspace-Seitenleisten-Shell
  • Dialog, Popover, Dropdown, Menüs und modale Panels
  • Studio Konzept-Browser und Bestätigungs-Overlays
  • Builder-Canvas, Geräte-Rahmen und Vorschau-Ebenen generierter Websites
  • Zieh-Vorschauen, Skalierungs-Feedback und temporäre Schwebe-Werkzeuge
  • Hauptaktionsschaltflächen, für die gemeinsame Schaltflächen-Tokens bereits Schatten definieren
  • Marketingseiten und visuelle Elemente generierter Websites, die vom aktuellen Theme gesteuert werden

Diese Ausnahmen dürfen gewöhnliche Inhaltskarten nicht durch breit gefasste Selektoren oder gemeinsame Tokens beeinflussen.

Prüf-Checkliste

  • Eigenständige Vollton-Inhaltskarten und Eingabefelder verwenden ausschließlich die gemeinsame Rolle des leichten Primärschattens.
  • Eigenständige Hauptaktionen, eigenständige Kapseln und Segmentsteuerungs-Gehäuse verwenden ausschließlich den gemeinsamen, sehr leichten Steuerungsschatten.
  • Seitengruppen, Listenzeilen, verschachtelte Karten, transparente Gruppen, wiederholte Tabs/Pills, Werkzeugleisten und innere Elemente zusammengesetzter Steuerungen bleiben flach.
  • Suche, Filter, Sortierung, Ansichten und Inline-Hauptaktionen in Werkzeugleisten bleiben flach; leichte Schatten gewöhnlicher Eingabefelder dürfen nicht in Werkzeugleisten übergehen, mit Ausnahme des Tastaturfokus-Rings.
  • Wenn sich Segmented innerhalb einer bereits schattierten Karte, eines Dialogs oder einer Werkzeugleiste befindet, bleiben sowohl das Gehäuse als auch das ausgewählte Element flach; Mausklicks zeigen keinen Tastaturfokus-Ring.
  • Mit Ausnahme echter Overlays werden in derselben Vorfahren-Kette keine mehreren gewöhnlichen Schatten überlagert.
  • Hover lässt Inhaltskarten nicht vertikal wandern.
  • Verschachtelte Inhaltskarten wurden entfernt oder die äußere Ebene wurde explizit als Shell definiert.
  • Nur echte Shells verwenden --workspace-shell-shadow.
  • Nur echte Overlays und temporäre Interaktionsebenen verwenden stärkere Schatten.
  • Hinter der Hintergrundunschärfe befinden sich sichtbare Inhalte und es gibt einen lesbaren Fallback-Hintergrund.
  • focus-visible verwendet Fokus-Ringe.
  • Ausreichender Kontrast wird sowohl in hellen als auch in dunklen Themes beibehalten.
  • Abgerundete Oberflächen schneiden Hover-, Fokus-, Zieh- oder Overlay-Feedback nicht ab.
  • Desktop- und Mobile-Breiten verursachen keinen neuen horizontalen Überlauf.
  • npm run ui:check-card-surfaces --workspace @qokit-ai/web Prüfung bestanden.

Auf dieser Seite