{"id":30020079,"url":"https://github.com/ktsu-dev/themeprovider","last_synced_at":"2026-06-27T01:08:04.432Z","repository":{"id":305695018,"uuid":"1023640910","full_name":"ktsu-dev/ThemeProvider","owner":"ktsu-dev","description":"A semantic color theming library for .NET applications that provides 44+ beautiful themes with intelligent color mapping, framework integration, and accessibility-first design.","archived":false,"fork":false,"pushed_at":"2026-06-24T23:25:47.000Z","size":405,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T01:08:44.666Z","etag":null,"topics":["accessibility","c","color","color-palette","color-science","color-space","colors","contrast-ratio","dark-theme","dear-imgui","imgui","light-theme","net","oklab","perceptual-color","semantic-colors","theme","theming","ui-framework","wcag"],"latest_commit_sha":null,"homepage":"https://ktsu.dev","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ktsu-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":"COPYRIGHT.md","agents":null,"dco":null,"cla":null}},"created_at":"2025-07-21T13:18:19.000Z","updated_at":"2026-06-24T23:25:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"836cf1d7-fb06-4bd3-9a68-d38940531934","html_url":"https://github.com/ktsu-dev/ThemeProvider","commit_stats":null,"previous_names":["ktsu-dev/themeprovider"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/ktsu-dev/ThemeProvider","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FThemeProvider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FThemeProvider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FThemeProvider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FThemeProvider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ktsu-dev","download_url":"https://codeload.github.com/ktsu-dev/ThemeProvider/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FThemeProvider/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34838050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","c","color","color-palette","color-science","color-space","colors","contrast-ratio","dark-theme","dear-imgui","imgui","light-theme","net","oklab","perceptual-color","semantic-colors","theme","theming","ui-framework","wcag"],"created_at":"2025-08-06T01:38:33.712Z","updated_at":"2026-06-27T01:08:04.415Z","avatar_url":"https://github.com/ktsu-dev.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ktsu.ThemeProvider\n\n\u003e A semantic color theming library for .NET applications with 44+ themes, intelligent color mapping, and framework integration.\n\n[![License](https://img.shields.io/github/license/ktsu-dev/ThemeProvider.svg?label=License\u0026logo=nuget)](LICENSE.md)\n[![NuGet Version](https://img.shields.io/nuget/v/ktsu.ThemeProvider?label=Stable\u0026logo=nuget)](https://nuget.org/packages/ktsu.ThemeProvider)\n[![NuGet Version](https://img.shields.io/nuget/vpre/ktsu.ThemeProvider?label=Latest\u0026logo=nuget)](https://nuget.org/packages/ktsu.ThemeProvider)\n[![NuGet Downloads](https://img.shields.io/nuget/dt/ktsu.ThemeProvider?label=Downloads\u0026logo=nuget)](https://nuget.org/packages/ktsu.ThemeProvider)\n[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/ktsu-dev/ThemeProvider?label=Commits\u0026logo=github)](https://github.com/ktsu-dev/ThemeProvider/commits/main)\n[![GitHub contributors](https://img.shields.io/github/contributors/ktsu-dev/ThemeProvider?label=Contributors\u0026logo=github)](https://github.com/ktsu-dev/ThemeProvider/graphs/contributors)\n[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ktsu-dev/ThemeProvider/dotnet.yml?label=Build\u0026logo=github)](https://github.com/ktsu-dev/ThemeProvider/actions)\n\n## Introduction\n\n`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 44 carefully crafted themes from popular color schemes and provides built-in Dear ImGui integration with an extensible architecture for other UI frameworks.\n\n## Features\n\n- **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\n- **44 Built-in Themes**: Includes Catppuccin, Tokyo Night, Gruvbox, Everforest, Nightfox, Kanagawa, PaperColor, Nord, Dracula, VSCode, One Dark, Monokai, and Nightfly theme families\n- **Centralized Theme Registry**: Discover, filter, and instantiate themes by name, family, or light/dark classification with rich metadata\n- **Dear ImGui Integration**: Companion package `ktsu.ThemeProvider.ImGui` provides complete ImGui color palette mapping via `ImGuiPaletteMapper`\n- **Perceptual Color Science**: Uses Oklab perceptual color space for uniform color interpolation, extrapolation, and lightness-based priority mapping\n- **WCAG Accessibility**: Built-in contrast ratio calculations, accessibility level checking (AA/AAA), and automatic color adjustment to meet WCAG standards\n- **Extensible Framework Mappers**: Implement `IPaletteMapper\u003cTColorKey, TColorValue\u003e` to integrate with any UI framework\n- **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\n- **Multi-Target Support**: Targets .NET 5.0 through 10.0, plus .NET Standard 2.0 and 2.1\n\n## Installation\n\n### Package Manager Console\n\n```powershell\nInstall-Package ktsu.ThemeProvider\n```\n\n### .NET CLI\n\n```bash\ndotnet add package ktsu.ThemeProvider\n```\n\n### Package Reference\n\n```xml\n\u003cPackageReference Include=\"ktsu.ThemeProvider\" Version=\"x.y.z\" /\u003e\n```\n\nFor Dear ImGui integration, also install:\n\n```bash\ndotnet add package ktsu.ThemeProvider.ImGui\n```\n\n## Usage Examples\n\n### Basic Example\n\n```csharp\nusing ktsu.ThemeProvider;\nusing static ktsu.ThemeProvider.ThemeRegistry;\n\n// Create a theme directly\nvar theme = new Themes.Catppuccin.Mocha();\n\n// Or find and create via the registry\nThemeInfo? themeInfo = FindTheme(\"Catppuccin Mocha\");\nISemanticTheme? registryTheme = themeInfo?.CreateInstance();\n\n// Map semantic color requests to actual colors\nvar requests = new[]\n{\n    new SemanticColorRequest(SemanticMeaning.Primary, Priority.Medium),\n    new SemanticColorRequest(SemanticMeaning.Error, Priority.High),\n    new SemanticColorRequest(SemanticMeaning.Neutral, Priority.VeryLow),\n};\nIReadOnlyDictionary\u003cSemanticColorRequest, PerceptualColor\u003e colors =\n    SemanticColorMapper.MapColors(requests, theme);\n```\n\n### Theme Discovery with the Registry\n\n```csharp\nusing ktsu.ThemeProvider;\nusing static ktsu.ThemeProvider.ThemeRegistry;\n\n// Browse all themes\nIReadOnlyList\u003cThemeInfo\u003e allThemes = AllThemes;\nIReadOnlyList\u003cThemeInfo\u003e darkThemes = DarkThemes;\nIReadOnlyList\u003cThemeInfo\u003e lightThemes = LightThemes;\n\n// Browse by family\nIReadOnlyList\u003cstring\u003e families = Families;\nIReadOnlyList\u003cThemeInfo\u003e catppuccinThemes = GetThemesInFamily(\"Catppuccin\");\n\n// Find a specific theme by name (case-insensitive)\nThemeInfo? themeInfo = FindTheme(\"Tokyo Night Storm\");\nISemanticTheme? theme = themeInfo?.CreateInstance();\n\n// Create all theme instances at once\nIReadOnlyList\u003cISemanticTheme\u003e allInstances = CreateAllThemeInstances();\nIReadOnlyList\u003cISemanticTheme\u003e gruvboxInstances = CreateThemeInstancesInFamily(\"Gruvbox\");\n```\n\n### Complete Palette Generation\n\n```csharp\nusing ktsu.ThemeProvider;\n\nvar theme = new Themes.Nord.Nord();\n\n// Generate the complete palette (all meaning + priority combinations)\nIReadOnlyDictionary\u003cSemanticColorRequest, PerceptualColor\u003e completePalette =\n    SemanticColorMapper.MakeCompletePalette(theme);\n\n// Access any color from the palette\nvar primaryMedium = completePalette[new SemanticColorRequest(SemanticMeaning.Primary, Priority.Medium)];\nRgbColor rgb = primaryMedium.RgbValue;\nstring hex = rgb.ToHex();\n```\n\n### Dear ImGui Integration\n\n```csharp\nusing ktsu.ThemeProvider;\nusing ktsu.ThemeProvider.ImGui;\nusing Hexa.NET.ImGui;\n\n// Create theme and mapper\nvar theme = new Themes.Catppuccin.Mocha();\nvar mapper = new ImGuiPaletteMapper();\n\n// Get complete ImGui color palette\nIReadOnlyDictionary\u003cImGuiCol, Vector4\u003e imguiColors = mapper.MapTheme(theme);\n\n// Apply to ImGui style\nvar style = ImGui.GetStyle();\nforeach ((ImGuiCol colorKey, Vector4 colorValue) in imguiColors)\n{\n    style.Colors[(int)colorKey] = colorValue;\n}\n```\n\n### Accessibility Checking\n\n```csharp\nusing ktsu.ThemeProvider;\n\nvar foreground = RgbColor.FromHex(\"#FFFFFF\");\nvar background = RgbColor.FromHex(\"#1E1E2E\");\n\n// Calculate contrast ratio\nfloat contrastRatio = ColorMath.GetContrastRatio(foreground, background);\n\n// Check WCAG compliance\nAccessibilityLevel level = ColorMath.GetAccessibilityLevel(foreground, background, isLargeText: false);\n\n// Adjust a color to meet accessibility requirements\nRgbColor adjusted = ColorMath.AdjustForAccessibility(foreground, background, AccessibilityLevel.AA);\n\n// Create perceptually uniform gradients\nRgbColor[] gradient = ColorMath.CreateGradient(foreground, background, steps: 10);\n```\n\n## Advanced Usage\n\n### Creating Custom Framework Mappers\n\nImplement `IPaletteMapper\u003cTColorKey, TColorValue\u003e` to integrate with any UI framework:\n\n```csharp\nusing ktsu.ThemeProvider;\n\npublic class MyFrameworkMapper : IPaletteMapper\u003cMyColorEnum, MyColorType\u003e\n{\n    public string FrameworkName =\u003e \"My UI Framework\";\n\n    public IReadOnlyDictionary\u003cMyColorEnum, MyColorType\u003e MapTheme(ISemanticTheme theme)\n    {\n        var requests = new Dictionary\u003cMyColorEnum, SemanticColorRequest\u003e\n        {\n            { MyColorEnum.Button, new(SemanticMeaning.Primary, Priority.Medium) },\n            { MyColorEnum.Background, new(SemanticMeaning.Neutral, Priority.VeryLow) },\n            { MyColorEnum.ErrorText, new(SemanticMeaning.Error, Priority.High) },\n        };\n\n        var palette = SemanticColorMapper.MapColors(requests.Values, theme);\n\n        var result = new Dictionary\u003cMyColorEnum, MyColorType\u003e();\n        foreach (var kvp in requests)\n        {\n            if (palette.TryGetValue(kvp.Value, out var color))\n            {\n                result[kvp.Key] = ConvertToMyColor(color.RgbValue);\n            }\n        }\n        return result;\n    }\n}\n```\n\n### Creating Custom Themes\n\nImplement `ISemanticTheme` with colors from your palette:\n\n```csharp\nusing ktsu.ThemeProvider;\nusing System.Collections.ObjectModel;\n\npublic class MyCustomTheme : ISemanticTheme\n{\n    private static readonly PerceptualColor Background = PerceptualColor.FromRgb(\"#1A1B26\");\n    private static readonly PerceptualColor Foreground = PerceptualColor.FromRgb(\"#C0CAF5\");\n    private static readonly PerceptualColor Blue = PerceptualColor.FromRgb(\"#7AA2F7\");\n    private static readonly PerceptualColor Green = PerceptualColor.FromRgb(\"#9ECE6A\");\n    private static readonly PerceptualColor Red = PerceptualColor.FromRgb(\"#F7768E\");\n\n    public bool IsDarkTheme =\u003e true;\n\n    public Dictionary\u003cSemanticMeaning, Collection\u003cPerceptualColor\u003e\u003e SemanticMapping { get; } = new()\n    {\n        { SemanticMeaning.Neutral, new() { Background, Foreground } },\n        { SemanticMeaning.Primary, new() { Blue } },\n        { SemanticMeaning.Success, new() { Green } },\n        { SemanticMeaning.Error, new() { Red } },\n    };\n}\n```\n\n## API Reference\n\n### `SemanticMeaning` (enum)\n\nDefines semantic color purposes.\n\n| Value | Description |\n|-------|-------------|\n| `Neutral` | Backgrounds, borders, inactive elements |\n| `Primary` | Main brand/accent colors |\n| `Alternate` | Secondary accent, binary choice emphasis |\n| `Success` | Successful operations, confirmations |\n| `CallToAction` | Important buttons and highlights demanding attention |\n| `Information` | Informational content, help text |\n| `Caution` | Cautionary content needing attention |\n| `Warning` | Warning states, potentially problematic |\n| `Error` | Error states, incorrect conditions |\n| `Failure` | Failed operations (distinct from error) |\n| `Debug` | Debug/development information |\n\n### `Priority` (enum)\n\nControls color intensity and lightness within a semantic meaning.\n\n| Value | Description |\n|-------|-------------|\n| `VeryLow` | Lowest intensity (backgrounds in dark themes, lightest in light themes) |\n| `Low` | Low intensity |\n| `MediumLow` | Below-medium intensity |\n| `Medium` | Default intensity level |\n| `MediumHigh` | Above-medium intensity |\n| `High` | High intensity |\n| `VeryHigh` | Highest intensity (foreground text in dark themes, darkest in light themes) |\n\n### `SemanticColorRequest`\n\nA readonly record struct combining a `SemanticMeaning` and `Priority` to specify a color.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `Meaning` | `SemanticMeaning` | The semantic purpose of the color |\n| `Priority` | `Priority` | The intensity/lightness level |\n\n### `SemanticColorMapper`\n\nStatic class that maps semantic color requests to actual colors.\n\n#### Methods\n\n| Name | Return Type | Description |\n|------|-------------|-------------|\n| `MapColors(requests, theme)` | `IReadOnlyDictionary\u003cSemanticColorRequest, PerceptualColor\u003e` | Maps a collection of requests to colors using the theme |\n| `MakeCompletePalette(theme)` | `IReadOnlyDictionary\u003cSemanticColorRequest, PerceptualColor\u003e` | Generates all possible meaning+priority combinations for a theme |\n\n### `ThemeRegistry`\n\nStatic class providing centralized theme discovery and management.\n\n#### Properties\n\n| Name | Type | Description |\n|------|------|-------------|\n| `AllThemes` | `IReadOnlyList\u003cThemeInfo\u003e` | All 44 registered themes with metadata |\n| `DarkThemes` | `IReadOnlyList\u003cThemeInfo\u003e` | All dark themes |\n| `LightThemes` | `IReadOnlyList\u003cThemeInfo\u003e` | All light themes |\n| `Families` | `IReadOnlyList\u003cstring\u003e` | All theme family names |\n| `ThemesByFamily` | `IReadOnlyDictionary\u003cstring, IReadOnlyList\u003cThemeInfo\u003e\u003e` | Themes grouped by family |\n\n#### Methods\n\n| Name | Return Type | Description |\n|------|-------------|-------------|\n| `FindTheme(name)` | `ThemeInfo?` | Finds a theme by name (case-insensitive) |\n| `GetThemesInFamily(family)` | `IReadOnlyList\u003cThemeInfo\u003e` | Gets all themes in a family |\n| `CreateAllThemeInstances()` | `IReadOnlyList\u003cISemanticTheme\u003e` | Creates instances of all themes |\n| `CreateThemeInstancesInFamily(family)` | `IReadOnlyList\u003cISemanticTheme\u003e` | Creates instances of themes in a family |\n\n### `ColorMath`\n\nStatic class providing color space conversions and accessibility utilities.\n\n#### Methods\n\n| Name | Return Type | Description |\n|------|-------------|-------------|\n| `RgbToOklab(rgb)` | `OklabColor` | Converts linear RGB to Oklab color space |\n| `OklabToRgb(oklab)` | `RgbColor` | Converts Oklab to linear RGB color space |\n| `GetRelativeLuminance(rgb)` | `float` | Calculates WCAG relative luminance |\n| `GetContrastRatio(color1, color2)` | `float` | Calculates WCAG contrast ratio (1:1 to 21:1) |\n| `GetAccessibilityLevel(fg, bg, isLargeText)` | `AccessibilityLevel` | Checks WCAG AA/AAA compliance |\n| `AdjustForAccessibility(fg, bg, level, isLargeText)` | `RgbColor` | Adjusts color to meet WCAG requirements |\n| `CreateGradient(from, to, steps)` | `RgbColor[]` | Creates a perceptually uniform gradient |\n\n### `PerceptualColor`\n\nReadonly record struct representing a color with perceptual properties in Oklab space.\n\n#### Properties\n\n| Name | Type | Description |\n|------|------|-------------|\n| `OklabValue` | `OklabColor` | The color in Oklab perceptual space |\n| `RgbValue` | `RgbColor` | The RGB representation |\n| `Hue` | `float` | Hue in Oklab polar coordinates |\n| `Chroma` | `float` | Chroma (colorfulness) in Oklab polar coordinates |\n| `Lightness` | `float` | Lightness in Oklab space |\n\n#### Methods\n\n| Name | Return Type | Description |\n|------|-------------|-------------|\n| `FromRgb(RgbColor)` | `PerceptualColor` | Creates from an RGB color |\n| `FromRgb(string hex)` | `PerceptualColor` | Creates from a hex color string |\n| `SemanticDistanceTo(other)` | `float` | Calculates perceptual distance to another color |\n\n### `RgbColor`\n\nReadonly record struct representing a linear RGB color with float precision.\n\n#### Methods\n\n| Name | Return Type | Description |\n|------|-------------|-------------|\n| `FromBytes(r, g, b)` | `RgbColor` | Creates from 8-bit values (0-255) |\n| `FromHex(hex)` | `RgbColor` | Creates from hex string (e.g., \"#FF0000\") |\n| `ToHex()` | `string` | Converts to hex string |\n| `ToBytes()` | `(byte R, byte G, byte B)` | Converts to 8-bit values |\n| `ToSRgb()` | `SRgbColor` | Converts to sRGB gamma-corrected values |\n\n### `IPaletteMapper\u003cTColorKey, TColorValue\u003e`\n\nInterface for mapping semantic themes to framework-specific color palettes.\n\n#### Properties\n\n| Name | Type | Description |\n|------|------|-------------|\n| `FrameworkName` | `string` | The name of the target UI framework |\n\n#### Methods\n\n| Name | Return Type | Description |\n|------|-------------|-------------|\n| `MapTheme(theme)` | `IReadOnlyDictionary\u003cTColorKey, TColorValue\u003e` | Maps a theme to a framework-specific palette |\n\n## Available Themes\n\n| Family | Variants | Description |\n|--------|----------|-------------|\n| **Catppuccin** | Latte, Frappe, Macchiato, Mocha | Warm pastel themes with excellent readability |\n| **Tokyo Night** | Night, Storm, Day | Clean themes inspired by Tokyo's neon nights |\n| **Gruvbox** | Dark, Dark Hard, Dark Soft, Light, Light Hard, Light Soft | Retro groove colors with warm backgrounds |\n| **Everforest** | Dark, Dark Hard, Dark Soft, Light, Light Hard, Light Soft | Green forest colors for comfortable viewing |\n| **Nightfox** | Nightfox, Dayfox, Duskfox, Nordfox, Terafox, Carbonfox, Dawnfox | Fox-inspired vibrant themes |\n| **Kanagawa** | Wave, Dragon, Lotus | Japanese-inspired themes |\n| **PaperColor** | Light, Dark | Material Design inspired themes |\n| **VSCode** | Dark, Light | Microsoft VSCode default themes |\n| **Nord** | - | Arctic-inspired theme with cool blue tones |\n| **Dracula** | - | Gothic theme with purple and pink accents |\n| **One Dark** | - | Atom's iconic One Dark theme |\n| **Monokai** | - | Classic Monokai with vibrant colors |\n| **Nightfly** | - | Dark blue theme inspired by night flying |\n\n## Contributing\n\nContributions are welcome! Feel free to open issues or submit pull requests.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktsu-dev%2Fthemeprovider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fktsu-dev%2Fthemeprovider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktsu-dev%2Fthemeprovider/lists"}