Zum Inhalt springen
Dokumentation

Grundlagen

Hell und dunkel

Stabil

Das Farbschema hängt an einer Klasse am Wurzelelement: ThemeProvider, dark-Variante, Umschalter und semantische Farben.

Hell und dunkel sind keine zwei Oberflächen, sondern zwei Sätze von Token-Werten. Alle Komponenten lesen dieselben semantischen Namen; das Theme entscheidet nur, welche Werte dahinterstehen. Deshalb braucht kein Produkt eigene Dark-Mode-Regeln.

ThemeProvider einrichten

ThemeProvider aus @neodin-eu/ui umschließt die Anwendung im Root-Layout. Er setzt attribute="class", defaultTheme="system" und enableSystem; die Theme-Klasse landet damit vor der Hydration auf <html>. Genau deshalb trägt <html> das Attribut suppressHydrationWarning:

tsx
import { NeodinProvider, ThemeProvider } from "@neodin-eu/ui";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="de" suppressHydrationWarning>
      <body>
        <ThemeProvider>
          <NeodinProvider locale="de-AT">{children}</NeodinProvider>
        </ThemeProvider>
      </body>
    </html>
  );
}

ThemeProvider ist ein dünner Wrapper um next-themes; next-themes ist deshalb ein Peer und muss in der Anwendung installiert sein. useTheme() liefert die Library unverändert aus next-themes weiter, zusammen mit ThemeProvider und ThemeToggle. Die vollständige Einrichtung samt TooltipProvider und Toaster steht unter Installation.

Die dark-Variante

styles.css definiert die dunkle Variante über eine Klasse, nicht über prefers-color-scheme:

css
@custom-variant dark (&:where(.dark, .dark *));

Damit greifen dark:-Utilities genau dann, wenn .dark auf <html> oder einem Vorfahren liegt. ThemeProvider setzt diese Klasse; die Systemwahl kommt über enableSystem und defaultTheme="system" ins Spiel. Die Token-Werte für .dark stehen in der Tabelle unter Design-Tokens.

Umschalten

ThemeToggle ist ein Menüknopf mit zugänglichem Namen. Er öffnet ein Menü mit den Einträgen Hell, Dunkel und System, markiert die aktuelle Wahl und schreibt sie über useTheme zurück. Er braucht nur den ThemeProvider darüber:

tsx
import { ThemeToggle } from "@neodin-eu/ui";

export function Kopfzeile() {
  return <ThemeToggle />;
}

Im Seitenkopf der Doku sitzt genau dieser Umschalter. Varianten und Details stehen unter Farbschema (ThemeProvider, ThemeToggle).

Keine rohen Markenfarben

Produktoberflächen verwenden nur semantische Utilities: bg-page, bg-background, text-foreground, text-muted-foreground, bg-primary, border-border, text-success und so weiter. Die Rohwerte (navy, navy-deep, cloud, line, slate, orange, amber-text) sind ausschließlich für Logo und OpenFrame vorgesehen.

Die Library erzwingt das mit einem Test (packages/ui/src/no-raw-brand-colors.test.ts): Er liest jede Komponentendatei und schlägt fehl, sobald eine Utility wie bg-navy, text-orange oder border-line auftaucht. Nur logo.tsx und open-frame.tsx sind ausgenommen. Übernimm die Regel auch in deiner Anwendung – sonst bricht die Oberfläche beim Theme-Wechsel.

Barrierefreiheit

  • Der Umschalter ist ein echter button mit Text oder aria-label; er ist per Tastatur erreichbar und hat einen sichtbaren Fokusring.
  • --input ist so dunkel gewählt, dass der Rahmen mindestens 3:1 zur Fläche erreicht (WCAG 1.4.11). Fokus läuft über ring-ring.
  • Status wird nie nur über Farbe transportiert: Jede Statusfarbe hat ein Icon und einen Text. Die Kontraste beider Themes stehen unter Design-Tokens.
  • Wechselt das Theme, bleiben Texte und Flächen aus denselben semantischen Tokens; es gibt keine Komponente, die nur in einem Theme funktioniert.