ktsu.ThemeProvider 3.0.7

ktsu.ThemeProvider

A semantic color theming library for .NET applications with 38 themes, intelligent color mapping, and framework integration.

Introduction

ktsu.ThemeProvider is a comprehensive theming system that uses semantic color specifications rather than arbitrary color names. Instead of hardcoding colors like "blue" or "red", you define colors by their purpose (Primary, Error, Warning) and priority level, and the library generates consistent, accessible color palettes. It includes 38 carefully crafted themes from popular color schemes and provides built-in Dear ImGui integration with an extensible architecture for other UI frameworks.

Features

• Semantic Color System: Define colors by purpose (Primary, Error, Warning, Neutral) and priority level rather than specific hues, enabling consistent theming across any UI framework
• 38 Built-in Themes: Includes Catppuccin, Tokyo Night, Gruvbox, Everforest, Nightfox, Kanagawa, PaperColor, Nord, Dracula, VSCode, One Dark, Monokai, and Nightfly theme families
• Centralized Theme Registry: Discover, filter, and instantiate themes by name, family, or light/dark classification with rich metadata
• Dear ImGui Integration: Companion package ktsu.ThemeProvider.ImGui provides complete ImGui color palette mapping via ImGuiPaletteMapper
• Perceptual Color Science: Uses Oklab perceptual color space for uniform color interpolation, extrapolation, and lightness-based priority mapping
• WCAG Accessibility: Built-in contrast ratio calculations, accessibility level checking (AA/AAA), and automatic color adjustment to meet WCAG standards
• Extensible Framework Mappers: Implement IPaletteMapper<TColorKey, TColorValue> to integrate with any UI framework
• Priority-Based Color Hierarchy: Seven priority levels (VeryLow to VeryHigh) automatically mapped to appropriate lightness values, with theme-aware ordering for dark and light themes
• Multi-Target Support: Targets .NET 5.0 through 10.0, plus .NET Standard 2.0 and 2.1

Installation

Package Manager Console

Install-Package ktsu.ThemeProvider

.NET CLI

dotnet add package ktsu.ThemeProvider

Package Reference

<PackageReference Include="ktsu.ThemeProvider" Version="x.y.z" />

For Dear ImGui integration, also install:

dotnet add package ktsu.ThemeProvider.ImGui

Usage Examples

Basic Example

using ktsu.ThemeProvider;
using static ktsu.ThemeProvider.ThemeRegistry;

// Create a theme directly
var theme = new Themes.Catppuccin.Mocha();

// Or find and create via the registry
ThemeInfo? themeInfo = FindTheme("Catppuccin Mocha");
ISemanticTheme? registryTheme = themeInfo?.CreateInstance();

// Map semantic color requests to actual colors
var requests = new[]
{
    new SemanticColorRequest(SemanticMeaning.Primary, Priority.Medium),
    new SemanticColorRequest(SemanticMeaning.Error, Priority.High),
    new SemanticColorRequest(SemanticMeaning.Neutral, Priority.VeryLow),
};
IReadOnlyDictionary<SemanticColorRequest, Color> colors =
    SemanticColorMapper.MapColors(requests, theme);

Theme Discovery with the Registry

using ktsu.ThemeProvider;
using static ktsu.ThemeProvider.ThemeRegistry;

// Browse all themes
IReadOnlyList<ThemeInfo> allThemes = AllThemes;
IReadOnlyList<ThemeInfo> darkThemes = DarkThemes;
IReadOnlyList<ThemeInfo> lightThemes = LightThemes;

// Browse by family
IReadOnlyList<string> families = Families;
IReadOnlyList<ThemeInfo> catppuccinThemes = GetThemesInFamily("Catppuccin");

// Find a specific theme by name (case-insensitive)
ThemeInfo? themeInfo = FindTheme("Tokyo Night Storm");
ISemanticTheme? theme = themeInfo?.CreateInstance();

// Create all theme instances at once
IReadOnlyList<ISemanticTheme> allInstances = CreateAllThemeInstances();
IReadOnlyList<ISemanticTheme> gruvboxInstances = CreateThemeInstancesInFamily("Gruvbox");

Complete Palette Generation

using ktsu.ThemeProvider;
using ktsu.Semantics.Color;

var theme = new Themes.Nord.Nord();

// Generate the complete palette (all meaning + priority combinations)
IReadOnlyDictionary<SemanticColorRequest, Color> completePalette =
    SemanticColorMapper.MakeCompletePalette(theme);

// Access any color from the palette
var primaryMedium = completePalette[new SemanticColorRequest(SemanticMeaning.Primary, Priority.Medium)];
string hex = primaryMedium.ToHex();

Dear ImGui Integration

using ktsu.ThemeProvider;
using ktsu.ThemeProvider.ImGui;
using Hexa.NET.ImGui;

// Create theme and mapper
var theme = new Themes.Catppuccin.Mocha();
var mapper = new ImGuiPaletteMapper();

// Get complete ImGui color palette
IReadOnlyDictionary<ImGuiCol, Vector4> imguiColors = mapper.MapTheme(theme);

// Apply to ImGui style
var style = ImGui.GetStyle();
foreach ((ImGuiCol colorKey, Vector4 colorValue) in imguiColors)
{
    style.Colors[(int)colorKey] = colorValue;
}

Accessibility Checking

using ktsu.ThemeProvider;
using ktsu.Semantics.Color;

Color foreground = Color.FromHex("#FFFFFF");
Color background = Color.FromHex("#1E1E2E");

// Calculate contrast ratio (1.0 .. 21.0)
double contrastRatio = foreground.ContrastRatio(background);

// Check WCAG compliance
AccessibilityLevel level = foreground.AccessibilityLevelAgainst(background, largeText: false);

// Adjust a color to meet accessibility requirements
Color adjusted = foreground.AdjustForContrast(background, AccessibilityLevel.AA);

// Create perceptually uniform gradients
IReadOnlyList<Color> gradient = foreground.Gradient(background, steps: 10);

Advanced Usage

Creating Custom Framework Mappers

Implement IPaletteMapper<TColorKey, TColorValue> to integrate with any UI framework:

using ktsu.ThemeProvider;

public class MyFrameworkMapper : IPaletteMapper<MyColorEnum, MyColorType>
{
    public string FrameworkName => "My UI Framework";

    public IReadOnlyDictionary<MyColorEnum, MyColorType> MapTheme(ISemanticTheme theme)
    {
        var requests = new Dictionary<MyColorEnum, SemanticColorRequest>
        {
            { MyColorEnum.Button, new(SemanticMeaning.Primary, Priority.Medium) },
            { MyColorEnum.Background, new(SemanticMeaning.Neutral, Priority.VeryLow) },
            { MyColorEnum.ErrorText, new(SemanticMeaning.Error, Priority.High) },
        };

        var palette = SemanticColorMapper.MapColors(requests.Values, theme);

        var result = new Dictionary<MyColorEnum, MyColorType>();
        foreach (var kvp in requests)
        {
            if (palette.TryGetValue(kvp.Value, out var color))
            {
                result[kvp.Key] = ConvertToMyColor(color.RgbValue);
            }
        }
        return result;
    }
}

Creating Custom Themes

Declare your palette as a SemanticPalette and let it build the mapping. Colors are written as hex strings, the notation upstream color schemes publish, so a theme can be diffed against its source:

using ktsu.ThemeProvider;
using ktsu.Semantics.Color;
using System.Collections.ObjectModel;

public class MyCustomTheme : ISemanticTheme
{
    private static readonly SemanticPalette Palette = new()
    {
        // Neutrals are a ramp; the mapper interpolates between them across priority levels.
        Neutrals = ["#C0CAF5", "#1A1B26"],
        Primary = "#7AA2F7",
        Alternate = "#BB9AF7",
        Success = "#9ECE6A",
        CallToAction = "#9ECE6A",
        Information = "#7DCFFF",
        Caution = "#FF9E64",
        Warning = "#E0AF68",
        Error = "#F7768E",
        Failure = "#F7768E",
        Debug = "#BB9AF7",
    };

    public Dictionary<SemanticMeaning, Collection<Color>> SemanticMapping => Palette.ToSemanticMapping();

    public bool IsDarkTheme => true;
}

SemanticMapping is the only contract, so a theme with unusual needs (more than two neutrals, or a meaning driven by something other than a fixed hex) can still build the dictionary itself.

API Reference

SemanticMeaning (enum)

Defines semantic color purposes.

Priority (enum)

Controls color intensity and lightness within a semantic meaning.

SemanticColorRequest

A readonly record struct combining a SemanticMeaning and Priority to specify a color.

SemanticColorMapper

Static class that maps semantic color requests to actual colors.

Methods

ThemeRegistry

Static class providing centralized theme discovery and management.

Properties

Methods

Color types (ktsu.Semantics.Color)

Colors are represented by the Color type from the ktsu.Semantics.Color package (linear RGB + alpha, gamma-correct). It is the currency type for themes (ISemanticTheme.SemanticMapping) and SemanticColorMapper.

Common members:

Migration note (v2.0): ThemeProvider's in-house RgbColor, SRgbColor, OklabColor, PerceptualColor, and ColorMath types were removed in favour of ktsu.Semantics.Color. This also fixed a long-standing sRGB-as-linear gamma bug — base theme colors render identically, but the semantic mapper's derived colors and accessibility numbers are now computed correctly.

IPaletteMapper<TColorKey, TColorValue>

Interface for mapping semantic themes to framework-specific color palettes.

Properties

Methods

Available Themes

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License. See the LICENSE.md file for details.