@crewlethq/tokens 0.49.1 → 0.51.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -1
- package/dist/color.d.ts +39 -0
- package/dist/color.js +110 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/package.json +1 -1
- package/test/color.mjs +23 -55
package/README.md
CHANGED
|
@@ -67,9 +67,27 @@ if (text && ground) {
|
|
|
67
67
|
| `contrast(a, b)` | The WCAG 2 ratio between two opaque colours, from 1 to 21, in either order. Unrounded: compare the raw ratio with a floor, and round only to display it, because a ratio that passes only once rounded does not pass. |
|
|
68
68
|
| `luminance(rgb)` | WCAG relative luminance, from 0 to 1. |
|
|
69
69
|
| `WCAG_CONTRAST` | The floors, frozen: `aa` 4.5 and `aaa` 7 for body text, `aaLarge` 3 and `aaaLarge` 4.5 for large text (24px, or 18.66px bold); `aaLarge` is also the floor for a graphical mark and a control's boundary. |
|
|
70
|
+
| `nearestContrastShade(hex, ground, min)` | The colour nearest `hex` that clears `min` against `ground`, as lowercase `#rrggbb`, or `null` when no shade of it can (or either value is not `#rrggbb`). Only its OKLab lightness moves, in both directions, and the nearer passing shade wins; its hue is kept, and its chroma gives way only where a screen cannot show it. A colour that already clears the floor comes back unchanged. The floor is held on the rounded value it returns. |
|
|
70
71
|
| `Rgb` | The type of a colour as channels from 0 to 255. |
|
|
71
72
|
|
|
72
|
-
The implementation is `src/color.ts`, built to `dist/color.js`. The published palette suite imports it from there and re-exports it, and the token build reads the same source to derive each palette's tints, so there is one copy of the maths.
|
|
73
|
+
The implementation is `src/color.ts`, built to `dist/color.js`. The published palette suite imports it from there and re-exports it (the OKLab conversions included), and the token build reads the same source to derive each palette's tints, so there is one copy of the maths.
|
|
74
|
+
|
|
75
|
+
When a pair falls short, offer the nearest shade rather than a verdict alone. It keeps the colour a person chose, so accepting it is a correction rather than a repaint:
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
import { WCAG_CONTRAST, contrast, nearestContrastShade, parseHex } from '@crewlethq/tokens';
|
|
79
|
+
|
|
80
|
+
nearestContrastShade('#00baba', '#f6f7fb', WCAG_CONTRAST.aa); // '#007f7f', 4.51:1
|
|
81
|
+
nearestContrastShade('#00baba', '#f6f7fb', WCAG_CONTRAST.aaLarge); // '#00a0a0', 3.00:1
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Show the ratio of the value it returns, measured with `contrast`, rather than the floor it was asked for.
|
|
85
|
+
|
|
86
|
+
## Changed in 0.50.0: the nearest shade that clears a floor
|
|
87
|
+
|
|
88
|
+
| What changed | What to change | Details |
|
|
89
|
+
| --- | --- | --- |
|
|
90
|
+
| `@crewlethq/tokens` exports `nearestContrastShade(hex, ground, min)`, the colour nearest `hex` (same hue, lightness moved) that clears `min` against `ground`, or `null`. In `@crewlethq/tokens/test/palette`, `toOklab`, `oklabToLinear`, `fromOklab` and `hex` are now the runtime module's functions, re-exported, with the same signatures and results. | Nothing. Replace a suggestion helper of your own with it. | [Contrast at runtime](#contrast-at-runtime) |
|
|
73
91
|
|
|
74
92
|
## Changed in 0.49.0: contrast at runtime, the brand kind and the brand mapping
|
|
75
93
|
|
package/dist/color.d.ts
CHANGED
|
@@ -59,3 +59,42 @@ export declare function luminance({ r, g, b }: Rgb): number;
|
|
|
59
59
|
* ratio against `WCAG_CONTRAST`.
|
|
60
60
|
*/
|
|
61
61
|
export declare function contrast(a: Rgb, b: Rgb): number;
|
|
62
|
+
/** A colour in OKLab: perceptual lightness `L` from 0 to 1, and the two opponent axes. */
|
|
63
|
+
export interface Oklab {
|
|
64
|
+
L: number;
|
|
65
|
+
a: number;
|
|
66
|
+
b: number;
|
|
67
|
+
}
|
|
68
|
+
/** sRGB channels (0 to 255) in OKLab. */
|
|
69
|
+
export declare function toOklab({ r, g, b }: Rgb): Oklab;
|
|
70
|
+
/**
|
|
71
|
+
* OKLab to LINEAR sRGB, unclipped. A channel under 0 or over 1 says the
|
|
72
|
+
* colour is outside what a screen can show, which `fromOklab` hides by
|
|
73
|
+
* clipping each channel on its own, and clipping one channel turns the hue: a
|
|
74
|
+
* search that walks lightness has to know where the gamut ends rather than be
|
|
75
|
+
* handed a different colour from the one it asked for.
|
|
76
|
+
*/
|
|
77
|
+
export declare function oklabToLinear({ L, a, b }: Oklab): Rgb;
|
|
78
|
+
/** One linear channel, 0 to 1, as an sRGB channel, 0 to 255, clipped but not rounded. */
|
|
79
|
+
export declare function fromLinear(v: number): number;
|
|
80
|
+
/** OKLab to sRGB, each channel clipped and rounded to a whole step. */
|
|
81
|
+
export declare function fromOklab(lab: Oklab): Rgb;
|
|
82
|
+
/** Channels as lowercase `#rrggbb`. */
|
|
83
|
+
export declare function formatHex({ r, g, b }: Rgb): string;
|
|
84
|
+
/**
|
|
85
|
+
* The colour nearest `hex` that clears `min` against `ground`, as lowercase
|
|
86
|
+
* `#rrggbb`, or null when no shade of it can (or either value is not
|
|
87
|
+
* `#rrggbb`).
|
|
88
|
+
*
|
|
89
|
+
* THE SAME COLOUR, LIGHTER OR DARKER. Its hue and chroma are kept in OKLab and
|
|
90
|
+
* only its lightness moves, in both directions from where it stands; the
|
|
91
|
+
* nearer shade that clears the floor wins, so a teal too light for a light
|
|
92
|
+
* page becomes a darker teal rather than a different colour. Where a shade
|
|
93
|
+
* cannot carry the colour's full chroma on a screen, chroma gives way and the
|
|
94
|
+
* hue never does. A colour that already clears the floor is its own answer.
|
|
95
|
+
*
|
|
96
|
+
* The floor is held on the rounded value the function returns, unrounded, as
|
|
97
|
+
* every contrast here is: a shade that clears it only before rounding is not
|
|
98
|
+
* returned.
|
|
99
|
+
*/
|
|
100
|
+
export declare function nearestContrastShade(hex: string, ground: string, min: number): string | null;
|
package/dist/color.js
CHANGED
|
@@ -79,3 +79,113 @@ export function contrast(a, b) {
|
|
|
79
79
|
const [hi, lo] = la > lb ? [la, lb] : [lb, la];
|
|
80
80
|
return (hi + 0.05) / (lo + 0.05);
|
|
81
81
|
}
|
|
82
|
+
/** sRGB channels (0 to 255) in OKLab. */
|
|
83
|
+
export function toOklab({ r, g, b }) {
|
|
84
|
+
const lr = linearChannel(r);
|
|
85
|
+
const lg = linearChannel(g);
|
|
86
|
+
const lb = linearChannel(b);
|
|
87
|
+
const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
|
|
88
|
+
const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
|
|
89
|
+
const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
|
|
90
|
+
return {
|
|
91
|
+
L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
|
|
92
|
+
a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
|
|
93
|
+
b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* OKLab to LINEAR sRGB, unclipped. A channel under 0 or over 1 says the
|
|
98
|
+
* colour is outside what a screen can show, which `fromOklab` hides by
|
|
99
|
+
* clipping each channel on its own, and clipping one channel turns the hue: a
|
|
100
|
+
* search that walks lightness has to know where the gamut ends rather than be
|
|
101
|
+
* handed a different colour from the one it asked for.
|
|
102
|
+
*/
|
|
103
|
+
export function oklabToLinear({ L, a, b }) {
|
|
104
|
+
const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
|
|
105
|
+
const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
|
|
106
|
+
const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
|
|
107
|
+
return {
|
|
108
|
+
r: 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
|
|
109
|
+
g: -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
|
|
110
|
+
b: -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
/** One linear channel, 0 to 1, as an sRGB channel, 0 to 255, clipped but not rounded. */
|
|
114
|
+
export function fromLinear(v) {
|
|
115
|
+
const c = v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055;
|
|
116
|
+
return Math.min(255, Math.max(0, c * 255));
|
|
117
|
+
}
|
|
118
|
+
/** OKLab to sRGB, each channel clipped and rounded to a whole step. */
|
|
119
|
+
export function fromOklab(lab) {
|
|
120
|
+
const { r, g, b } = oklabToLinear(lab);
|
|
121
|
+
return { r: Math.round(fromLinear(r)), g: Math.round(fromLinear(g)), b: Math.round(fromLinear(b)) };
|
|
122
|
+
}
|
|
123
|
+
/** Channels as lowercase `#rrggbb`. */
|
|
124
|
+
export function formatHex({ r, g, b }) {
|
|
125
|
+
return `#${[r, g, b].map((v) => Math.round(v).toString(16).padStart(2, '0')).join('')}`;
|
|
126
|
+
}
|
|
127
|
+
/** Whether linear sRGB is inside what a screen can show, with a hair of tolerance for rounding. */
|
|
128
|
+
function inGamut({ r, g, b }) {
|
|
129
|
+
const ok = (v) => v >= -1e-6 && v <= 1 + 1e-6;
|
|
130
|
+
return ok(r) && ok(g) && ok(b);
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* A lightness in OKLab, at the hue of `a` and `b`, as the most chroma the
|
|
134
|
+
* screen can show there, up to the colour's own: a dark or a very light shade
|
|
135
|
+
* of a vivid colour cannot carry its full chroma, and giving up chroma (never
|
|
136
|
+
* hue) is what keeps it the same colour.
|
|
137
|
+
*/
|
|
138
|
+
function shadeAt(L, a, b) {
|
|
139
|
+
if (inGamut(oklabToLinear({ L, a, b })))
|
|
140
|
+
return fromOklab({ L, a, b });
|
|
141
|
+
let lo = 0;
|
|
142
|
+
let hi = 1;
|
|
143
|
+
for (let i = 0; i < 24; i += 1) {
|
|
144
|
+
const k = (lo + hi) / 2;
|
|
145
|
+
if (inGamut(oklabToLinear({ L, a: a * k, b: b * k })))
|
|
146
|
+
lo = k;
|
|
147
|
+
else
|
|
148
|
+
hi = k;
|
|
149
|
+
}
|
|
150
|
+
return fromOklab({ L, a: a * lo, b: b * lo });
|
|
151
|
+
}
|
|
152
|
+
/** How finely the lightness is walked: a thousandth of OKLab's range. */
|
|
153
|
+
const LIGHTNESS_STEP = 0.001;
|
|
154
|
+
/**
|
|
155
|
+
* The colour nearest `hex` that clears `min` against `ground`, as lowercase
|
|
156
|
+
* `#rrggbb`, or null when no shade of it can (or either value is not
|
|
157
|
+
* `#rrggbb`).
|
|
158
|
+
*
|
|
159
|
+
* THE SAME COLOUR, LIGHTER OR DARKER. Its hue and chroma are kept in OKLab and
|
|
160
|
+
* only its lightness moves, in both directions from where it stands; the
|
|
161
|
+
* nearer shade that clears the floor wins, so a teal too light for a light
|
|
162
|
+
* page becomes a darker teal rather than a different colour. Where a shade
|
|
163
|
+
* cannot carry the colour's full chroma on a screen, chroma gives way and the
|
|
164
|
+
* hue never does. A colour that already clears the floor is its own answer.
|
|
165
|
+
*
|
|
166
|
+
* The floor is held on the rounded value the function returns, unrounded, as
|
|
167
|
+
* every contrast here is: a shade that clears it only before rounding is not
|
|
168
|
+
* returned.
|
|
169
|
+
*/
|
|
170
|
+
export function nearestContrastShade(hex, ground, min) {
|
|
171
|
+
const colour = parseHex(hex);
|
|
172
|
+
const base = parseHex(ground);
|
|
173
|
+
if (!colour || !base || !(min >= 1))
|
|
174
|
+
return null;
|
|
175
|
+
if (contrast(colour, base) >= min)
|
|
176
|
+
return formatHex(colour);
|
|
177
|
+
const { L, a, b } = toOklab(colour);
|
|
178
|
+
for (let i = 1; i * LIGHTNESS_STEP <= 1; i += 1) {
|
|
179
|
+
const dL = i * LIGHTNESS_STEP;
|
|
180
|
+
// Darker first at an equal distance: on the light grounds a brand is
|
|
181
|
+
// checked against most, darker is the shade that reads as the same ink.
|
|
182
|
+
for (const next of [L - dL, L + dL]) {
|
|
183
|
+
if (next < 0 || next > 1)
|
|
184
|
+
continue;
|
|
185
|
+
const shade = shadeAt(next, a, b);
|
|
186
|
+
if (contrast(shade, base) >= min)
|
|
187
|
+
return formatHex(shade);
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
return null;
|
|
191
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -343,7 +343,7 @@ export { themes } from './palettes.js';
|
|
|
343
343
|
export type { ThemeName } from './palettes.js';
|
|
344
344
|
export { themeGroups, themeRegistry, DEFAULT_THEME_ID, isThemeId } from './themes.js';
|
|
345
345
|
export type { ThemeGroupId, ThemeEntry, ThemeId } from './themes.js';
|
|
346
|
-
export { WCAG_CONTRAST, contrast, luminance, parseHex } from './color.js';
|
|
346
|
+
export { WCAG_CONTRAST, contrast, luminance, nearestContrastShade, parseHex } from './color.js';
|
|
347
347
|
export type { Rgb } from './color.js';
|
|
348
348
|
export { BRAND_SCOPE_CLASS, BRAND_SCOPE_LAYER_CLASS, BRAND_THEME_PREFIX, brandScopeCss, brandSlots, brandThemeName, parseBrandLayer } from './brand.js';
|
|
349
349
|
export type { BrandLayer, BrandModeValues } from './brand.js';
|
package/dist/index.js
CHANGED
|
@@ -342,5 +342,5 @@ export const zIndex = {
|
|
|
342
342
|
};
|
|
343
343
|
export { themes } from './palettes.js';
|
|
344
344
|
export { themeGroups, themeRegistry, DEFAULT_THEME_ID, isThemeId } from './themes.js';
|
|
345
|
-
export { WCAG_CONTRAST, contrast, luminance, parseHex } from './color.js';
|
|
345
|
+
export { WCAG_CONTRAST, contrast, luminance, nearestContrastShade, parseHex } from './color.js';
|
|
346
346
|
export { BRAND_SCOPE_CLASS, BRAND_SCOPE_LAYER_CLASS, BRAND_THEME_PREFIX, brandScopeCss, brandSlots, brandThemeName, parseBrandLayer } from './brand.js';
|
package/package.json
CHANGED
package/test/color.mjs
CHANGED
|
@@ -13,16 +13,30 @@
|
|
|
13
13
|
* It is published as part of `@crewlethq/tokens/test/palette`, so a consumer
|
|
14
14
|
* runs the same maths over the version it installed.
|
|
15
15
|
*
|
|
16
|
-
* The colour values
|
|
17
|
-
* package's runtime module (`src/color.ts`,
|
|
18
|
-
* `@crewlethq/tokens` itself exports, and
|
|
19
|
-
* interface that shows a contrast ratio
|
|
20
|
-
*
|
|
16
|
+
* The colour values, the WCAG ratio and the OKLab conversions are not
|
|
17
|
+
* implemented here: they are the package's runtime module (`src/color.ts`,
|
|
18
|
+
* built to `dist/color.js`), which `@crewlethq/tokens` itself exports, and
|
|
19
|
+
* this file re-exports them. An interface that shows a contrast ratio, or
|
|
20
|
+
* suggests the nearest shade that clears one, and the suite that holds a theme
|
|
21
|
+
* to one therefore compute it with the same code.
|
|
21
22
|
*/
|
|
22
23
|
|
|
23
|
-
import {
|
|
24
|
-
|
|
25
|
-
|
|
24
|
+
import {
|
|
25
|
+
contrast,
|
|
26
|
+
formatHex,
|
|
27
|
+
fromLinear,
|
|
28
|
+
fromOklab,
|
|
29
|
+
linearChannel,
|
|
30
|
+
luminance,
|
|
31
|
+
oklabToLinear,
|
|
32
|
+
parseHex,
|
|
33
|
+
parseRgba,
|
|
34
|
+
toOklab,
|
|
35
|
+
withAlpha,
|
|
36
|
+
} from '../dist/color.js';
|
|
37
|
+
|
|
38
|
+
export { contrast, fromOklab, luminance, oklabToLinear, parseHex, parseRgba, toOklab, withAlpha };
|
|
39
|
+
export { formatHex as hex };
|
|
26
40
|
|
|
27
41
|
/** @typedef {{ r: number, g: number, b: number }} RGB */
|
|
28
42
|
|
|
@@ -132,20 +146,6 @@ export function flatten(value, backdrop) {
|
|
|
132
146
|
// greens a reader cannot tell apart at 11px.
|
|
133
147
|
// ---------------------------------------------------------------------------
|
|
134
148
|
|
|
135
|
-
export function toOklab({ r, g, b }) {
|
|
136
|
-
const lr = linearChannel(r);
|
|
137
|
-
const lg = linearChannel(g);
|
|
138
|
-
const lb = linearChannel(b);
|
|
139
|
-
const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
|
|
140
|
-
const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
|
|
141
|
-
const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
|
|
142
|
-
return {
|
|
143
|
-
L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
|
|
144
|
-
a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
|
|
145
|
-
b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
|
|
146
|
-
};
|
|
147
|
-
}
|
|
148
|
-
|
|
149
149
|
/** Perceptual distance, scaled to roughly CIE dE units so floors read familiar. */
|
|
150
150
|
export function deltaE(x, y) {
|
|
151
151
|
const a = toOklab(x);
|
|
@@ -164,38 +164,6 @@ export function chroma(c) {
|
|
|
164
164
|
return Math.hypot(a, b) * 100;
|
|
165
165
|
}
|
|
166
166
|
|
|
167
|
-
function fromLinear(v) {
|
|
168
|
-
const c = v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055;
|
|
169
|
-
return Math.min(255, Math.max(0, c * 255));
|
|
170
|
-
}
|
|
171
|
-
|
|
172
|
-
/**
|
|
173
|
-
* OKLab to LINEAR sRGB, unclipped. A channel under 0 or over 1 says the
|
|
174
|
-
* colour is outside what a screen can show, which fromOklab hides by clipping
|
|
175
|
-
* each channel on its own, and clipping one channel turns the hue: a search
|
|
176
|
-
* that walks chroma has to know where the gamut ends rather than be handed a
|
|
177
|
-
* different colour from the one it asked for.
|
|
178
|
-
*/
|
|
179
|
-
export function oklabToLinear({ L, a, b }) {
|
|
180
|
-
const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
|
|
181
|
-
const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
|
|
182
|
-
const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
|
|
183
|
-
return {
|
|
184
|
-
r: 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
|
|
185
|
-
g: -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
|
|
186
|
-
b: -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
|
|
187
|
-
};
|
|
188
|
-
}
|
|
189
|
-
|
|
190
|
-
/** OKLab to sRGB, clipped. Used to search for the nearest passing value. */
|
|
191
|
-
export function fromOklab(lab) {
|
|
192
|
-
const { r, g, b } = oklabToLinear(lab);
|
|
193
|
-
return { r: Math.round(fromLinear(r)), g: Math.round(fromLinear(g)), b: Math.round(fromLinear(b)) };
|
|
194
|
-
}
|
|
195
|
-
|
|
196
|
-
export const hex = ({ r, g, b }) =>
|
|
197
|
-
`#${[r, g, b].map((v) => Math.round(v).toString(16).padStart(2, '0')).join('')}`;
|
|
198
|
-
|
|
199
167
|
/**
|
|
200
168
|
* Move a colour along OKLab lightness only, keeping hue and chroma, until
|
|
201
169
|
* `ok` holds. A failing token moves MINIMALLY and inside its own hue family;
|
|
@@ -205,7 +173,7 @@ export function nudge(value, direction, ok, step = 0.002) {
|
|
|
205
173
|
const lab = toOklab(parseHex(value));
|
|
206
174
|
for (let i = 0; i <= 500; i += 1) {
|
|
207
175
|
const candidate = fromOklab({ L: lab.L + direction * step * i, a: lab.a, b: lab.b });
|
|
208
|
-
if (ok(candidate)) return { value:
|
|
176
|
+
if (ok(candidate)) return { value: formatHex(candidate), dL: +(direction * step * i * 100).toFixed(1) };
|
|
209
177
|
}
|
|
210
178
|
return null;
|
|
211
179
|
}
|