Grundlagen
Hell und dunkel
StabilDas 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:
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:
@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:
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
buttonmit Text oderaria-label; er ist per Tastatur erreichbar und hat einen sichtbaren Fokusring. --inputist so dunkel gewählt, dass der Rahmen mindestens 3:1 zur Fläche erreicht (WCAG 1.4.11). Fokus läuft überring-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.