@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 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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crewlethq/tokens",
3
- "version": "0.49.1",
3
+ "version": "0.51.0",
4
4
  "description": "Crewlet design tokens. Single JSON source compiled to CSS variables and typed JS modules.",
5
5
  "license": "MIT AND OFL-1.1",
6
6
  "repository": {
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 and the WCAG ratio are not implemented here: they are the
17
- * package's runtime module (`src/color.ts`, built to `dist/color.js`), which
18
- * `@crewlethq/tokens` itself exports, and this file re-exports them. An
19
- * interface that shows a contrast ratio and the suite that holds a theme to
20
- * one therefore compute it with the same code.
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 { contrast, linearChannel, luminance, parseHex, parseRgba, withAlpha } from '../dist/color.js';
24
-
25
- export { contrast, luminance, parseHex, parseRgba, withAlpha };
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: hex(candidate), dL: +(direction * step * i * 100).toFixed(1) };
176
+ if (ok(candidate)) return { value: formatHex(candidate), dL: +(direction * step * i * 100).toFixed(1) };
209
177
  }
210
178
  return null;
211
179
  }