Skip to content
AkiEvansDevPublic

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

NE.Colors

A named colour palette that resolves to RGBA: 32 colours, each adjustable by a tint or a shade in ten steps and by an opacity, rendering to System.Drawing.Color, to an eight-digit hex string, or to an ANSI escape sequence for a terminal — and the way back, from any colour to the palette step nearest to it.

Targets netstandard2.1. No dependencies.

Install

dotnet add package NE.Colors

Released to nuget.org.

A first look

using System.Drawing;
using NE.Colors;

var teal = new ColorVariant(ColorName.AstralTeal);

Color color = teal.ToColor();          // 0, 110, 100, alpha 255
var hex = teal.ToHex();                // "#006E64FF"
var light = teal.IsLight();            // false: white text reads better on it

// A tint moves towards white, a shade towards black, in ten steps.
var pale = new ColorVariant(ColorName.AstralTeal, ColorAdjustment.Tint, 8);
var deep = new ColorVariant(ColorName.AstralTeal, ColorAdjustment.Shade, 4);

// Opacity is the fourth component, and applies with or without an adjustment.
ColorVariant scrim = new ColorVariant(ColorName.IronFog, ColorAdjustment.Shade, 10).WithOpacity(160);

ColorVariant is a readonly record struct, so it compares and copies by value:

var selected = teal with { Adjustment = ColorAdjustment.Tint, Factor = 5, Opacity = 48 };

The palette

Thirty-two names in nine families, numbered so a family can grow without renumbering the rest.

Family Names
Neutral IronFog SilverNight BronzeDusk
Red / Pink StellarRed NebulaRose LunarPink PulsarMagenta
Orange / Yellow SolarAmber NebulaLemon LunarYellow SolarGold
Olive / Lime EclipseOlive NebulaLime LunarSage
Green AuroraGreen NebulaMint LunarFern
Teal / Cyan AstralTeal NebulaCyan LunarMoss
Blue QuantumBlue NebulaAqua LunarAzure
Purple NovaPurple NebulaViolet LunarLavender
Accent Comet Flare Ember Photon Vortex Halo

Each name carries a [Description] with its display form (AstralTeal → "Astral Teal"). The number of a name never changes, so a colour stored as its number reads back the same in every later version.

To see them all — every colour, its full tint and shade ramp, the opacity range, and what a terminal makes of each one — open examples/palette.html in a browser. The page is generated from the palette itself, so it cannot drift from it.

Adjustments

Factor runs from 0 to 10. At 0 an adjustment does nothing; at 10 a tint reaches white and a shade reaches black. Anything outside that range throws ArgumentOutOfRangeException, as does an unknown ColorName.

ColorAdjustment.None the base colour
ColorAdjustment.Tint channel + (255 - channel) * factor / 10
ColorAdjustment.Shade channel * (1 - factor / 10)

Opacity is applied independently of the adjustment, so WithOpacity works on an unadjusted colour too.

IsLight() is true when black text on the colour has more contrast than white, by the WCAG formula.

A colour the palette has no name for

A palette name is what a variant normally carries, and it is what keeps a design coherent. For the colour the palette cannot answer — one a person picked, one that arrived from outside — a variant carries an explicit Rgb instead. Set, it wins over the name, and adjustment, factor and opacity apply to it identically, so a picked colour tints and shades like every other.

ColorVariant picked = ColorVariant.FromRgb(0x2E, 0x7D, 0x32);
ColorVariant fromDrawing = ColorVariant.FromColor(Color.FromArgb(160, 46, 125, 50));

// #RGB, #RGBA, #RRGGBB and #RRGGBBAA, with or without the hash.
if (ColorVariant.TryParseHex("#2e7d32", out ColorVariant parsed))
{
    var paler = (parsed with { Adjustment = ColorAdjustment.Tint, Factor = 3 }).ToHex();
}

The nearest palette colour

Nearest goes the other way: from any colour to the name, adjustment and factor that look closest to it. The distance is measured in OKLab, where equal steps look equal, rather than in sRGB, where they do not. Opacity is carried over, not matched.

ColorVariant gold = ColorVariant.Nearest(Color.FromArgb(161, 126, 21));   // SolarGold, Shade, 3
ColorVariant green = ColorVariant.Nearest(0x2E, 0x7D, 0x32);              // Comet, Shade, 4

// From a picked or parsed colour back to a name.
if (ColorVariant.TryParseHex("#e6b41e", out ColorVariant picked))
{
    ColorVariant named = picked.ToNearestNamed();                         // SolarGold
}

On a terminal

NE.Colors.Terminal renders the same colours as ANSI escape sequences, downgraded to what the terminal can show. Which mode applies is the caller's decision — detecting the terminal is not this package's business.

using NE.Colors;
using NE.Colors.Terminal;

var teal = new ColorVariant(ColorName.AstralTeal);

teal.ToAnsiForeground();                              // ESC[38;2;0;110;100m
teal.ToAnsiForeground(ConsoleColorMode.Ansi256);      // ESC[38;5;23m
teal.ToAnsiBackground(ConsoleColorMode.Ansi16);       // ESC[46m
teal.ToAnsiForeground(ConsoleColorMode.NoColor);      // ""

// The parameters alone, for a renderer joining a colour with bold into one prefix.
teal.ToAnsiParameters();                              // "38;2;0;110;100"
teal.ToAnsiParameters(ConsoleColorMode.Ansi16, isBackground: true);   // "46"

Console.WriteLine(AnsiColor.Paint("ready", teal));    // painted and reset

Console.ForegroundColor = teal.ToConsoleColor();      // ConsoleColor.DarkCyan, for a console without ANSI

A terminal has no alpha channel, so Opacity is dropped there; a tint or a shade is the way to soften a colour on a terminal.

Ansi16Palette and Ansi256Palette are public in their own right: they map a colour to the nearest slot or palette entry and back, which is what a page rendering a preview of terminal output needs.

Contributing

This repository is a read-only mirror. Development happens in a private repository and everything here is generated from it, so pull requests are switched off here — anything merged would be erased by the next release.

Issues are open and welcome — bugs, questions and feature requests all belong here.

License

MIT. See LICENSE.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages