ktsu.Semantics.Color 5.3.0

ktsu.Semantics.Color

A physically-grounded color type with linear-RGB math, perceptual Oklab operations, and built-in WCAG accessibility checks.

ktsu.Semantics.Color is one package in the ktsu.Semantics family. Start at the root README for the family overview.

Introduction

ktsu.Semantics.Color treats color the way rendering and color science do: the canonical Color type stores linear (non gamma-encoded) RGB plus straight alpha, each channel in 0..1, and all math happens in linear space. Gamma-encoded sRGB is a separate type (Srgb) that you cross into only when you convert. That distinction is the difference between correct blending, mixing, and luminance and the subtly-wrong results you get from doing arithmetic on gamma-encoded values.

On top of that foundation the package adds perceptual operations in the Oklab color space, hex and byte interop, System.Numerics vector output, and WCAG contrast tooling that can rate a color pair and automatically nudge a color until it meets a target conformance level.

Features

• Linear RGB as the hub: Color stores linear RGBA in 0..1, and all mixing, interpolation, and luminance math happens there.
• Color spaces: sRGB (Srgb), HSL (Hsl), HSV (Hsv), Oklab (Oklab), and Oklch (Oklch). Every color type (including Color) converts directly to and from every other through From* / To* methods. Each hop is routed through the nearest shared hub, so a conversion crosses the gamma boundary at most once and never takes a redundant gamma round-trip.
• Interop: hex parse and format (#RGB, #RRGGBB, #RRGGBBAA), 8-bit byte tuples, and linear or sRGB Vector3 / Vector4 output (the sRGB vectors are what ImGui expects).
• WCAG accessibility: relative luminance, contrast ratio (1..21), conformance rating against a background, and AdjustForContrast which binary-searches Oklab lightness to hit a target while preserving hue and chroma.
• Perceptual operations: Oklab distance (DistanceTo), perceptually uniform mixing (MixOklab), and Oklab gradients (Gradient), alongside plain linear Lerp.
• Adjustments: lighten/darken, saturate/desaturate, hue offset, grayscale, and invert. HSL-based on Color, Hsl, and Srgb; perceptually-uniform (lightness/chroma) variants on Oklch.
• Named colors: a CSS/X11 subset with case-insensitive lookup.

Installation

Package Manager Console

Install-Package ktsu.Semantics.Color

.NET CLI

dotnet add package ktsu.Semantics.Color

Package Reference

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

Usage Examples

Basic Example: accessible text color

using ktsu.Semantics.Color;

Color text = Color.FromHex("#777777");
Color background = NamedColors.White;

double ratio = text.ContrastRatio(background);                        // ~4.48
AccessibilityLevel level = text.AccessibilityLevelAgainst(background); // Fail for AA body text

if (level < AccessibilityLevel.AA)
{
    // darkens or lightens in Oklab, preserving hue and chroma, until AA is met
    text = text.AdjustForContrast(background, AccessibilityLevel.AA);
}

Console.WriteLine(text.ToHex());

Perceptually uniform gradients

using ktsu.Semantics.Color;

Color start = Color.FromSrgb(0.9, 0.1, 0.2);   // sRGB input, stored as linear
Color end = NamedColors.Blue;

// Oklab interpolation, inclusive of both endpoints; steps must be >= 2
IReadOnlyList<Color> ramp = start.Gradient(end, 5);

foreach (Color c in ramp)
{
    (byte r, byte g, byte b, byte a) = c.ToBytes();
    Console.WriteLine($"{c.ToHex()}  rgba({r},{g},{b},{a})");
}

Space conversions and vector interop

using System.Numerics;
using ktsu.Semantics.Color;

Color c = NamedColors.Orange;

Hsl hsl = c.ToHsl();                                            // H in degrees, S/L in 0..1
Color complementary = Color.FromHsl(hsl with { H = (hsl.H + 180) % 360 });

Oklch lch = c.ToOklch();                                        // perceptual lightness/chroma/hue
Color brighter = Color.FromOklch(lch with { L = lch.L + 0.1 });

Vector4 imguiColor = complementary.ToSrgbVector4();             // gamma-encoded RGBA for ImGui

Conversions are not limited to Color. Any color type converts straight to any other, so you can stay in whichever space fits the task:

using ktsu.Semantics.Color;

Hsl hsl = Color.FromHex("#3366CC").ToHsl();

Oklab lab = hsl.ToOklab();          // sRGB family -> perceptual family, through linear Color
Hsv hsv = lab.ToHsv();              // and back again
Srgb srgb = Oklch.FromHsl(hsl).ToSrgb();
Color linear = hsl.ToColor();       // every satellite also has ToColor() / FromColor()

Adjusting colors

using ktsu.Semantics.Color;

Color c = Color.FromHex("#3366CC");

Color hover = c.LightenBy(0.1);          // HSL lightness, alpha preserved
Color muted = c.DesaturateBy(0.3);       // HSL saturation
Color accent = c.OffsetHue(30);          // rotate hue 30 degrees
Color negative = c.Invert();             // per-channel negative in sRGB

// For perceptually-uniform tinting, adjust in Oklch instead of HSL
Color perceptualHover = c.ToOklch().LightenBy(0.1).ToColor(c.A);

API Reference

Color

The canonical color: linear RGBA, each channel double in 0..1. A readonly record struct with positional properties R, G, B, A.

Construction and conversion

Operations

Adjustments

Convenience adjustments on Color operate in HSL and preserve alpha; for perceptually-uniform lightness and chroma use the Oklch equivalents via ToOklch(). All are also available natively on Hsl (returning Hsl) and Srgb (returning Srgb).