Osysharp.Color — colour maths for apps that let people choose colours

`Osysharp.Color` reads and writes hex colours, measures contrast the way the accessibility guidelines do, nudges a colour until text on it can be read, and proposes whole palettes, light and dark, from one base colour.

You are here: Building with agents › The kits › Color

Summary#

Osysharp.Color reads and writes hex colours, measures contrast the way the accessibility guidelines do, nudges a colour until text on it can be read, and proposes whole palettes, light and dark, from one base colour.

It is not about agents. It was released together with the agents family, and it is on this map so that the list of the release's kits is whole. It is plain Osy# with no network and no data, and gives the same answers on the server and in the browser.


Package	`Osysharp.Color`, version 0.2.0
You add it with	`use Osysharp.Color;` in the app's manifest.
Its own test app	The producer's test project for Osysharp — `kits/color/tests`

Description#

What do you get without writing anything?#

Readable-on: the nearest colour that text can be read on.
A palette, light and dark, from one colour.

When do you need it?#

When an app lets people pick colours — a theme, a label, a brand.

What does it expose?#

The tables below are generated from the kit itself, not written by hand: osy kits Osysharp.Color --surface lists each of them with the code of the kit's own test app that uses it, and the tests that show it working.

Functions you call, those its own tests show most first.

Function	What it does	Tests that show it
`NormalizeHex(string text)`	The colour as "#rrggbb" in capitals, from "#abc", "abc", "#aabbcc" or "aabbcc" (spaces around it ignored).	10
`ToOklch(string hex)`	The colour in oklch.	8
`FromOklch(double l, double c, double h)`	The hex of an oklch colour — the nearest colour a screen shows, found as `ShownLinear` finds it.	8
`Luminance(string hex)`	The colour's relative luminance, 0 (black) to 1 (white), as WCAG defines it.	6
`ContrastRatio(string one, string other)`	The contrast between two colours, from 1 (none) to 21 (black on white).	6
`PassesAA(string text, string ground, bool large = …)`	Can text in this colour be read on that ground — wcag aa: 4.5 for ordinary text, 3 for large text?	5
`IsDark(string hex)`	Is this a dark colour — one that white text reads better on than black?	5
`InkOn(string ground)`	Black or white, whichever reads better on this colour.	5
`ReadableOn(string colour, string ground, double ratio = …)`	`colour`, made readable on `ground`: the same hue and chroma, its lightness moved — away from the ground's — only as far as it takes to reach `ratio` (4.5 unless said).	5
`ContrastText(string one, string other)`	The contrast as a person reads it: "4.6 : 1".	4
`SuggestPalettes(string baseColor)`	Four palettes around one base colour, each light and dark: - Quiet — the base's own hue, almost grey: a tinted paper, ink of the same family, the base as the accent.	4
`IsReadable(PaletteMode mode)`	Is every pair of this mode readable, by wcag aa?	3
`IsHexColor(string text)`	Is this text a colour — three or six hex digits, with or without the "#"?	2
`WithLightness(string hex, double lightness)`	The same hue and chroma at another lightness (0 to 1).	1
`WithChroma(string hex, double chroma)`	The same lightness and hue at another chroma (0 is grey).	1
`Rotated(string hex, double degrees)`	The colour with its hue turned by so many degrees — 180 is its complement.	1
`Mix(string first, string second, double amount)`	A colour between two: `amount` 0 is the first, 1 the second, 0.5 halfway — mixed in OKLab, so the middle of blue and yellow is not a mud.	1

Go deeper#

The colour kit — contrast, OKLCH, and palettes from one colour — the kit's reference page