Theme Tokens

Overview

The Beep theme system uses a token-based architecture where every visual property is a named token defined in the IBeepTheme interface. BeepTheme implements this contract across 35 partial files, with each file handling one control type's token defaults. Concrete themes (Ubuntu, GNOME, Cyberpunk, Candy, Zen) subclass BeepTheme and override only the tokens that differ from the defaults. At runtime, a three-level resolution pipeline determines the final value for each token.

IBeepTheme Contract

public interface IBeepTheme
{
    string ThemeName { get; }
    Font DefaultFont { get; }
    Font TitleFont { get; }
    int BorderRadius { get; }
    float Opacity { get; }

    // Button tokens
    Color ButtonBackColor { get; }
    Color ButtonForeColor { get; }
    Color ButtonBorderColor { get; }
    Color ButtonHoverColor { get; }
    Color ButtonPressedColor { get; }
    Color ButtonDisabledColor { get; }
    int ButtonBorderRadius { get; }
    Color ButtonFocusBorderColor { get; }

    // TextBox tokens
    Color TextBoxBackColor { get; }
    Color TextBoxForeColor { get; }
    Color TextBoxBorderColor { get; }
    Color TextBoxFocusedBorderColor { get; }
    Color TextBoxPlaceholderColor { get; }
    Color TextBoxReadOnlyBackColor { get; }

    // Grid tokens
    Color GridHeaderBackColor { get; }
    Color GridHeaderForeColor { get; }
    Color GridCellBackColor { get; }
    Color GridAlternatingRowBackColor { get; }
    Color GridSelectionBackColor { get; }
    Color GridBorderColor { get; }
    Color GridGridLineColor { get; }

    // Chart tokens
    Color ChartSeriesPalette0 { get; } // through Palette7
    Color ChartAxisColor { get; }
    Color ChartAxisLabelColor { get; }
    Color ChartGridLineColor { get; }
    Color ChartBackgroundColor { get; }
    Color ChartLegendBackColor { get; }
    Color ChartLegendTextColor { get; }

    // ... ~170 more tokens for every control type
}

BeepTheme Partial Class (35 Files)

Each partial file provides default token values for one control type. Concrete themes override these defaults:

Token Map by Major Control Type

Token Resolution Pipeline

1. Control checks its own ThemeOverrides -- Per-control override dictionary (ThemeOverrideConfig). Highest priority.
2. Falls back to BeepThemesManager.CurrentTheme -- Global singleton theme. Medium priority.
3. Falls back to default values -- Hardcoded in BeepTheme partial files. Lowest priority, always available.

Color GetButtonBackColor(BaseControl control)
{
    // 1. Per-control override
    if (control.ThemeOverrides?.ButtonBackColor != null)
        return control.ThemeOverrides.ButtonBackColor;

    // 2. Global theme
    var currentTheme = BeepThemesManager.CurrentTheme;
    if (currentTheme?.ButtonBackColor != null)
        return currentTheme.ButtonBackColor;

    // 3. Default fallback
    return DefaultTheme.ButtonBackColor;  // Navy blue
}

Per-Control Overrides

Each BaseControl has a ThemeOverrides property of type ThemeOverrideConfig. This class mirrors IBeepTheme with nullable versions of every token. When a token is set (non-null), it overrides the global theme for that specific control instance. When null, the token falls through to the global theme or default.

myButton.ThemeOverrides = new ThemeOverrides
{
    ButtonBackColor = Color.Crimson,
    ButtonForeColor = Color.White,
    BorderRadius = 16,
    // All other tokens remain null -> fall through to global theme
};

Theme Inheritance

Concrete themes (Ubuntu, GNOME, Cyberpunk, etc.) subclass BeepTheme, which provides default values for all ~200 tokens. A concrete theme only needs to override the tokens that differ from the defaults. Partial files in each theme project organize overrides by control type, mirroring the structure of BeepTheme.

public class CyberpunkTheme : BeepTheme
{
    public override Color ButtonBackColor => Color.FromArgb(40, 40, 40);
    public override Color ButtonForeColor => Color.Magenta;
    public override Color ButtonBorderColor => Color.Cyan;
    public override int BorderRadius => 0;
    // ... 197 more overrides
    // Non-overridden tokens inherit from BeepTheme defaults
}

Code Examples

// Global theme switch
BeepThemesManager.Instance.SetTheme("CyberpunkTheme");
// -> All controls receive ApplyTheme() -> UpdateVisualStyle()

// Per-control override
myButton.ThemeOverrides = new ThemeOverrides
{
    ButtonBackColor = Color.Crimson,
    BorderRadius = 16
};

// Custom theme with selected overrides
var myTheme = new BeepTheme
{
    ButtonBackColor = Color.Navy,
    ButtonForeColor = Color.White,
    GridHeaderBackColor = Color.DarkSlateGray
    // All non-overridden tokens get BeepTheme defaults
};
BeepThemesManager.Instance.RegisterTheme(myTheme);