Grundlagen & Tokens

Design-Tokens

Alle Werte (Farben, Größen, Radien, Schatten, Abstände) sind CSS-Custom-Properties, die in tokens.css definiert sind. Komponenten verwenden niemals hartcodierte Werte — sie referenzieren immer einen Token. Überschreibe einen beliebigen Token, um WebBlocks UI an deine Marke anzupassen.

Regel: Verwende Tokens auch in deinen eigenen Komponenten. Codiere niemals eine Farbe, Größe oder einen Radius hart, die sich bei einem Theme-Wechsel ändern könnte.

Oberflächen & Text

Token	Standard (hell)	Verwendung
--wb-bg	#f4f6fb	Seitenhintergrund
--wb-surface	#ffffff	Karten, Panels, Modals
--wb-surface-2	#edf1f7	Dezente Hintergründe, Tabellenzeilen
--wb-surface-3	#e2e8f2	Hover-Zustände, Trennlinien
--wb-text	#18212f	Primärer Text
--wb-muted	#5a6a84	Sekundärer Text, Labels, Platzhalter
--wb-border	#d6e0ee	Alle Rahmen und Trennlinien

Semantische Farben

Token	Varianten	Verwendung
--wb-success	-dark · -soft	Erfolgs-Alerts, Badges, Icons
--wb-warning	-dark · -soft	Warn-Alerts, Vorsichtszustände
--wb-danger	-dark · -soft	Fehlerzustände, destruktive Aktionen
--wb-info	-dark · -soft	Informations-Alerts, Hinweise

Abstands-Skala (4px Basis)

Token	Wert	Token	Wert
--wb-s1	4px	--wb-s8	32px
--wb-s2	8px	--wb-s10	40px
--wb-s3	12px	--wb-s12	48px
--wb-s4	16px	--wb-s16	64px
--wb-s5	20px	--wb-s20	80px
--wb-s6	24px	—	—

Rahmenradius

Token	Wert
--wb-r-sm	5px
--wb-r-md	9px
--wb-r-lg	14px
--wb-r-xl	20px
--wb-r-full	9999px (Pill/Kreis)

Typografie

Token	Beschreibung
--wb-font	Body-Schriftart (Inter, system-ui-Fallbacks)
--wb-font-heading	Überschriften-Schriftart (standardmäßig wie Body)
--wb-font-mono	Monospace-Stack (Cascadia Code, Menlo, Consolas)
--wb-font-size-xs/sm/md/lg/xl	0,75 / 0,875 / 1 / 1,125 / 1,25 rem

Schatten

Token	Verwendung
--wb-shadow-sm	Dezente Erhebung (Karten, Eingaben)
--wb-shadow-md	Dropdowns, Popovers
--wb-shadow-lg	Modals, Drawer
--wb-shadow-xl	Command-Palette, erhöhte Overlays

Z-Index-Skala

Token	Wert	Verwendung
--wb-z-dropdown	100	Dropdowns, Popovers, Tooltips
--wb-z-modal	200	Modals, Drawer, Bestätigungsdialoge
--wb-z-toast	300	Toast-Benachrichtigungen

Tokens überschreiben

Überschreibe einen beliebigen Token in deinem eigenen CSS über :root oder einen eingeschränkten Selektor:

/* Globale Überschreibung */
:root {
  --wb-font: 'Geist', sans-serif;
  --wb-r-md: 12px;
}

/* Eingeschränkte Überschreibung — wirkt nur auf einen Bereich */
.my-hero {
  --wb-accent: #8b5cf6;
}

Akzentfarben

Setze data-accent auf dem <html>-Element, um die gesamte Benutzeroberfläche auf ein anderes Farbschema umzustellen. Jeder Akzent definiert 12 Tokens.

ocean

forest

sunset

royal

mint

amber

rose

slate-fire

Klicke auf ein Farbmuster, um den Akzent auf dieser Seite zu testen.

Akzent-Token-Set (12 Tokens pro Akzent)

Token	Verwendung
--wb-accent	Primärer Akzent — Button-Hintergründe, aktive Zustände
--wb-accent-hover	Hover-Zustand für akzentfarbige Elemente
--wb-accent-active	Aktiver / gedrückter Zustand
--wb-accent-soft	Getönter Hintergrund (Badges, Chips)
--wb-accent-softer	Sehr heller Farbton (Seitenabschnitte, Callouts)
--wb-accent-border	Akzentgetönter Rahmen
--wb-accent-text	Akzenttext auf hellem Hintergrund
--wb-accent-on	Textfarbe auf Akzenthintergrund (immer weiß oder nahezu weiß)
--wb-accent-ring	Fokus-Ring-Farbe
--wb-accent-ring-rgb	RGB-Werte für rgba()-Fokus-Ring mit Transparenz
--wb-accent-selection	Textselektion-Hintergrund
--wb-accent-glow-rgb	RGB-Werte für Glüheffekte

Abwärtskompatibilität: --wb-primary, --wb-primary-dark und --wb-primary-soft sind Aliasse, die auf ihre --wb-accent*-Entsprechungen zeigen. Verwende im neuen Code immer --wb-accent*.

Dunkelmodus

Der Dunkelmodus wird über das Attribut data-mode auf <html> gesteuert. Drei Werte werden unterstützt.

Wert	Verhalten
light	Immer heller Modus
dark	Immer dunkler Modus
auto	Folgt der `prefers-color-scheme`-Systemeinstellung

Wie der Dunkelmodus funktioniert

Der Dunkelmodus überschreibt Oberflächen-, Text- und Rahmen-Tokens über einen [data-mode="dark"]-Selektor in dark.css. Alle Komponentenstile erben die neuen Werte automatisch — separate Dunkelmodus-Klassen-Varianten werden nicht benötigt.

<!-- Statisch -->
<html data-mode="dark">

<!-- Vom Benutzer umgeschaltet -->
<button data-wb-mode-cycle>Modus umschalten</button>

<!-- Programmgesteuert setzen -->
<script>WBTheme.setMode('dark');</script>

localStorage-Persistenz: WBTheme speichert die Moduswahl des Benutzers in localStorage unter dem Schlüssel wb-mode und stellt sie beim nächsten Seitenaufruf wieder her. Setze das initiale data-mode in HTML, um ein Aufblitzen des falschen Modus zu vermeiden.

Presets

Presets sind benannte Bündel, die mehrere Achsen auf einmal setzen — Radius, Schatten, Dichte, Schriftart und Rahmen. Verwende sie als Ausgangspunkte für einen konsistenten Look; einzelne Achsen können Preset-Werte weiterhin überschreiben.

Preset	Radius	Schatten	Dichte	Schrift	Rahmen
modern	standard	standard	standard	modern	subtle
minimal	sharp	flat	compact	system	subtle
rounded	soft	soft	comfortable	modern	none
bold	sharp	standard	standard	modern	bold
editorial	sharp	flat	comfortable	editorial	medium

<!-- "rounded"-Preset anwenden, nur Akzent überschreiben -->
<html data-preset="rounded" data-accent="rose">

<!-- "minimal" anwenden, Radius auf soft überschreiben -->
<html data-preset="minimal" data-radius="soft">

Presets werden in der CSS-Kaskade vor einzelnen Achsen-Attributen angewendet, sodass individuelle Achsen immer gewinnen.

Theme-Achsen

Neben Dunkelmodus und Akzent erlauben fünf weitere Achsen, die visuelle Persönlichkeit der Benutzeroberfläche anzupassen.

Radius — `data-radius`

Wert	Effekt
sharp	Reduziert alle Rahmenradien — strukturierter, Enterprise-Look
soft	Erhöht alle Rahmenradien — freundlich, verbraucherorientiert

Dichte — `data-density`

Wert	Effekt
compact	Reduziert Padding bei Buttons, Eingaben, Tabellenzeilen — mehr Inhalt pro Bildschirm
comfortable	Erhöht Padding — mehr Luft, besser für Touch

Schatten — `data-shadow`

Wert	Effekt
flat	Entfernt Schatten — rahmenbasierte Tiefe, sauber und minimal
soft	Erhöht Schattenunschärfe und -deckkraft — stärker erhöht, Premium-Gefühl

Schrift — `data-font`

Wert	Schrift-Stack
system	Native OS-Schriftart — keine Webschrift geladen
modern	Inter (CDN) — klar, gut lesbar
editorial	Playfair Display (CDN) + Inter — redaktionell, verlegerisch

Rahmen — `data-border`

Wert	Effekt
none	Entfernt Rahmen — Oberflächen nur durch Schatten definiert
subtle	Helle Rahmen (Standard)
medium	Mittelschwere Rahmen
bold	Schwere Rahmen — starke visuelle Struktur
dashed	Gestrichelte Rahmen — markant, technisches Gefühl

Alle Achsen kombinieren

<!-- Maximale Anpassung ohne eine einzige Zeile benutzerdefiniertes CSS -->
<html
  data-mode="dark"
  data-accent="royal"
  data-preset="rounded"
  data-density="comfortable"
  data-font="modern"
>

Eigene Token-Überschreibungen

Für markenspezifische Anpassungen, die über die integrierten Achsen hinausgehen, überschreibe Tokens direkt in deinem eigenen CSS.

/* ── Marken-Schriftart ───────────────────────────────── */
:root {
  --wb-font:         'DM Sans', sans-serif;
  --wb-font-heading: 'DM Serif Display', serif;
}

/* ── Eigener Akzent (außerhalb der 8 integrierten) ───── */
:root {
  --wb-accent:           #0f766e;
  --wb-accent-hover:     #0d6e66;
  --wb-accent-active:    #0b605a;
  --wb-accent-soft:      #ccfbf1;
  --wb-accent-softer:    #f0fdf4;
  --wb-accent-border:    #5eead4;
  --wb-accent-text:      #0d6e66;
  --wb-accent-on:        #ffffff;
  --wb-accent-ring:      rgb(15 118 110);
  --wb-accent-ring-rgb:  15 118 110;
  --wb-accent-selection: #ccfbf1;
  --wb-accent-glow-rgb:  15 118 110;
}

/* ── Engerer Abstand für ein dichtes Datengitter ─────── */
.my-data-table {
  --wb-s3: 0.5rem;
  --wb-s4: 0.75rem;
}