ktsu.Semantics.Color 2.9.8

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).

Supporting types

The satellite spaces carry their own adjustments: Hsl and Srgb have the full HSL set (saturation/lightness/hue/grayscale; Srgb routes these through HSL and also adds Invert()), while Oklch exposes perceptually-uniform WithLightness/LightenBy/DarkenBy, chroma ops (WithChroma/MultiplyChroma/SaturateBy/DesaturateBy/ToGrayscale), and OffsetHue. Color's adjustment methods forward to Hsl.

Converting between spaces

Beyond the base conversion listed above, every color type (including Color) exposes To{Space}() and From{Space}(...) for every other space, plus a uniform ToColor() / FromColor(Color) pair. Those extra methods are one-liners that reuse the base conversions rather than reimplementing any color math, routed through the nearest shared hub:

• Within the sRGB family (Srgb, Hsl, Hsv) conversions route through Srgb, so no gamma decode/encode happens.
• Within the perceptual family (Oklab, Oklch) conversions route through Oklab.
• Across the two families conversions route through the linear Color hub, crossing the gamma boundary exactly once.

So srgb.ToHsl() is the direct HSL definition, while hsl.ToOklab() goes Hsl → Srgb → linear Color → Oklab. Because the satellite spaces carry no alpha, cross-space conversions preserve only the color; use the Color overloads (or WithAlpha) when you need alpha.

FromHex throws ArgumentException for lengths other than 3, 6, or 8, and Gradient throws ArgumentException for steps < 2.

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.