@crewlethq/tokens 0.48.2 → 0.49.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/dist/themes.js CHANGED
@@ -116,6 +116,14 @@ export const themes = {
116
116
  "presence": {
117
117
  "flagText": "#ffffff"
118
118
  },
119
+ "artifact": {
120
+ "kind": {
121
+ "brand": "#8f3884",
122
+ "brandInk": "#74246a",
123
+ "brandFill": "rgba(143, 56, 132, 0.12)",
124
+ "brandLine": "rgba(143, 56, 132, 0.38)"
125
+ }
126
+ },
119
127
  "scrollbar": "rgba(7, 8, 13, 0.2)",
120
128
  "scrollbarHover": "rgba(7, 8, 13, 0.32)"
121
129
  },
@@ -242,6 +250,14 @@ export const themes = {
242
250
  "presence": {
243
251
  "flagText": "#07080d"
244
252
  },
253
+ "artifact": {
254
+ "kind": {
255
+ "brand": "#cc7bd1",
256
+ "brandInk": "#dabcdb",
257
+ "brandFill": "rgba(204, 123, 209, 0.12)",
258
+ "brandLine": "rgba(204, 123, 209, 0.38)"
259
+ }
260
+ },
245
261
  "scrollbar": "rgba(255, 255, 255, 0.16)",
246
262
  "scrollbarHover": "rgba(255, 255, 255, 0.26)"
247
263
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crewlethq/tokens",
3
- "version": "0.48.2",
3
+ "version": "0.49.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": {
@@ -26,6 +26,8 @@
26
26
  },
27
27
  "./css": "./dist/css/tokens.css",
28
28
  "./css/base": "./dist/css/base.css",
29
+ "./css/brand": "./dist/css/brand.css",
30
+ "./css/brand-scope": "./dist/css/brand-scope.css",
29
31
  "./css/breakpoint": "./dist/css/breakpoint.css",
30
32
  "./css/density": "./dist/css/density.css",
31
33
  "./css/fonts": "./dist/css/fonts.css",
package/test/color.mjs CHANGED
@@ -12,8 +12,18 @@
12
12
  *
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
+ *
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.
15
21
  */
16
22
 
23
+ import { contrast, linearChannel, luminance, parseHex, parseRgba, withAlpha } from '../dist/color.js';
24
+
25
+ export { contrast, luminance, parseHex, parseRgba, withAlpha };
26
+
17
27
  /** @typedef {{ r: number, g: number, b: number }} RGB */
18
28
 
19
29
  // ---------------------------------------------------------------------------
@@ -102,26 +112,6 @@ export function cascade(sources, matches) {
102
112
  // Colour values
103
113
  // ---------------------------------------------------------------------------
104
114
 
105
- export function parseHex(hex) {
106
- const match = /^#([0-9a-f]{6})$/i.exec(hex.trim());
107
- if (!match) return null;
108
- const n = parseInt(match[1], 16);
109
- return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };
110
- }
111
-
112
- export function parseRgba(value) {
113
- const match = /^rgba?\(([^)]+)\)$/i.exec(value.trim());
114
- if (!match) return null;
115
- const parts = match[1]
116
- .split(/[,/\s]+/)
117
- .filter(Boolean)
118
- .map(Number);
119
- const [r, g, b, a] = parts;
120
- if (r === undefined || g === undefined || b === undefined) return null;
121
- if ([r, g, b].some(Number.isNaN)) return null;
122
- return { rgb: { r, g, b }, a: a === undefined ? 1 : a };
123
- }
124
-
125
115
  /** Composite a possibly translucent value over an opaque backdrop. */
126
116
  export function flatten(value, backdrop) {
127
117
  const hex = parseHex(value);
@@ -136,33 +126,6 @@ export function flatten(value, backdrop) {
136
126
  };
137
127
  }
138
128
 
139
- /** The same colour at a new alpha, as the CSS value the build emits. */
140
- export function withAlpha(value, alpha) {
141
- const rgb = parseHex(value) ?? parseRgba(value)?.rgb;
142
- if (!rgb) throw new Error(`cannot re-alpha "${value}"`);
143
- return `rgba(${Math.round(rgb.r)}, ${Math.round(rgb.g)}, ${Math.round(rgb.b)}, ${alpha})`;
144
- }
145
-
146
- // ---------------------------------------------------------------------------
147
- // WCAG
148
- // ---------------------------------------------------------------------------
149
-
150
- function channel(v) {
151
- const c = v / 255;
152
- return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
153
- }
154
-
155
- export function luminance({ r, g, b }) {
156
- return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
157
- }
158
-
159
- export function contrast(a, b) {
160
- const la = luminance(a);
161
- const lb = luminance(b);
162
- const [hi, lo] = la > lb ? [la, lb] : [lb, la];
163
- return (hi + 0.05) / (lo + 0.05);
164
- }
165
-
166
129
  // ---------------------------------------------------------------------------
167
130
  // OKLab. Perceptual distance is what "these two hues are separable" means.
168
131
  // RGB distance says magenta and red are far apart and says the same of two
@@ -170,9 +133,9 @@ export function contrast(a, b) {
170
133
  // ---------------------------------------------------------------------------
171
134
 
172
135
  export function toOklab({ r, g, b }) {
173
- const lr = channel(r);
174
- const lg = channel(g);
175
- const lb = channel(b);
136
+ const lr = linearChannel(r);
137
+ const lg = linearChannel(g);
138
+ const lb = linearChannel(b);
176
139
  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
177
140
  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
178
141
  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
@@ -253,9 +216,9 @@ export function nudge(value, direction, ok, step = 0.002) {
253
216
 
254
217
  /** Simulate protanopia or deuteranopia. Enough to answer "do these collide?". */
255
218
  export function simulate(c, kind) {
256
- const r = channel(c.r);
257
- const g = channel(c.g);
258
- const b = channel(c.b);
219
+ const r = linearChannel(c.r);
220
+ const g = linearChannel(c.g);
221
+ const b = linearChannel(c.b);
259
222
  const L = 0.31399022 * r + 0.63951294 * g + 0.04649755 * b;
260
223
  const M = 0.15537241 * r + 0.75789446 * g + 0.08670142 * b;
261
224
  const S = 0.01775239 * r + 0.10944209 * g + 0.87256922 * b;
@@ -91,6 +91,7 @@ export interface Rgb {
91
91
  }
92
92
 
93
93
  export function contrast(a: Rgb, b: Rgb): number;
94
+ export function luminance(colour: Rgb): number;
94
95
  export function deltaE(a: Rgb, b: Rgb): number;
95
96
  export function chroma(colour: Rgb): number;
96
97
  export function flatten(value: string, backdrop: Rgb): Rgb;
@@ -210,3 +211,12 @@ export const PRESENCE_HUES: readonly string[];
210
211
 
211
212
  /** The ink of the name on a presence flag, held to 4.5:1 on every presence hue. */
212
213
  export const PRESENCE_FLAG_TEXT: string;
214
+
215
+ /** Every artifact kind, the six node-hue kinds in the order the tokens declare them, then `brand`, whose hue is its own. */
216
+ export const ARTIFACT_KINDS: readonly string[];
217
+ /** Each kind's hue, by custom-property name (`--color-artifact-kind-<kind>`), in ARTIFACT_KINDS order. */
218
+ export const ARTIFACT_KIND_HUES: readonly string[];
219
+ /** The alpha a kind's fill is its hue at. */
220
+ export const ARTIFACT_KIND_FILL_ALPHA: number;
221
+ /** How far apart, in OKLab dE under normal vision, any two kind hues sit. */
222
+ export const ARTIFACT_KIND_DE: number;
package/test/palette.mjs CHANGED
@@ -345,6 +345,33 @@ export const AVATAR_TINTS = Array.from({ length: 10 }, (_, i) => `--color-avatar
345
345
  export const PRESENCE_HUES = ['purple', 'cyan', 'green', 'amber', 'rose', 'blue'].map((hue) => `--color-node-${hue}`);
346
346
  export const PRESENCE_FLAG_TEXT = '--color-presence-flag-text';
347
347
 
348
+ // ---------------------------------------------------------------------------
349
+ // Artifact kinds
350
+ // ---------------------------------------------------------------------------
351
+
352
+ /**
353
+ * The hue each kind of artifact is drawn in (`--color-artifact-kind-<kind>`),
354
+ * with its `-ink` step: the illustration on a "Start a new artifact" tile and
355
+ * a card's ground are drawn in the hue, and the kind's glyph in the ink, on
356
+ * the kind's own fill (a Make row's tile, a list's name cell) or straight on
357
+ * the page (an artifact's bar, a card's badge).
358
+ *
359
+ * Six kinds are aliases of the six node hues; `brand` has a hue of its own,
360
+ * because every node hue was already a kind. A kind's hue is identity and
361
+ * never state (its name is always drawn beside it), so the hues are held
362
+ * apart under normal vision only, at ARTIFACT_KIND_DE: the nearest pair the
363
+ * six node hues already make is dE 8.2, and a seventh hue has to keep that
364
+ * distance from every one of them. The hue clears 3:1 as a mark on every
365
+ * rung, and the ink 4.5:1 on its own fill and on every rung, the floor every
366
+ * other ink step keeps.
367
+ */
368
+ export const ARTIFACT_KINDS = ['doc', 'slides', 'design', 'dashboard', 'html', 'sheet', 'brand'];
369
+ export const ARTIFACT_KIND_HUES = ARTIFACT_KINDS.map((kind) => `--color-artifact-kind-${kind}`);
370
+ /** The alpha a kind's fill is its hue at: the build's node fill alpha. */
371
+ export const ARTIFACT_KIND_FILL_ALPHA = 0.12;
372
+ /** How far apart, in OKLab dE under normal vision, any two kind hues sit. */
373
+ export const ARTIFACT_KIND_DE = 8;
374
+
348
375
  // ---------------------------------------------------------------------------
349
376
  // The rail
350
377
  // ---------------------------------------------------------------------------
@@ -815,6 +842,21 @@ function surfacesOf(values) {
815
842
  return { ground, opaque, all };
816
843
  }
817
844
 
845
+ /**
846
+ * The token a `var()` alias finally names in one state, or the name itself
847
+ * when its value is not an alias. A token such as an artifact kind's hue is
848
+ * emitted as `var(--color-node-blue)`, which resolve() alone cannot measure.
849
+ */
850
+ function dereference(values, name) {
851
+ let current = name;
852
+ for (let hops = 0; hops < 8; hops += 1) {
853
+ const match = /^var\((--[a-z0-9-]+)\)$/i.exec((values.get(current) ?? '').trim());
854
+ if (!match) return current;
855
+ current = match[1];
856
+ }
857
+ throw new Error(`token ${name} is an alias chain more than 8 deep`);
858
+ }
859
+
818
860
  function resolve(values, name, ground) {
819
861
  const raw = values.get(name);
820
862
  if (raw === undefined) throw new Error(`token ${name} has no value`);
@@ -937,6 +979,41 @@ function checkState(state, values, profile, push, theme = { tint: null, contrast
937
979
  }
938
980
  }
939
981
 
982
+ // ARTIFACT KINDS. See ARTIFACT_KIND_HUES. Six of the hues are aliases of a
983
+ // node hue, so each is followed to the value it names in this state. The
984
+ // fill is recomputed from the hue rather than read from its token, so a
985
+ // hand-edited fill that no longer belongs to its hue fails.
986
+ {
987
+ const kinds = ARTIFACT_KIND_HUES.map((name) => [name, colour(dereference(values, name))]);
988
+ for (const [name, hueRgb] of kinds) {
989
+ const mark = worst(hueRgb, opaque);
990
+ say('an artifact kind hue clears 3:1 as a mark', mark.ratio >= 3, name, mark.ratio, `${mark.ratio.toFixed(2)}:1 (worst on ${mark.name})`);
991
+ const { r, g, b } = hueRgb;
992
+ const fills = opaque.map(([rung, rgb]) => [
993
+ `${name} fill on ${rung}`,
994
+ flatten(`rgba(${Math.round(r)}, ${Math.round(g)}, ${Math.round(b)}, ${ARTIFACT_KIND_FILL_ALPHA})`, rgb),
995
+ ]);
996
+ const ink = worst(colour(dereference(values, `${name}-ink`)), [...fills, ...opaque]);
997
+ say(
998
+ "an artifact kind's ink clears 4.5:1 on its own fill and on every rung",
999
+ ink.ratio >= 4.5,
1000
+ `${name}-ink`,
1001
+ ink.ratio,
1002
+ `${ink.ratio.toFixed(2)}:1 (worst on ${ink.name})`,
1003
+ );
1004
+ }
1005
+ if (profile === 'full') {
1006
+ for (let i = 0; i < kinds.length; i += 1) {
1007
+ for (let j = i + 1; j < kinds.length; j += 1) {
1008
+ const [a, aRgb] = kinds[i];
1009
+ const [b, bRgb] = kinds[j];
1010
+ const dE = deltaE(aRgb, bRgb);
1011
+ say('artifact kind hues stay apart', dE >= ARTIFACT_KIND_DE, `${a} vs ${b}`, dE, `dE ${dE.toFixed(1)} >= ${ARTIFACT_KIND_DE}`);
1012
+ }
1013
+ }
1014
+ }
1015
+ }
1016
+
940
1017
  // THE PRIMARY ACTION'S STEPS. See ACTION_STEPS.
941
1018
  for (const [rule, step, from] of ACTION_STEPS) {
942
1019
  const name = labelOf(step);
@@ -17,6 +17,9 @@ import assert from 'node:assert/strict';
17
17
  import { describe, test } from 'node:test';
18
18
  import {
19
19
  ACTION_STEPS,
20
+ ARTIFACT_KIND_DE,
21
+ ARTIFACT_KIND_HUES,
22
+ ARTIFACT_KINDS,
20
23
  CARD_HAIRLINE,
21
24
  DATA,
22
25
  DATA_ADJACENT_DE,
@@ -452,6 +455,37 @@ describe('the state and chart hues', () => {
452
455
  );
453
456
  });
454
457
 
458
+ test('every artifact kind is measured in every theme state, and a hue too near another kind is caught', () => {
459
+ // Seven kinds, in the order the tokens declare them. Brand is the one
460
+ // kind whose hue is not a node hue, so a palette that dropped it, or a
461
+ // rule that stopped following the six aliases to their node hue, would
462
+ // leave a kind's colour unmeasured.
463
+ const KIND_MARK_RULE = 'an artifact kind hue clears 3:1 as a mark';
464
+ const KIND_INK_RULE = "an artifact kind's ink clears 4.5:1 on its own fill and on every rung";
465
+ const KIND_APART_RULE = 'artifact kind hues stay apart';
466
+ assert.deepEqual(ARTIFACT_KINDS, ['doc', 'slides', 'design', 'dashboard', 'html', 'sheet', 'brand']);
467
+ for (const state of THEME_STATES) {
468
+ for (const name of ARTIFACT_KIND_HUES) {
469
+ for (const [rule, subject] of [[KIND_MARK_RULE, name], [KIND_INK_RULE, `${name}-ink`]]) {
470
+ const measured = checks.filter((check) => check.state === state && check.rule === rule && check.subject === subject);
471
+ assert.equal(measured.length, 1, `${state}: ${rule}: ${subject}`);
472
+ assert.ok(measured[0].ok, `${state}: ${describeFailure(measured[0])}`);
473
+ }
474
+ }
475
+ const pairs = checks.filter((check) => check.state === state && check.rule === KIND_APART_RULE);
476
+ assert.equal(pairs.length, (ARTIFACT_KINDS.length * (ARTIFACT_KINDS.length - 1)) / 2, state);
477
+ }
478
+ // A brand drawn in design's purple clears every floor but the distance
479
+ // between kinds, which is what keeps a brand kit from reading as a design.
480
+ for (const palette of ['dark', 'light']) {
481
+ const failing = checksAfter(palette, '--color-artifact-kind-brand', typed[palette].color.node.purple);
482
+ assert.deepEqual(failing.map((check) => `${check.rule}: ${check.subject}`), [`${KIND_APART_RULE}: --color-artifact-kind-design vs --color-artifact-kind-brand`], palette);
483
+ assert.ok(failing[0].value < ARTIFACT_KIND_DE, palette);
484
+ }
485
+ // And an ink that disappears into its own fill is caught by the ink rule alone.
486
+ assert.deepEqual(failuresAfter('light', '--color-artifact-kind-brand-ink', '#d9c2d6'), [KIND_INK_RULE]);
487
+ });
488
+
455
489
  test('the chart ramp is four series, in every theme state and in the typed export', () => {
456
490
  // A fifth series would have to sit between two of the four in a hue
457
491
  // budget the reserved red and the accent have spent, so it is the