Eigene Themes

Ein Theme ist ein einziger ThemeTokens-Wert: Farben, Abstände, Radien, Schriftgrößen und Control-Maße. Kopieren Sie ein eingebautes Preset, ändern Sie die Felder, die Ihre Marke tragen, installieren Sie es mit cx.setTheme. Fertig ist Ihr Theme.

Diese Seite behandelt das Definieren und Installieren eines Themes. Wie Views Tokens nutzen (Stilfunktionen und Recipes), steht unter Styling und Themes.

Das Standard-Theme

Das Cx jedes Fensters startet mit ui.theme.dark. Eine App, die nie setTheme aufruft, ist dunkel, so wie Hello Button. Für ein anderes Theme setzen Sie es in der ersten Zeile Ihrer Mount-Funktion, bevor irgendein Node existiert:

fn mountUI(cx: *ui.Cx, scope: *ui.Scope) anyerror!*ui.Node {
    // Cx starts on ui.theme.dark. Pick the theme before building any node,
    // so every component reads the right tokens when it mounts.
    cx.setTheme(&ui.theme.light);

    const root = try ui.boxStyled(cx, S.root, .{});
    // …
    return root;
}

Bei mehreren Fenstern hat jedes sein eigenes Cx, setzen Sie das Theme also in jeder Mount-Funktion. zenit folgt dem Erscheinungsbild des Systems noch nicht: Ein Hell/Dunkel-Wechsel des Systems löst nur ein Neuzeichnen aus, und es gibt keine öffentliche API, um das System-Erscheinungsbild zu lesen. Bieten Sie Ihren Nutzern stattdessen einen Umschalter an (siehe „Wechsel zur Laufzeit“).

Aufbau von ThemeTokens

pub const ThemeTokens = struct {
    name: []const u8 = "unnamed",
    scheme: ColorScheme = .light,      // .light / .dark, the one flag for "is this dark?"
    color: ColorTokens,                // 54 colors, no defaults: you must provide all of them
    space: SpaceScale = .{},           // _0 … _12  (0 … 48 px, 4 px grid)
    radius: RadiusScale = .{},         // none sm md lg xl full
    font_size: FontSizeScale = .{},    // xxs … xxxl (9 … 24)
    border_width: BorderWidthScale = .{},
    size: SizeTokens = .{},            // checkbox, switch, badge, dot, close button
    control: ControlScale = .{},       // xs / sm / md / lg metrics for every control
    duration: DurationTokens = .{},    // fast / normal / slow (seconds)
    shadow: ShadowTokens = .{},        // sm / md / lg
};

Alles außer color hat Standardwerte. Die 54 Farben in ColorTokens haben keine, schreiben Sie also kein Struct-Literal von Grund auf. Kopieren Sie ui.theme.light, ui.theme.dark oder ui.theme.high_contrast und ändern Sie nur, was Sie brauchen.

Ein Marken-Theme ableiten

Schreiben Sie Themes als consts auf Container-Ebene; der Initialisierungsblock läuft zur Compile-Zeit und das Ergebnis liegt im statischen Speicher, sodass der Zeiger, den cx.setTheme(&brand) behält, während der gesamten Programmlaufzeit gültig bleibt. Nehmen Sie nie die Adresse eines Themes, das in einer lokalen Variable einer Funktion liegt.

// theme.zig: your app's themes. Container-level consts: they are
// evaluated at compile time and live for the whole program, which is
// what cx.setTheme(&brand) needs (it keeps the pointer).
const ui = @import("ui");

pub const brand: ui.ThemeTokens = blk: {
    var t = ui.theme.light; // copy a complete preset (every color is required)
    t.name = "brand";
    t.scheme = .light;

    const blue = ui.Color.hex(0x1144AA);
    t.color.accent = blue;                       // links, checked states, active tabs…
    t.color.accent_hover = ui.Color.hex(0x0D3688);
    t.color.accent_subtle = ui.Color.hex(0xE6ECF7);
    t.color.button_primary_bg = blue;            // primary buttons read these two,
    t.color.button_primary_fg = ui.Color.WHITE;  //   not accent
    t.color.border_focus = blue;
    t.color.selection_bg = ui.Color.hex(0xC9D6F0);
    t.color.list_selection_bg = ui.Color.hex(0xE6ECF7);

    t.radius.lg = 10;
    t.control.md.radius = 10;
    t.control.md.padding_h = 14;
    break :blk t;
};

Ein passendes dunkles Theme

Leiten Sie die dunkle Variante von ui.theme.dark ab, statt das helle Marken-Theme umzufärben: Die Dutzenden Hintergrund-, Text- und Rahmenwerte im dunklen Preset sind als Satz abgestimmt. Auf dunklen Hintergründen muss die Markenfarbe meist aufgehellt werden, und der Text von Primary-Buttons wird dunkel.

pub const brand_dark: ui.ThemeTokens = blk: {
    var t = ui.theme.dark; // start from the dark preset, not from brand
    t.name = "brand_dark";
    t.scheme = .dark;      // Notification palettes and DevTools key off this

    const blue = ui.Color.hex(0x7FA2F0); // lighter on dark backgrounds
    t.color.accent = blue;
    t.color.button_primary_bg = blue;
    t.color.button_primary_fg = ui.Color.hex(0x0D1119);
    t.color.border_focus = blue;
    break :blk t;
};

brand (hell)

brand_dark

ui.theme.dark (Standard)

Welche Tokens was steuern

Gruppiert danach, was Komponenten tatsächlich lesen (Quellcode v0.1.0-alpha). Beginnen Sie beim Theming mit diesen:

Einige Komponenten bringen eigene Farben mit, statt ColorTokens zu lesen: Der Notifier wählt anhand von scheme zwischen seinen eingebauten hellen und dunklen Paletten, und GlassBox-Tönungen sowie einige Details von Progress und Select sind feste Werte. Sie folgen Hell/Dunkel, aber nicht Ihrer Markenfarbe.

Radien, Abstände und Control-Maße

Nicht-Farb-Tokens lassen sich Feld für Feld überschreiben. Am nützlichsten ist control: Button, Input, Select, ComboBox, DatePicker, DateRangePicker, Tabs und Chip teilen sich vier Maßsätze, xs / sm / md / lg. Die Höhe eines Controls ist kein Token. Sie wird berechnet:

Um md-Controls höher zu machen, ändern Sie also t.control.md.padding_y oder die Schriftgröße, und alle md-Controls folgen; codieren Sie keine height für ein Control fest. Halten Sie icon_size nicht größer als die Zeilenhöhe.

Wechsel zur Laufzeit

cx.setTheme kann jederzeit aufgerufen werden: Es tauscht den Token-Zeiger aus, spielt die on_theme- / before_render-Hooks im gesamten cx.root-Teilbaum (inklusive Overlay-Portal) erneut ab und fordert ein Neuzeichnen an.

const Prefs = struct {
    cx: *ui.Cx,
    dark: bool = false,

    pub fn toggle(self: *Prefs) void {
        self.dark = !self.dark;
        self.cx.setTheme(if (self.dark) &themes.brand_dark else &themes.brand);
    }
};

// In mountUI:
const prefs = try cx.bindState(Prefs, .{ .cx = cx });
cx.setTheme(&themes.brand);
// …
.on_click = cx.on(Prefs, prefs, Prefs.toggle),

// A reactive read of the current theme (lives as long as `scope`).
const theme_sig = try cx.themeSignal(scope);
const is_dark = theme_sig.get().scheme == .dark;

Vor der Auslieferung

• ✓

  scheme passt zum Hintergrund (ein dunkler Hintergrund muss .dark sein).

• ✓

  button_primary_fg auf button_primary_bg und status_fg auf danger erreichen mindestens 4.5:1, dieselbe Prüfung, mit der die eingebauten Presets getestet werden.

• ✓

  border bleibt von bg_primary unterscheidbar (die Preset-Tests verlangen ≥ 1.2).

• ✓

  Stellen Sie das Storybook auf Ihr Theme um und klicken Sie sich durch die gängigen Komponenten (die Story Component Wall ist ein guter Anfang).