@crewlethq/tokens 0.5.8 → 0.6.1

package/test/palette.mjs

@@ -74,7 +74,7 @@ export const OPAQUE_SURFACES = [
  * - THE SHEET OVER THE FRAME is the whole layering device: a content sheet
  *   floating inside the application ground. At dE 3, the floor this file holds
  *   every "can a reader notice it" difference to, the sheet reads as a
- *   separate plane; the approved dark sheet, #0f0f12, measured 2.91 and was
+ *   separate plane; the approved dark sheet, #0c0e15, measured 2.96 and was
  *   nudged to clear it.
  * - A CARD OVER THE SHEET is deliberately near-flat, dE 1.5, because a card is
  *   found by its HAIRLINE rather than by its fill: a page of cards each lifted
@@ -105,16 +105,28 @@ export const RUNG_STEPS = [
 export const CARD_HAIRLINE = ['--color-border-default', '--color-surface-subtle', '--color-surface-background'];
 export const HAIRLINE_DE = 3;
 
+/**
+ * A chip drawn on the raised rung inside the strong hairline, as [fill,
+ * edge]: the neutral pill, and a key cap. Its fill IS raised, so on a raised
+ * ground (a lead block, a raised card, the rail's current row) the fill alone
+ * draws nothing, and what finds the chip is its edge. So the chip's boundary,
+ * the fill or the edge, whichever stands further off its ground, is held to
+ * HAIRLINE_DE on every ground it can land on: each opaque rung, and each
+ * overlay a hovered, pressed or inset row composites onto one. A component
+ * suite holds the chip to drawing this pair; this is what keeps a palette
+ * from taking the edge away.
+ */
+export const RAISED_CHIP = ['--color-surface-elevated', '--color-border-strong'];
+
 /**
  * THE OVERLAY STEPS HAVE TO BE SEEN, on every rung.
  *
- * A translucent overlay is one alpha on four grounds, and the alpha is FITTED
- * (the hover token says how): the approved design paints its hover as one
- * opaque colour, and a stronger overlay costs the tertiary text step contrast
- * on the rungs it lightens or darkens most. Left to that trade alone, the
- * cheapest answer for the text is an overlay nobody sees, and the light
- * palette's frame kept asking for it: the design's own light hover sits dE
- * 0.60 off the frame. This is the floor that stops it. A hovered row separates
+ * A translucent overlay is one alpha on four grounds, and a stronger overlay
+ * costs the tertiary text step contrast on the rungs it lightens or darkens
+ * most. Left to that trade alone, the cheapest answer for the text is an
+ * overlay nobody sees, and a light frame keeps asking for it: an overlay that
+ * clears the sheet and the card can still sit under dE 3 on the frame. This
+ * is the floor that stops it. A hovered row separates
  * from its rung by dE 3, and a pressed row from a hovered one by dE 3 more,
  * because dE 3 is the floor this file holds every "can a reader notice it"
  * difference to. The marketing root is exempt, as it is from the rungs.
@@ -143,6 +155,18 @@ export const TEXT_STEPS = [
   ['--color-text-tertiary', 4.5],
 ];
 
+/**
+ * A DIMMED word against the word being read, as [read, dimmed, contrast]: the
+ * primary step and the tertiary one. A screen dims what is not its subject by
+ * dropping it from the first step to the third (a calendar's days from the
+ * neighbouring month, a resolved row under an open one), and both are facts,
+ * so each clears its own floor above. What this holds is that the two are a
+ * STEP apart rather than a rounding: 2:1 between the inks themselves. A ramp
+ * squeezed from both ends, a dimmer primary over a tertiary lifted for its
+ * floor on a pressed raised row, can keep every floor and lose the step.
+ */
+export const DIMMED_TEXT = ['--color-text-primary', '--color-text-tertiary', 2];
+
 /** A hue used as TEXT on a surface. */
 export const INK_STEPS = [
   '--color-brand-accent-ink',
@@ -169,11 +193,11 @@ export const STATUS = [
 ];
 
 /**
- * The chart series, in the order a figure assigns them: blue, orange, aqua and
- * an ochre yellow, the four the approved design draws.
+ * The chart series, in the order a figure assigns them: blue, orange, green
+ * and yellow, the four the approved palette draws.
  *
- * FOUR, because four is what both floors below can hold at once. The design's
- * four clear them with room (its tightest neighbours sit dE 19.8 apart under
+ * FOUR, because four is what both floors below can hold at once. The shipped
+ * four clear them with room (their tightest neighbours sit dE 20.6 apart under
  * normal vision), and a fifth would have to sit between two of them in a hue
  * budget the reserved red, the accent and a dichromat's collapse of red onto
  * green have already spent.
@@ -219,13 +243,13 @@ export const LABEL_ON_FILL = [
  * the fill is the whole of the feedback, so every step clears two things. It
  * is SEEN: ACTION_DE, the floor this file holds every "can a reader notice
  * it" difference to. And it moves AWAY from its label, which is ACTION_LABEL
- * on every fill: a hover or a press only ever gains contrast. The approved
- * design brightened its hover instead (brightness(1.08)), which is the step
- * TOWARD a white label, and on the dark accent it took white from 4.53:1 to
- * 4.18:1, under the text floor at the moment a reader is about to press. The
- * label rule above catches that number in dark; this rule is what catches the
- * same move in light, where the brightened step still measured 5.01:1 and
- * only its direction was wrong.
+ * on every fill: a hover or a press only ever gains contrast. A hover drawn as
+ * brightness(1.08) is the step TOWARD a white label: on either accent it
+ * takes white under the text floor (4.25:1 in dark, 4.19:1 in light) at the
+ * moment a reader is about to press, which the label rule above catches. This
+ * rule is what catches a step toward the label that still clears it: the
+ * accent dulled at its own lightness reads as a step and keeps its label over
+ * 4.5:1, and only its direction is wrong.
  *
  * The DESTRUCTIVE action is the other filled action, and it is held the same
  * way: a toast's destructive action is the danger fill under the same white
@@ -284,12 +308,12 @@ export const RAIL_GROUND = '--color-surface-frame';
  * border drawn round it INSIDE the row, and the primary ink.
  *
  * It is found the way a card is found. Its fill is allowed to be near-flat on
- * the frame, RAIL_CURRENT_LIFT, because in light raised is only dE 1.84 off
+ * the frame, RAIL_CURRENT_LIFT, because in light raised is only dE 1.93 off
  * the frame (the design draws it there); what carries the row is the
  * hairline, held to HAIRLINE_DE against the fill it is drawn on. The hairline
- * is also what tells the current row from a HOVERED one, which draws none: in
- * dark the two fills land dE 1.56 apart, because the fitted hover overlay
- * lifts the frame almost to raised.
+ * is also what tells the current row from a HOVERED one, which draws none: a
+ * hover overlay strong enough to be seen on the frame can lift it close to
+ * raised, and nothing else keeps the two apart.
  *
  * It used to be the accent's own soft tint with the label in the accent ink.
  * The accent is the primary action's fill now, so a violet row in the rail
@@ -443,14 +467,13 @@ export const VEIL_BAND = [1.5, 3];
  * somewhere the ink steps were never measured against, and it does it in the
  * one state where a reader cannot tell a rendering fault from a design.
  *
- * 0.65 is the approved dark scrim's 0.62 moved the least distance into the
- * band for every root. At 0.62 the veiled dark page's own primary text still
- * measured 3.02:1 to 3.15:1 over the four rungs, over the 3:1 ceiling, and the
- * marketing root, near-white on black, needs 0.65 before its brightest
- * composite comes under it. At 0.65 dark measures 2.73:1 to 2.84:1, light
- * 2.18:1 to 2.30:1 and the marketing root 2.75:1 to 2.93:1. The approved light
- * scrim, a dark wash at 0.28, left the light page at 8.35:1 to 9.64:1: a page
- * nobody had faded at all.
+ * 0.65 is the least alpha that brings every root into the band: the marketing
+ * root, near-white on black, needs it before its brightest composite comes
+ * under the 3:1 ceiling, and the approved palette draws its veil at it in both
+ * themes. At 0.65 dark measures 2.56:1 to 2.76:1, light 2.18:1 to 2.29:1 and
+ * the marketing root 2.75:1 to 2.93:1. A light veil drawn as a dark wash
+ * instead leaves the light page's text readable through it: a page nobody has
+ * faded at all.
  */
 export const VEIL_GROUND = '--color-surface-frame';
 export const VEIL_ALPHA = 0.65;
@@ -550,12 +573,11 @@ const ACCENT_DICHROMAT = 8;
 // because it is the one hue that means the same thing everywhere in a product,
 // and the accent's dichromat floor. Red, orange and green fall onto one axis
 // for a dichromat, so this is the floor the chart's orange and aqua spend the
-// most on: the approved aqua sat dE 0.73 from the approved red under
-// protanopia, and the approved orange 9.08 from it under normal vision in dark
-// and 7.45 in light. The fit moves the red further than the orange or the
-// aqua, darker, because it had to darken for its white label anyway, and in
-// dark it turns toward crimson as well, which spares the orange more than it
-// costs the red.
+// most on: the approved green sat dE 6.79 from the approved red under
+// deuteranopia in dark and 2.30 in light, and the approved orange 11.39 from
+// it under normal vision in dark. The fit moves the red darker, because it had
+// to darken for its white label anyway, and turns the green toward aqua, which
+// takes it off the axis the red falls on.
 const DANGER_NORMAL = 14;
 const DANGER_DICHROMAT = 8;
 
@@ -671,6 +693,12 @@ function checkState(state, values, profile, push) {
     const low = worst(colour(name), all);
     say('text step clears its floor', low.ratio >= floor, name, low.ratio, `${low.ratio.toFixed(2)}:1 >= ${floor} (worst on ${low.name})`);
   }
+  {
+    // A dimmed word against the word being read. See DIMMED_TEXT.
+    const [read, dimmed, floor] = DIMMED_TEXT;
+    const ratio = contrast(colour(read), colour(dimmed));
+    say('a dimmed word is a step from the word being read', ratio >= floor, `${read} vs ${dimmed}`, ratio, `${ratio.toFixed(2)}:1 >= ${floor}`);
+  }
 
   {
     // It exists for a hairline glyph and a disabled affordance. The assertion
@@ -1042,6 +1070,29 @@ function checkState(state, values, profile, push) {
       );
     }
   }
+  {
+    // A chip on every ground it can land on. See RAISED_CHIP.
+    const [fill, edge] = RAISED_CHIP;
+    const grounds = [
+      ...opaque,
+      ...OVERLAYS.flatMap((overlay) => opaque.map(([name, rgb]) => [`${overlay} on ${name}`, flatten(values.get(overlay), rgb)])),
+    ];
+    const low = grounds.reduce(
+      (least, [name, ground]) => {
+        const filled = flatten(values.get(fill), ground);
+        const drawn = Math.max(deltaE(filled, ground), deltaE(flatten(values.get(edge), filled), ground));
+        return drawn < least.drawn ? { drawn, name } : least;
+      },
+      { drawn: Infinity, name: '' },
+    );
+    say(
+      'the strong hairline finds a raised chip on every ground',
+      low.drawn >= HAIRLINE_DE,
+      `${edge} round ${fill}`,
+      low.drawn,
+      `dE ${low.drawn.toFixed(2)} >= ${HAIRLINE_DE} (worst on ${low.name})`,
+    );
+  }
 }
 
 const describe = (measured) => measured.map((value, i) => `${VISIONS[i].slice(0, 1)}${value.toFixed(1)}`).join('/');

package/test/palette.test.mjs

@@ -22,6 +22,7 @@ import {
   DATA_ADJACENT_DE,
   DATA_ADJACENT_NORMAL_DE,
   describeFailure,
+  DIMMED_TEXT,
   fromOklab,
   hex,
   oklabToLinear,
@@ -30,6 +31,7 @@ import {
   paletteStates,
   parseHex,
   RAIL_CURRENT_ROW,
+  RAISED_CHIP,
   runPalette,
   RUNG_STEPS,
   tightest,
@@ -155,6 +157,17 @@ describe('the palette', () => {
     assert.ok(onBase.includes('text step clears its floor'));
   });
 
+  test('a dimmed word is measured in every state, and one a rounding from the word being read is caught', () => {
+    const DIMMED_RULE = 'a dimmed word is a step from the word being read';
+    assert.deepEqual(DIMMED_TEXT, ['--color-text-primary', '--color-text-tertiary', 2]);
+    for (const state of STATES) {
+      assert.equal(checks.filter((check) => check.state === state && check.rule === DIMMED_RULE).length, 1, state);
+    }
+    // The tertiary step lifted onto the secondary one: each clears its own
+    // floor, and the step between the first and the third is gone.
+    assert.deepEqual(failuresAfter('dark', '--color-text-tertiary', typed.dark.color.text.secondary), [DIMMED_RULE]);
+  });
+
   test('the theme layer is dark first, and wins over the token layer', () => {
     // themes.css is imported second on purpose. If that ever stopped being
     // true the dark state would silently be the marketing palette; and if the
@@ -257,6 +270,18 @@ describe('the four rungs', () => {
     assert.deepEqual(darkFailures(line, dark.surface.subtle), ['the hairline that finds a card is visible on both sides of it']);
   });
 
+  test('a raised chip is measured in every theme state, and one whose edge is its own fill is caught', () => {
+    const CHIP_RULE = 'the strong hairline finds a raised chip on every ground';
+    const [fill, edge] = RAISED_CHIP;
+    assert.deepEqual([fill, edge], ['--color-surface-elevated', '--color-border-strong']);
+    for (const state of THEME_STATES) {
+      assert.equal(checks.filter((check) => check.state === state && check.rule === CHIP_RULE).length, 1, state);
+    }
+    // The edge drawn in the chip's own fill: on a raised ground the chip is
+    // loose words, and nothing else the palette measures notices.
+    assert.deepEqual(darkFailures(edge, dark.surface.elevated), [CHIP_RULE]);
+  });
+
   test('raised at the card\'s own value is caught', () => {
     assert.deepEqual(darkFailures('--color-surface-elevated', dark.surface.subtle), ['raised separates from the card']);
   });
@@ -279,8 +304,8 @@ describe('the accent and the primary action', () => {
   const [HOVER_RULE, PRESS_RULE] = ACTION_STEPS.map(([rule]) => rule);
 
   /**
-   * What `filter: brightness(1.08)` does to a colour, which is the hover the
-   * approved design drew: each sRGB channel scaled and clipped.
+   * What `filter: brightness(1.08)` does to a colour, the usual way to light a
+   * button under the pointer: each sRGB channel scaled and clipped.
    */
   const brightened = (value) => {
     const { r, g, b } = parseHex(value);
@@ -303,18 +328,33 @@ describe('the accent and the primary action', () => {
     }
   });
 
-  test("the approved design's brightening hover is caught in both palettes", () => {
-    // In dark it takes the white label under the text floor (4.18:1), which
-    // the label rule sees; in light it still clears 5.01:1, and only the step
-    // rule sees that it moved toward the label rather than away from it.
-    assert.equal(brightened(typed.dark.color.brand.accent), '#865dff');
-    assert.deepEqual(failuresAfter('dark', '--color-brand-accent-hover', brightened(typed.dark.color.brand.accent)), [
-      LABEL_RULE,
-      HOVER_RULE,
-    ]);
-    assert.deepEqual(failuresAfter('light', '--color-brand-accent-hover', brightened(typed.light.color.brand.accent)), [
-      HOVER_RULE,
-    ]);
+  test('a hover that brightens the fill is caught in both palettes', () => {
+    // It takes the white label under the text floor (4.25:1 in dark, 4.19:1
+    // in light), which the label rule sees, and the step rule sees that it
+    // moved toward the label rather than away from it.
+    assert.equal(brightened(typed.dark.color.brand.accent), '#7b62f8');
+    for (const palette of ['dark', 'light']) {
+      assert.deepEqual(
+        failuresAfter(palette, '--color-brand-accent-hover', brightened(typed[palette].color.brand.accent)),
+        [LABEL_RULE, HOVER_RULE],
+        palette,
+      );
+    }
+  });
+
+  test('a visible step toward the label is caught while the label still clears', () => {
+    // The accent dulled to 0.8 of its chroma at its own lightness: a step a
+    // reader sees (dE 3.94 in dark), under which the white label still clears
+    // the floor (4.72:1), and which moves toward the label all the same. Only
+    // the step rule's direction stands between it and a hover that fades.
+    const dulled = (value) => {
+      const lab = toOklab(parseHex(value));
+      return hex(fromOklab({ L: lab.L, a: lab.a * 0.8, b: lab.b * 0.8 }));
+    };
+    assert.equal(dulled(typed.dark.color.brand.accent), '#7164d1');
+    for (const palette of ['dark', 'light']) {
+      assert.deepEqual(failuresAfter(palette, '--color-brand-accent-hover', dulled(typed[palette].color.brand.accent)), [HOVER_RULE], palette);
+    }
   });
 
   test('a step nobody can see is caught, even one in the right direction', () => {
@@ -357,10 +397,12 @@ describe('the accent and the primary action', () => {
     assert.deepEqual(failuresAfter('dark', line, typed.dark.color.surface.elevated), [
       "the hairline round the rail's current row is visible on it",
     ]);
-    // Raised two steps off the light frame: every other rule raised is held
-    // to still holds, and the row is no longer there.
-    const { r, g, b } = parseHex(typed.light.color.surface.frame);
-    assert.deepEqual(failuresAfter('light', fill, hex({ r: r + 2, g: g + 2, b: b + 2 })), [
+    // Raised two steps off the dark frame: every other rule raised is held
+    // to still holds, and the row is no longer there. In light the hairline
+    // sits dE 1.23 from the frame, so a row lowered onto the frame loses its
+    // line as well, and only dark shows the lift on its own.
+    const { r, g, b } = parseHex(typed.dark.color.surface.frame);
+    assert.deepEqual(failuresAfter('dark', fill, hex({ r: r + 2, g: g + 2, b: b + 2 })), [
       "the rail's current row lifts off the rail",
     ]);
   });
@@ -410,39 +452,37 @@ describe('the state and chart hues', () => {
   });
 
   test("the design's stopped red is caught by its label, by deuteranopia and by the chart hues", () => {
-    // The approved #f26d6d carries a destructive action's white label at
-    // 2.92:1, and a deuteranopic reader finds it dE 5.7 from done (5.59
-    // against the design's own green, before either moved). It also sits
-    // under the floors the reserved red keeps from the orange, the aqua
-    // (protanopia 2.0) and the yellow.
-    const failing = checksAfter('dark', '--color-feedback-danger', '#f26d6d').map(summary);
+    // The approved #f0506e carries a destructive action's white label at
+    // 3.46:1, and a deuteranopic reader finds it dE 5.9 from done. It also
+    // sits under the floors the reserved red keeps from the orange (11.4
+    // under normal vision, 6.8 under deuteranopia) and from the green
+    // (deuteranopia 4.9).
+    const failing = checksAfter('dark', '--color-feedback-danger', '#f0506e').map(summary);
     assert.deepEqual(failing, [
-      `${LABEL_RULE}: --color-text-on-accent on --color-feedback-danger: 2.92:1 (worst on --color-feedback-danger on --color-surface-frame)`,
-      `${STATUS_RULE}: --color-feedback-success vs --color-feedback-danger: dE n30.4/p15.2/d5.7 >= 10`,
-      `${DANGER_RULE}: --color-data-2: dE n7.8/p8.3/d7.3 >= 14 normal, 8 dichromat`,
-      `${DANGER_RULE}: --color-data-3: dE n28.7/p2.0/d14.0 >= 14 normal, 8 dichromat`,
-      `${DANGER_RULE}: --color-data-4: dE n13.6/p8.9/d7.0 >= 14 normal, 8 dichromat`,
+      `${LABEL_RULE}: --color-text-on-accent on --color-feedback-danger: 3.46:1 (worst on --color-feedback-danger on --color-surface-frame)`,
+      `${STATUS_RULE}: --color-feedback-success vs --color-feedback-danger: dE n34.5/p18.6/d5.9 >= 10`,
+      `${DANGER_RULE}: --color-data-2: dE n11.4/p9.9/d6.8 >= 14 normal, 8 dichromat`,
+      `${DANGER_RULE}: --color-data-3: dE n32.5/p12.7/d4.9 >= 14 normal, 8 dichromat`,
     ]);
   });
 
   test("the design's light yellow is caught as a mark nobody can see on the frame", () => {
-    // #eda100 on the light frame is 1.85:1, the palest mark the design draws,
-    // and the only rule it breaks: a yellow dark enough to be seen on a light
-    // page is an ochre.
-    assert.deepEqual(checksAfter('light', '--color-data-4', '#eda100').map(summary), [
-      `${MARK_RULE}: --color-data-4: 1.85:1 (worst on --color-surface-frame)`,
+    // #edb302 on the light frame is 1.61:1, and that is the only rule it
+    // breaks: a yellow dark enough to be seen on a light page is an ochre.
+    assert.deepEqual(checksAfter('light', '--color-data-4', '#edb302').map(summary), [
+      `${MARK_RULE}: --color-data-4: 1.61:1 (worst on --color-surface-frame)`,
     ]);
   });
 
   test('a neighbour that clears every dichromat floor is still caught under normal vision', () => {
-    // An olive fourth series beside the aqua third: dE 12.1 apart under both
-    // protanopia and deuteranopia, which the dichromat floor alone passes,
-    // and 11.6 under normal vision, two shades of one hue to every reader who
-    // sees colour. Nothing else it touches fails, so the normal-vision floor
-    // is the only thing standing between it and a chart.
-    const failing = checksAfter('dark', '--color-data-4', '#5a8100');
+    // A teal fourth series beside the aqua green third: dE 13.0 apart under
+    // protanopia and 12.3 under deuteranopia, which the dichromat floor alone
+    // passes, and 13.0 under normal vision, two shades of one hue to every
+    // reader who sees colour. Nothing else it touches fails, so the
+    // normal-vision floor is the only thing standing between it and a chart.
+    const failing = checksAfter('dark', '--color-data-4', '#008c87');
     assert.deepEqual(failing.map(summary), [
-      `${ADJACENT_RULE}: --color-data-3 vs --color-data-4: dE n11.6/p12.1/d12.1 >= ${DATA_ADJACENT_NORMAL_DE} normal, ${DATA_ADJACENT_DE} every vision`,
+      `${ADJACENT_RULE}: --color-data-3 vs --color-data-4: dE n13.0/p13.0/d12.3 >= ${DATA_ADJACENT_NORMAL_DE} normal, ${DATA_ADJACENT_DE} every vision`,
     ]);
     assert.ok(failing[0].value >= DATA_ADJACENT_DE, 'the mutation has to clear the dichromat floor, or it proves nothing about the normal one');
   });