Designsystem

Die Designsprache, aus der ranui gebaut ist, und der vollständige Katalog der Tokens, die sie ausdrücken: jede globale --ran-*-Custom-Property, die die Bibliothek deklariert, samt ihrem Wert in beiden Themes. Komponenten lesen diese Tokens, statt Werte festzuschreiben — ein Token zu überschreiben gestaltet also alles um, was es verwendet.

Drei Seiten beantworten drei verschiedene Fragen, und sie sind bewusst getrennt:

Einsetzen, wenn du den Namen oder den Wert eines Tokens brauchst (eine Farbrolle, eine Abstandsstufe, eine Symbolgröße, eine Schattenstufe, eine Beschleunigungskurve) oder verstehen willst, warum die Skalen so geformt sind, wie sie sind.

Die Sprache: Geist

Die Tokens von ranui beruhen auf Geist, dem quelloffenen Designsystem von Vercel. Jede Farbskala ist eine Leiter fester Aufgaben, eine je Sprosse, kein Vorrat an Tönen zur Auswahl: Sprosse 200 ist nicht „ein etwas dunkleres Grau“, sie ist „der Hintergrund beim Überfahren“. Steht die Aufgabe einer Sprosse fest, ist die Farbwahl für einen Interaktionszustand ein Nachschlagen, keine Ermessensfrage.

ranui übernimmt diese Leiter als seine --ran-*-Skalen, legt semantische Tokens darüber und liefert Geist Sans / Geist Mono als Standardschriften mit.

Zwei Ebenen

Ebene 1: die Basispalette. Die rohen Skalen weiter unten. Selten unmittelbar verwendet.

Ebene 2: die semantischen Tokens. --ran-color-* und Verwandte, auf Ebene 1 abgebildet. Verwende diese Ebene. Der Dunkelmodus definiert nur Ebene 1 neu, jedes semantische Token wechselt also über var() mit — ohne eine einzige Dunkel-Sonderregel je Komponente irgendwo in der Bibliothek.

--ran-gray-1000        →  #171717 (hell)   /  #ededed (dunkel)   ← Ebene 1, wechselt
--ran-color-text       →  var(--ran-gray-1000)                    ← Ebene 2, folgt
--ran-btn-color        →  var(--ran-color-text, …)                ← Komponenten-Token

Diese Kette ist die ganze Architektur: Ändere eine Basissprosse, und es wirkt überall; ändere ein semantisches Token, und es ändert eine Rolle; ändere ein Komponenten-Token, und es ändert ein Element.

Farbe

Die Leiter

Jede Farbtonskala läuft von 100 bis 1000, und jede Sprosse hat genau eine Aufgabe:

Hintergründe

Grau — --ran-gray-100..1000

Die Skala hinter Text, Rahmen und Flächen.

Grau mit Alpha — --ran-gray-alpha-100..1000

Durchscheinend, legt sich also über jede Fläche: die richtige Wahl für einen Schleier, einen Hover-Hauch oder eine Trennlinie, die auf unbekanntem Inhalt liegen muss.

Blau — --ran-blue-100..1000

Reserviert für Links und den Fokusring.

Rot — --ran-red-100..1000

Gefahr und Fehler.

Bernstein — --ran-amber-100..1000

Warnungen.

Grün — --ran-green-100..1000

Erfolg.

Semantische Farbtokens

Die Ebene, die Komponenten tatsächlich lesen. Alles hier löst sich über die Skalen oben auf und wechselt daher von selbst mit dem Theme.

--ran-color-primary-hover / -active sind die beiden Literale der semantischen Ebene: Sie bewegen sich auf den Seitenhintergrund zu statt entlang einer Skala, deshalb definiert der Dunkelmodus sie unmittelbar neu.

Was jeder Akzent bedeutet

• Primär ist monochrom: schwarz auf weiß im Hellen, weiß auf schwarz im Dunklen (der Markenton von Geist, <r-button type="primary">). Text und Symbole darauf nutzen --ran-color-primary-text, das mitwechselt. Ein eigenes „Kontrast“-Token gibt es nicht: Primär ist die Aktion mit dem höchsten Kontrast.
• Blau ist reserviert für Links (--ran-color-link) und den Fokusring. Es ist kein alternatives Primär.
• Grün = Erfolg · Bernstein = Warnung · Rot = Gefahr. Je eine Bedeutung.

Es gibt kein --ran-color-error; das Token heißt --ran-color-danger. Ein var(), das eine nie deklarierte Eigenschaft nennt, löst sich zu nichts auf, und die ganze Deklaration fällt stillschweigend weg — deshalb lohnt es, einen falschen Namen an dieser Tabelle zu prüfen statt zu raten.

Abstand

Die Zwischenräume zwischen Dingen: padding, margin, gap. Eine Basiseinheit von 4px mit neun Werten, mehr nicht:

Die Zahl ist das Vielfache von 4px, die Skala springt also: Ein --ran-space-5 gibt es nicht. Genau darum geht es: Eine begrenzte Auswahl erzeugt den Rhythmus einer Seite.

Größen

Die eigenen Maße eines Elements: Symbolgrößen, Höhen von Bedienelementen, kleine quadratische oder rechteckige Steuerelemente.

Das ist mit Absicht eine eigene Skala neben dem Abstand, und beide zu mischen ist ein maschinell geprüfter Fehler (sizing-scale). Die beiden haben unterschiedliche Bereiche und Abstufungen (eine Abstandsskala, die ab 4px verdoppelt, ergibt für Symbol- und Bedienelementgrößen ungeschickte Werte), und wer sie verwendet, muss die eine nachjustieren können, ohne die andere zu stören: Ein größer werdendes Symbol soll nicht zugleich jeden Zwischenraum verbreitern, der zufällig denselben Pixelwert teilt. Wo eine Sprosse zahlenmäßig mit einer Abstandsstufe zusammenfällt (--ran-size-4 und --ran-space-6 sind beide 24px), ist das Zufall, kein Alias.

Ein wirklich einmaliges Maß, das keine andere Komponente teilt (etwa das min-width eines Menüs), bleibt ein schlichtes Komponenten-Token mit eigenem literalen Rückfallwert, statt in eine Stufe gezwungen zu werden.

Typografie

Schrift ist nach Rolle geordnet, und die Rolle legt Schriftart, Größe, Stärke und Zeilenhöhe gemeinsam fest:

Zwei Tokens gibt es nur, damit eine Rolle richtig sitzt:

Geist deckelt die Stärke bei 600 (Semibold). Betonung kommt aus Größe und Abstand, nicht aus einem fetteren Schnitt. Ein --ran-text-copy-3 gibt es nicht: Die 12px-Stufe heißt --ran-text-label-3.

Schriften

ranui hostet beide Schnitte selbst (variable Stärke 100–900, SIL OFL 1.1), ein einziger Import lädt sie also ohne CDN-Abhängigkeit:

import 'ranui/fonts'; // Bundler

<link rel="stylesheet" href="…/ranui/dist/fonts/fonts.css" />

Ohne ihn fallen die Tokens auf die Schriftstapel des Systems zurück; alles funktioniert weiter, nur ohne die Geist-Schnitte.

Radius

Elevation

Schatten ist eine Rolle, keine Dekoration. Wähle die Stufe danach, was das Element ist. Der Dunkelmodus ersetzt alle drei, denn ein für eine weiße Seite abgestimmter Schatten verschwindet auf einer schwarzen.

Rahmenlose Overlays verlassen sich für die Abgrenzung allein auf den Schatten, die Overlay-Stufen tragen also echtes Gewicht; ein Overlay, das auf die gehobene Stufe zurückfällt, wirkt flach und an die Seite geheftet.

Stapelung

Schwebende Overlays werden nach <body> portalt und brauchen daher eine ausdrückliche Stufe:

Die Leiter beginnt bei 1000, damit sie gewöhnliches Seitenrahmenwerk überragt (Navigationsleisten und Hintergründe liegen üblicherweise im Zehnerbereich). Überschreibe eine Stufe an :root oder je Komponente (--ran-dropdown-host-z-index, --ran-modal-root-z-index, --ran-message-z-index), niemals mit !important.

Bewegung

Die spring-Familie ist aus abgestimmten SwiftUI-Federn destilliert (Response und Dämpfung auf eine Bézier mit einem einzigen Überschwingen eingedampft).

Kombiniere sie nur mit Bewegungseigenschaften: transform, opacity, die Geometrie des Kastens. Paletteneigenschaften (background-color, color, border-color, box-shadow, fill, stroke) tragen bewusst keinen Standardübergang, denn CSS kann eine Interaktion nicht von einem Themenwechsel unterscheiden: Jede Überblendung, die du einer Farbe gibst, feuert auch beim Wechsel zwischen hell und dunkel. Jede Komponente bietet trotzdem einen --ran-*-transition-Haken, falls du es doch willst.

Fokus

Der Ring hat zwei Lagen: einen inneren in der Hintergrundfarbe und einen äußeren in Blau. So bleibt er auf jeder Fläche sichtbar und bleibt blau, statt dem inzwischen monochromen Primär zu folgen.

--ran-focus-ring-inverse-color wird bewusst nicht im Dunkelmodus neu definiert: Es gibt ihn für eine Komponente, deren eigene Fläche unabhängig vom Seitenthema fest dunkel ist (die Steuerleiste von r-player, über beliebigem Video), und diese Fläche ändert sich nicht, wenn die Seite es tut.

Skin-Primitive

Die wenigen strukturellen Werte, die Komponenten teilen und die weder Farbe noch Größe noch Schrift sind. Bewusst knapp gehalten: Diese Ebene war einmal viel größer, und das meiste davon fiel mit den Theme-Paketen weg.

Was der Dunkelmodus neu definiert

data-ran-theme="dark" an <html> (oder an einem beliebigen Teilbaum, siehe Themengestaltung) definiert die Basispalette neu und sonst nichts, mit drei Ausnahmen, die sich nicht über eine Skala auflösen lassen:

• die gesamte Ebene 1: jede Sprosse von Grau, Grau-Alpha, Blau, Rot, Bernstein und Grün sowie beide Hintergründe;
• --ran-color-bg-elevated, das im Dunklen auf --ran-gray-100 zeigt, damit sich eine Karte von einer schwarzen Seite abhebt, statt darin zu verschwinden;
• --ran-color-primary-hover / -active, die Literale sind statt Verweise auf eine Skala;
• alle drei Schattenstufen, für einen dunklen Grund neu abgestimmt.

Alles andere (jedes weitere semantische Token, jede Größe, jede Dauer) ist genau einmal definiert.

Komponenten-Tokens

Unterhalb der semantischen Ebene stellt jede Komponente eigene Haken bereit, benannt als:

--ran-{component}-{element}[-{state}]-{property}

zum Beispiel --ran-btn-hover-background, --ran-select-search-active-border-width. Sie fallen standardmäßig auf semantische Tokens zurück: var(--ran-btn-background, var(--ran-color-primary, #171717)). Ein semantisches Token zu überschreiben erreicht sie also alle, ein Komponenten-Token zu überschreiben verengt die Änderung auf ein einzelnes Element.

Die vollständige erzeugte Liste ist style-tokens-public.md im Repository; die API je Element steht hier. Wie man sie anwendet, zeigt die Themengestaltung.

Tokens im eigenen CSS verwenden

.panel {
  background: var(--ran-color-bg-elevated);
  color: var(--ran-color-text);
  border: var(--ran-skin-border-width) var(--ran-skin-border-style) var(--ran-color-border);
  border-radius: var(--ran-radius-md);
  padding: var(--ran-space-4);
  box-shadow: var(--ran-shadow-elevated);
}

Drei Regeln halten das im Dunkeln sicher:

1. Kein roher Hex-Wert für etwas, das dem Theme folgen soll.
2. Ein Rückfallwert muss ein Token nennen, das mitwechselt: var(--ran-color-text, var(--ran-gray-1000)), niemals var(--ran-color-text, #171717).
3. Ein Rückfallwert muss ein Token nennen, das es gibt, sonst fällt die Deklaration weg und das Element behält stillschweigend, was es geerbt hat.

Jedes globale Token, das die Bibliothek deklariert, steht auf dieser Seite, und ein Unit-Test schlägt fehl, wenn eines hinzukommt, ohne hier dokumentiert zu sein. Komponentenbezogene Tokens werden getrennt erzeugt, in style-tokens-public.md.